Copyright: Version 7.0.2 Copyright © 2000 Sybase, Inc. All rights reserved.


Replication and Synchronization Guide
Version 7.0.2

Document ID:  MC0061

November 2000

 Copyright page

 About This Manual

 PART 1. Replication Basics

 PART 2. MobiLink Synchronization

 PART 3. SQL Remote

 PART 4. Appendixes


Copyright page
  Replication and Synchronization Guide

 Copyright page

Copyright © 2000 Sybase, Inc. All rights reserved.

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, 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-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Library, APT-Translator, APT Workbench, ASEP, Backup Server, BayCam, Bit-Wise, Certified PowerBuilder Developer, Certified SYBASE Professional, Certified SYBASE Professional (logo), ClearConnect, Client Services, Client-Library, CodeBank, Cohesion, Column Design, ComponentPack, Connection Manager, CSP, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution Director, Dynamo, E-Anywhere, E-Whatever, Electronic Case Management, 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, Financial Fusion, First Impression, Formula One, Gateway Manager, GeoPoint, ImpactNow, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InstaHelp, Intellidex, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase, Logical Memory Manager, MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MethodSet, MobiCATS, MySupport, Net-Gateway, Net-Library, NetImpact, Next Generation Learning, Next Generation Learning Studio, O DEVICE, OASiS, OASiS (logo), ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Client, Open Client/Server, Open Client/Server Interfaces, Open ClientConnect, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, Partnerships that Work, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, PhysicalArchitect, Power Through Knowledge, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript, PowerSite, PowerSocket, Powersoft, Powersoft Portfolio, Powersoft Professional, PowerStage, PowerStudio, PowerTips, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, Relational Beans, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Report Workbench, Report-Execute, Resource Manager, RW-DisplayLib, RW-Library, S-Designor, S Designor, SAFE, SAFE/PRO, 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 Server SNMP SubAgent, SQL Server/CFT, SQL Server/DBM, SQL SMART, SQL Station, SQL Toolset, SQLJ, Startup.Com, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase Development Framework, Sybase Financial Server, Sybase Gateways, Sybase Learning Connection, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase Synergy Program, Sybase User Workbench, Sybase Virtual Server Architecture, Sybase MPP, SybaseWare, Syber Financial, SyberAssist, SyBooks, System XI (logo), System 10, System 11, SystemTools, Tabular Data Stream, The Enterprise Client/Server Company, The Extensible Software Platform, The Future Is Wide Open, The Learning Connection, The Model For Client/Server Solutions, The Online Information Center, Transact-SQL, Translation Toolkit, Turning Imagination Into Reality, UltraLite, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual Components, VisualSpeller, VisualWriter, VQL, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, WarehouseArchitect, Watcom, Watcom SQL Server, Watcom SQL, Web.PB, Web.SQL, Web Deployment Kit, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server, and XP Server are trademarks of Sybase, Inc. or its subsidiaries.

Certicom, MobileTrust, and SSL Plus are trademarks and Security Builder is a registered trademark of Certicom Corp. Copyright © 1997-2000 Certicom Corp. Portions are Copyright © 1997-1998, Consensus Development Corporation, a wholly owned subsidiary of Certicom Corp. All rights reserved. Contains an implementation of NR signatures, licensed under U.S. patent 5,600,725. Protected by U.S. patents 5,787,028; 4,745,568; 5,761,305. Patents pending.

All other trademarks are property of their respective owners.

Last modified: June 2000. Part Number: MC0061.

 Copyright page

 About This Manual

 PART 1. Replication Basics

 PART 2. MobiLink Synchronization

 PART 3. SQL Remote

 PART 4. Appendixes


About This Manual
  Replication and Synchronization Guide

 About This Manual

 About this Manual

 Documentation conventions


About this Manual
  Replication and Synchronization Guide

    About This Manual

 About this Manual

Subject

This manual describes MobiLink, a session-based synchronization system, and SQL Remote, a message-based replication system. Both Sybase technologies allow two-way replication. Either can be used in mobile computing environments.

Audience

This manual is for users of Adaptive Server Anywhere and Adaptive Server Enterprise who wish to add synchronization or replication to their information systems.


Documentation conventions
  Replication and Synchronization Guide

    About This Manual

 Documentation conventions

This section lists the typographic and graphical conventions used in this documentation.

 Syntax conventions

 Graphic icons

 Installed files


Syntax conventions
  Replication and Synchronization Guide

    About This Manual

      Documentation conventions

 Syntax conventions

The following conventions are used in the SQL syntax descriptions:

•	Keywords    All SQL keywords are shown in UPPER CASE. However, SQL keywords are case insensitive, so you can enter keywords in any case you wish; SELECT is the same as Select which is the same as select.

•	Placeholders    Items that must be replaced with appropriate identifiers or expressions are shown in italics.

•	Continuation    Lines beginning with ... are a continuation of the statements from the previous line.

•	Repeating items    Lists of repeating items are shown with an element of the list followed by an ellipsis (three dots). One or more list elements are allowed. If more than one is specified, they must be separated by commas.

•	Optional portions    Optional portions of a statement are enclosed by square brackets. For example, ...

RELEASE SAVEPOINT [ savepoint-name ]

... indicates that the savepoint-name is optional. The square brackets should not be typed.

•	Options    When none or only one of a list of items must be chosen, the items are separated by vertical bars and the list enclosed in square brackets.

For example, ...

[ ASC | DESC ]

... indicates that you can choose one of ASC, DESC, or neither. The square brackets should not be typed.

•	Alternatives    When precisely one of the options must be chosen, the alternatives are enclosed in curly braces. For example ...

QUOTES { ON | OFF }

... indicates that exactly one of ON or OFF must be provided. The braces should not be typed.


Graphic icons
  Replication and Synchronization Guide

    About This Manual

      Documentation conventions

 Graphic icons

The following icons are used in this documentation:

Icon	Meaning
	A client application.
	A database server, such as Sybase Adaptive Server Anywhere or Adaptive Server Enterprise.
	An UltraLite application and database server. In UltraLite, the database server and the application are part of the same process.
	A database. In some high-level diagrams, the icon may be used to represent both the database and the database server that manages it.
	Replication or synchronization middleware. These pieces of software assist in sharing data among databases. Examples are the MobiLink synchronization server, the SQL Remote Message Agent, and the Replication Agent (Log Transfer Manager) for use with Replication Server.


Installed files
  Replication and Synchronization Guide

    About This Manual

      Documentation conventions

 Installed files

The following terms are used throughout the manual:

•	Installation directory    The directory into which you install SQL Anywhere Studio.

•	Executable directory    The executables and other files for each operating system are held in an executable subdirectory of the installation directory. This subdirectory has the following name:

•	Windows NT and Windows 95/98    win32

•	UNIX    bin

•	NetWare and Windows CE    The executables are held in the SQL Anywhere installation directory itself on these platforms.

 Copyright page

 About This Manual

 PART 1. Replication Basics

 PART 2. MobiLink Synchronization

 PART 3. SQL Remote

 PART 4. Appendixes


PART 1. Replication Basics
  Replication and Synchronization Guide

 PART 1. Replication Basics

This part describes general replication concepts. It also provides and overview of the Sybase technologies, including MobiLink, SQL Remote, and Replication Server, and provides guidelines for selecting the most appropriate technology.

 CHAPTER 1.  Sybase Replication Technologies


CHAPTER 1.  Sybase Replication Technologies
  Replication and Synchronization Guide

    PART 1. Replication Basics

 CHAPTER 1.  Sybase Replication Technologies

About this chapter

Data replication is the sharing of data among physically distinct databases. When an application modifies shared data at any one database, the changes are propagated to the other databases in the replication setup. Changes can be propagated by various means and through a variety of channels, preserving data integrity yet allowing flexible replication setups.

Sybase has three replication technologies. MobiLink and SQL Remote are designed for replication between a central database and a large number of remote databases. Replication Server is intended for near-real-time replication between a relatively small number of databases.

 Introduction

 Consolidated and remote databases

 Propagation methods

 Sybase replication technologies


Introduction
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

 Introduction

This section introduces basic concepts in data replication.

 Benefits of data replication

 Challenges for replication technologies


Benefits of data replication
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Introduction

 Benefits of data replication

Data availability

One of the key benefits of a data replication system is that data is made available locally, rather than through potentially expensive, less reliable, and slow connections to a single central database. Data is accessible locally even in the absence of any connection to a central server, so that you are not cut off from data in the event of a failure of a long-distance network connection.

Response time

Replication improves response times for data requests for two reasons. Retrieval rates are faster because requests are processed on a local server, without accessing a wide area network. Also, local processing offloads work from a central database server so that competition for processor time is decreased.


Challenges for replication technologies
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Introduction

 Challenges for replication technologies

Any replication technology must address several challenges that arise as a result of the increased flexibility permitted by replication.

Transactional integrity

One of the challenges of any replication system is to ensure that each database retains transactional integrity at all times.

Some replication systems, such as Sybase Replication Server and SQL Remote, replicate portions of the transaction log in such a way that transactions are replicated atomically: either a whole transaction is replicated, or none of it is replicated. This ensures transactional integrity at each database in the setup.

Other technologies, such as Sybase MobiLink, replicate data by consolidating changes made in multiple, committed transactions. These changes are applied to another database in a single transaction.

Data consistency

Another challenge to replication systems is to maintain data consistency throughout the setup. Replication systems maintain a loose consistency in the setup as a whole: that is, all changes are replicated to each site over time in a consistent manner, but different sites may have different copies of data at any instant.


Consolidated and remote databases
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

 Consolidated and remote databases

Both MobiLink and SQL Remote provide data replication between a consolidated database and a set of remote databases.

A consolidated database is a database that contains all the data to be replicated. A remote database is a database that may be running at the same site as the consolidated database or at a physically distant site.

The figure shows a schematic illustration of a small installation.

Remote users

A replication installation includes many remote databases. Each remote database contains a subset of the information in the consolidated database. Each remote database is a physically separate database, usually on a separate computer. All remote databases must stay consistent with the consolidated database.

The entire replication setup may be considered a single dispersed database, with the master copy of all shared data being kept at the consolidated database.

Each remote site that submits replications to the consolidated database is considered to be a remote user of the consolidated database. In the case that a remote site is a multi-user server, the entire site is considered to be a single remote user of the consolidated database.

 Hierarchical database configurations

 Two-way replication


Hierarchical database configurations
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Consolidated and remote databases

 Hierarchical database configurations

For databases in a hierarchical configuration, every database has a single parent database, except the consolidated database, which has no parent.

SQL Remote supports hierarchical configurations of databases; it does not support peer-to-peer replication or other non-hierarchical configurations. MobiLink is also normally used with a hierarchical configuration, but can also be used in other configurations.

For any two databases directly sharing data in a hierarchical configuration, one is always above or below the other in the hierarchy.

For databases in a non-hierarchical configuration, there is not any well-defined notion of above or below.

In a MobiLink or SQL Remote installation, each database contains all or a subset of the data replicated by the database above it in the hierarchy.

Remote databases can contain tables that are not present at the consolidated database, as long as they are not involved in replication. SQL Remote requires that the table and column names in the remote databases match the ones in the consolidated database. In contrast, MobiLink allows data to be stored in different columns and tables in the remote databases than in the consolidated database, allowing greater flexibility.


Two-way replication
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Consolidated and remote databases

 Two-way replication

All Sybase replication technologies provide two-way replication: changes made at the consolidated database are propagated to remote databases and changes made at remote databases are propagated to the consolidated database and, hence, to other remote databases. Sybase Replication Server requires that a particular piece of data can be modified at only one location. Both SQL Remote and MobiLink allow the same data to be changed simultaneously at multiple locations and provide a means of resolving any conflicts.


Propagation methods
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

 Propagation methods

When a transaction modifies shared data at any one database, the transaction or changes must be replicated to the other databases in the replication setup. There are various means by which this task may be accomplished.

 Session-based replication: MobiLink

 Message-based replication: SQL Remote

 Connection-based replication: Replication Server


Session-based replication: MobiLink
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Propagation methods

 Session-based replication: MobiLink

In a session-based replication scheme, synchronization occurs in real time over some sort of direct communications link. For example, the connection could be over a modem, network, or radio modem. Remote sites connect at intervals of minutes, hours, days, or weeks.

A session-based synchronization process is analogous to a telephone conversation in which all outstanding issues at both ends are resolved. The process follows a particular format. A MobiLink remote site begins by opening a connection to a MobiLink synchronization server and uploading a complete list of all the changes made to the remote database since the previous synchronization. Upon receiving this data, the server updates the consolidated database, then sends back all relevant changes. The remote site incorporates the entire set of changes, then sends back a confirmation and closes the connection.


Message-based replication: SQL Remote
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Propagation methods

 Message-based replication: SQL Remote

SQL Remote exchanges data between databases using messages. Messages are typically files, placed in a particular directory, or specially formatted e-mail messages. A message agent, attached to each database, sends messages regarding changes to its own data. The same agent also receives messages from one or more other databases and modifies the database, according to the contents of the received messages. This system allows replication between databases that have no direct connection: an occasional message-based connection such as e-mail or a periodic dial-up link is sufficient.

In message-based communications, each message carries its destination address and other control information, so that no direct connection is needed between applications exchanging information. For example, an e-mail message contains the destination address; there is no direct connection between the sending server and the recipient.

Message services use store and forward methods

Just as session-based client/server applications rely on network communication protocol stacks, such as TCP/IP or Novell NetWare's IPX, so message-based applications rely on message services such as Internet Simple Mail Transfer Protocol (SMTP), Microsoft's Messaging API (MAPI), Lotus' Vendor Independent Messaging (VIM), or a simple shared file link.

Message services use store-and-forward methods to get each message to its destination: for example, e-mail systems store messages until the recipient opens their mail folder to read their mail, at which time the e-mail system forwards the message.

Building a replication system on top of a message system means that a message-based replication system, such as SQL Remote, does not need to implement a store-and-forward system to get messages to their destination. Just as session-based client/server applications do not implement their own protocol stacks to pass information between client and server, so SQL Remote uses existing message systems to pass the messages.

Guaranteed delivery

To work reliably, a message-based replication system must both guarantee that all messages reach their destination and that the messages are applied in the same order that they are sent. Sybase SQL Remote incorporates a protocol to guarantee application of replication updates in the correct order.


Connection-based replication: Replication Server
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Propagation methods

 Connection-based replication: Replication Server

Some replication technologies rely on the presence of a continuous, or at least almost continuous, connection between the databases. Through this connection, the two databases conduct an ongoing dialogue. These types of systems excel at replicating changes quickly. Indeed, given sufficient resources and channel capacity, replication can occur reliably with a lag time of no more than a few seconds.

Sybase Replication server is near real-time replication system designed primarily for replication between a small number of databases. It is normally used with a continuous, reliable, high-speed connection. It incorporates store-and-forward techniques that allow replication to continue automatically when a connection is lost and later re-established.

The main drawback of this type of system is that a reliable, continuous connection can be expensive to maintain. This restriction makes connection-based technologies suited to replication between two large, fixed databases. In environments where the remote machines are mobile or are only occasionally connected, message-based or session-based technologies provide more flexible solutions.


Sybase replication technologies
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

 Sybase replication technologies

Sybase provides three replication technologies:

•	MobiLink    is a session-based technology intended for the two-way replication of data between a central, consolidated database and a large number of remote databases. It supports a variety of consolidated database servers, including non-Sybase databases. Administration and resource requirements at the remote sites are minimal, making it well suited to a variety of mobile applications. At the end of each synchronization session, the databases are consistent.

•	SQL Remote    is a message-based technology intended for the two-way replication of transactions. It is designed for two-way replication involving a consolidated data server and large number of remote databases. Administration and resource requirements at the remote sites are minimal, making it well suited to mobile databases. This system is message based. Depending on the setup, typical lag times between the consolidated and remote databases can be on the order of seconds, minutes, or hours.

•	Replication Server    is a connection-based technology intended for the two-way replication of transactions. It is well suited to replication between a small number of enterprise databases connected by a high-speed network, generally with an administrator at each site. In such a setup, it is possible to achieve lag times as low as a few seconds.

 Choosing a replication technology


Choosing a replication technology
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Sybase replication technologies

 Choosing a replication technology

Each Sybase replication technology lends itself to particular applications. The following descriptions differentiate the technologies and let you select the one best suited to your needs.

You should consider which of the following considerations are important in your application

Your consolidated database system

In a typical replication environment, a large database serves as a central repository for information. Sometimes you can choose a database system that suits your needs. Other times, a central database already exists and you must adapt the replication system to work with it.

MobiLink can work with many popular database servers, including Sybase Adaptive Server Anywhere, Sybase Adaptive Server Enterprise, Oracle, Microsoft SQL Server, and IBM DB2.

In a SQL Remote installation, the central database must be either Sybase Adaptive Server Anywhere or Sybase Adaptive Server Enterprise.

Your remote database system

Sybase replication technologies also differ in the types of remote databases that they can support. MobiLink allows your remote database to be either Adaptive Server Anywhere or UltraLite.

SQL Remote supports only Adaptive Server Anywhere remote databases.

Network characteristics

MobiLink and SQL Remote are both well suited to occasionally-connected environments, where remote sites must operate for hours or days in isolation, although more frequent synchronization is possible whenever a network connection is available. In contrast, Replication Server is designed for a continuous connection to allow large amounts of data to be replicated promptly.

MobiLink is session based. A real-time connection is required during synchronization. If this connection is interrupted before synchronization is complete, the process will not complete until the next synchronization. In contrast, SQL Remote relays information via messages, which can be sent or received asynchronously. These messages may take the form of files on a hard disk, or e-mail messages. These messages can be processed whenever they are received, allowing replication to occur incrementally.

Latency

In some situations, it may be important that your information is replicated immediately. In others, replication once or twice a day may suffice. In fact, more frequent replication may be impossible when no network connection is available.

Both MobiLink and SQL Remote are primarily intended for situations where replication occurs infrequently; for example every few hours or days. MobiLink and SQL Remote can both handle more frequent synchronization, but resource and network requirements are greater. However, given sufficient resources, MobiLink synchronizations can occur every few minutes. SQL Remote, when run in continuous mode, allows replication to occur every few seconds.

Replication Server is designed for setups requiring near real-time replication.

The number of remote sites

If you have a very large number of remote users, the best options are MobiLink or SQL Remote. The SQL Remote message-based design allows a typical installation to handle thousands of remote users. MobiLink scalability is limited only by the scalability of the consolidated database-management system. Replication Server is designed for only a few sites.

While these numbers are guidelines, there is no hard limit on the maximum number of remote sites with any of these systems. The actual number depends on the amount of information replicated, the frequency of synchronization, and the design of your application.

Transaction ordering

SQL Remote replicates data by scanning the transaction log and preparing messages, as appropriate, for each transaction. It orders these messages and sends them to the remote or consolidated site. When processing received messages, SQL Remote always processes them in the same order as they were applied to the other database. When necessary, it automatically delays processing a message until all earlier messages have been applied.

MobiLink, in contrast, works by grouping the results of multiple transactions on the remote database into one set of changes to be applied to the consolidated database. Since synchronization always occurs at a transaction boundary, referential integrity is preserved. The order of the individual changes made during the component transactions is not preserved. However, since uncommitted data is never synchronized, data integrity is preserved.

Achieving data consistency at a particular time

Immediately following each MobiLink synchronization session, the data in the two databases is consistent. The ability to guarantee the consistency of the data at a remote site at a particular point in time is an advantage of MobiLink session-based replication. For example, if it is important that the data at a remote site accurately reflect the data in the consolidated database at a particular time, say 10 o'clock in the morning, this objective can be achieved by synchronizing just prior to this time. As long as the synchronization completes successfully, the currency of the data at the remote site is assured.

When changes to the data are replicated through an exchange of messages, it is difficult to guarantee that the data in a particular remote site is completely consistent with the data in the consolidated site at any particular point in time. For example, sometimes a message is lost in transit. SQL Remote automatically recognizes this fault and resends the message, but such interruptions can cause unexpected delays.

 MobiLink characteristics

 SQL Remote characteristics

 Replication Server characteristics


MobiLink characteristics
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Sybase replication technologies

          Choosing a replication technology

 MobiLink characteristics

MobiLink is designed for replication installations with the following requirements:

•	Large numbers of databases    MobiLink is designed to support large numbers of remote databases. It can support thousands of remote databases in a single installation.

•	Occasionally connected    MobiLink supports databases that are occasionally connected or indirectly connected to the network on which the server is running. MobiLink scalability is limited only by the scalability of the consolidated database-management system.

•	Medium to high latency    Latency is the lag time between data being entered at one database and being replicated to each database in the installation. Applications typically connect and synchronize at periods of minutes, hours, or days.

•	Low to medium volume    Download information for remote sites is prepared for one remote site at a time. Large amounts of data in a MobiLink system can cause long connection times, since the remote site cannot disconnect until synchronization is complete.

•	Heterogeneous databases    MobiLink supports many of the most popular relational-database systems for use as a consolidated database. The schema of the remote sites can be different from that of the consolidated database because you control the synchronization process by writing scripts.


SQL Remote characteristics
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Sybase replication technologies

          Choosing a replication technology

 SQL Remote characteristics

SQL Remote is designed for replication installations with the following requirements:

•	Large numbers of databases    SQL Remote is designed to support large number of remote databases. It can support thousands of remote databases in a single installation because the messages for many remote sites can be prepared simultaneously.

•	Occasionally connected    SQL Remote supports databases that are occasionally connected or indirectly connected to the network on which the server is running.

•	Low to high latency    High latency means a long lag time between data being entered at one database and being replicated to each database in the installation. With SQL Remote, replication messages are sent typically at periods of seconds, minutes, hours, or days.

•	Low to moderate volume    As replication messages are delivered occasionally, a high transaction volume at each remote site can lead to a very large volume of messages. SQL Remote is best suited to systems with a relatively low volume of replicated data per remote database. At the consolidated site, SQL Remote can, however, prepare messages efficiently by preparing messages for multiple sites simultaneously.

•	Homogeneous databases    SQL Remote supports Adaptive Server Enterprise and Adaptive Server Anywhere databases. Each database in the system must have a very similar schema.


Replication Server characteristics
  Replication and Synchronization Guide

    PART 1. Replication Basics

      CHAPTER 1.  Sybase Replication Technologies

        Sybase replication technologies

          Choosing a replication technology

 Replication Server characteristics

Replication Server is designed for replication installations with the following requirements:

•	Small numbers of databases    Replication Server is designed to support replication among servers, with installations typically involving fewer than one hundred servers.

•	Continuously connected    Connections between primary sites and replicate sites may be over a wide area network, but Replication Server is designed for situations where there is a near-continuous connection path for data exchange among the servers in the installation.

•	Low latency    Low latency means a short lag time between data being entered at one database and being replicated to each database in the installation. With Replication Server, replication messages are sent typically within seconds of being entered at a primary site.

•	High volume    With near-continuous connections and high performance, Replication Server is designed for a high volume of replication messages.

•	Heterogeneous databases    Replication Server supports several leading DBMSs, and allows mapping of object names during replication, so that support for heterogeneous databases is provided.


PART 2. MobiLink Synchronization
  Replication and Synchronization Guide

 PART 2. MobiLink Synchronization

This part describes the concepts, architecture, and features of MobiLink Synchronization technology. The material describes both Adaptive Server Anywhere and UltraLite clients, as well as the use of consolidated databases from a variety of vendors.

 CHAPTER 2.  Introducing MobiLink Synchronization

 CHAPTER 3.  Synchronization Basics

 CHAPTER 4.  Writing Synchronization Scripts

 CHAPTER 5.  Synchronization Techniques

 CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

 CHAPTER 7.  Adaptive Server Anywhere Clients

 CHAPTER 8.  Reference


CHAPTER 2.  Introducing MobiLink Synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

 CHAPTER 2.  Introducing MobiLink Synchronization

About this chapter

This chapter introduces you to the Sybase MobiLink synchronization technology. It describes the purpose and defining characteristics of MobiLink.

 Overview

 What's new in 7.0.2

 What's new in 7.0.1

 What's new in 7.0

 What's new in 6.0.3


Overview
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

 Overview

Most mobile and embedded applications require data to be uploaded to a central database, downloaded from a central database, or both uploaded and downloaded. This functionality is essential to making the application function effectively within the information infrastructure of an organization.

Adaptive Server Anywhere and UltraLite applications are equipped with the ability to synchronize data with a central database. Often, this task must be accomplished through a low-bandwidth channel. To make the most of limited channels, synchronization uses an efficient means of transferring information between consolidated and remote databases. MobiLink is the name of the technology that provides this synchronization functionality.

MobiLink synchronization technology, included in SQL Anywhere Studio, is designed to work with industry-standard enterprise SQL database-management systems from Sybase and other vendors.

MobiLink clients

In a MobiLink setup, each mobile or embedded application has its own database. These databases are called remote databases, and may be an integral part of the application, as in the case of UltraLite applications, or may be separate components, as is the case when using Adaptive Server Anywhere.

These two types of remote databases, the ones within UltraLite applications and Adaptive Server Anywhere databases, may also be referred to as MobiLink clients because, in addition to the remote data, each type contains logic that forms an integral part of the MobiLink replication system.

MobiLink clients automatically keep track of the changes made to the remote database since the last synchronization with the central database. When the remote database is next synchronized, all these changes are uploaded. UltraLite clients automatically use internal logic to keep track of the changes, using a separate field that records the status of each row. Adaptive Server Anywhere clients automatically track the changes using their transaction log.

Subset of the central data

Mobile and embedded databases contain a fraction of the data that exists in the central database. The central database is called the consolidated database because it consolidates all the data throughout the MobiLink installation.

The tables in each remote database contain a subset of the data in the central database. For example, a customer table might contain over 100 columns and 100,000 rows in the consolidated database, but the remote database may only require 4 columns and 1000 rows. MobiLink technology allows you to define the exact subset to be downloaded to each remote database.

MobiLink synchronization is flexible. You define the subset of data using the native SQL dialect of the central database-management system. Tables in the remote database may correspond to tables in the central database, or you may reorganize the data using tables and rows more appropriate to the needs of the remote application. You can populate a remote table from a consolidated table with a different name, or even from a join of two or more tables.

When synchronizing, it is important to only transfer data that has changed rather than a complete copy of the data. The MobiLink client automatically keeps track of and uploads only data that has changed since the previous synchronization. You control which data is downloaded to each client using the native SQL dialect of the central database-management system. This system ensures that only needed information is transferred.

Conflict resolution

Mobile and embedded databases frequently share common data. They also must allow updates to this data. When two or more remote databases update the same row, the conflict cannot be prevented. Instead, it must be detected and resolved when the changes are uploaded to the central database. MobiLink synchronization automatically detects these conflicts. You implement the conflict resolution logic using the native SQL dialect of the central DBMS.

Encryption

When the remote and consolidated databases are far apart, replication may be possible only over a public network. To ensure your privacy, MobiLink technology supports strong encryption of all communication between the remote databases and the MobiLink synchronization server.

The MobiLink synchronization server

A MobiLink client synchronizes with a central, consolidated database through a MobiLink synchronization server. This server provides an interface between the communications from the remote application and the central, consolidated database server.

You control the synchronization process using scripts. These scripts are SQL statements or procedures written in the native language of the consolidated DBMS. For example, you can use a SELECT statement to identify the columns and tables in the consolidated database that correspond to each column of a row uploaded from a table in your remote database. These scripts are stored in tables within the consolidated database. Each script controls a particular event during the synchronization process.

Synchronization streams

Synchronization can occur through a variety of streams. One option is a TCP/IP connection between the application and the MobiLink synchronization server. Other platforms require different solutions. For example, UltraLite applications on the Palm Computing Platform can use HotSync, ScoutSync, HTTP, TCP/IP, or direct serial port communication. Regardless of the stream, you control the synchronization process using the same SQL scripts defined in your consolidated database.

  For a detailed introduction to MobiLink synchronization, see MobiLink Synchronization.


What's new in 7.0.2
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

 What's new in 7.0.2

Following is a list of changes and additions to the software introduced in version 7.0.2.

•	Liveness detection for TCP/IP synchronization streams    If TCP/IP connections from MobiLink clients disappear during synchronization, the corresponding MobiLink synchronization server worker thread that updates the database can be stuck waiting for replies from the client.

A new synchronization stream parameter for TCP/IP clients and for the MobiLink synchronization server enables you to check the liveness of a TCP/IP connection.

  For more information, see MobiLink synchronization server

•	Maximum number of threads applying upload streams    To reduce database contention, the -wu command line switch can now be used to set the maximum number of worker threads allowed to upload concurrently. The upload requests are processed in first-come, first-serve order.

•	Setting maximum number of processors    MobiLink has a new option for setting the maximum number of processors to use. The -zt switch provides for greater control of the resources used by the MobiLink server. It can also help to discover and/or work around an ODBC driver with multi-processor issues.

 Behavior Changes


Behavior Changes
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

        What's new in 7.0.2

 Behavior Changes

The MobiLink consolidated-database upgrade scripts are organized into the following sub-directories of the ASA install directory:

File	Description
MobiLink\upgrade\6.0.x	Scripts for upgrading from ASA 6.0.x
MobiLink\upgrade\7.0.0_or_7.0.1	Scripts for upgrading from ASA 7.0.0 or 7.0.1
readme.txt	Text file that describes how to perform the upgrade
upgrade_ase.sql	ASE upgrade script
upgrade_db2.sql	IBM DB2 UDB upgrade script
upgrade_mss.sql	Microsoft SQL Server upgrade script
upgrade_ora.sql	Oracle upgrade script


What's new in 7.0.1
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

 What's new in 7.0.1

Following is a list of changes and additions to the software introduced in version 7.0.1.

•	User authentication    A password-based system for user authentication adds additional security to your MobiLink installation.

  For more information, see Authenticating MobiLink users.

•	Extensive documentation of transport-layer security    The transport-layer security documentation has been extended to describe a variety of architectures possible with this powerful security mechanism.

  For more information, see Transport-layer security.

•	Customizing synchronization and synchronization-related processes    The Adaptive Server Anywhere synchronization client dbmlsync now supports a set of events. You can add stored procedures to your Adaptive Server Anywhere database to program event-based actions. This adds flexibility to the synchronization process, including the ability to schedule synchronization.

  For more information, see Customizing the synchronization process.

•	Synchronization optimizations    You can optimize the following aspects of the synchronization process.

•	UltraLite client applications can specify that a synchronization includes only uploads, and that no download phase should be attempted.

This option lessens the overall synchronization time when only uploads are needed.

•	Adaptive Server Anywhere clients can specify an incremental upload option to reduce memory requirements for large uploads.

  For more information, see Tuning synchronization.

•	Adaptive Server Anywhere clients can permit concurrent modification of rows during synchronization.

 For more information, see Concurrency during synchronization.

•	Scheduling synchronization    You can use an extended option to configure the dbmlsync utility or a synchronization definition to synchronize according to a schedule.

  For more information, see Scheduling synchronization.

•	Adaptive Server Anywhere client synchronization utility enhancements    There are several enhancements to the dbmlsync utility:

•	You can supply the -mp and -mn command-line switches to supply or change the MobiLink password.

•	You can supply repeated -n command-line switches to synchronize more than one synchronization definition.

•	The -v command-line switch now generates more useful information, including command-line switches and options set in the synchronization definition.

•	The -r command-line switch is extended to allow more flexibility in uploads when the recorded progress indicators in the client and consolidated databases do not match.

•	The -x command-line switch renames and restarts the transaction log. This option is useful if you use the consolidated database as a backup of the data at the client, so that client-side backups are not required.

•	If you do not specify connection parameters on the command line, dbmlsync displays a dialog on which you can provide connection parameters and startup options.

•	The dbmlsync window displays synchronization progress, and allows you to cancel synchronization.

  For more information, see Adaptive Server Anywhere client synchronization utility.

•	New MobiLink synchronization server options    The MobiLink synchronization server provides additional command-line switches.

  For more information, see MobiLink synchronization server.

•	New script events    New scripts have been added for handling and reporting errors arising from the ODBC Driver Manager, and to provide additional flexibility when designing synchronization techniques.

  For more information, see the following:

•	handle_odbc_error connection script

•	prepare_for_download connection script

•	report_odbc_error connection script.

•	Interface to dbmlsync features    Developers using the C programming language can add features of the dbmlsync command-line utility to their application.

  For more information, see Including dbmlsync functionality in an application.


What's new in 7.0
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

 What's new in 7.0

Following is a list of changes and additions to the software since version 6.0.3.

•	Adaptive Server Anywhere clients    MobiLink technology now supports Adaptive Server Anywhere as a client, as well as UltraLite applications.

  For more information, see Adaptive Server Anywhere Clients.

•	mlxtract creates Adaptive Server Anywhere client databases    mlxtract creates Adaptive Server Anywhere databases, suitable for use as MobiLink clients, using an Adaptive Server Anywhere reference database as a template.

•	Synchronization script versions    Synchronization scripts can now be grouped by assigning a script version name with each script. This feature allows the MobiLink synchronization server to respond differently when synchronizing different types of applications, or different versions of the same application.

•	New data types    LONG BINARY and LONG VARCHAR data types can now be replicated using MobiLink technology.

•	New HotSync conduit    A new HotSync conduit allows HotSync synchronization with a centrally located MobiLink synchronization server. The MobiLink synchronization server no longer needs to be on the same machine as the HotSync manager is.

•	ScoutSync conduit    UltraLite applications for the Palm Computing Platform can now synchronize using ScoutSync technology, available from Riverbed Technologies.

•	report_error script    A new script provides a convenient way to report errors during synchronization. The report_error script also makes debugging the behavior of the handle_error script much easier. The report_error script has the same parameters as the handle_error script, except that the first parameter is the action code returned by handle_error.

•	Maximum number of threads applying upload streams    To reduce database contention, the -wu command line switch can now be used to set the maximum number of worker threads allowed to upload concurrently. The upload requests are processed in first-come, first-serve order.

•	Setting maximum number of processors    MobiLink has a new option for setting the maximum number of processors to use. The -zt switch provides for greater control of the resources used by the MobiLink server. It can also help to discover and/or work around an ODBC driver with multi-processor issues.

 Behavior changes

 Upgrade issues


Behavior changes
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

        What's new in 7.0

 Behavior changes

•	New table and script names    The tables that hold synchronization scripts and related information in the consolidated database now have new names. Previously, these table names began with the prefix ul_. This prefix has been changed to ml_. Older consolidated databases must be upgraded for compatibility with version 7.0.

Similarly, the stored procedure that facilitates adding table scripts has been renamed from sp_table_script to ml_add_table_script and the stored procedure that facilitates adding connection scripts has been renamed from sp_connection_script to ml_add_connection_script.

Under DB2, these names are truncated to 18 characters.

•	dbssrv6 is now called dbmlsrv7    The name of the command that starts the MobiLink synchronization server is now called dbmlsrv7. Likewise, the command that stops this server is now called dbmlstop.

•	Synchronization scripts require a version name    Synchronization scripts must now be assigned a script version name. Script version names allow the MobiLink synchronization server to treat different clients differently.


Upgrade issues
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

        What's new in 7.0

 Upgrade issues

Subject to the above behavior changes, older versions of UltraLite applications can synchronize with the new version of the MobiLink synchronization server. However, Adaptive Server Anywhere databases and new UltraLite applications are incompatible with older versions of the MobiLink synchronization server.

Old consolidated databases can be upgraded using included scripts.


What's new in 6.0.3
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

 What's new in 6.0.3

Following is a list of changes and additions to the software since version 6.0.2.

•	New data types    Real and double data types are now fully supported.

•	ODBC 3.51    The MobiLink synchronization server now uses ODBC 3.51, in common with the rest of Adaptive Server Anywhere. Version 6.0.2 of the MobiLink synchronization server used ODBC 2.0.

•	Character set translation    The MobiLink synchronization server now translates all uploaded characters to Unicode and passes them to the consolidated database using the Unicode ODBC API. Conversely, it translates all downloaded characters from Unicode to the character set of your UltraLite application. Character set translation within the consolidated database server can influence the results, but the new system allows more consistent behavior across multiple platforms.

  For more information, see Character-set translation during MobiLink synchronization.

•	Free technical advice    Technical advice and limited support is available for free on the newsgroup sybase.public.sqlanywhere.mobilink. The host for this newsgroup is forums.sybase.com.

•	MobiLink synchronization server runs as a Windows NT service    When you run the MobiLink synchronization server as a service, you can configure it to continue running when you log off the Windows NT workstation.

  For more information, see Running the MobiLink synchronization server as a Windows NT service.

•	DB2 setup scripts provided    To make it easier to use IBM DB2 as a consolidated database, a DB2 setup script has been added to the available set scripts.

  For a list of setup scripts, see Creating a consolidated database.

 Behavior changes

 Upgrade issues


Behavior changes
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

        What's new in 6.0.3

 Behavior changes

•	Location of synchronization scripts changed    The synchronization scripts for non-Adaptive Server Anywhere databases are now installed into the MobiLink\setup subdirectory of your Adaptive Server Anywhere installation directory.


Upgrade issues
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 2.  Introducing MobiLink Synchronization

        What's new in 6.0.3

 Upgrade issues

Older versions of UltraLite applications can synchronize with the new version of the MobiLink synchronization server. However, new UltraLite applications cannot synchronize with older versions of the MobiLink synchronization server.


CHAPTER 3.  Synchronization Basics
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

 CHAPTER 3.  Synchronization Basics

About this chapter

This chapter describes the MobiLink technology, which provides a synchronization mechanism for Adaptive Server Anywhere client databases and UltraLite applications.

 Parts of the synchronization system

 The MobiLink synchronization server

 MobiLink clients

 The synchronization process

 The consolidated database

 Creating a consolidated database

 Running the MobiLink synchronization server

 Details of the synchronization process

 Character-set considerations

 Authenticating MobiLink users

 Transport-layer security

 Transport-layer security and digital certificates


Parts of the synchronization system
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Parts of the synchronization system

The following diagram displays the components of the synchronization system. The communications channel between the application and the MobiLink synchronization server can be any of the supported communication protocols. These protocols include TCP/IP, HTTP, Serial, and HotSync, although some protocols are not available on all platforms.


The MobiLink synchronization server
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 The MobiLink synchronization server

The MobiLink synchronization server provides an interface between the consolidated database and the remote clients. The synchronization server communicates with a consolidated database server via ODBC. It can communicate with MobiLink clients using a number of popular protocols over various types of networks.

Given sufficient resources, many remote applications can synchronize simultaneously, making MobiLink synchronization well suited to large-scale deployment.

Because the MobiLink synchronization server is a separate component, it is not tied to one database product. It can communicate with a number of commercially available database servers, including Sybase Adaptive Server Anywhere, Sybase Adaptive Server Enterprise, Oracle, IBM DB2, and Microsoft SQL Server.

Synchronization logic is stored in the consolidated database

The MobiLink synchronization server handles the synchronization process between clients and database server. The MobiLink synchronization server is connected to a consolidated database server that serves as the central repository for all the replicated data.

You store synchronization information, including synchronization scripts, in the consolidated database. These scripts guide the MobiLink synchronization server in handling connections with remote users and in matching data in the remote databases with that in the consolidated database.

Development tip
You can use a single Adaptive Server Anywhere database as both reference and consolidated database during development. You can switch the consolidated database later, if necessary.

  For information about the reference database, see Creating the reference database.

  For information about the consolidated database, see The consolidated database.


MobiLink clients
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 MobiLink clients

The remote applications in a MobiLink setup are referred to as MobiLink clients because, in addition to the remote data, each contains logic that forms an integral part of the MobiLink replication system. In particular, a MobiLink client must contain logic to keep track of changes to the database, to prepare data to send to the server, and to incorporate data that it receives in reply.

Two types of MobiLink clients are presently available:

•	Adaptive Server Anywhere   MobiLink client logic is built into Adaptive Server Anywhere, allowing it to be used as clients.

•	UltraLite applications   Applications built with the UltraLite technology available in Adaptive Server Anywhere are automatically MobiLink enabled whenever the application includes a call to the appropriate MobiLink synchronization function.

 UltraLite MobiLink clients

 Adaptive Server Anywhere MobiLink clients

 The synchronization user name


UltraLite MobiLink clients
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        MobiLink clients

 UltraLite MobiLink clients

The UltraLite development tools, included in SQL Anywhere Studio, automatically include synchronization logic when you build your UltraLite application.

Since the UltraLite runtime handles the synchronization actions at the application end, you can write your UltraLite application with little regard to synchronization. The UltraLite runtime keeps track of changes made since the previous synchronization.

Synchronization can take place through HotSync, ScoutSync, TCP/IP, HTTP, or direct serial port communication. You must connect and configure one of these communications channels.

Initiating synchronization from an UltraLite application

Synchronization is initiated from your application by a single call to the ULSynchronize function when using TCP/IP, HTTP, or serial port synchronization. The interface for HotSync is slightly different.

Once synchronization is initiated from the application or from HotSync, the MobiLink synchronization server and the UltraLite runtime control the actions that occur during synchronization.

  For more information on initiating synchronization, see Adding synchronization to your application.

  For details of how to implement synchronization on each platform, see Platform-Specific Development Instructions.


Adaptive Server Anywhere MobiLink clients
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        MobiLink clients

 Adaptive Server Anywhere MobiLink clients

Adaptive Server Anywhere clients must be configured to work with MobiLink synchronization. Although the logic is included, you must define which columns, rows, or tables are to be included in the synchronization process.

Using appropriate definition statements, you can identify the data that is to be synchronized with a particular synchronization server. You can choose to synchronize all or some of the data with one MobiLink synchronization server, or specify that some data is to be synchronized with one server and other data with another server.

Initiating synchronization from Adaptive Server Anywhere

Synchronization is initiated by running a command-line utility called dbmlsync. This utility connects to the remote database and prepares the upload stream using information contained in the transaction log of the remote database. It then uses information stored in a synchronization definition, contained in the remote database, to connect to the MobiLink synchronization server and exchange data.

  For more information about Adaptive Server Anywhere clients, see Adaptive Server Anywhere Clients.


The synchronization user name
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        MobiLink clients

 The synchronization user name

The ml_user table holds a list of MobiLink client user names. It also records the synchronization state of each user in the commit_state column or the progress column. This information allows proper recovery if synchronization is interrupted.

The user name uniquely identifies each MobiLink client. If a client attempts to synchronize, but the user identification it carries is absent from the user table, the MobiLink synchronization server automatically inserts a new row. For this reason, you do not need to take any action to maintain this table.

In addition to the user name, you can use a password to improve the security of your installation by providing MobiLink user authentication.

  For more information, see Authenticating MobiLink users.


The synchronization process
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 The synchronization process

To synchronize, a remote device must establish a connection with a MobiLink synchronization server, which in turn maintains a pool of connections to a database server and hence the consolidated database. The synchronization process happens in several steps, depicted in the following diagram.

The upload stream and the download stream

To upload rows, MobiLink clients prepare and send an upload stream that contains a list of all the rows that have been updated, inserted, or deleted on the MobiLink client since the last synchronization. Similarly, to download rows, the MobiLink synchronization server prepares and sends a download stream that contains a list of inserts, updates, and deletes. These two streams are part of steps 1 and 2, respectively, in the synchronization process.

 Steps in the synchronization process

 Built-in automation and communications fault recovery


Steps in the synchronization process
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        The synchronization process

 Steps in the synchronization process

The synchronization process proceeds as follows. Each step in the following description is divided into two parts. One part describes the actions of the MobiLink client; the other part describes the actions of the MobiLink synchronization server.

1	The MobiLink client   automatically keeps track of which rows on the remote device have been inserted, updated, or deleted since the previous successful synchronization. The MobiLink client establishes a connection with the MobiLink synchronization server and uploads these changes. These actions are initiated by the MobiLink client.

The upload stream consists of a set of single-row inserts, updates, and deletes.

The MobiLink synchronization server   receives and applies the upload stream instructions to the consolidated database. The changes are made in a single transaction. When finished, the MobiLink synchronization server commits the transaction in the consolidated database.

2	The MobiLink synchronization server   compiles a list of rows to be inserted, updated, or deleted on the MobiLink client, by executing the scripts present in the consolidated database. It sends these rows back to the MobiLink client in the form of a download stream.

The MobiLink synchronization server prepares this download stream using a single transaction in the consolidated database, but it does not commit any changes until the application confirms receipt. You can use this transaction to maintain a record of which information has been sent to each remote database.

The MobiLink client   is assured that all the changes it sent to the server in the upload stream have been committed in the consolidated database when it starts to receive the download stream.

The MobiLink client automatically updates its record of which data is modified so that the same changes are not sent again. It then processes the download stream, deleting old rows, inserting new rows, and updating rows that have changed. It makes all these changes in a single transaction in its own database. When finished, it commits the transaction.

3	The MobiLink client   sends a short message back to the MobiLink synchronization server, confirming that it has received and processed all the changes.

The MobiLink synchronization server   commits the download transaction in the consolidated database upon receipt of this confirmation.

During MobiLink synchronization, there are few distinct exchanges of information. The entire upload stream is built and sent from the remote site and, in response, the entire download stream is built and sent from the MobiLink synchronization server. Limiting the chattiness of the protocol is especially important when communication is slower and has higher latency, as is the case when using telephone lines or public wireless networks.

  For a more detailed description of the synchronization process, see Scripts and the synchronization process.


Built-in automation and communications fault recovery
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        The synchronization process

 Built-in automation and communications fault recovery

Built-in automation frees you from routine implementation tasks. For example, the MobiLink client automatically keeps track of the rows in each table that have been inserted, updated, or deleted since the last synchronization. When you synchronize, the MobiLink client automatically identifies the new, modified, or deleted rows and uploads each to the MobiLink synchronization server.

During the synchronization process, state information is maintained in both the application and the MobiLink synchronization server. Should the synchronization be interrupted, both the MobiLink synchronization server and application retain information regarding their own states. Upon the next attempt to synchronize, they automatically continue synchronization where they left off, without explicit direction.


The consolidated database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 The consolidated database

Applications synchronize with a central, consolidated database. It is often convenient to make the schema of the remote databases similar to the schema of the consolidated database. Indeed, one way to design the application database is to use the schema of the consolidated database as a starting point. In the consolidated database, you may already have tables that correspond to each of the remote tables.

Consolidated and reference databases

While the reference database you use to build your application must be an Adaptive Server Anywhere database, you can build a consolidated database using any supported ODBC-compliant product. You can use a Sybase product, such as Adaptive Server Anywhere or Adaptive Server Enterprise, or you can use a product sold by other companies, such as Oracle, IBM DB2, or Microsoft SQL Server. A single Adaptive Server Anywhere database can fulfill both reference and consolidated roles.

 Consolidated database server requirements

 How remote tables relate to consolidated tables

 MobiLink system tables


Consolidated database server requirements
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        The consolidated database

 Consolidated database server requirements

MobiLink synchronization was designed to work with Sybase database products as well as other ODBC-supporting database-management systems, such as Oracle, IBM DB2, and Microsoft SQL Server. You can use the synchronization scripts to exploit the features of your particular consolidated server.

The MobiLink synchronization server can handle multiple simultaneous synchronization requests. It does so by maintaining a pool of connections with the database server and temporarily assigning these as required when remote devices connect and synchronize.

When running in a production environment, you may want to keep the MobiLink synchronization server connected to the database server indefinitely, even if it is inactive for long periods of time. You should disable any feature that disconnects client applications after a certain period of inactivity. On Adaptive Server Anywhere, you should set the database server -ti command-line option to zero to prevent the server from disconnecting the MobiLink synchronization server if it is inactive for a significant length of time.

  For information on the -ti command-line, see -ti command-line option.


How remote tables relate to consolidated tables
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        The consolidated database

 How remote tables relate to consolidated tables

Synchronization designs can specify an arbitrary mapping between tables and rows in the remote database and tables and rows in the consolidated database. The only restriction is that columns containing the same data in the consolidated database be compatible in type with those in the application. Corresponding columns would usually be of the same type, but automatic or explicit type conversion can be used, if necessary.

Arbitrary relationships permitted

Tables present in a remote database need not exist in the consolidated database. Synchronized data in one remote application table can be distributed between columns in different tables, even between tables in different consolidated databases. You specify these arbitrary relationships using the synchronization scripts.

Direct relationships are simple

Although complicated schemes are possible, you can often simplify your design by using a table structure in the remote database that is a subset of that in consolidated database. Using this method, every table in the remote database exists in the consolidated database. Corresponding tables have the same structure and foreign key relationships.

Tables in the consolidated database will frequently contain extra columns that are not synchronized. Indeed, extra columns can aid synchronization. For example, a timestamp column can identify new or updated rows in the consolidated database. In other cases, extra columns or tables in the consolidated database may hold information that is not required at remote sites.


MobiLink system tables
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        The consolidated database

 MobiLink system tables

You direct the actions of the MobiLink synchronization server by writing scripts. These scripts are stored in tables that must reside in the consolidated database. An additional table contains information about each remote user. These tables have the following structure.

IBM DB2 only supports column names and other identifiers of 18 characters or less. MobiLink system tables are truncated where necessary.

These tables have the same structure in non-Sybase database-management systems, but the columns are of equivalent, native types.


Creating a consolidated database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Creating a consolidated database

To create a database that can be used as a MobiLink consolidated database, you must install the MobiLink system tables. Setup scripts are provided for Sybase Adaptive Server Anywhere, Sybase Adaptive Server Enterprise, Oracle 8, Microsoft SQL Server, or IBM DB2.

Install the system tables

The way you install the MobiLink system tables depends on the DBMS you wish to use as a consolidated database.

•	Adaptive Server Anywhere     Create an Adaptive Server Anywhere database. The MobiLink system tables are created automatically. If you are using this database as a reference database also, do not disable Java support. If you have a database created with an earlier version of Adaptive Server Anywhere, you can run the Upgrade utility to carry out this task.

•	Sybase Adaptive Server Enterprise    Run the syncase.SQL SQL script, located in the MobiLink\setup subdirectory of your SQL Anywhere installation.

•	Microsoft SQL Server    Run the syncmss.SQL SQL script, located in the MobiLink\setup subdirectory of your SQL Anywhere installation.

•	Oracle    Run the syncora.SQL SQL script, located in the MobiLink\setup subdirectory of your SQL Anywhere installation.

•	IBM DB2    Run the syncdb2.SQL SQL script, located in the MobiLink\setup subdirectory of your SQL Anywhere installation.

The syncdb2.SQL script has a default connection statement connect to DB2Database. You should make a copy of the script and alter this line to be appropriate for your installation.

Also, there are columns that require a LONG tablespace. If there is no default LONG tablespace, the creation statements for the tables containing these columns must be qualified appropriately, as in the following example.

CREATE TABLE ... ( ... )

IN tablespace

LONG IN long-tablespace

The stored procedures in syncdb2.SQL are implemented in Java in the associated file SyncDB2.class. The source code is provided in SyncDB2.java. The script uses the tilde character (~) as command delimiter.

The default tablespace (usually called USERSPACE1) of a DB2 database that you wish to use as a consolidated database must use 8 kb pages.

  For an example using the sample application, see Creating a DB2 consolidated database for CustDB.

  For instructions on running scripts, see the documentation for your DBMS.

Create an ODBC data source

To carry out synchronization, the MobiLink synchronization server needs an ODBC connection to your consolidated database. You must have an ODBC driver for your server, and create an ODBC data source for the database on the machine on which your MobiLink synchronization server is running.

  For information on starting the MobiLink synchronization server, see Running the MobiLink synchronization server.

Create synchronization scripts

You need to design and write synchronization scripts, and store them in your consolidated database. You can do this from Sybase Central. Sybase Central requires a JDBC or ODBC connection to your database.

Synchronization scripts are written in the SQL dialect of the consolidated database.

  For information on designing and writing synchronization scripts, see Writing Synchronization Scripts.

  For information on adding scripts to your database with Sybase Central, see Adding scripts to your consolidated database.


Running the MobiLink synchronization server
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Running the MobiLink synchronization server

All MobiLink clients synchronize through the MobiLink synchronization server. None can connect directly to a database server. You must start the MobiLink synchronization server before asking a MobiLink client to synchronize.

  For information about synchronization using HotSync, see Synchronization on the Palm OS Platform.

You can start the MobiLink synchronization server in the following ways:

•	as an executable—see Starting the MobiLink synchronization server

•	as a Windows NT service—see Running MobiLink synchronization server as Windows services

 Starting the MobiLink synchronization server

 Running MobiLink synchronization server as Windows services

 Logging MobiLink synchronization server actions


Starting the MobiLink synchronization server
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Running the MobiLink synchronization server

 Starting the MobiLink synchronization server

The MobiLink synchronization server opens connections, via ODBC, with your consolidated database server. It then accepts connections from remote applications and controls the synchronization process.

♦ To start the MobiLink synchronization server

•	Run the command-line utility dbmlsrv7. Use the -c switch to specify the ODBC connection parameters for your consolidated database.

You must specify the database connection parameters. Other switches are available, but optional.

  For a list of connection parameters, See MobiLink synchronization server.

Example

•	The following command starts the MobiLink synchronization server, identifying the ODBC data source UltraLite Sample 7.0 as the consolidated database. Enter the entire command on one line.

dbmlsrv7

-c "DSN=UltraLite Sample 7.0;UID=DBA;PWD=SQL"

-o mlsync.log

-vcr

-x tcpip

The above command uses the -o switch to specify that the log file should be named mlsync.log. The contents of this file are verbose because of the -v switch and parameters. The -x switch specifies that MobiLink clients will be permitted to connect via TCP/IP. Replace the word tcpip with the word serial if your applications use a serial connection.

♦ To stop the MobiLink synchronization server

•	Execute the command-line utility dbmlstop on the machine on which the MobiLink synchronization server is running.

dbmlstop

The server will shut down, possibly following a short delay.


Running MobiLink synchronization server as Windows services
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Running the MobiLink synchronization server

 Running MobiLink synchronization server as Windows services

You can run the MobiLink synchronization server as a service under Windows NT. In some circumstances, this mode has security and ease-of-administration benefits.

When you start a program as an executable, it runs under your Windows NT login session. When you log off, the program terminates. Only one person logs onto Windows NT, on any one computer, at one time. If you wish to keep a program running much of the time, as is commonly the case with database servers, you must stay logged onto the computer. Staying logged onto the computer can present a security risk, if the computer is left unattended.

By running the MobiLink synchronization server as a service, it can run after you log off the machine. In addition, you can configure the service to start up automatically when Windows NT is started.

♦ To run the MobiLink synchronization server as a service

1	Start Sybase Central. From the Windows NT Start button, choose Programs [image] Sybase [image] Sybase Central.

2	In the left pane, under MobiLink Synchronization, open the Services folder. Double-click Add Service in the right pane.

3	Select MobiLink Synchronization Server from the list. Follow the instructions in the wizard.

  For more information on configuring services, and accommodating service dependencies, see Running the server outside the current session.


Logging MobiLink synchronization server actions
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Running the MobiLink synchronization server

 Logging MobiLink synchronization server actions

You can control the operation of the MobiLink synchronization server using its command-line options. Logging the actions that the server takes is particularly useful during the development process, and when troubleshooting.

Logging output to a file

Logging output is sent to the MobiLink synchronization server window. In addition, you can send the output to a log file using the -o command-line option. The following command sends output to a log file named mlsync.log.

dbmlsrv7 -o mlsync.log -c ...

Controlling the amount of logging output

You can control the amount of output that is logged using the -v command-line option. This option switches on verbose logging, and takes one or more of the following modifiers:

•	-vc    Log the contents of scripts. This implies -vs.

•	-vn    Log row counts.

•	-vr    Log row values and row processing.

•	-vs    Log script names.

•	-vt    Log translated script contents.

These switches can be used in combination. For example, the following command logs the names of scripts, and the row values as they are processed.

dbmlsrv7 -o mlsync.log -vsr -c ...


Details of the synchronization process
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Details of the synchronization process

This section describes in more detail some important aspects of synchronization, including the tasks that are carried out automatically by the MobiLink client, and by the MobiLink synchronization server.

The information in this section is not required in order to implement simple MobiLink synchronization designs, but it is useful as you move to more robust and demanding synchronization schemes.

  For an overview of the three-step synchronization process, see The synchronization process.

 Transactions in the synchronization process

 How synchronization failure is handled

 How the upload stream is processed

 Referential integrity and synchronization


Transactions in the synchronization process
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Details of the synchronization process

 Transactions in the synchronization process

The MobiLink synchronization server incorporates changes uploaded from each remote application into the consolidated database in one transaction. Changes to the consolidated database occur primarily as a result of uploaded information in step 1, the MobiLink synchronization server commits these results once it is through inserting new rows, deleting old rows, making updates, and resolving any conflicts.

The MobiLink synchronization server prepares the download stream, including all deletes, inserts, and updates, using another transaction. It does not commit this transaction until it receives a positive confirmation from the MobiLink client. If the client confirms a successful download, the MobiLink synchronization server commits the download transaction. If the application encounters problems or cannot reply, the MobiLink synchronization server instead rolls back the download transaction.

Do not commit or rollback transactions within a script
COMMIT or ROLLBACK statements within scripts would alter the transactional nature of the synchronization steps, and are not allowed.

Tracking downloaded information

The primary role of the download transaction is to select rows in the consolidated database. However, you can use the download transaction to track the information downloaded to each remote device. For example, the download transaction could update a timestamp that records the time of the last download to a particular MobiLink client. During the next synchronization, only rows updated since the previous download need be sent. If the rows are not downloaded successfully, the download transaction is rolled back and your last download timestamp remains accurate.

The MobiLink synchronization server uses two other transactions, one at the beginning of synchronization, and one at the end. These transactions allow you to record information regarding each synchronization and its duration. Thus, you can record statistics about attempted synchronizations, successful synchronizations, and the duration of synchronizations. Since data is committed at various points in the process, these transactions also let you commit data useful when analyzing failed synchronization attempts.

Similarly, the MobiLink client processes information in the download stream in one transaction. Rows are inserted, updated, and deleted to bring the remote database up to date with the consolidated data.


How synchronization failure is handled
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Details of the synchronization process

 How synchronization failure is handled

MobiLink synchronization is fault tolerant. For example, if a communication link fails during synchronization, both the remote database and the consolidated database are left in a consistent state. In an UltraLite application, the SQLCode is set to SQLE_COMMUNICATION_ERROR when ULSynchronize returns.

There are three cases that are handled in different ways

•	Failure during upload    If the failure occurs while building or applying the upload stream, the remote database is left in exactly the same state as at the start of synchronization. At the server, any part of the upload stream that has been applied will be rolled back.

•	Failure between upload and download    If the failure occurs once the upload stream is complete, but before the MobiLink client receives the download stream, the remote database is left in an uncertain state. At the server, the upload stream might be fully applied and committed, or the failure may have occurred before the server applied the entire upload stream. The MobiLink synchronization server automatically rolls back incomplete transactions.

The next time the MobiLink client synchronizes, it determines the fate of the previous upload stream before building the new upload stream. If the previous upload was not committed, the new upload stream contains all changes from the previous upload stream.

•	Failure during download    If the failure occurs in the remote device while applying the download stream, any part of the download that has been applied is rolled back and the remote database is left in the same state as before the download. The MobiLink synchronization server automatically rolls back the download transaction in the consolidated database.


How the upload stream is processed
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Details of the synchronization process

 How the upload stream is processed

When the MobiLink synchronization server receives an upload stream from a MobiLink client, the entire upload stream is stored until the synchronization is complete. This is done for three purposes.

•	Deadlock    When an upload stream is being applied to the consolidated database, it may encounter deadlock due to concurrency with other transactions. These transactions might be upload transactions from other MobiLink synchronization server database connections, or transactions from other applications using the consolidated database. When an upload transaction is deadlocked, it is rolled back and the MobiLink synchronization server automatically starts applying the upload stream from the beginning again.

Performance tip
It is important to write your synchronization scripts to avoid contention as much as possible. Contention will have a significant impact on performance when multiple users are synchronizing simultaneously.

•	Filtering download rows    The most common technique for determining rows to download is to download rows that have been modified since the previous download. When synchronizing, the upload precedes the download. Any rows inserted or updated during the upload will be rows that have been modified since the previous download.

It would be difficult to write a download_cursor script that omits from the download stream rows that were sent as part of the upload. For this reason, the MobiLink synchronization server automatically removes these rows from the download stream. When a row is being added to the download stream, the MobiLink synchronization server locates the row in the upload stream and omits the row from the download stream when it is found to be the same.

•	Processing deletes after inserts and updates    The upload stream is applied to the consolidated database in an order that avoids referential integrity violations. The upload stream is formatted so all operations (inserts, updates, and deletes) for a single table are grouped together. The tables in the upload stream are ordered based on foreign key relationships. All tables in the remote database that are referenced by another table in the remote database will be in the upload stream before the referencing table.

For example, if table A and table C both have foreign keys that reference a primary key column in B, then table B rows are uploaded first.

When the upload stream is applied to the consolidated database, the inserts and updates are applied in the order they appear in the upload stream. When an inserted or updated row references a newly inserted row, this ensures the referenced row will be inserted before the referencing row. Deletes are applied in the opposite order after all inserts and updates have been applied. When a row being deleted references another row that is also being deleted, this order of operations ensures the referencing row is deleted before the referenced row is deleted.


Referential integrity and synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Details of the synchronization process

 Referential integrity and synchronization

All MobiLink clients enforce referential integrity when they incorporate the download stream into the remote database.

Rather than failing the download transaction, the MobiLink client automatically deletes all rows that violate referential integrity.

This feature affords you these key benefits.

•	Protection from mistakes in your synchronization scripts. Given the flexibility of the scripts, it is possible to accidentally download rows that would break the integrity of the remote database. The MobiLink client automatically maintains referential integrity without requiring intervention.

•	You can use this referential integrity mechanism to delete information from a remote database efficiently.

Referential integrity checked at the end of the transaction

The MobiLink client incorporates changes from the download stream in a single transaction. To offer more flexibility, referential integrity checking occurs at the end of this transaction. Because checking is delayed, the database may temporarily pass through states where referential integrity is violated as rows are inserted, updated, and deleted, but the rows that violate referential integrity are automatically removed before the download is committed.

Errors are avoided

The MobiLink client resolves referential integrity violations automatically. This feature minimizes administration requirements. It also prevents an error in a synchronization script from disabling an MobiLink client.

An efficient means to delete rows

You can exploit the automatic referential integrity mechanism of MobiLink clients to delete large quantities of information in a very efficient manner. If your MobiLink client contains a primary row, and other rows that reference it, you can delete all the referencing rows simply by synchronizing a delete of the primary row.

Example

Suppose that an UltraLite sales application contains, among others, the following two tables. One table contains sales orders. Another table contains items that were sold in each order. They have the following relationship.

If you use the download_deletes_cursor for the sales_order table to delete an order, the automatic referential integrity mechanism automatically deletes all rows in the sales_order_items table that point to the deleted sales order.

This arrangement has the following advantages.

•	You do not require a sales_order_items script, because rows from this table will be deleted automatically.

•	The efficiency of synchronization is improved. You need not download rows to delete from the sales_order_item table. If each sales order contains many items, the performance improves because the download stream is now smaller. This technique is particularly valuable when using slow communication methods.


Character-set considerations
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Character-set considerations

Each character of text is represented in one or more bytes. The mapping from characters to binary codes is called the character set encoding. Some character sets used for languages with small alphabets, such as Eurpoean languages, use a single-byte representation. Others, such as Unicode, use double-byte numbers. Because they use twice the storage space for each character, double-byte character sets can represent a much larger number of characters.

When the character set of your MobiLink client database is the same as your consolidated database, character translation issues are avoided. The characters you type can be transferred reliably.

Errors can occur or data can be lost when text using one character set must be translated to another character set. Not all characters can be represented in all character sets. In particular, single-byte character sets can represent a much smaller number of characters than multi-byte systems because of the limited number of codes available.

Most text needs to be sorted to build indexes and to prepare ordered result sets, such as directory listings. The sort order identifies the order of the characters. For example, a sort order typically states that the letter a comes before the letter b, which comes before the letter c.

Each database has a collation sequence. You set the collation sequence when you create the database, although how you do so can differ between database systems. The collation sequence defines both the character set and the sort order for that database.

Tip
Whenever possible, define the collation sequence of your reference database to be the same as that of your consolidated database. Doing so ensures that the collation sequence of your MobiLink client database will match that of your consolidated database as closely as possible. This arrangement reduces the chance of erroneous translations.

  For more information, see Collation sequences.

 Character-set translation during synchronization: Windows

 Character-set translation during synchronization: non-Windows

 Controlling ODBC driver character-set translation


Character-set translation during synchronization: Windows
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Character-set considerations

 Character-set translation during synchronization: Windows

During synchronization, characters may need to be translated from one character set to another. The following translations occur as characters are passed between the remote application and the consolidated database.

Character-set translation during upload

The MobiLink client sends data to the MobiLink synchronization server using the character set of the remote database.

1	The MobiLink synchronization server communicates with the consolidated database using the Unicode ODBC API. To do so, the MobiLink synchronization server translates all characters received from the remote database into Unicode.

2	If necessary, the ODBC driver for the consolidated database server translates the characters from Unicode into the character set of your consolidated database. This translation is controlled solely by the ODBC driver for your consolidated database system. Hence, behavior can differ between two different database systems, particularly systems made by different manufacturers. MobiLink synchronization works with a number of database systems. Check the documentation of your particular consolidated server for details.

Character-set translation during download

1	The ODBC driver for the consolidated database system receives characters in the coding of the consolidated database. It translates these characters into Unicode to pass them through the Unicode API to the MobiLink synchronization server. This translation is controlled solely by the ODBC driver for your consolidated database system. Check the documentation of your particular consolidated server for details.

2	The MobiLink synchronization server receives characters through the Unicode ODBC API. If the remote database uses a different character set, the MobiLink synchronization server translates the characters before downloading them.

Examples

•	UltraLite applications on Windows CE devices use the Unicode character set.

When you synchronize a Window CE application, no character translation occurs within the MobiLink synchronization server. The server finds that data arriving from the application is already in Unicode and passes it directly to the ODBC driver. Similarly, no character-set translation is necessary when downloading data.

•	All Adaptive Server Anywhere databases and all UltraLite applications on platforms other than Windows CE use the character set determined by the collating sequence of the database.

When you synchronize a remote database, the MobiLink synchronization server performs character set translations between the character set of the remote database and Unicode.


Character-set translation during synchronization: non-Windows
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Character-set considerations

 Character-set translation during synchronization: non-Windows

ODBC drivers on non-Windows platforms do not have Unicode entry points. The MobiLink synchronization server exchanges data with the ODBC driver using the character set determined by the collating sequence of the remote database.

When the remote database is an UltraLite applications running under Windows CE, the MobiLink synchronization server performs character-set translation between Unicode and the character set being used with ODBC.


Controlling ODBC driver character-set translation
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Character-set considerations

 Controlling ODBC driver character-set translation

Because most consolidated databases are unlikely to use Unicode, it is important to understand how the ODBC driver for your consolidated database system converts data to and from Unicode. Some ODBC drivers use the language settings of the machine running MobiLink to determine what character set to use. In these cases, it is best if the language and code-page settings of the machine running the MobiLink synchronization server match those of the consolidated database.

Other ODBC drivers, such as the driver for Sybase Adaptive Server Enterprise, allow each connection to use a specific character set. To avoid translation errors, the character set used by MobiLink should be set to match that of the consolidated database.

For a detailed description of how character-set translations take place in your database server's ODBC driver, consult that product's ODBC driver documentation.


Authenticating MobiLink users
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Authenticating MobiLink users

There are several aspects to securing data throughout a widely distributed system such as a MobiLink installation:

•	Protecting data in the consolidated database    Data in the consolidated database is protected by the DBMS user authentication system and other security features.

  For more information, see your DBMS documentation. If you are using an Adaptive Server Anywhere consolidated database, see Keeping Your Data Secure.

•	Protecting data in the remote databases    If you are using Adaptive Server Anywhere MobiLink clients, the data is protected using the Adaptive Server Anywhere security features. These are designed to prevent unauthorized access through client/server communications, but not to be proof against a serious attempt to extract information directly from the database file.

Files on the client are protected by the security features of the client operating system.

•	Protecting data during synchronization    Communication from MobiLink clients to MobiLink synchronization servers is protected by the MobiLink transport layer security features. For more information, see Transport-layer security.

•	Protecting the synchronization system from unauthorized users    MobiLink synchronization is secured by a password-based user authentication system, discussed in the current section. This prevents unauthorized users from downloading data or uploading changes.

The MobiLink user-authentication mechanism is discussed in this section.

 Choosing a MobiLink user-authentication mechanism

 MobiLink user-authentication architecture

 Providing initial passwords for users

 Synchronizations from new users

 Supplying MobiLink passwords at the client

 Changing MobiLink passwords

 Using a custom user-authentication mechanism


Choosing a MobiLink user-authentication mechanism
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Authenticating MobiLink users

 Choosing a MobiLink user-authentication mechanism

User authentication is one part of a security system for protecting your data.

MobiLink provides you with a choice of user-authentication mechanisms. You do not have to use a single installation-wide mechanism; MobiLink lets you use different authentication mechanisms for different users within the installation for flexibility.

•	No MobiLink user authentication    If your data is such that you do not need password protection, you can choose not to use any user authentication in your installation.

•	Built-in MobiLink user authentication    MobiLink uses the user names and passwords stored in the ml_user system table to perform authentication.

The built-in mechanism is described in the following sections.

•	Custom authentication    You can use the MobiLink script authenticate_user to replace the built-in MobiLink user authentication system with one of your own. For example, depending on your consolidated database-management system, you may be able to use the database user authentication instead of the MobiLink system.

  For more information on custom user-authentication mechanisms, see Using a custom user-authentication mechanism.


MobiLink user-authentication architecture
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Authenticating MobiLink users

 MobiLink user-authentication architecture

The MobiLink user authentication system relies on user names and passwords. In the built-in authentication system, both the user name and the password are stored in the ml_user MobiLink system table in the consolidated database. The password is stored in hashed form so that applications other than the MobiLink synchronization server cannot access the original form of the password.

  In addition to security, the user name is used to partition data among users. For more information on this aspect of user names, see The synchronization user name.

When an Adaptive Server Anywhere or UltraLite MobiLink client synchronizes, it supplies a user name and password. UltraLite client applications generally obtain information from the end user to include in the synchronization call.

At the beginning of the synchronization process, the MobiLink synchronization server compares the password to that stored in the ml_user table. If the passwords match, synchronization proceeds. If they do not match, synchronization is canceled and an error code is returned to the client.

New users and NULL passwords
If the ml_user.hashed_password column is NULL, then no comparison is made for that user and there is no user authentication check before synchronization.

If a MobiLink client supplies a user name that is not present in the ml_user table, the behavior is determined by a MobiLink command-line switch. The default behavior, for compatibility with earlier releases, adds the new user to the MobiLink system with a NULL password. This behavior provides good compatibility with earlier releases, but lax security.

  For more information, see Synchronizations from new users.

Custom authentication

If you want to substitute your own authentication mechanism for the MobiLink mechanism, you can do so by providing an authenticate_user script. If this script exists, it is executed instead of the password comparison. The script returns error codes for success or failure of the authentication.

The following sections describe how to implement the different pieces of the authentication system, and describe some specific issues you may encounter.


Providing initial passwords for users
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Authenticating MobiLink users

 Providing initial passwords for users

The password for each user is stored along with the user name in the ml_user table. You can provide initial passwords from Sybase Central, or by using the dbmluser command-line utility.

Sybase Central is a convenient way of adding individual users and passwords. The dbmluser utility is useful for batch additions.

If you create a user with no password, then MobiLink performs no user-authentication for that user: they can connect and synchronize without supplying a password.

♦ To provide an initial MobiLink password for a user (Sybase Central):

1	Connect to the consolidated database from Sybase Central, using the MobiLink plugin.

2	Open the User folder.

3	Double-click Add User. The Add a New User wizard appears.

4	Supply a user name and an optional password.

5	Click Finish to complete the task.

♦ To provide initial MobiLink passwords (command line):

1	Create a file with a single user name and password on each line, separated by white space.

2	Open a command prompt, and execute the dbmluser command-line utility. For example:

dbmluser -c "dsn=my_dsn" -pf password-file

In this command line, the -c command-line switch specifies an ODBC connection to the consolidated database. The -pf switch specifies the file containing the user names and passwords.

  For information on dblmuser, see MobiLink user-authentication utility.


Synchronizations from new users
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Authenticating MobiLink users

 Synchronizations from new users

If a MobiLink client synchronizes with a user name that is not in the current ml_user table, MobiLink takes the following actions:

•	New user with no password    If the user supplied no password, then by default the user name is added to the ml_user table with a NULL password. This behavior provides compatibility with earlier releases of MobiLink, which did not include user authentication, but is less secure.

  For more information, see MobiLink synchronization server.

•	New user with password    If the user supplies a password, then the user name and password are both added to the ml_user table and the new user name becomes a recognised name in your MobiLink system. The password appears in hashed form and is not readable.

•	New user with new password    A new user may provide information in the new password field, instead of or as well as in the password field. In either case, the new password setting overrides the password setting, and the new user is added to the MobiLink system using the new password.

Preventing synchronization by new users

You can change the default behavior by starting the MobiLink synchronization server using the -zu command-line switch. In this case, the MobiLink synchronization server rejects any attempt to synchronize from a user name that is not present in the ml_user table.


Supplying MobiLink passwords at the client
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Authenticating MobiLink users

 Supplying MobiLink passwords at the client

The end user must supply a MobiLink user name and password each time they synchronize from a MobiLink client, unless your MobiLink installation does not use any MobiLink user authentication.

♦ To prompt your end users to enter MobiLink passwords:

•	The mechanism for supplying the user name and password is different for UltraLite and Adaptive Server Anywhere clients.

•	UltraLite    When synchronizing, the UltraLite client must supply a valid value in the password field of the synchronization structure (C/C++) or object (Java). For built-in MobiLink synchronization, a valid password is one that matches the value in the ml_user MobiLink system table.

Your application should prompt the end user to enter the user name and password when synchronizing  or at logon time.

  For more information, see Setting synchronization parameters.

•	Adaptive Server Anywhere    Supply a valid password on the dbmlsync command line, or in the dbmlsync connection dialog if you do not supply command-line parameters.

If the connection failes because of an authentication failure, you are prompted to re-enter the user name and password.

  For more information, see Adaptive Server Anywhere client synchronization utility.


Changing MobiLink passwords
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Authenticating MobiLink users

 Changing MobiLink passwords

MobiLink provides a mechanism for end-users to change their password. The interface differs between UltraLite and Adaptive Server Anywhere clients.

♦ To prompt your end users to enter MobiLink passwords:

•	The mechanism for supplying the user name and password is different for UltraLite and Adaptive Server Anywhere clients.

•	UltraLite    When synchronizing, the application must supply the existing password in the password field of the synchronization structure and the new password in the new_password field.

  For more information, see Setting synchronization parameters.

•	Adaptive Server Anywhere    Supply a valid existing password together with the new password on the dbmlsync command line, or in the dbmlsync connection dialog if you do not supply command-line parameters.

  For more information, see Adaptive Server Anywhere client synchronization utility.

The new password is not verified until the next synchronization attempt. For the dbmlsync utility, or if you prompt at synchronization time in an UltraLite application, this attempt is almost immediate.

  An initial password can be set at the database server or on the first synchronization attempt. For more information, see Providing initial passwords for users, and Synchronizations from new users.

Once a password is assigned, you cannot reset the password to NULL from the client side.


Using a custom user-authentication mechanism
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Authenticating MobiLink users

 Using a custom user-authentication mechanism

You can choose to use a user-authentication mechanism other than the built-in MobiLink mechanism.

To implement your own user-authentication mechanism, you must write an authenticate_user script. The script then overrides the default MobiLink user-authentication mechanism. It does not supplement the default MobiLink mechanism.

Reasons for using a custom user-authentication mechanism include integration with existing DBMS user authentication schemes, or supplying custom features, such as minimum password length or password expiry, not present in the built-in MobiLink mechanism.

The authenticate_user script is executed immediately before, and in the same transaction as, the begin_synchronization script. The transaction is ended immediately after the begin_synchronization script.

The parameters used in an authenticate_user script are as follows:

error_code

user_name

password

new_password

  For more information, see authenticate_user script.

A typical authenticate_user script would be a call to a stored procedure that uses the parameters. The order of the parameters in the call must match the order above. For example, in an Adaptive Server Anywhere consolidated database, the format would be as follows:

call my_authentication( ?, ?, ?, ? )

where the first argument is the error code, and so on. The error code is an integer type, and the other parameters are VARCHAR(128).

A Transact-SQL format would be as follows:

execute ? = my_authentication( ?, ?, ? )

where the error code is the parameter on the left hand side.


Transport-layer security
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Transport-layer security

When communication between a remote site and a MobiLink synchronization server must take place over a public network or via wireless communication, the data contained in the upload and download streams is susceptible to unauthorized access. For example, someone with a suitable radio or network connection could read or intercept your data.

MobiLink provides the facility to encrypt data as it flows between the MobiLink synchronization server and the MobiLink clients. When transport-layer security is invoked, all messages sent between the client and server are encrypted using a 128-bit cipher.

In addition, this facility allows your clients to positively identify the server with which they are syncronizing. Postive server identification prevents your clients from accidentally sharing sensitive information with an unauthorized MobiLink synchronization server.

MobiLink transport-layer security is implemented using Certicom encryption technology. This public-key cryptographic technology uses an elliptic-curve cipher suite.

Configuring security features

To invoke the server authentication features, you must create and use digital certificates. Different types of certificates and different arrangements of these certificates allow you to provide various levels of security. You create these certificates using tools included with SQL Anywhere Studio.

What is public-key cryptography?

Public key cryptography makes use of mathematical systems that work with pairs of very large, associated numbers. These numbers, called keys, have particular properties. One of the keys, called the public key, can be published in a public forum (like a phone book) and can be used to encrypt information to be sent to the owner of the public key. The owner keeps the second key, called the private key, secret.

A message encrypted with the public key can be decrypted only using the private key. Since the public key is published, anyone can create a message that only the private key owner can read. In addition, a message encrypted with the private key can be decrypted by anyone who knows the public key. In this way, the owner of the private key can "prove" they know the private key to someone using the associated public key.

It is essential that the private key cannot be found easily through knowledge of the public key. The ease at which the private key can be derived from the public key is often associated with the strength of the cryptosystem and the size (in bits) of the public key. Another aspect of the private key is that it must be difficult to guess. The generation of high-quality private keys must incorporate randomness designed to be truly unpredictable. The tools provided with MobiLink gather pseudo-random data from the operating system when generating new private keys. Were this data predictable, it would be easier for an adversary to guess the value of your keys.

The role of public-key cryptography

Public-key cryptography has many advantages. Using the public key, anyone can send a message that can be read only by the person who knows the matching private key. They can verify a sender's identity, since only a person who knows the private key can create a message that can be read using the matching public key. These features make public-key cryptography especially useful when establishing a secure communication link.

Once the secure link is established, server and client automatically switch to a symmetric-key system of equivalent strength. In a symmetric system, the same key is used to encrypt and decrypt messages. This type of symmetric cipher can be computed more efficiently, meaning that computation time is required to encrypt and decrypt messages.

 Invoking transport-layer security

 Server authentication

 Invoking server authentication

 Client architecture

 Adaptive Server Anywhere clients

 UltraLite clients


Invoking transport-layer security
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security

 Invoking transport-layer security

You can use transport-layer security when using the TCP/IP or HTTP communication protocol. To invoke security, use the security parameter when specifying your communication protocol. Set the security to the cipher suite of your choice.

At present, the only cipher suite presently available is Certicom TLS. This suite uses a 128-bit elliptic curve cipher suite.

Transport-layer security is licensed separately from SQL Anywhere Studio. Please contact Sybase for further information.

Example

•	Starting the MobiLink synchronization server as follows allows connections through TCP/IP. All communication through this connection will be encrypted using the Certicom cipher suite

dbmlsrv7 -x tcpip{port=3333;security=certicom_tls} ...

How transport-layer security works

Transport-layer security works by filtering all in-going and all out-going communication through the cipher of your choice. The translation occurs between the MobiLink synchronization server and the communication protocol of your choice. For example, adding security to a TCP/IP connection affects the architecture as shown in the following diagram.

The only cipher currently supported is Certicom elliptic-curve encryption. To specify this cipher, include the communication parameter security=certicom_tls when you start the MobiLink synchronization server.

Transport-level security requires additional communication between a MobiLink client and the MobiLink synchronization server before the upload stream is sent. When a client initiates synchronization, it passes a message to the server. The client encrypts this message using the server's public key. The server decrypts this message using its private key. Initially, the server encrypts all messages to the client using the client's public key.

While this public-key/private-key cipher is secure, as long as the private keys are kept secret, the encryption and decryption process is computationally intensive. To make further communication more efficient, the client and server agree upon and exchange another key and switch to a symmetric key cipher. They use this key and cipher for the rest of their communication because the symmetric cipher allows data to be encrypted and decrypted more efficiently.


Server authentication
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security

 Server authentication

One method of breaking a system of this type is to masquerade as the server. The client connects to what it thinks is the server, but the connection is unknowingly made to another, hostile server. To guard against this form of attack, the server can use a digital certificate. A digital certificate plays the role of an identy card.

Each digital certificate contains a public encryption key and information about the owner's identiy. The certificates are designed in such a way that they can be altered only by someone who knows the matching private key. As long as this private key is kept a secret, clients can safely assume the identity information accurately identifies a server. To ensure they are talking to the correct server, clients ask the server to prove that it knows the matching private key. The server can do so by decrypting a message that has been encrypted with the public key shown in the certificate.

The Certicom security software built into MobiLink uses certificates for the purpose of server identification. A sample certificate is provided with Adaptive Server Anywhere. The sample certificate is called mobilink.crt. The password for the sample certificate is tJ1#m6+W.

Caution
The sample certificate should be used for testing purposes only. The sample certificate provides no security in deployed situations because it and the corresponding password are widely distributed with Sybase software. To protect your system, you must create your own certificate.


Invoking server authentication
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security

 Invoking server authentication

You invoke server authentication by specifying the following parameters to the security cipher on the dbmlsrv7 command line.. The following parameters are required when using a certificate other than the sample certificate.

•	certificate    The file name of the certificate. The MobiLink synchronization server searches for this file in the same way that it locates executable files. It searches the directories in your path, the directory in which the MobiLink synchronization server executable resides, and your current directory. The default value is mobilink.crt.

•	certificate_password    The password for the certificate named above. The default value is tJ1#m6+W.

Example

Starting the MobiLink synchronization server as follows allows connections through TCP/IP. All communication through this connection will be encrypted using the Certicom cipher suite and clients can verify server identity using the sample certificate. This command should be entered on a single line.

dbmlsrv7 -x tcpip{port=2439;

security=certicom_tls{certificate=mobilink.crt;

certificate_password=tJ1#m6+W}} ...

Obtaining certificates of authentication

The sample certificate is for testing purposes only. It provides no security because the certificate and password are distributed with Sybase software. You must obtain a customized certificate from Certicom to create or deploy your own secure system.

Confirming proper startup

The MobiLink synchronization server screen displays informational messages on startup. These messages are also sent to the log file if you start the server with the -o option. You can use the -v option to provide more detailed messages.

If Certicom security starts properly, the informational messages confirm this fact. Absence of such messages indicate that Certicom security has not started properly.


Client architecture
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security

 Client architecture

To synchronize with a MobiLink synchronization server through secure means, the client must use the same cipher suite as the server. All messages received from the server via a communication protocol, such as TCP/IP, are decrypted before being passed to the remote MobiLink client. The following diagram depicts how Certicom TLS cipher suite is added to a client using TCP/IP to communicate with a MobiLink synchronization server.


Adaptive Server Anywhere clients
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security

 Adaptive Server Anywhere clients

To invoke transport-layer security when using an Adaptive Server Anywhere client, you set the security parameter in the ADDRESS field of a synchronization definition. Similarly, you can specify the parameter in the ADDRESS field of a synchronization template or site, then extract the database. The corresponding synchronization definition in the extracted site inherits the security parameter and value.

Example

•	The address clause of the following synchronization definition specifies that the connection to myhost should be made using the Certicom TLS cipher suite.

CREATE SYNCHRONIZATION DEFINITION mysharedtables

SITE 'demo_sync_site'

TYPE 'tcpip'

ADDRESS 'host=myhost;security=certicom_tls'

OPTION memory=2m,dir=c:\db\logs

(table People( person_id, fname, lname ),

table Pets WHERE pet_id=2);


UltraLite clients
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security

 UltraLite clients

To invoke transport-layer security when using an UltraLite client, you must select a Certicom TLS stream and set specific parameters before initiating synchronization. For example, when coding in C, you call the ULSecureCerticomTLSStream function to initialize the secure stream, set the desired parameters, and then use the ULSynchronize function to trigger synchronization with a MobiLink synchronization server.

When you build your application, the UltraLite analyzer recognizes the new parameters and automatically builds all the necessary encryption components into your UltraLite application.

  For detailed information about synchronizing UltraLite applications, see Adding synchronization to your application.


Transport-layer security and digital certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

 Transport-layer security and digital certificates

MobiLink transport-layer security protects the confidentiality and integrity of the synchronization data stream as it passes between MobiLink clients and a MobiLink synchronization server. Furthermore, it allows a client application to verify the identity of a MobiLink synchronization server, hence ensuring that it synchronizes with only trusted MobiLink synchronization servers.

This security is implemented by means of digital certificates. You can achieve a variety of security objectives by using different types of certificates and can configuring them in different ways. This section introduces concepts that underlie public-key cryptography and explains how they apply to digital certificates. Examples illustrate several typical arrangements, each offering different benefits.

 Digital certificates

 How certificates are used in MobiLink synchronization

 Using chains of certificates

 Self-signed certificates

 Certificate authorities

 Certificate chains

 Enterprise root certificates

 Globally signed certificates

 Verifying certificate fields

 Summary


Digital certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Digital certificates

A digital certificate is an electronic document that identifies a person or entity and contains a copy of their public key. Each certificate includes a public key so that anyone can communicate securely with the person or entity by encrypting information with this public key. Digital certificates conform to a standardized file format that contains the following information:

1	Identity information, such as the name and address of the certificate owner

2	Public key

3	Expiry date

4	One ore more digital signatures

Digital signatures

A digital signature provides a means to detect whether a certificate has been altered. A digital signature is a cryptographic operation created by calculating a value, called a message digest, from the identity information and the public key.

A message digest is a bit-value designed to change if any part of the certificate changes. The algorithm used to calculate the message digest is known to all users of the certificates. The correct value is encrypted with the private key contained in the certificate. Thus, anyone can detect alteration using the algorithm to calculate the message digest, using the public key to decrypt the message digest contained in the certificate, and comparing the two values.

A certificate constructed in this manner is called a self-signed certificate because the digital signature is constructed with the matching private key. Such a certificate cannot be altered without knowledge of the private key.

The importance of digital certificates

Digital certificates play the role of identity cards. The signatures prevent alteration because as long as the private keys used to create the signatures are kept secret, the digital certificate cannot be altered.


How certificates are used in MobiLink synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 How certificates are used in MobiLink synchronization

A MobiLink synchronization server must be able to identify itself to clients with its own server certificate. The client must ensure that the certificate is authentic. To do so, the client must already have a trusted copy of the public certificate. Alternatively, the server's certificate may be signed by another certificate. In the latter case, the client must have a reliable copy of the signing certificate.

The MobiLink synchronization server must have access to its public certificate and to the private key for this certificate. This information is contained in a server identity. A server certificate is constructed by appending the private key to the matching public certificate.

The following figure shows a sample server certificate. This certificate is a server identity, suitable for use by a MobiLink synchronization server. This particular certificate has been signed by another certificate. The file contains both public certificates and the server's password.

Since other users may have access to the machine running the MobiLink synchronization server, the file containing the private key is protected by a password. This password is intended to maintain the honesty of the people given access to the machine. It does not provide an adequate barrier to an outside attack, as the password is only a few characters in length. To further protect the private key, outsiders must be denied access to the MobiLink synchronization server by a firewall, or by other traditional means.

Instead of being signed directly by the certificate authority, the server's certificate may be the first certificate in a certificate chain. In this case, the client must trust the owners of all certificates and must have a trusted copy of the final certificate in the chain, called the root certificate. Such a certificate file would have a structure similar to that shown above, but could contain a longer list of certificates.


Using chains of certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Using chains of certificates

A certificate may be signed by other certificates, or it may be self-signed, which means it is signed only with its own private key. A sequence of public certificates, each signed by the next, is called a certificate chain. At one end of a typical chain is a certificate used for a particular MobiLink synchronization server. At the other end is a certificate, signed by no other certificates, called the root certificate.

You can arrange certificates in various ways, depending on your requirements. The following sections describe how to construct and use certificate chains to achieve particular security goals. The following topics are covered:

•	If you have only a single server, the simplest setup is to create a self-signed certificate. The only true disadvantage is that the private key for the certificate must be held on the synchronization server, where it is harder to protect.

•	An enterprise root certificate is of particular benefit to organizations using more than one MobiLink synchronization server. In this setup, MobiLink clients need keep only a copy of this root certificate to recognize any MobiLink synchronization server issuing a certificate signed by this root certificate.

•	Commercial certificate authorities can benefit organizations that require the utmost in security. These organizations can help in two ways. First, the root certificates they use are of the highest possible quality, making these certificates somewhat less prone to attack. Secondly, commercial certificate authorities can provide a trusted third party when two companies wish to communicate securely but are not familiar with each other.

•	You can, and in some cases should, use the facilities provided to verify certificate fields. This precaution is appropriate in many scenarios, but is particularly so when using a globally signed certificate. In this case, you are unlikely to want your clients to trust certificates that your certificate authority has signed for other customers.

In all cases, you must ensure that the MobiLink command line and log file are secure. This is best done by using a firewall and by otherwise limiting access to the machine running the MobiLink synchronization server.

MobiLink transport-layer security is a flexible mechanism that lets you achieve the security important to your setup. The basic system allows you to keep information private, but certificates ensure MobiLink clients that they are talking to a trusted MobiLink synchronization server.


Self-signed certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Self-signed certificates

SQL Anywhere Studio includes tools for working with certificates. These are included in the distribution if your license permits it. If so, you can choose to install these security components.

A utility named gencert allows you to generate new certificates. Since certificates are normally written in a machine-readable format, another utility, named readcert, displays the contents of a certificate in human-readable format.

You can make a number of types of certificates with the gencert utility. The easiest type to make is a self-signed (root) certificate, as no other signing certificate is required.

The main advantage of a setup with only one root certificate is simplicity; you need create only one certificate. This setup is often sufficient for simple setups involving only one MobiLink synchronization server. If you operate multiple MobiLink synchronization servers, an enterprise level certificate, discussed later, is often more convenient.

The biggest disadvantage is that a self-signed certificate is easier than other types to forge. This type of attack can be accomplished by creating a counterfeit certificate using a different key pair. Other types of certificates are more secure because they bear more than one digital signature.

 Making a new self-signed certificate

 Using a self-signed certificate


Making a new self-signed certificate
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Self-signed certificates

 Making a new self-signed certificate

To indicate that you want to make a root certificate, start the gencert utility from a command prompt using the -r switch. The utility prompts you to enter the identity information, the certificate password and expiry date, and the names of the new certificate files.

> gencert -r

Sybase Elliptic Curve Certificate Generation Tool

Generating key pair using curve ec163a02 (please wait)...

Country: CA

State/Province: Ontario

Locality: Waterloo

Organization: Sybase, Inc.

Organizational Unit: MEC

Common Name: MobiLink

Serial Number: 2000.02.29.01

Certificate valid for how many years: 2

Enter password to protect private key: password

Enter file path to save certificate: self.crt

Enter file path to save private key: self.pri

Enter file path to save server identity: serv1.crt

The response to each question should be a string, except for the number of years to the expiry date, which must be an integer.

The utility creates three files, using the names you supply. In this case, the following three files are created.

•	self.crt    This file contains the new certificate, including the identity information, public key, expiry date, and signature. You can give out copies of this file to people whom you wish to contact you.

•	self.pri    This file contains the private key that matches the public key encoded in the certificate. The private key is encoded using the password you supplied, providing a modest barrier to others with access to your machine. However, since password encryption is not very secure, you must restrict access to this file to maintain secrecy.

•	serv1.crt    This file contains the same information as the above two files, combined into one file. It is intended for use with a MobiLink synchronization server. The server sends the public information to identify itself to clients. It requires the private key to decode messages returned by the clients. You must restrict access to this file. It, too, contains a copy of the private key, protected only by the password.

The server certificate contains the information in the public and private certificate files. You can make a server certificate by concatenating a public certificate and the file containing the private key.


Using a self-signed certificate
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Self-signed certificates

 Using a self-signed certificate

You can use the self-signed certificate for server authentication by following these steps.

1	Supply a copy of the certificate to all clients. When they first contact the MobiLink synchronization server, the server will send them a copy of the public certificate, self.crt. The client can detect fake certificates by comparing the one sent by the server with the copy they already have.

2	Tell each client that it is to trust only servers that can decrypt messages encoded using the public key contained within the copy of the supplied public certificate. For Adaptive Server Anywhere clients, you do so using the trusted_certificates security parameter. For example, you can tell an Adaptive Server Anywhere client to trust only the self.crt certificate by including the following parameter in the ADDRESS clause of the SYNCHRONIZATION DEFINITION.

CREATE SYNCHRONIZATION DEFINITION test

SITE 'user001'

ADDRESS 'security=certicom_tls{trusted_certificates=self.crt}'

To tell an UltraLite client to trust only the desired certificate, name the trusted certificate using the -r switch when running the UltraLite generator, as follows. Enter the entire command on one line.

> ulgen -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL"

-r self.crt -j custapi

Sybase Adaptive Server Anywhere UltraLite Code Generator Version 7.0.0

Running UltraLite analyzer

Loading schema information

Loading SQL statements

Analyzing access plans

Generating source code for SQL statements

Generating source code for UltraLite schema

Saving source code into database

Writing source code to output file

1	When you start the MobiLink synchronization server, specify the name of the server certificate file, serv1.crt, and the corresponding password. Enter the entire command on one line.

dbmlsrv7 -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL"

-x tcpip{security=certicom_tls{certificate=serv1.crt;

certificate_password=password}}

Note that the clients do not need and should not have either the private key or the password that unlocks it. Clients need only the public certificate.

In contrast, the MobiLink synchronization server requires access to the private key, as well as to the public parts of the certificate. Thus, the server requires access to the server certificate file, which contains both public and private information.

The MobiLink synchronization server must have access to the private key and the password that protects it. For this reason, you must ensure that the MobiLink command line and log file are secure. This is best done by using a firewall and by otherwise limiting access to the machine running the MobiLink synchronization server.


Certificate authorities
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Certificate authorities

One problem with self-signed certificates is that an adversary can create a fake certificate using a different public- and private-key pair. Someone, mistaking the fake certificate for the original, may unknowingly encrypt his or her message using the substitute public key, rather than that owned by the intended recipient. Only the adversary, who knows the substitute private key, could read a message encrypted using the fake certificate.

To guard against such an attack, both the user and the owner of the certificate must agree to trust a third party. This third party, called a signing authority or certificate authority, adds a digital signature to the certificate using his or her private key. Once signed, the document certificate can be altered only with the aid of the third party. To sign a certificate, the certificate authority need not know the private key of the certificate owner.

The certificate authority need not be an external person or organization. If the certificates are to be used only within the company, it may be appropriate for someone at the company to act as the certificate authority.

To create a trustworthy system, a certificate authority must confirm the identity of a certificate owner before signing a certificate. In particular, they must check that the identity fields in the certificate accurately describe the certificate owner and that the certificate owner owns the matching private key.

Someone wishing to use this certificate to communicate with the certificate owner must have confidence in the following.

1	Before signing the certificate, the certificate authority made certain that the identity information contained in the certificate correctly identified the certificate owner.

2	Each private key is known only to the certificate owner.

3	The user has a reliable copy of the certificate authority's public key.

To satisfy these conditions, not only must the user have confidence in the integrity of the certificate authority, but the user also must have obtained the same public key directly from the certificate authority.

To obtain valid copies of a public key, users of this system typically obtain copies of a self-signed certificate owned by the certificate authority. To foil impostors, the certificate must be obtained by reliable means.

In addition, each client must store the copy of the certificate authority's certificate securely. Should an adversary have access to the user's computer, he or she could replace the certificate authority's certificate with a fake.


Certificate chains
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Certificate chains

When deploying a replication system, a large number of certificates may be required. The responsibility of signing many certificates may place too great a burden on the certificate authority. To lessen their workload, a certificate authority can delegate signing authority to others. To do so, the certificate authority signs a certificate held by the delegate. The delegate then proceeds to sign certificates using the private key that matches the one in this certificate.

A certificate chain is a sequence of certificates such that each certificate is signed by the next. The final certificate, called the root certificate, is owned by a certificate authority. For example, a server certificate can be signed by a delegate. The delegate's certificate can be signed by a certificate authority. The certificate authority's public key is contained in a third certificate. Such a situation comprises a chain of three certificates.

In fact, a delegate can also have delegates. Thus a chain of certificates can be of any length. However, the final certificate is always a self-signed root certificate, owned by a certificate authority.

To trust a chain, a user must trust each of the following.

1	Before signing each certificate, the certificate authority and all delegates made certain that the identity information contained in the certificate correctly identified the certificate owner.

2	Each private key is known only to the certificate owner.

3	The user has a reliable copy of the certificate authority's public key.

All conditions are extremely important. The chain of certificates is only as strong as its weakest link.


Enterprise root certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Enterprise root certificates

A deployment of MobiLink that involves multiple servers can be improved by assigning each server a unique certificate also signed by a common root certificate. A certificate authority within the enterprise holds the root certificate.

This arrangement has the following advantages.

•	Each MobiLink synchronization server can be given a unique certificate, so that if one site is compromised, the others are not affected.

•	Security is enhanced because the private key for the enterprise root certificate need not be stored on the MobiLink synchronization server.

•	Clients do not need to keep a copy of each server's public certificate, only a copy of the public root certificate, because you can configure them to trust any certificate signed by the root certificate.

The security of the system can be improved somewhat by obtaining a globally signed certificate, discussed later, from a commercial certificate authority. In practice, however, this arrangement provides adequate security for many applications.

You can program your clients to verify the values of some certificate fields, as discussed later. In this way, you can ensure that they synchronize with particular MobiLink synchronization servers within your organization.

This setup provides more flexibility than self-signed server certificates. For example, you can add a new server and give it a new certificate. If the new certificate is signed with the same enterprise root certificate, existing clients will automatically trust it. Were you, instead, to give each MobiLink synchronization server a self-signed certificate, all clients would require a copy of the new public certificate.

 Creating the certificates

 Using the signed certificates


Creating the certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Enterprise root certificates

 Creating the certificates

The first step in setting up an enterprise-level system is to generate the common self-signed certificate. To generate this root certificate, start gencert with the -r switch.

> gencert -r

Sybase Elliptic Curve Certificate Generation Tool

Generating key pair using curve ec163a02 (please wait)...

Country: CA

State/Province: Ontario

Locality: Waterloo

Organization: Sybase, Inc.

Organizational Unit: MEC

Common Name: MobiLink

Serial Number: 2000.02.29.02

Certificate valid for how many years: 2

Enter password to protect private key: password2

Enter file path to save certificate: ent_root.crt

Enter file path to save private key: ent_root.pri

Enter file path to save server identity: ent_serv.crt

Three files are generated as before.

•	ent_root.crt    This file contains the new certificate. This certificate should be published as all clients require a reliable copy.

•	ent_root.pri    This file contains the private key that matches the public key encoded in the certificate.

•	ent_serv.crt    This file contains the same information as the above two files, combined. It is intended for use with a MobiLink synchronization server.

The first two of these three files can be used to sign additional, new certificates. To generate a signed certificate, start gencert with the -s switch. Enter the name of the signing certificate file, the name of the signing private-key file, and the password for the signing private key.

> gencert -s

Sybase Elliptic Curve Certificate Generation Tool

Generating key pair using curve ec163a02 (please wait)...

Country: CA

State/Province: Ontario

Locality: Waterloo

Organization: Sybase, Inc.

Organizational Unit: MEC

Common Name: MobiLink

Serial Number: 2000.02.29.03

Certificate valid for how many years: 1

Enter file path of signer's certificate: ent_root.crt

Enter file path of signer's private key: ent_root.pri

Enter password for signer's private key: password2

Enter password to protect private key: password3

Enter file path to save server identity: serv1.crt

This time, gencert creates only one file. This file contains the signed certificate and the private key. It is intended for use with a MobiLink synchronization server.

Repeat this last step as many times as necessary to create a signed certificate for each MobiLink synchronization server.

> gencert -s

Sybase Elliptic Curve Certificate Generation Tool

Generating key pair using curve ec163a02 (please wait)...

Country: CA

State/Province: Ontario

Locality: Waterloo

Organization: Sybase, Inc.

Organizational Unit: MEC

Common Name: MobiLink

Serial Number: 2000.02.29.04

Certificate valid for how many years: 1

Enter file path of signer's certificate: ent_root.crt

Enter file path of signer's private key: ent_root.pri

Enter password for signer's private key: password2

Enter password to protect private key: password4

Enter file path to save server identity: serv2.crt

You now have the following files.

•	Root certificate, ent_root.crt

•	Root private key, ent_root.pri

•	Root combined certificate, ent_serv.crt

•	Combined certificate for the first MobiLink synchronization server, serv1.crt

•	Combined certificate for the second MobiLink synchronization server, serv2.crt

You do not need the combined root certificate because no MobiLink synchronization server uses it directly. Instead, you created a separate certificate for each MobiLink synchronization server.


Using the signed certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Enterprise root certificates

 Using the signed certificates

You can use the signed certificates for server-authentication by following these steps.

1	Supply a copy of the public root certificate to all clients. When they first contact the MobiLink synchronization server, the server will send them a copy of its own public certificate. This certificate will bear the signature of the root certificate. The client can detect fake certificates by verifying that the root signature matches the public key in their copy of the root certificate.

2	Tell each client that it is to trust only servers whose certificates bear the signature of the root certificate. For Adaptive Server Anywhere clients, use the trusted_certificates security parameter. For example, you can tell an Adaptive Server Anywhere client to trust only the ent_cert.crt certificate by including this parameter in the ADDRESS clause of the SYNCHRONIZATION DEFINITION, as follows.

CREATE SYNCHRONIZATION DEFINITION test

SITE 'user001'

ADDRESS 'security=certicom_tls{

trusted_certificates=ent_cert.crt}'

To tell an UltraLite client to trust only the desired certificate, name the trusted certificate using the -r switch when running the UltraLite generator, as follows. Enter the entire command on one line.

> ulgen -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL"

-r ent_cert.crt -j custapi

Sybase Adaptive Server Anywhere UltraLite Code Generator Version 7.0.0

Running UltraLite analyzer

Loading schema information

Loading SQL statements

Analyzing access plans

Generating source code for SQL statements

Generating source code for UltraLite schema

Saving source code into database

Writing source code to output file

1	When you start each MobiLink synchronization server, specify the name of that server's certificate file and the corresponding password. Enter each command on one line.

dbmlsrv7 -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL"

-x tcpip{port=3333;

security=certicom_tls{certificate=serv1.crt;

certificate_password=password3}}

dbmlsrv7 -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL"

-x tcpip{port=4444;

security=certicom_tls{certificate=serv2.crt;

certificate_password=password4}}


Globally signed certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Globally signed certificates

You can improve a deployment of MobiLink that involves multiple servers by assigning each server a unique certificate that is signed by a common root certificate. You can improve it further by using a certificate signed by a commercial certificate authority. Such a certificate is called a global certificate or a globally-signed certificate. A commercial certificate authority is an organization that is in the business of creating high-quality certificates and using these certificates to sign other certificates.

A global certificate has the following advantages:

•	Security requires that both parties trust the root certificate. In the case of inter-company communication, common trust in an outside, recognized authority may increase confidence in the security of the system because a certificate authority must guarantee the accuracy of the identification information in any certificate that it signs.

•	Security is enhanced when keys are created using pseudo-random data of high quality. The data used with the gencert utility is of cryptographic quality, but other, even better methods can be used in controlled environments.

•	The private key for the root certificate must remain private. An enterprise may not have a suitable place to store this crucial information, whereas a certificate authority can afford to design and maintain dedicated facilities.

When using a globally signed certificate, each client must verify certificate field values to avoid trusting certificates that the same certificate authority has signed for other clients. This process is described in the next section.

MobiLink transport-layer security is based on Certicom SSL/TLS Plus libraries, which require elliptic-curve certificates. You can obtain a global certificate from Certicom, or any other certificate authority that can supply certificates in the correct format.

 Obtaining MobileTrust server-authentification certificates

 Running the reqtool utility

 Using a global certificate as a server certificate


Obtaining MobileTrust server-authentification certificates
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Globally signed certificates

 Obtaining MobileTrust server-authentification certificates

Certicom is a certificate authority that can provide certificates in the correct format. The procedure for obtaining a global certificate and a signed enterprise-level certificate from Certicom is as follows.

1	Use the reqtool utility, included with MobiLink transport-layer security components to create a server certificate and a global certificate request.

2	Copy the contents of the public certificate onto the clipboard.

3	Read the agreement and policies statement on the Certicom MobileTrust web site, located at http://www.certicom.com/mobiletrust/ecommerceserver/. Choose a payment option.

4	Paste the contents of the public certificate into the web form located on the MobileTrust site. Only submit the public component of the certificate request. You must not disclose your private key.

5	A Certicom MobileTrust Registration Agent will process your application. Once processing is complete you will be contacted, usually by telephone, and supplied with a password you can use to obtain your global certificate from the MobileTrust web site.

For more information about this procedure, see the document reqtool.pdf, located in the bin or win32 directory in the MobiLink distribution.


Running the reqtool utility
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Globally signed certificates

 Running the reqtool utility

The reqtool utility, included in SQL Anywhere Studio, creates server certificates and a global signature request document suitable for submission to Certicom. This utility is used as follows. The only key type compatible with MobiLink is elliptic-curve cryptography, or ECC.

> reqtool

-- Certicom Corp. Certificate Request Tool 3.0d1 --

Choose certificate request type:

  E - Personal email certificate request.

  S - Server certificate request.

  Q - Quit.

Please enter your request [Q] : S

Choose key type:

  R - RSA key pair.

  D - DSA key pair.

  E - ECC key pair.

  Q - Quit.

Please enter your request [Q] : E

Using curve ec163a02. Generating key pair (please wait)...

Country: CA

State: Ontario

Locality: Waterloo

Organization: Sybase, Inc.

Organizational Unit: MEC

Common Name: MobiLink

Enter password to protect private key : password5

Enter file path to save request : global.req

Enter file path to save private key : global.pri

The file global.req contains the public certificate and request information. Paste the contents of this file into the web form on the Certicom MobileTrust web site.

The file global.pri contains the private key for the enterprise certificate. This file is protected by the password you entered, but since the protection provided by the password is weak, you must store this file in a secure location.

A Certicom MobileTrust Registration Agent will process your application. Once processing is complete you will be contacted, usually by telephone, and supplied with a password that you can use to obtain your global certificate from the MobileTrust web site. Download the certificate soon afterwards. The certificate may be received in two different formats: a binary format and a text format. Both files contain the same information. In this case, you should store the text version of the certificate in a file called global.crt.


Using a global certificate as a server certificate
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Globally signed certificates

 Using a global certificate as a server certificate

You can use your global certificate directly as a MobiLink synchronization server certificate. To do so, you must create a server identity certificate by concatenating the public and private certificates. Enter the following statement at a command prompt.

copy global.crt+global.pri global2.crt

You can now start a MobiLink synchronization server, specifying the new certificate and the password for your private certificate. Enter the entire statement on one line.

dbmlsrv7

-c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL" -x

tcpip{security=certicom_tls{certificate=global2.crt; certificate_password=password5}}

You must also ensure that clients contacting your MobiLink synchronization server trust the certificate. To do so, you must tell the clients to trust the root certificate in the chain. In this case, the root certificate in the chain is a certificate held by the certificate authority.

By default, MobiLink clients trust certificates signed by the Certicom root certificate, or by the Sybase root certificate used to sign the sample certificate included with MobiLink. Hence, if Certicom signs your global certificate, MobiLink clients will automatically accept it as valid.

For better security, however, you should ensure that clients consider only the root certificate of your certificate authority to be valid.

You can tell an Adaptive Server Anywhere MobiLink client to accept only the Certicom root certificate by naming only this certificate in the Address clause of the SQL CREATE SYNCHRONIZATION DEFINITION statement:

CREATE SYNCHRONIZATION DEFINITION test

SITE 'user001'

ADDRESS 'security=certicom_tls{trusted_certificates=certicom.crt}'

To tell an UltraLite client to trust only the Certicom root certificate, name the trusted certificate using the -r switch when running the UltraLite generator, as follows. Enter the entire command on one line.

> ulgen -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL"

-r certicom.crt -j custapi

Sybase Adaptive Server Anywhere UltraLite Code Generator Version 7.0.0

Running UltraLite analyzer

Loading schema information

Loading SQL statements

Analyzing access plans

Generating source code for SQL statements

Generating source code for UltraLite schema

Saving source code into database

Writing source code to output file

For convenience, the file certicom.crt is included in the MobiLink distribution, although you can obtain your own copy directly from Certicom, if you prefer.


Verifying certificate fields
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Verifying certificate fields

Global certificates have one potentially serious flaw. Because the MobiLink clients, as configured above, trust all certificates signed by the certificate authority, they may also trust certificates that the same certificate authority has issued to other companies. Without a means to discriminate, your clients might mistake a competitor's MobiLink synchronization server for your own and accidentally send it sensitive information.

Similar precautions can be required in other scenarios, too. A company may use an enterprise certificate, but it may still be important to verify with which department a MobiLink client is connected.

This problem can be resolved by requiring your clients to test the value of fields in the identity portion of the certificate. Three fields in the certificate can be verified. You can verify any or all of these fields.

1	Organization

2	Organizational Unit

3	Common Name

To verify the fields, you supply the acceptable value. For example, the following code tells an Adaptive Server Anywhere client to check all three fields and to accept only the named values. Enter this SQL statement on one line.

CREATE SYNCHRONIZATION DEFINITION test

SITE 'user'

ADDRESS 'port=3333;security=certicom_tls{ 	trusted_certificates=certicom.crt;

certificate_company=Sybase, Inc.;

certificate_unit=MEC;certificate_name=MobiLink}'

You can verify the fields from an UltraLite client in a similar manner. The precise syntax depends upon the interface used to build the application. The following fragment of C code accomplishes the same task when developing the UltraLite application using embedded SQL in C or C++.

ul_synch_info info;

. . .

info.security_parms =

UL_TEXT( "certificate_company=Sybase, Inc." )

UL_TEXT( ";" )

UL_TEXT( "certificate_unit=MEC" )

UL_TEXT( ";" )

UL_TEXT( "certificate_name=MobiLink" );

. . .

ULSynchronize( &info );

This example verifies all three fields. You can instead choose to verify only one or two fields.

 Verifying fields in certificate chains

 Using a globally-signed certificate as an enterprise certificate


Verifying fields in certificate chains
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Verifying certificate fields

 Verifying fields in certificate chains

When the first certificate is part of a chain, all the specified field values are checked in that certificate. If specified, the company name is also checked in all the other certificates, except for the root certificate. This arrangement allows for the case that the root certificate is held by a certificate authority. In this case, the field values of the root certificate will be different, as it is owned by the certificate authority, rather than your company or organization.


Using a globally-signed certificate as an enterprise certificate
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

          Verifying certificate fields

 Using a globally-signed certificate as an enterprise certificate

Instead of using a global certificate as a server certificate, it is possible to instead use it to sign other certificates, as you would an enterprise certificate. This setup lets you combine the benefits of a global certificate and an enterprise certificate. The most important advantage is that you need not store the private key for your global certificate on the computer running the MobiLink synchronization server.

To create such a setup, generate a unique certificate for each MobiLink synchronization server. When you do so, sign them with your global certificate.

The following example shows how two server certificates can be generated and signed by the global certificate.

> gencert -s

Sybase Elliptic Curve Certificate Generation Tool

Generating key pair using curve ec163a02 (please wait)...

Country: CA

State/Province: Ontario

Locality: Waterloo

Organization: Sybase, Inc.

Organizational Unit: MEC

Common Name: MobiLink

Serial Number: 2000.02.29.06

Certificate valid for how many years: 1

Enter file path of signer's certificate: global.crt

Enter file path of signer's private key: global.pri

Enter password for signer's private key: password5

Enter password to protect private key: password6

Enter file path to save server identity: serv6.crt

> gencert -s

Sybase Elliptic Curve Certificate Generation Tool

Generating key pair using curve ec163a02 (please wait)...

Country: CA

State/Province: Ontario

Locality: Waterloo

Organization: Sybase, Inc.

Organizational Unit: MEC

Common Name: MobiLink

Serial Number: 2000.02.29.07

Certificate valid for how many years: 1

Enter file path of signer's certificate: global.crt

Enter file path of signer's private key: global.pri

Enter password for signer's private key: password5

Enter password to protect private key: password7

Enter file path to save server identity: serv7.crt

The above commands generate two server identity certificates, intended for use with two MobiLink synchronization servers.

•	The server identity certificate for MobiLink synchronization server #1 is serv6.crt

•	The server identity certificate for MobiLink synchronization server #2 is serv7.crt

Both certificates are signed by global.crt, which in turn is signed by the Certicom root certificate.

You can start these two MobiLink synchronization servers with the following commands, entered one command per line.

dbmlsrv7 -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL" -x tcpip{port=3333;security=certicom_tls{certificate=serv6.crt; certificate_password=password6}}

dbmlsrv7 -c "dsn=UltraLite 7.0 Sample;uid=DBA;pwd=SQL" -x tcpip{port=4444;security=certicom_tls{certificate=serv7.crt; certificate_password=password7}}

In addition, you must ensure that each client trusts the Certicom root certificate. If you used a certificate authority other than Certicom, then you should ensure that your clients trust only that authority's certificate, instead.

The steps for ensuring that MobiLink clients trust only the Certicom root certificate are shown above.


Summary
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 3.  Synchronization Basics

        Transport-layer security and digital certificates

 Summary

If you have only a single server, the simplest setup is to create a self-signed certificate. The only true disadvantage is that the private key for the certificate must be held on the synchronization server, where it is harder to protect.

An enterprise root certificate is of particular benefit to organizations using more than one MobiLink synchronization server. In this setup, MobiLink clients need keep only a copy of this root certificate to recognize any MobiLink synchronization server issuing a certificate signed by this root certificate.

Commercial certificate authorities can benefit organizations that require the utmost in security. These organizations can help in two ways. First, the root certificates they use are of the highest possible quality, making these certificates somewhat less prone to attack. Secondly, commercial certificate authorities can provide a trusted third party when two companies wish to communicate securely but are not familiar with each other.

You can, and in some cases should, use the facilities provided to verify certificate fields. This precaution is appropriate in many scenarios, but is particularly so when using a globally signed certificate. In this case, you are unlikely to want your clients to trust certificates that your certificate authority has signed for other customers.

In all cases, you must ensure that the MobiLink command line and log file are secure. This is best done by using a firewall and by otherwise limiting access to the machine running the MobiLink synchronization server.

MobiLink transport-layer security is a flexible mechanism that lets you achieve the security important to your setup. The basic system allows you to keep information private, but certificates ensure MobiLink clients that they are talking to a trusted MobiLink synchronization server.


CHAPTER 4.  Writing Synchronization Scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

 CHAPTER 4.  Writing Synchronization Scripts

About this chapter

You control the synchronization process by writing synchronization scripts and storing them in the consolidated database. This chapter describes the role these scripts play and how to write them.

 Introduction to synchronization scripts

 Scripts and the synchronization process

 Script versions

 Adding scripts to your consolidated database

 Writing scripts to download rows

 Writing scripts to upload rows

 Writing scripts to handle errors

 DBMS-dependent scripts


Introduction to synchronization scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 Introduction to synchronization scripts

Synchronization scripts consist of SQL statements stored in your consolidated database. During synchronization, the MobiLink synchronization server reads the scripts and executes them against the consolidated database. Scripts provide you opportunities to perform tasks at various points of time during the synchronization process. You can use Sybase Central to add scripts to the consolidated database.

The synchronization process is composed of multiple steps. A unique event name identifies each step. You control the synchronization process by writing scripts associated with some of these events. You write a script only when some particular action must occur at a particular event. The MobiLink synchronization server executes each script when its associated event occurs. If you do not define a script for a particular event, the MobiLink synchronization server simply proceeds to the next step.

For example, one event is named begin_upload_rows. You can write a script and associate it with this event. The MobiLink synchronization server reads this script when it is first needed, and executes it during the upload phase of synchronization. If you write no script, the MobiLink synchronization server proceeds immediately to the next step, which is processing the uploaded rows.

Some scripts, called table scripts, are associated not only with an event, but also with a particular table in the remote database. The MobiLink synchronization server performs some tasks on a table-by-table basis; for example, downloading rows. You can have many scripts associated with the same event, but each with different application tables. Alternatively, you can define many scripts for some application tables, but none for others.

  For an overview of the synchronization steps, see Steps in the synchronization process.

 A simple synchronization script

 Adding scripts to your consolidated database

 Using this chapter


A simple synchronization script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Introduction to synchronization scripts

 A simple synchronization script

MobiLink provides many events that you can exploit, but it is not mandatory to provide scripts for each event. In a simple synchronization model, you may need only a few scripts.

The ULProduct table in the CustDB sample application is synchronized by downloading all the rows from the table to each remote database. In this case, no additions are permitted at the remote databases. You can implement this simple form of synchronization with a single script; in this case only one event has a script associated with it.

The MobiLink event controlling the rows to be downloaded during each synchronization is named download_cursor. Cursor scripts must contain SELECT statements. The MobiLink synchronization server uses these queries to define a cursor. In the case of a download_cursor script, the cursor selects the rows to be downloaded to one particular table in the remote database.

In the CustDB sample application, there is a single download_cursor script for the ULProduct table in the sample application, which consists of the following query.

SELECT prod_id, price, prod_name

FROM ULProduct

This query generates a result set. The rows that make up this result set are downloaded to the client. In this case, all the rows of the table are downloaded.

The MobiLink synchronization server knows to send the rows to the ULProduct application table because this script is associated with both the download_cursor event and ULProduct table by the way it is stored in the consolidated database. Sybase Central allows you to make these associations.

Note
In this example, the query selects data from a consolidated table also named ULProduct. The names need not match. You could, instead, download data to the ULProduct application table from any table, or any combination of tables, in the consolidated database by rewriting the query.

You can write more complicated synchronization scripts. For example, you could write a script that downloads only recently modified rows, or one that provides different information to each remote database. These issues are the subject of this and the following chapter.


Adding scripts to your consolidated database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Introduction to synchronization scripts

 Adding scripts to your consolidated database

You can write and modify synchronization scripts using Sybase Central.

♦ To add a script to a database

1	Start Sybase Central and connect to a database. In this case, use the CustDB sample database.

•	Select Manage MobiLink Synchronization from the Adaptive Server Anywhere program group.

  For a description of how to carry out this step, see Lesson 8: Browse the consolidated database.

2	Under the UltraLite Sample database icon, open the Synchronized Tables folder. Then double-click the ULProduct table.

ULProduct has a single synchronization script, associated with the download_cursor event. This is the script described in the previous section.

3	You could add a new script to the ULProduct table by double-clicking Add Table Script. A wizard is displayed.

If you were adding a script to the database, you would select an event from the list, and enter the script text into the Sybase Central editor. Do not do this at this time.


Using this chapter
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Introduction to synchronization scripts

 Using this chapter

The first section of this chapter provides a introduction to the kinds of MobiLink scripts available and how these scripts fit into the synchronization process.

•	For a description of the types of scripts that you can write, see Script types.

•	For a description of how scripts are associated with a sequence of events that occur during the synchronization process, see Scripts and the synchronization process.

Later sections describe the following topics:

•	How to add scripts to your consolidated database (Adding scripts to your consolidated database).

•	Details of how the scripts that handle the data transfer work (Writing scripts to upload rows, Writing scripts to download rows).

•	How to write a script to handle errors (Writing scripts to handle errors).


Scripts and the synchronization process
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 Scripts and the synchronization process

Each script corresponds to a particular event in the synchronization process. You write a script only when some action must occur at a particular event. All unnecessary scripts can be left undefined.

The two principal parts of the process are the processing of uploaded information and the preparation of rows for downloading. This section describes the events that are available during synchronization and the order in which they occur.

The MobiLink synchronization server reads and prepares each script once, when it is first needed. The script is then executed whenever the event is invoked.

Reading the pseudo-code

Each event is listed in order. For example, begin_connection is the first event that is invoked.

In the pseudo-code below, events are followed by the parameters that any script associated with that event can accept. For example, the begin_synchronization connection script receives a single parameter, which is the user name that the application supplied in the synchronization call. You can, optionally, use the values of these parameters within your scripts.

The sequence of events

The following pseudo code outlines the sequence in which events are invoked.

begin_connection

COMMIT

for each synchronization

authenticate_user( authentication_code, user_name,

user_pswd, user_new_pswd )

begin_synchronization(user_name)

for each remote table

begin_synchronization(user_name, table)

next table

COMMIT

process upload stream (see separate diagram)

COMMIT

prepare_for_download(user_name)

prepare download stream (see separate diagram)

COMMIT

for each remote table

end_synchronization(user_name, table)

next table

end_synchronization(user_name)

COMMIT

next synchronization

end_connection

COMMIT

  For the details of upload stream processing, see Script events during upload.

  For the details of download stream processing, see Events during download.

Notes

•	MobiLink technology allows multiple clients to synchronize concurrently. In this case, each client uses a separate connection to the consolidated database.

•	The begin_connection and end_connection events are independent of any one synchronization, as one connection can handle many synchronization requests. These scripts have no parameters. These are examples of connection-level scripts.

•	Some events are invoked only once for each synchronization and have a single parameter. This parameter is the user name, which uniquely identifies the MobiLink client that is synchronizing. These are also examples of connection-level scripts.

•	Some events are invoked once for each table being synchronized. Scripts associated with these events are called table-level scripts. They provide two parameters. The first is the user name supplied in the call to the synchronization function, and the second is the name of the table in the remote database being synchronized.

While each table can have its own table scripts, you can also write table-level scripts that are shared by several tables.

•	Some events, such as begin_synchronization, occur at both the connection level and the table level. You can supply both connection and table scripts for these events.

•	The COMMIT statements illustrate how the synchronization process is broken up into distinct transactions.

•	Errors are a separate event that can occur at any point within the synchronization process. Errors are handled using the following script.

handle_error(error_code, error_message, user_name, table_name )

  For reference material, including detailed information about each script and its parameters, see Reference.

 Script types

 Cursor scripts

 Connection scripts

 Table scripts

 Script parameters

 Table names need not match


Script types
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Scripts and the synchronization process

 Script types

Synchronization scripts fall into the following categories.

•	cursor scripts   These scripts perform the actions associated with upload and download of data. Each script is associated with one particular remote table. These scripts are the first scripts to consider when learning about synchronization.

•	connection scripts    These scripts perform actions that are connection-specific or synchronization-specific and that are independent of any one remote table. These scripts are used in conjunction with other scripts when implementing more complex synchronization schemes.

•	table scripts    These scripts perform actions specific to one synchronization and one particular remote table. These scripts are used in conjunction with other scripts when implementing more complex synchronization schemes.


Cursor scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Scripts and the synchronization process

 Cursor scripts

Each cursor script must contain a SELECT statement. The MobiLink synchronization server defines a cursor based on this statement.

The following cursor script events are available. The first three are the ones used most frequently.

•	upload_cursor    This script defines a cursor through which the MobiLink synchronization server applies the upload stream to the consolidated database, during the first step of synchronization.

  For information, see Writing scripts to upload rows.

•	download_cursor    This script prepares inserts and updates for download to remote databases during the second step of synchronization. You must define a download_cursor cursor script for each remote table to which you want to download rows.

  For information, see Writing scripts to download rows.

•	download_delete_cursor    This script prepares deletes for download to remote databases during the second step of synchronization. You use this script to select rows that are to be deleted from the remote database.

  For information, see Deleting rows with the download_delete_cursor script.

The following cursor script events are also available. These scripts are used for conflict resolution.

•	old_row_cursor    Defines a cursor that the MobiLink synchronization server uses to insert the old values of uploaded rows.

•	new_row_cursor    Defines a cursor that the MobiLink synchronization server uses to insert the new values of uploaded rows.

  For information, see Handling conflicts.


Connection scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Scripts and the synchronization process

 Connection scripts

Connection scripts control actions centered on connecting, and disconnecting. They also permit actions at synchronization-level events such as beginning and ending the upload or download process.

You only need to write a connection-level script when some action must occur at a particular event. You may need to create scripts for only a few events. The default action at any event is for the MobiLink synchronization server to carry out no actions. Some simple synchronization schemes need no connection scripts.


Table scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Scripts and the synchronization process

 Table scripts

Table scripts allow actions at specific events relating to the synchronization of a specific table, such as the start or end of uploading rows, resolving conflicts, or selecting rows to download.


Script parameters
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Scripts and the synchronization process

 Script parameters

Most synchronization scripts receive parameters from the MobiLink synchronization server. You can use these parameters in your scripts by placing question marks in the script.

The following parameters are typically available within scripts.

•	synchronization user name   The value of this parameter is the string that uniquely identifies a MobiLink client. Each client must identify itself by this name when initiating synchronization with a MobiLink synchronization server. This parameter is available within most connection-level scripts, all table-level scripts, and some cursor scripts.

The user name can be used to partition tables among remote databases.

•	table name   This parameter identifies a table in the remote database. The consolidated database may or may not contain a table with the same name. Only table scripts use this parameter.

To use parameters, place a single question mark in your script for each parameter. Some parameters are optional. The MobiLink synchronization server replaces each question mark with the value of a parameter. It substitutes values in the order the parameters appear in the script definition.

Upload scripts are exceptions

The upload_cursor script, which is used to process the upload stream, is an exception to the rule. The parameters to this script are the values of the columns of the primary key in the remote database. These parameters are ordered in the same order as the corresponding columns are defined in the reference database. The MobiLink synchronization server requires these parameters to update, delete, or select rows in the consolidated database. You must use all parameters in a WHERE clause so as to uniquely identify a row in the consolidated database.

The old_row_cursor and new_row_cursor scripts use no parameters because they are used only to insert rows.

  For the specific parameters available to each script, see Scripts.


Table names need not match
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Scripts and the synchronization process

 Table names need not match

The names of tables in the remote databases need not match the names of the tables in the consolidated database. The MobiLink synchronization server determines which scripts are associated with a table by looking up the remote table name in the ml_table table.

The synchronization scripts for a given table can refer to any table, or combination of tables, in the consolidated database. You can use this feature to fill a particular remote table with data stored in one or more consolidated tables, or to store data uploaded from a single remote table into multiple tables in the consolidated database.


Script versions
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 Script versions

Scripts are organized into groups called script versions. By specifying a particular version, MobiLink clients can select which set of synchronization scripts will be used to process the upload stream and prepare the download stream.

Application of script versions

Script versions allow you to organize your scripts into sets, which are run under different circumstances. This ability provides flexibility and is especially useful in the following circumstances.

•	customization    Using a different set of scripts to process information from different types of remote users. For example, you could write a different set of scripts for use when managers synchronize their databases than would be used for other people in the organization. Although you could achieve the same functionality with one set of scripts, these scripts would be more complicated.

•	upgrading applications    When you wish to upgrade a database application, new scripts may be needed because the new version of your application may handle data differently. New scripts are almost always necessary when the remote database changes. It is usually impossible to upgrade all users simultaneously. MobiLink clients can request that a new set of scripts be used during synchronization. Since both old and new scripts can coexist on the server, all users can synchronize, no matter which version of your application they are using.

•	multiple applications    A single MobiLink synchronization server may need to synchronize two entirely different applications. For example, some employees may use a sales application, whereas others require an application designed for inventory control. When two applications require different sets of data, you can create two versions of the synchronization scripts, one version for each application.

Assigning version names

A script version name is a string. You specify this name when you add a script to the consolidated database. For example, if you add your scripts with the ml_add_connection_script and the ml_add_table_script stored procedures, the script version name is the first parameter. Alternatively, if you add your scripts using Sybase Central, you are prompted for the version name.

The default script version

Whenever a remote site fails to supply a script version, the MobiLink synchronization server uses the first version defined in the ml_script_version table.


Adding scripts to your consolidated database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 Adding scripts to your consolidated database

When you set up a non-Adaptive Server Anywhere consolidated database for use with MobiLink, you run a script that creates a set of MobiLink system tables. The tables are created automatically when you create an Adaptive Server Anywhere database.

The MobiLink system tables hold information about which tables are involved in synchronization, about the user names involved in synchronization, and about the synchronization scripts.

  For information about the MobiLink system tables, see MobiLink system tables.

 Sybase Central is the synchronization management tool

 Using stored procedures to add synchronization scripts

 Direct inserts of scripts

 Example scripts for UltraLite

 Testing script syntax


Sybase Central is the synchronization management tool
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Adding scripts to your consolidated database

 Sybase Central is the synchronization management tool

Sybase Central provides an environment for managing synchronization. You can add new scripts, edit existing ones, and even test your scripts against your consolidated database.

  For a description of how to add scripts to a consolidated database using Sybase Central, see Adding scripts to your consolidated database.

This section describes other ways of adding scripts that you may wish to use if you work in a more automated environment.

  For a description of the MobiLink system tables, see Creating a consolidated database.


Using stored procedures to add synchronization scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Adding scripts to your consolidated database

 Using stored procedures to add synchronization scripts

You can add scripts to a database using stored procedures that are installed along with the MobiLink system tables when you create a consolidated database. The CustDB sample application uses these stored procedures.

Adaptive Server Enterprise limitation
You cannot use stored procedures to add scripts longer than 255 bytes to Adaptive Server Enterprise. Instead, use Sybase Central or direct insertion to define longer scripts.

Adding connection scripts

You use the ml_add_connection_script procedure to add a connection script. For example, the following statement adds a connection script associated with the begin_synchronization event. The script itself is the single statement that sets the @EmployeeID variable.

call ml_add_connection_script( 'custdb',

'begin_synchronization',

'set @EmployeeID = ?' )

This example is taken from the file custdb.sql. It applies to Adaptive Server Anywhere databases. Other consolidated databases may require a different syntax.

Adding table and cursor scripts

You use the ml_add_table_script procedure to add table and cursor scripts. For example, the following command adds a cursor script associated with the upload_cursor event on the ULCustomer table.

call ml_add_table_script( 'custdb',

'ULCustomer',

'upload_cursor',

'SELECT cust_id, cust_name

FROM ULCustomer WHERE cust_id = ?' )

Quotes in scripts
If you add a script using a stored procedure, the script is a string. Any strings within the script need to be escaped. For Adaptive Server Anywhere, each quotation mark (') needs to be doubled so as not to terminate the string.


Direct inserts of scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Adding scripts to your consolidated database

 Direct inserts of scripts

The scripts are stored in the MobiLink system tables, and so you can construct INSERT statements that directly add the script into the MobiLink system tables.

The details of the INSERT statements can be seen in the source code for the ml_add_connection_script and ml_add_table_script stored procedures. The source code for these stored procedures is dependent on the DBMS you are using as a consolidated database, and the different versions can be found in the syncasa.sql, syncase.sql, syncmss.sql, syncdb2.sql, and syncora.sql scripts.

The syncasa.sql script is held in the scripts subdirectory of your Adaptive Server Anywhere installation directory. The other scripts are held in the MobiLink\setup subdirectory. IBM DB2 only supports column names and other identifiers of 18 characters or less, and so the names are truncated. For example, ml_add_connection_script is shortened to ml_add_connection_.


Example scripts for UltraLite
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Adding scripts to your consolidated database

 Example scripts for UltraLite

When you build an UltraLite application, the UltraLite generator automatically inserts an example_upload_cursor script and an example_download_cursor script into the UltraLite reference database. The action of the example download script is to download all rows of a corresponding table that exists in the remote database. These scripts specify the select list in the correct order and the example upload_cursor script includes the correct WHERE clause.

The example scripts are inserted into the ml_scripts table, but they are not used unless you insert an entry in the ml_table_script table that associates them with the upload_cursor or download_cursor event, respectively.

Minimally, the example scripts for download cursors provide the order of columns expected by the remote database.

  For information on adding the MobiLink system tables to your reference database, see Creating a consolidated database.


Testing script syntax
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Adding scripts to your consolidated database

 Testing script syntax

As you develop your synchronization scripts, you can use Sybase Central to test for syntax errors in your scripts.

Testing the scripts is done without any remote site in place. No data is added to the database or downloaded from the database during testing. The validity of the synchronized data itself is not tested.

♦ To test a your synchronization scripts

1	Start Sybase Central and connect to a database. In this case, use the CustDB sample database.

•	Select Manage MobiLink Synchronization from the Sybase program group.

  For a description of how to carry out this step, see Lesson 8: Browse the consolidated database.

2	Under the UltraLite Sample database icon, right click on the Synchronized Tables folder or the Connection scripts folder, and select Test Scripts from the popup menu. The script-testing window is displayed.

3	Click Test. If prompted, choose to use the default user name. The results of the test are displayed in the window.

The test results include a listing of which scripts are executed, in which order. They also include a listing of any syntax errors or data type errors found during the test.


Writing scripts to download rows
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 Writing scripts to download rows

There are two cursor scripts that can be used during download-stream processing for each table. These are the download_cursor script, which carries out inserts and updates, and the download_delete_cursor script, which carries out deletes.

These scripts are either SELECT statements or calls to procedures that return result sets. The MobiLink synchronization server downloads the result set of the script to the remote database. The MobiLink client automatically inserts or updates rows based on the download_cursor script result set, and deletes rows based on the download_delete_cursor event.

 Writing download_cursor scripts

 Deleting rows with the download_delete_cursor script

 Events during download


Writing download_cursor scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to download rows

 Writing download_cursor scripts

You write download_cursor scripts to download information from the consolidated database to your remote database. You must write one of these scripts for each table in the remote database for which you want to download changes. You can use other scripts to customize the download process, but no others are necessary.

•	Each download_cursor script must contain a SELECT statement or a call to a procedure that contains a SELECT statement. The MobiLink synchronization server uses this statement to define a cursor in the consolidated database.

•	The script must select all columns that correspond to the columns in the corresponding table in the remote database. The columns in the consolidated database can have different names than the corresponding columns in the remote database, but they must be of compatible types.

•	The columns must be selected in the order that the corresponding columns are defined in the remote database. This order is identical to the order of the columns in the reference database.

Examples

•	The following script could serve as a download_cursor script for a remote table that holds employee information. The MobiLink synchronization server would use this SQL statement to define the download cursor. This script downloads information about all the employees.

SELECT emp_id, emp_fname, emp_lname

FROM employee

•	The MobiLink synchronization server passes specific parameters to some scripts. To use these parameters, you include a question mark in your SQL statement. The MobiLink synchronization server substitutes the value of the parameter before executing the statement against the consolidated database. The following script downloads information about the employees that report directly to the present user.

SELECT emp_id, emp_fname, emp_lname

FROM employee

WHERE manager_id = ?

In this example, the MobiLink synchronization server replaces the question mark with the value of the parameter to the download_cursor script, which is the name of the present user.

Notes

•	Row values can be selected from a single table or from a join of multiple tables.

•	The script itself need not include the name of the remote table. The remote table need not have the same name as the table in the consolidated database. The name of the remote table is identified by an entry in the ml_table table. In Sybase Central, the remote tables are listed together with their scripts.

•	The rows in the remote table must contain the values of emp_id, emp_fname, and emp_lname. The remote columns must be in that order, although they can have different names. The columns in the remote database are in the same order as those in the reference database.

UltraLite tip
The example scripts list the columns in the order that they are defined in the reference database. Inspect the example_download_cursor and example_upload_cursor scripts to see the column order.

•	All cursor scripts must select the columns in the same order as the columns are defined in the remote database. Where column names or table structure is different in the consolidated database, columns should be selected in the correct order for the remote database, or equivalently, the reference database. Columns are assigned to columns in the remote database based on their order in the SELECT statement.

•	When you build an UltraLite application, the UltraLite generator creates a sample download script for each table in your UltraLite application. It inserts these sample scripts into your reference database. The example scripts assume that the consolidated database contains the same tables as your application. You must modify the sample scripts if your consolidated database differs in design, but these scripts provide a starting point.


Deleting rows with the download_delete_cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to download rows

 Deleting rows with the download_delete_cursor script

You write download_delete_cursor scripts to delete rows from your remote database. You must write one of these scripts for each table in the remote database from which you want to delete rows during synchronization.

The MobiLink synchronization server deletes rows by selecting values from the consolidated database and passing those values to the remote database. If the values match those of a primary key in the remote database, then that row is deleted. If the primary key values match no remote row, the values are discarded. The MobiLink synchronization server executes the SELECT statement against the consolidated database; the deletes are performed in the remote database.

•	Each download_delete_cursor script must contain a SELECT statement or a call to a stored procedure that returns a result set. The MobiLink synchronization server uses this statement to define a cursor in the consolidated database.

•	This statement must select all the columns that correspond to the primary-key columns in the table in the remote database. The columns in the consolidated database can have different names than the corresponding columns in the remote database, but they must be of compatible types.

•	The values must be selected in the same order as the corresponding columns are defined in the reference database. That order is the order of the columns in the CREATE TABLE statement used to make the table, not the order they appear in the statement which defines the primary key.

•	The columns must be selected in the order that the corresponding columns are defined in the remote database. This order is identical to the order of the columns in the reference database.

Note
Each download_delete_cursor script must select all the column values present in the primary key of the corresponding remote table. However, it may, optionally, select all the other columns, too. This feature is present only for compatibility with older clients. Selecting the additional columns is less efficient, as the database engine must retrieve more data. Unless the client is of an old design, the MobiLink synchronization server discards the extra values immediately. The extra values are downloaded only to older clients.

Examples

•	The following selection could serve as a download_delete_cursor script for a remote table that holds employee information. The MobiLink synchronization server would use this SQL statement to define the delete cursor. This script deletes information about all the employees.

SELECT emp_id

FROM employee

•	The MobiLink synchronization server substitutes the value of the parameter for question marks. The following script deletes information about the employees that do not report directly to the present user.

SELECT emp_id

FROM employee

WHERE NOT manager_id = ?

In this example, the MobiLink synchronization server replaces the question mark with the value of the parameter to the download_delete_cursor script, which is the name of the present user.

•	Optionally, the above example may be rewritten as follows, assuming the remote table contains only these three columns. This format is recommended only for use with older clients, as it is less efficient.

SELECT emp_id, emp_fname, emp_lname

FROM employee

WHERE NOT manager_id = ?

Tips
The above examples could prove inefficient in an organization with many employees. You can make the delete process more efficient by selecting only rows that could be present in the remote database. For example, you could limit the number of rows by selecting only those people who have recently been assigned a new manager.

Another strategy is to allow the client application to delete the rows itself. This method is possible only when a rule identifies the unneeded rows. For example, if the rows contain a timestamp that indicates an expiry date. Use the STOP SYNCHRONIZATION DELETE statement to stop these deletes being uploaded during the next synchronization.

  You can use the referential integrity checking built into all MobiLink clients to delete rows in a particularly efficient manner. For details, see Referential integrity and synchronization.


Events during download
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to download rows

 Events during download

The MobiLink synchronization server builds the download stream, in a single transaction, as follows.

begin_download(user)

for each remote table

begin_download(user, table)

next table

for each remote table

begin_download_deletes(user, table)

SELECT using download_delete_cursor(user)

end_download_deletes(user, table)

begin_download_rows(user, table)

SELECT using download_cursor(user)

end_download_rows(user, table)

next table

for each remote table

end_download(user, table)

next table

end_download(user)

wait for confirmation from remote device or timeout

if ( confirmation ) then

COMMIT

else

ROLLBACK

end if

Notes

•	Like the upload stream, the download stream starts and ends with connection events. Other events are table-level events.

•	If no confirmation of the downloads is received from the client, the entire download transaction is rolled back in the consolidated database.

•	The begin_download and end_download scripts for each remote table hold logic that is independent of the individual rows being updated.

•	The download stream does not distinguish between inserts and updates. The script associated with the download_cursor event is a SELECT statement that defines the rows to be downloaded. The client detects whether the row exists or not and carries out the appropriate insert or update operation.

•	At the end of the download processing, the client automatically deletes rows if necessary to avoid referential integrity violations.

  For more information, see Referential integrity and synchronization.


Writing scripts to upload rows
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 Writing scripts to upload rows

To upload information contained in your remote database to your consolidated database, you must define an upload_cursor script. Each upload_cursor script is specific to a particular table in the remote database.

The upload_cursor script is a SELECT statement that defines a cursor in the consolidated database table. This cursor is used to apply uploaded inserts, updates, and deletes. Although both upload_cursor and download_cursor scripts contain queries, these queries perform different functions.

 Writing upload_cursor scripts

 Script events during upload

 Conflict detection and resolution


Writing upload_cursor scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to upload rows

 Writing upload_cursor scripts

The upload_cursor script takes a different set of parameters from other scripts. This script takes one parameter for each column in the primary key of the table. The script must be a SELECT statement. The WHERE clause of the SELECT statement must use the parameters to uniquely identify rows in the consolidated database.

For example, the ULCustomer upload_cursor script in the CustDB sample application uses the primary key value of the ULCustomer table as a parameter.

SELECT cust_id, cust_name

FROM ULCustomer

WHERE cust_id = ?

Meaning of the SELECT statement

Although both upload_cursor and download_cursor scripts contain SELECT statements, the meaning of the two statements is quite different. The download script selects all rows to be downloaded, but the MobiLink synchronization server requires the WHERE clause of the query in the upload_cursor script to identify exactly one row in the consolidated database to be updated or deleted.

Inserts are a special case

If a table is to have only inserts at all remote databases, with no updates or deletes, no WHERE clause is required. No rows are being deleted or updated, and so the WHERE clause does not need to uniquely identify the row.

The old_row_cursor and new_row_cursor scripts are always used only for inserts. Therefore, they never require parameters or a WHERE clause.

SELECT FOR UPDATE

SELECT statements in the upload_cursor script define cursors through which updates, deletes, and inserts are performed. SELECT statements in the new_row_cursor or old_row_cursor scripts are used in conflict resolution define cursors through which inserts are performed.

Some database-management systems use an additional clause on the SELECT statement to indicate that the query defines a cursor that may be used for changes. If the DBMS you are using as a consolidated database uses such a clause, you may wish to include it in SELECT statements in your upload cursors.

Microsoft SQL Server, Sybase Adaptive Server Enterprise, IBM DB2, and Oracle use a FOR UPDATE clause to indicate queries that may be updated. No additional clause is required for Adaptive Server Anywhere.

Example

The following upload_cursor script includes a WHERE clause, and the condition in that clause uses the script parameters to uniquely identify a row in the employee table.

SELECT emp_id, emp_fname, emp_lname

FROM employee

WHERE emp_id = ?

This example assumes that the employee ID number is the primary key of the employee table in the consolidated database and, thus, uniquely identifies an employee. This example also assumes that the remote table uses the employee number as a primary key. The table and the employee number column can have different names in the remote database as long as the number, order, and type of columns in the SELECT statement correspond to the number, order, and type of columns in the remote table.

The primary key, in this case the single column emp_id, is present in both the list of selected columns and the WHERE clause. All columns in the primary key of the remote table must be present in both positions.


Script events during upload
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to upload rows

 Script events during upload

The MobiLink synchronization server processes the uploaded data, in a single transaction, as follows.

begin_upload(user)

for each remote table

begin_upload(user, table)

next table

for each remote table

begin_upload_rows(user, table)

for each row uploaded from this table

if ( INSERT ) then

if ( upload_cursor defined ) then

INSERT using upload_cursor(pk1, ..., pkn)

else

INSERT using new_row_cursor(pk1, ..., pkn)

resolve_conflict(user, table)

end if

else if ( UPDATE ) then

if ( upload_cursor defined ) then

SELECT using upload_cursor(pk1, ..., pkn)

if ( not conflict ) then

UPDATE using upload_cursor(pk1, ..., pkn)

end if

end if

if ( conflict or not upload_cursor defined )

INSERT using old_row_cursor(pk1, ..., pkn)

INSERT using new_row_cursor(pk1, ..., pkn)

resolve_conflict(user, table)

end if

end if

next row

end_upload_rows(user, table)

next table

for each remote table [reverse order]

begin_upload_deletes(user, table)

if ( DELETE ) then

for each row uploaded from this table

if ( upload_cursor defined ) then

DELETE using upload_cursor(pk1, ..., pkn)

else

INSERT using old_row_cursor(pk1, ..., pkn)

resolve_conflict(user, table)

end if

next row

end if

end_upload_deletes(user, table)

next table

for each remote table

end_upload(user, table)

next table

end_upload(user)

COMMIT

Notes

•	The upload starts and ends with connection events. Other events are table-level events.

•	The begin_upload and end_upload scripts for each remote table hold logic that is independent of the individual rows being updated.

•	The MobiLink synchronization server uses the upload_cursor script to fetch the values of existing rows from the consolidated database before any updates are applied. These values are used to detect conflicts.

•	The upload stream consists of single row inserts, updates, and deletes. These are applied by opening a cursor on the appropriate tables and applying the action through the cursor. The script associated with the upload_cursor event is a SELECT statement that defines this cursor.

•	The upload_cursor script takes a different set of parameters than the other scripts. Its parameters are the primary key values identifying the row being uploaded.


Conflict detection and resolution
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to upload rows

 Conflict detection and resolution

When a row has been updated in the remote database, both old and new values are sent during synchronization. If the row exists in the consolidated database, the MobiLink synchronization server checks whether the values it holds match the old values sent from the remote database. If the old values match the current values, the MobiLink synchronization server updates the row using new values sent from the remote database. If the old values do not match the current values, a conflict is detected.

Caution
Never update primary keys in a MobiLink environment.

  A conflict arises when the same row is updated in both the consolidated and remote databases, independently. For more information about conflict resolution, see Handling conflicts.


Writing scripts to handle errors
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 Writing scripts to handle errors

An error in a synchronization script occurs when an operation in the script fails while the MobiLink synchronization server is executing it. The DBMS returns a SQL Code to the MobiLink synchronization server indicating the nature of the error. Each consolidated database DBMS has its own set of SQL Codes.

When an error occurs, the MobiLink synchronization server invokes the handle_error event. You should provide a connection script associated with this event to handle errors. The MobiLink synchronization server passes several parameters to this script to provide information on the nature and context of the error, and requires an output value to tell it how to respond to the error.

Error handling actions

Some actions you may wish to take in an error-handling script are:

•	Log the error in a separate table.

•	Instruct the MobiLink synchronization server whether to ignore the error and continue, or rollback the synchronization, or rollback the synchronization and shut down the MobiLink synchronization server.

•	Send an e-mail message.

 Parameters for error handling scripts

 Error handling scripts return an action code

 Reporting errors

 Handling multiple errors on a single SQL statement


Parameters for error handling scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to handle errors

 Parameters for error handling scripts

The MobiLink synchronization server passes the following parameters to the handle_error script, which provide the nature of the error and the context in which it occurred.

1	An integer holding the native SQL error code.

2	A string containing the error message from the DBMS.

3	A string holding the synchronization user name that requested this synchronization.

4	A string holding the name of the table being referenced. If the offending script was not a table script, then the table name is NULL.


Error handling scripts return an action code
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to handle errors

 Error handling scripts return an action code

The handle_error script consists of a call to a stored procedure. The stored procedure must return an action code telling the MobiLink synchronization server what to do next.

The action code is one of the following values:

•	1000    Skip the current row and continue processing.

•	3000    Rollback the current transaction and cancel the current synchronization. This is the default action code, and is used when no handle_error script is defined or this script causes an error.

•	4000    Rollback the current transaction, cancel the synchronization, and shut down the server.

You can return a value from the handle_error script in two ways.

•	Pass the action parameter to an OUTPUT parameter of a procedure:

CALL my_handle_error( ?, ?, ?, ?, ? )

•	Set the action code via a procedure or function return value:

? = CALL my_handle_error( ?, ?, ?, ? )

Most DBMS's use the RETURN statement to set the return value from a procedure or function.

When the MobiLink synchronization server runs this script, it sets the action code to a default value, depending on the type of error that occurred. Your procedure may modify this code. In either case, however, your script must return the action code.

The CustDB sample application contains error handlers for various database-management systems.


Reporting errors
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to handle errors

 Reporting errors

Since errors can disrupt the natural progression of the synchronization process, it can be difficult to create a log of errors and their resolutions. The report_error script provides a means of accomplishing this task. The MobiLink synchronization server executes this script whenever an error occurs. If the handle_error script is defined, it is executed immediately prior to the reporting script.

The parameters to the report_error script are identical to those of the handle_error script, except that the report_error script can not modify the action code. Since the value of the action code is that returned by the handle_error script, this script can be used to debug error-handling problems.

This script typically consists of an insert statement, which records the values, perhaps with other data, such as the time or date, in a table for later reference. To ensure that this data is not lost, the MobiLink synchronization server always runs this script in a separate transaction and automatically commits the changes as soon as this script completes.

Example

The following report_error script, which consists of a single insert statement, adds the script parameters into a table, along with the current date and time. The script does not commit this change because the MobiLink synchronization server always does so automatically.

INSERT INTO errors

VALUES( CURRENT DATE, ?, ? ,?, ?, ? );


Handling multiple errors on a single SQL statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

        Writing scripts to handle errors

 Handling multiple errors on a single SQL statement

ODBC allows multiple errors per SQL statement, and some DBMSs make use of this feature. Microsoft SQL Server, for example, can have two errors for a single statement. The first is the actual error, and the second is usually an informational message telling you why the current statement has been terminated.

When a single SQL statement causes multiple errors, the handle_error script is invoked once per error. The MobiLink synchronization server uses the most severe action code (that is, the numerically greatest) to determine the action to take. The same applies to the handle_error script.

If the handle_error script itself causes a SQL error, then the default action code (3000) is assumed.


DBMS-dependent scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 4.  Writing Synchronization Scripts

 DBMS-dependent scripts

The MobiLink synchronization server can be used with ODBC compliant databases other than Adaptive Server Anywhere, so some aspects of scripts depend on the DBMS you are using.

Invoking procedures from scripts    Some databases, SQL Server for example, require that procedure calls with parameters be written using the ODBC syntax.

{ CALL procedure_name( ?, ?, ... ) }

On these systems, an error-handler that uses a RETURN value can also be in the following form. For example, you can return values in OUTPUT parameters in IBM DB2.

{ ? = CALL procedure_name( ?, ?, ... ) }

Adaptive Server Enterprise also requires the latter format when returning a value from a procedure.

Numeric and decimal columns with ASE    The current version of the MobiLink synchronization server requires that primary key values of type numeric or decimal be explicitly converted to their types under Adaptive Server Enterprise.

You must add an explicit conversion to the numeric parameters in the script, as shown in the following examples.

SELECT ...

WHERE numeric_col = CONVERT( NUMERIC, ? )

...

The above statement explicitly converts the first parameter to type NUMERIC.

SELECT ...

WHERE decimal_col = CONVERT( DECIMAL(10,8), ? )

...

The above statement explicitly converts the first parameter to type DECIMAL (10,8).


CHAPTER 5.  Synchronization Techniques
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

 CHAPTER 5.  Synchronization Techniques

About this chapter

This chapter describes a variety of techniques that you can use to tackle common synchronization tasks encountered in MobiLink installations.

The techniques in this chapter are illustrated with examples taken from the CustDB sample application.

 Introduction

 Development tips

 The CustDB sample code

 Synchronization performance tips

 Snapshot synchronization

 Timestamp-based synchronization

 Partitioning rows among remote databases

 Maintaining unique primary keys with primary-key pools

 Handling conflicts

 Miscellaneous techniques

 Schema changes in remote databases


Introduction
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Introduction

The previous chapter, Writing Synchronization Scripts, describes how to write simple synchronization scripts, store them in your database, and test that they are free of syntax errors.

Many useful synchronization features require not just one script, but a set of scripts working together. This chapter describes how to implement some common synchronization techniques.

Example

The timestamp-based synchronization of the ULCustomer table used in the CustDB sample application requires the following scripts:

•	A begin_connection connection script to create a variable to hold the last download time.

•	A begin_download table script to maintain the last download time for the current user in the consolidated database, and to assign a value to the last download variable.

•	An upload_cursor script on the ULCustomer table to apply changes made at remote databases to the consolidated database.

•	A download_cursor script on the ULCustomer table to download new and updated rows to remote databases.

 Some common techniques


Some common techniques
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Introduction

 Some common techniques

The synchronization design in the CustDB sample application uses the following features.

•	Complete table downloads    All rows and columns of the ULProduct table are shared in their entirety with the remote databases.

•	Column subsets    All rows, but not all columns, of the ULCustomer table are shared with remote databases.

•	Row subsets    Different remote users get different sets of rows from the ULOrder table.

•	Snapshot-based synchronization    The ULProduct table is synchronized using a simple method that downloads all rows each time synchronization occurs.

  For general information on this technique, see Snapshot synchronization.

•	Timestamp-based synchronization    A method of identifying changes to the consolidated database made since the last time a device synchronized. The ULCustomer and ULOrder tables are synchronized using a method based on timestamps.

 For general information on this technique, see Timestamp-based synchronization.

•	Primary key pools to maintain unique primary keys    Ensuring that primary-key values are unique across a complete MobiLink installation is essential. The primary-key pool method used in this application is a practical method for ensuring unique primary keys.

 For general information on this technique, see Maintaining unique primary keys with primary-key pools.


Development tips
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Development tips

Adding synchronization functionality to an application adds an added level of complexity to your application. The following tips may be useful.

•	Wait    If you try to add synchronization to a prototype application, it can be difficult to deduce which functional components are causing problems. This is particularly the case with UltraLite applications, where database and application are compiled together. When developing a prototype, temporarily hard code INSERT statements in your application to provide data for testing and demonstration purposes. Once your prototype is working correctly, enable synchronization and discard the temporary INSERT statements.

•	Go step-by-step    Start with straightforward synchronization techniques. Operations such as a simple upload or download require only one or two scripts. Once those are working correctly, you can introduce more advanced techniques, such as timestamps, primary-key pools, and conflict resolution.

•	Set a large server timeout value    Many small devices have relatively slow processors. When synchronizing through a serial connection, they can take several minutes to process large download streams and return a confirmation to the MobiLink synchronization server. To avoid timeout error messages on the server when downloading large amounts of data, specify a long timeout period when starting the MobiLink synchronization server. This tip is particularly applicable to UltraLite applications.

  For MobiLink synchronization server parameters see, MobiLink synchronization server.


The CustDB sample code
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 The CustDB sample code

The examples in this chapter are drawn from the CustDB sample application. This UltraLite application is a MobiLink client. The application has been designed to illustrate several common techniques. To get the most out of this chapter, you should study the sample application as you read.

This section describes the pieces that make up the code for the sample application and database. The sample code is held in the UltraLite\samples\CustDB subdirectory of your SQL Anywhere installation directory. Platform-specific user interface code is held in subdirectories named for each operating system.

 The CustDB sample database

 Application logic source code

 Synchronization logic source code


The CustDB sample database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        The CustDB sample code

 The CustDB sample database

The CustDB sample database is provided as an Adaptive Server Anywhere database file. This database serves as a reference database, and as the consolidated database.

Examples based on Adaptive Server Anywhere
The examples described here are based on Adaptive Server Anywhere consolidated database. The SQL source code is held in the custdb.sql file. Other files, such as custase.sql, custmss.sql, custora.sql, and custdb2.sql files implement the same features in a way that is appropriate for other databases.

In addition, SQL scripts are provided so that you can rebuild the sample database or use a Sybase Adaptive Server Enterprise, Microsoft SQL Server, Oracle, or IBM DB2 database as a consolidated database.

To prepare databases other than Adaptive Server Anywhere for use as MobiLink consolidated databases, you must first run a script to install the MobiLink system tables. These files, which have names such as syncase.sql, syncmss.sql, syncora.sql, or syncdb2.sql, are located in the MobiLink\setup subdirectory. You do not need to prepare Adaptive Server Anywhere databases in this manner because the MobiLink system tables are automatically added when you created the database.

The SQL scripts for the CustDB sample application perform the following operations. On databases other than Adaptive Server Anywhere, these scripts can be run only after the MobiLink system tables have been added.

•	Create the CustDB tables    The table definitions are included in the scripts.

•	Add the data    The data for the CustDB database is added.

•	Add the synchronization scripts    The synchronization scripts control what happens when an application synchronizes. These scripts are added to the database.

 Creating a DB2 consolidated database for CustDB


Creating a DB2 consolidated database for CustDB
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        The CustDB sample code

          The CustDB sample database

 Creating a DB2 consolidated database for CustDB

The files needed to create a DB2 consolidate database for the CustDB sample application are as follows:

•	custdb2.sql

•	custdb2.java and its compiled form, custdb2.class.

•	custdb2setup.java and its compiled form, custdb2setup.class.

The custdb2.class file must be copied to the SQLLIB\FUNCTION directory on the DB2 server machine. This file contains the implementations of the procedures created in custdb2.sql.

♦ To set up a DB2 consolidated database for the sample application

1	Create a DB2 database on the DB2 server. Ensure that the default tablespace (usually called USERSPACE1) uses 8 kb pages. You may have to delete the default tablespace and re-create it with 8 kb pages. Consult your DB2 documentation for more information.

2	If necessary, change the connect command in custdb2.sql.

3	Start a DB2 Command Window from either the server or client machine. Enter the following command at the prompt:

db2 -c -ec -td~ +s -v -f custdb2.sql

4	When processing is complete, enter the following command to close the command window.

exit

5	On the DB2 client machine, create an ODBC data source called CustDB that references the DB2 database.

If you use a name other than CustDB, you will have to change the connection code in custdb2setup.java and recompile it, as follows, where jdk11dir is the path to your JDK 1.1 installation.

javac -g -classpath jdk11dir\lib\classes.zip;%db2path%\java\db2java.zip;%db2path%\java\runtime.zip custdb2setup.java

6	Also on the client machine, run the custdb2setup Java application, as follows, where username and password are the username and password for connecting to the CustDB ODBC data source.

java custdb2setup [username password]

The custdb2setup.class file contains a Java application that resets the CustDB example in the DB2 database. After the initial setup, you can run this application at any time to reset the DB2 CustDB database.


Application logic source code
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        The CustDB sample code

 Application logic source code

The application logic is held in the file custdb.sqc. This embedded SQL file holds the SQL statements needed to query and modify information from the UltraLite database and also holds the calls needed to start synchronization with the consolidated database. The user-interface features are held separately, in platform-specific subdirectories.


Synchronization logic source code
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        The CustDB sample code

 Synchronization logic source code

The source for the synchronization features of the sample application is the custdb.sql file, with custase.sql, custmss.sql, custora.sql, and custdb2.sql holding versions for other database-management systems. The scripts in custdb.sql are included in the custdb.db Adaptive Server Anywhere database.

Inspecting the synchronization scripts

You can use Sybase Central to inspect the synchronization scripts in the consolidated database.

  For information on running Sybase Central, see Browsing the CustDB database with Sybase Central.

Script types and events

The custdb.sql file adds each synchronization script into the consolidated database by calling ml_add_connection_script or ml_add_table_script.

Examples

The following lines in custdb.sql add a connection-level script, which is executed at the begin_connection event. The script consists of two CREATE VARIABLE statements.

call ml_add_connection_script(

'CustDB',

'begin_connection',

'create variable @LastDownload timestamp;

create variable @EmployeeID integer;' )

go

The following lines add a table-level script for the ULProduct table, which is executed at the download_cursor event. The script consists of a single SELECT statement.

call ml_add_table_script(

'CustDB',

'ULProduct', 'download_cursor',

'SELECT prod_id, price, prod_name FROM ULProduct' )

go

Some table-level scripts, such as this one, are associated with cursor events. These scripts are primarily responsible for the movement of data. As they play such a central role, this kind of table script is described separately as a cursor script.

  For more information about script types, see Script types.

  For a listing of available script types and events, see Reference.


Synchronization performance tips
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Synchronization performance tips

Synchronization performance can be addressed in several ways.

•	Download only the rows you need    The most important way to make synchronization fast is to download only the rows that are required. It is easier to write synchronization scripts that download all rows upon each synchronization, but downloading unneeded rows can make the remote database too large and also impacts synchronization performance.

•	Communications speed    If synchronization always occurs over a LAN while the machine is docked, then communication will be relatively fast. On the other hand, if synchronization may occur over a phone line or other low-bandwidth link, then communication will not be as fast and it is more important to have scripts that minimize the size of the download stream.

•	Optimize script execution    The performance of your scripts in the consolidated database is an important factor. It may help to create indexes on your tables so that download_cursor scripts and download_delete_cursor scripts can efficiently select the required rows.

•	Maximize concurrency    Concurrency considerations in your scripts can be an important factor for throughput.

For example, suppose a begin_download script increments a column in a table to count the total number of downloads. If multiple users may synchronize at the same time, this script would effectively serialize their downloads. The same counter would be better in the begin_synchronization or end_synchronization script because they are called just before a commit.

  For information on the transaction structure of synchronization, see Transactions in the synchronization process.


Snapshot synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Snapshot synchronization

Snapshot synchronization of a table is a complete download of all relevant rows in the table at each synchronization, even if they have been downloaded before. This is the simplest synchronization method, but can involve unnecessarily large data sets being exchanged, which can limit performance.

You can use snapshot synchronization for downloading all the rows of the table, or in conjunction with a partitioning of the rows as described in Partitioning rows among remote databases.

When to use snapshot synchronization

The snapshot method is typically most useful for tables that have both the following characteristics.

•	Relatively few rows    When there are few rows, the overhead associated with downloading all of them is small.

•	Rows that change frequently    When most rows in a table change frequently, there is little to be gained by explicitly excluding those that have not changed since the last synchronization.

A table that holds a list of exchange rates could be suited to this approach because there are relatively few currencies, but the rates of most change frequently. Depending on the nature of the business, a table that holds prices, a list of interest rates, or current news items could all be candidates.

♦ To implement snapshot-based synchronization

1	Leave the upload_cursor script undefined unless remote users update the values.

2	If the table may have rows deleted, write a download_delete_cursor script that deletes all the rows from the remote table, or at least all rows no longer required. Do not delete the rows from the consolidated database; rather, mark them for deletion. You must know the row values to delete them from the remote database.

  For more information, see Deleting rows with the download_delete_cursor script.

3	Write a download_cursor script that selects all the rows you want to include in the remote table.

Mark rows for deletion
Rather than deleting rows from the consolidated database, mark them for deletion. You must know the row values to delete them from the remote database. Select only unmarked rows in the download_cursor script and only marked rows in the download_delete_cursor script

The download_delete_cursor script is executed before the download_cursor script. If a row is to be included in the download stream, you need not include a row with the same primary key in the delete list. When a downloaded row is received at the remote location, it replaces a preexisting row with the same primary key.

  For more information, see Events during download.

An alternate deletion technique

Rather than delete rows from the remote database using a download_cursor script, you can allow the remote application to delete the rows. For example, immediately following synchronization, you could allow the application to execute SQL statements that delete the unneeded rows.

Rows deleted by the application are ordinarily uploaded to the MobiLink synchronization server upon the next synchronization, but you can prevent this upload using the STOP SYNCHRONIZATION DELETE statement, as follows.

STOP SYNCHRONIZATION DELETE;

DELETE FROM table-name

WHERE expiry_date < CURRENT TIMESTAMP;

COMMIT;

START SYNCHRONIZATION DELETE;

Naturally, a different condition may be required in the WHERE clause, depending on the business logic of the application.

Example

The ULProduct table in the sample application is maintained by snapshot synchronization. The table contains relatively few rows, and for this reason, there is little overhead in using snapshot synchronization.

1	There is no upload_cursor script. This reflects a business decision that products cannot be added at remote databases.

2	There is no download_delete_cursor, reflecting an assumption that products are not removed from the list.

3	The download_cursor script selects the product identifier, price, and name of every current product. If the product is pre-existing, the price in the remote table will be updated. If the product is new, a row will be inserted in the remote table.

SELECT prod_id, price, prod_name

FROM ULProduct


Timestamp-based synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Timestamp-based synchronization

The timestamp method is the most useful general technique for efficient synchronization. The technique involves tracking the last time that each user synchronized, and using this information to control the rows downloaded to each remote database.

The information uploaded on synchronization is controlled automatically by the client.

♦ To implement time-stamped synchronization for a single table

1	Add a column to the consolidated database to store the required date and time information. In general, you will want to compare the last download time for each user name with the last time each row was modified. This column is not needed in the remote database.

2	For more convenient access create a connection-level variable to store the last update time. Connection-level variables are specific to Adaptive Server Anywhere.

In the CustDB example, this variable is named @LastDownload. The variable is created during begin_connection, and set during begin_download.

3	If applicable, write an upload_cursor script to upload changes from the remote table.

4	Write a begin_download script that sets the variable to the previous download time and records the current time as the last download time for the next synchronization.

5	Use the previous download time in the download_deletes_cursor script to control information deleted from the remote database.

6	Use the previous download time in the download_ cursor script to control information downloaded to the remote database.

You can use an UPDATE trigger and an INSERT trigger at the consolidated database to keep the last modification times current.

 Timestamp synchronization example


Timestamp synchronization example
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Timestamp-based synchronization

 Timestamp synchronization example

The sample application uses timestamp-based synchronization for many of its tables. Here, we look at timestamp synchronization of the ULCustomer table.

In the consolidated database, ULCustomer has the following columns:

•	cust_id    An integer primary key column.

•	cust_name    The customer name

•	last_modified    A timestamp column holding the last time the row was modified. This column is excluded from the download_cursor script because it does not appear in the remote database.

Timestamp-based synchronization requires that several scripts work together. Each script is described in a separate section.

 The begin_connection script

 The begin_synchronization script

 The upload_cursor script

 The begin_download connection script

 The download_cursor script


The begin_connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Timestamp-based synchronization

          Timestamp synchronization example

 The begin_connection script

The begin_connection event takes place when the MobiLink synchronization server connects to the consolidated database. As the MobiLink synchronization server uses a connection pool, a single connection may be shared by several synchronizing applications, one after another. The begin_connection script is used for actions that are to be performed only once per connection. Creating variables is an example of such an action.

This script creates two variables (@LastDownload and @EmployeeID), which exist for the duration of the connection.

The script is as follows:

create variable @LastDownload timestamp;

create variable @EmployeeID integer;

Connection-level variables are available in Adaptive Server Anywhere, but are generally unavailable in other databases. For Adaptive Server Enterprise and Microsoft SQL Server, a temporary table is used. For Oracle, a global session package is used.

  For information about connection-level begin_connection scripts, see begin_connection connection script.


The begin_synchronization script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Timestamp-based synchronization

          Timestamp synchronization example

 The begin_synchronization script

The begin_synchronization event is triggered each time a client connects to the MobiLink synchronization server to synchronize. A single parameter is supplied to the begin_synchronization script, which is the user name of the connecting user as supplied in the client synchronization call.

The script is as follows:

set @EmployeeID = ?

The value of the Employee ID is specific to the remote database that is synchronizing, and so this value cannot be assigned in a begin_connection script.

  For more information about connection-level begin_synchronization scripts, see begin_synchronization connection script.


The upload_cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Timestamp-based synchronization

          Timestamp synchronization example

 The upload_cursor script

The first step in synchronization is to upload any changes made at the remote database. The client automatically flags any rows changed since the last successful synchronization, and all these flagged changes are sent to the MobiLink synchronization server to be applied to the consolidated database. The upload_cursor script defines a cursor through which these changes are applied.

You do not need to implement timestamp synchronization logic for uploads. The technique is applied only to the download phase.

The upload_cursor script is as follows.

SELECT cust_id, cust_name

FROM ULCustomer

WHERE cust_id = ?

The upload_cursor script takes a parameter value for each primary-key column. In this case, the cust_id column is the single primary-key column for the table.

For each row that has been updated, deleted, or inserted at the remote database, the upload_cursor script is executed at the consolidated database. The script opens a cursor on the ULCustomer table on the consolidated database, positioned at the primary key specified in the operation.

If the operation is an INSERT, the cursor position is irrelevant. If the operation is an UPDATE or DELETE, the cursor is positioned at the row, and the row is updated or deleted.

  For more information on upload_cursor scripts, see upload_cursor cursor script.


The begin_download connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Timestamp-based synchronization

          Timestamp synchronization example

 The begin_download connection script

The begin_download event is invoked each time the MobiLink synchronization server starts the download step of transferring data to the remote database.

The connection-level begin_download script does not transfer data: cursor scripts carry out that function. Instead, this script maintains the information concerning the last time that synchronization occurred.

The Adaptive Server Anywhere version of this script is as follows.

begin

  set @LastDownload =

    (select last_download from ULEmployee

     where emp_id = @EmployeeID);

  if @LastDownload is null then

    set @LastDownload = years(CURRENT TIMESTAMP, -100);

  end if;

  update ULEmployee

  set last_download = CURRENT TIMESTAMP

  where emp_id = @EmployeeID;

end

The ULEmployee table is used to hold the last download time of each user name. This table does not exist at the remote database. The script sets the @LastDownload variable to the current value from the ULEmployee table, and then updates the value in the table with the current time, ready for the next synchronization. As the download takes place in a single transaction, this change is rolled back if the download fails for any reason.

If this is the first download, then @LastDownload is set to a date that is sufficiently long ago that all data is downloaded on the first attempt. In this case, 100 years ago is chosen.

  For more information on the steps involved in synchronization, see The synchronization process.


The download_cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Timestamp-based synchronization

          Timestamp synchronization example

 The download_cursor script

The download_cursor script manages downloads of new or changed data to the remote database. The query in this cursor defines which rows are to be synchronized.

Upload and download cursor queries have different meanings
Despite their similar appearance, the upload_cursor and download_cursor scripts operate in different ways. The rows to be downloaded are defined by the download_cursor script. The rows to be uploaded are defined by UltraLite itself, automatically; the upload_cursor script defines the cursor through which these changes are applied to the consolidated database.

The download_cursor script is as follows:

SELECT cust_id, cust_name

FROM ULCustomer

WHERE last_modified > @LastDownload

The script selects all rows changed since the last download.

In the sample application, there is no facility for deleting customers, and hence no download_delete_cursor.

  For more information on download_cursor scripts, see download_cursor cursor script.


Partitioning rows among remote databases
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Partitioning rows among remote databases

Each user of a MobiLink client database can contain a different subset of the data in the consolidated database. Stated another way, you can write your scripts so that data is partitioned among remote databases.

The partitioning may be disjoint, or it may contain overlaps. For example, if each employee has their own set of customers, with no shared customers, the partitioning would be disjoint. If there are shared customers, who appear in more than one remote database, the partitioning contains overlaps.

Partitioning is implemented in the download_cursor and download_delete_cursor scripts for the table, which define the rows to be downloaded to the remote database. Each of these scripts has a single parameter, which is the synchronization user name. By defining your scripts using this parameter in the WHERE clause, each user gets the appropriate rows.

 Disjoint partitioning

 Partitioning with overlaps

 Partitioning child tables


Disjoint partitioning
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Partitioning rows among remote databases

 Disjoint partitioning

Partitioning is controlled by the download_cursor and download_delete_cursor scripts for each table involved in synchronization. These scripts take a single parameter, which is the user name supplied in the call to synchronize.

♦ To partition a table among remote databases

1	Include in the table definition a column containing the synchronization user name in the consolidated database. You need not download this column to remote databases.

2	Include a condition in the WHERE clause of the download_cursor and downloade_delete_cursor scripts requiring this column to match the script parameter.

The script parameter is represented by a question mark in the script. For example, the following download_cursor script partitions a table named Contact by employee ID.

SELECT id, contact_name

FROM Contact

WHERE emp_id = ?

Example

The primary-key pool tables in the CustDB sample application are used to supply each remote database with its own set of primary-key values. This technique is used to avoid duplicate primary keys, and is discussed in Maintaining unique primary keys with primary-key pools.

A necessary feature of the method is that primary-key-pool tables must be partitioned among remote databases in a disjoint fashion.

One key-pool table is ULCustomerIDPool, which holds primary-key values for each user to use when they add customers. The table has three columns:

•	pool_cust_id    A primary key value for use in the ULCustomer table. This is the only column downloaded to the remote database.

•	pool_emp_id    The employee who owns this primary key.

•	last_modified     This table is maintained using the timestamp technique, based on the last_modified column.

  For information on timestamp synchronization, see Timestamp-based synchronization.

The download_cursor script for this table is as follows.

SELECT pool_cust_id

FROM ULCustomerIDPool

WHERE pool_emp_id = @EmployeeID

AND last_modified > @LastDownload

Instead of using the "?" placeholder, this script uses the @EmployeeID variable to improve readability. The variable was set in the begin_synchronization script to be the synchronization user name. When not using a variable, you should use a join or sub-selection that includes the "?" placeholder.


Partitioning with overlaps
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Partitioning rows among remote databases

 Partitioning with overlaps

Some tables in your consolidated database may have rows that belong to many remote databases. Each remote database has a subset of the rows in the consolidated database and the subset overlaps with other remote databases. This is frequently the case with a customer table. In this case, there is a many-to-many relationship between the table and the remote databases and there will usually be a table to represent the relationship. The download_cursor needs to join the table being downloaded to the relationship table.

Example

The CustDB sample application uses this technique for the ULOrder table. The ULEmpCust table holds the many-to-many relationship information between ULCustomer and ULEmployee.

Each client receives only those rows from the ULOrder table for which the value of the emp_id column matches the user name supplied in the call to ULSynchronize.

The Adaptive Server Anywhere version of the download_cursor script for ULOrder in the CustDB application is as follows:

SELECT o.order_id, o.cust_id, o.prod_id, o.emp_id, o.disc, o.quant, o.notes, o.status

FROM ULOrder o , ULEmpCust ec

WHERE o.cust_id = ec.cust_id

AND ec.emp_id = @EmployeeID

AND ( o.last_modified > @LastDownload

OR ec.last_modified > @LastDownload)

AND	 ( o.status IS NULL

OR o.status != 'Approved' )

AND ( ec.action IS NULL )

This script is fairly complex. It illustrates that the query defining a table in the remote database can include more than one table in the consolidated database. The script downloads all rows in ULOrder for which:

•	the cust_id column in ULOrder matches the cust_id column in ULEmpCust,

•	the emp_id column in ULEmpCust matches the synchronization user name,

•	the last modification of either the order or the employee-customer relationship was later than the most recent synchronization time for this user,

•	the status is anything other than Approved.

The action column on ULEmpCust is used to mark columns for delete. Its purpose is not relevant to the current topic.

The download_delete_cursor script is as follows.

SELECT o.order_id

FROM ULOrder o, ULEmpCust ec

WHERE o.cust_id = ec.cust_id

  AND ec.emp_id = @EmployeeID

  AND ( o.last_modified > @LastDownload OR

        c.last_modified > @LastDownload)

  AND ( o.status IS NULL  OR

        o.status != 'Approved' )

  AND ( ec.action IS NULL )

This script deletes all approved rows from the remote database.


Partitioning child tables
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Partitioning rows among remote databases

 Partitioning child tables

The example above (Partitioning with overlaps) illustrates how to partition tables based on a criterion in some other table.

Some tables in your remote database may have disjoint subsets or overlapping subsets, but do not contain a column that determines the subset. These are child tables that usually have a foreign key (or a series of foreign keys) referencing another table. The referenced table has a column that determines the correct subset.

In this case, the download_cursor needs to join the referenced tables and have a WHERE clause that restricts the rows to the correct subset.


Maintaining unique primary keys with primary-key pools
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Maintaining unique primary keys with primary-key pools

It is often convenient to use a single column as the primary key for tables. For example, each customer should be assigned a unique identification value. If all the sales representatives work in an environment where they can maintain a direct connection to the database, assigning these numbers is easily accomplished. Whenever a new customer is inserted into the customer table, automatically add a new primary-key value that is greater than the last value.

In a disconnected environment, assigning unique values for primary keys when new rows are inserted is not as easy. When a sales representative adds a new customer, she is doing so to a remote copy of the Customer table. You must prevent other sales representatives, working on other copies of the Customer table, from using the same customer identification value.

An UltraLite database is usually a small subset of the consolidated database. For this reason, you cannot normally use automatically generated primary-key values. Features that automatically generate primary-key values (like the Adaptive Server Anywhere autoincrement feature or the Adaptive Server Enterprise identity column) rely on having the entire table available.

One efficient means of solving this problem is to assign each user of the database a pool of primary-key values to assign as the need arises. For example, you can assign each sales representative 100 new identification values. Each sales representative can freely assign values to new customers from his own pool.

♦ To implement a primary-key pool

1	Add a new table to the consolidated database and to each remote database to hold the new primary-key pool. Apart from a column for the unique value, these tables should contain a column for a user name, to identify who has been given the right to assign the value.

2	Write a stored procedure to ensure that each user is assigned enough new identification values. Assign more new values to remote users who insert many new entries or who synchronize infrequently.

3	Write a download_cursor script to select the new values assigned to each user and download them to the remote database.

4	Modify the application that uses the remote database so that when a user inserts a new row, the application uses one of the values from the pool. The application must then delete that value from the pool so it is not used a second time.

5	Write an upload_cursor script. The MobiLink synchronization server will then delete rows from the consolidated pool of values that a user has deleted from his personal value pool in the remote database.

6	Write an end_upload script to call the stored procedure that maintains the pool of values. Doing so has the effect of adding more values to the user's pool to replace those deleted during upload.

 A primary-key pool example


A primary-key pool example
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Maintaining unique primary keys with primary-key pools

 A primary-key pool example

The sample application allows remote users to add customers. It is essential that each new row has a unique primary-key value, and yet each remote database is disconnected when data entry is occurring.

The ULCustomerIDPool holds a list of primary-key values that can be used by each remote database. In addition, the ULCustomerIDPool_maintain stored procedure tops up the pool as values are used up. The maintenance procedures are called by a table-level end_upload script, and the pools at each remote database are maintained by upload_cursor and download_cursor scripts.

1	The ULCustomerIDPool table in the consolidated database holds the pool of new customer identification numbers. It has no direct link to the ULCustomer table.

2	The ULCustomerIDPool_maintain procedure updates the ULCustomerIDPool table in the consolidated database. The following sample code is for an Adaptive Server Anywhere consolidated database.

CREATE PROCEDURE ULCustomerIDPool_maintain ( IN syncuser_id INTEGER )

BEGIN

    DECLARE pool_count INTEGER;

    -- Determine how may ids to add to the pool

    SELECT COUNT(*) INTO pool_count

    FROM ULCustomerIDPool

    WHERE pool_emp_id = syncuser_id;

    -- Top up the pool with new ids

    WHILE pool_count < 20 LOOP

      INSERT INTO ULCustomerIDPool ( pool_emp_id )

      VALUES ( syncuser_id );

      SET pool_count = pool_count + 1;

    END LOOP;

END

This procedure counts the numbers presently assigned to the current user, and inserts new rows so that this user has a sufficient supply of customer identification numbers.

This procedure is called at the end of the upload stream, by the end_upload table script for the ULCustomerIDPool table. The script is as follows:

CALL ULCustomerIDPool_maintain( @EmployeeID )

3	The download_cursor script for the ULCustomerIDPool table downloads new numbers to the remote database.

SELECT pool_cust_id

FROM ULCustomerIDPool

WHERE pool_emp_id = @EmployeeID

AND last_modified > @LastDownload

This script uses the @EmployeeID variable instead of the user name placeholder, and uses timestamp replication to download only the required rows.

4	To insert a new customer, the application using the remote database must select an unused identification number from the pool, delete this number from the pool, and insert the new customer information using this identification number. The following embedded SQL function for an UltraLite application retrieves a new customer number from the pool.

bool CDemoDB::GetNextCustomerID( void )

/*************************************/

{

    short	ind;

    EXEC SQL SELECT min( pool_cust_id )

    INTO :m_CustID:ind FROM ULCustomerIDPool;

    if( ind < 0 ) {

        return false;

    }

    EXEC SQL DELETE FROM ULCustomerIDPool

    WHERE pool_cust_id = :m_CustID;

    return true;

}

5	The upload_cursor script deletes numbers from the consolidated pool of numbers once they have been used and hence deleted from the remote pool.

SELECT pool_cust_id

FROM ULCustomerIDPool

WHERE pool_cust_id = ?


Handling conflicts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Handling conflicts

Conflicts arise during the upload of rows to the consolidated database. If two users modify the same row, a conflict is detected when the second of the rows arrives at the MobiLink synchronization server. When conflicts can occur, you should define a process to compute the correct values, or at least to log the conflict.

No conflicts arise in the remote database as a result of synchronization. If a downloaded row contains a new primary key, the values are inserted into a new row. If the primary key matches that of a pre-existing row, the other values in the row are updated.

Conflicts are not the same as errors. Conflict handling can be an integral part of a well-designed application, allowing concurrency, even in the absence of locking.

 How conflicts are detected

 Programmatic conflict resolution

 Storing the user name


How conflicts are detected
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Handling conflicts

 How conflicts are detected

When the client updates any row of a table, it automatically retains a copy of the values the row contained at the time of last synchronization. When you next synchronize, your remote database contains not only the present data, but also a record of the values that were present the last time you synchronized.

When the client sends an updated row to the MobiLink synchronization server, it includes not only the new values, but also a copy of the original values. The MobiLink synchronization server processes each uploaded update using the following procedure.

1	The MobiLink synchronization server compares the old uploaded values to the current values of the row with the same primary-key values.

2	If the old uploaded values match the current contents in the consolidated database, the MobiLink synchronization server detects no conflict.

•	The MobiLink synchronization server updates the consolidated row using the new uploaded values. You define the cursor that the MobiLink synchronization server uses for this operation using the upload_cursor table script. The old uploaded values are discarded.

3	If any of the old uploaded values do not match the current consolidated values, the MobiLink synchronization server detects a conflict.

•	The MobiLink synchronization server inserts the old values row using the cursor defined by the old_row_cursor script.

•	The MobiLink synchronization server inserts the new values row using the cursor defined by the new_row_cursor script.

•	The MobiLink synchronization server executes the resolve_conflict script. In this script you can either call a stored procedure, or define a sequence of steps to resolve the conflict as appropriate.

You can resolve conflicts as they occur using the resolve_conflict script, or you can resolve all conflicts at once using the table's end_upload script.

Conflicts are detected only during updates of a row. If a row is deleted at one remote database, and updated at another, the delete takes precedence, no matter what order the actions are applied in.

  You can gain finer control the conflict detection and resolution process. For details, see Programmatic conflict resolution.


Programmatic conflict resolution
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Handling conflicts

 Programmatic conflict resolution

When no upload_cursor script is defined for a remote table, the MobiLink synchronization server attempts to insert all uploaded rows from that table using the cursors defined by the old_row_cursor and new_row_cursor scripts. In essence, all uploaded rows are then treated as conflicts. You can write stored procedures or scripts to process the uploaded values in any way you want.

Without the upload_cursor script, the normal conflict-resolution procedure, described above, is bypassed. This technique has two principal uses.

1	Manual conflict resolution   The automatic mechanism only detects errors when updating a row, and only then when the old values do not match the present values in the consolidated database. Other, less common, types of conflicts are possible.

•	When processing an update, the MobiLink synchronization server may find that the corresponding consolidated row is missing.

•	When processing an insert, the MobiLink synchronization server may find that the consolidated row already exists.

•	When processing a delete, the MobiLink synchronization server may find that the row has already been deleted.

You can capture the raw uploaded data using the old_row_cursor and new_row_cursor scripts, then analyze it as you see fit.

2	Performance   When the upload_cursor is not defined, the MobiLink synchronization server is relieved of its normal conflict-detection tasks, which involve querying the consolidated database one row at a time. Instead, it needs only to insert the raw uploaded information using the cursors defined by the old_row_cursor and new_row_cursor scripts. Since only inserts are involved, the MobiLink synchronization server performs these inserts using bulk operations that are more efficient.


Storing the user name
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Handling conflicts

 Storing the user name

When you write old_row_cursor or new_row_cursor scripts, you can include an extra column in your select statement. If you do so, the MobiLink synchronization server automatically inserts the user name into the first column, then uses the rest of the columns as usual. This mechanism is available because some database-management systems provide no convenient mechanism to store the identity of the current user.

You can use this feature to conveniently identify which user inserted each row. This information allows you to include user-specific logic in the resolve_conflict script.

For example, an ordinary old_row_cursor script is of the following form. The items in the select list correspond to the columns of the remote table.

SELECT c1, c2, . . . , cN FROM table

However, the following syntax is also permitted.

SELECT user_name, c1, c2, . . . , cN FROM table

Normally, the selected columns must match the columns of the remote table in both number and type. This case is an exception. The single extra column in the select list must be of a type suitable to hold the user name; for example, VARCHAR(128). The subsequent columns in the list must match the columns of the remote table in order and type, as usual. If you include more than one extra column, an error results.


Miscellaneous techniques
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Miscellaneous techniques

The following techniques are also common.

•	Data Entry    In some databases, there will be tables that are only used for data entry. During each synchronization, all rows inserted since the last synchronization are uploaded. When the download stream is built, all of these newly inserted rows will be removed from the Remote database and the table will be empty again. This can be done by uploading rows into a temporary table and inserting them into a base table using an end_upload table script. The temporary table can be used in the download_delete_cursor to remove rows from the Remote database following a successful synchronization. Alternatively, you can allow the client application to the delete the rows, using the STOP SYNCHRONIZATION DELETE statement to stop the deletes being uploaded during the next synchronization.

•	Handling deletes    When rows are deleted from the consolidated database, there needs to be a record of the row so it can be removed from any Remote databases that have the row.

One technique is to not delete the row. Data that is no longer required can be marked as inactive by changing a status column in the row. The download_cursor and download_delete_cursor can refer to the status of the row in the WHERE clause. The CustDB sample application uses this technique for the ULOrder table using the status column.

This technique is used in the ULEmpCust table in the sample application, in which the action column holds a D for Delete. The scripts use this value to delete the record from the Remote database, and delete the record from the consolidated database at the end of the synchronization.

A second technique is to have a shadow table that stores the primary-key values of deleted rows. When a row is deleted, a trigger can populate the shadow table. The download_delete_cursor can use the shadow table to remove rows from Remote databases. The shadow table only needs to have the primary-key columns from the real table.

•	Handling failed downloads    Bookkeeping information about what is downloaded must be maintained in the download transaction. This information is updated atomically with the download being applied to the Remote database.

If a failure occurs before the entire download stream is applied to the Remote database, the MobiLink synchronization server does not get confirmation for the download and rolls back the download transaction. Since the bookkeeping information is part of the download transaction, it is also rolled back. Next time the download stream is built, it will use the original bookkeeping information.

When testing your synchronization scripts, you should add logic to your end_download script that causes occasional failures. This will ensure that your scripts can handle a failed download.


Schema changes in remote databases
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

 Schema changes in remote databases

When the schema of a remote database changes, you need to re-generate the UltraLite database and build a new application. The application needs to be re-deployed and the new database populated by synchronizing with the MobiLink synchronization server. It is usually impractical to have all users upgrade to the new version of the application at the same time.

You need to be able to have both versions co-existing in the field and synchronizing with a single consolidated database. You can create two or more versions of the synchronization scripts that are stored in the consolidated database and control the actions of the MobiLink synchronization server. Each version of your application can then select the appropriate set of synchronization scripts by specifying the correct version name when it initiates synchronization.

The most common schema changes are to add a new column to an existing table or to add a new table to the database.

 Adding tables to remote databases

 Changing table definitions in remote databases


Adding tables to remote databases
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Schema changes in remote databases

 Adding tables to remote databases

Adding a new table does not create any problem at all. You will have a new row in ml_table and a new set of scripts that correspond to the new table. When a user synchronizes, the upload stream contains a list of the tables in the Remote database. The MobiLink synchronization server only expects data for tables in this list. Only tables listed in the upload stream are synchronized.


Changing table definitions in remote databases
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 5.  Synchronization Techniques

        Schema changes in remote databases

 Changing table definitions in remote databases

Changing the number or type of columns in an existing table must be done carefully. When a newer MobiLink client synchronizes, it expects cursor scripts, such as upload_cursor, download_cursor, that have select lists for all columns in the UltraLite table. An older UltraLite database expects cursor scripts that have only the original columns.

To accommodate the various versions of your application, you can create different versions of the synchronization scripts. Each time a client synchronizes, it specifies the correct script version name. Using this technique, an arbitrary number of versions of your application can co-exist while synchronizing with a single consolidated database.


CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

 CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

About this chapter

This chapter provides a tutorial that guides you through the process of synchronizing two Adaptive Server Anywhere databases via MobiLink. One of these databases is the consolidated database, the other is a remote database. You create these databases and then synchronize the two.

 Introduction

 Creating a SQL file for the consolidated database

 Running the synchronization tutorial

 Summary


Introduction
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

 Introduction

In this tutorial, you create a consolidated database and extract a remote database. The tutorial then guides you to synchronize the two databases via MobiLink.

In order to run the tutorial, you must first create a .sql file for the database. Use the sample code in the section Creating a SQL file for the consolidated database to create a server.sql file. This file creates and populates the tables in the consolidated database. In addition, this file also includes scripts that specify the contents to be uploaded to the consolidated database and downloaded to the remote database.

Reference versus consolidated databases
Do not confuse the reference and the consolidated database. Each has a different role. The reference database is an Adaptive Server Anywhere database that serves as a template for remote Adaptive Server Anywhere databases. The consolidated database is a central store of data, connected to the MobiLink synchronization server. The consolidated database can have a different schema, or even be made using a different database-management system. During this tutorial, you use the same database for both purposes. You can do so only when the consolidated database is an Adaptive Server Anywhere database and when the schema of the consolidated database contains the union of the schemas of the remote Adaptive Server Anywhere databases.

This tutorial assumes that you have installed Adaptive Server Anywhere on Windows 95/98/NT.

♦ To prepare for the tutorial

•	Create a directory to hold the files you will create: c:\synchtutorial.


Creating a SQL file for the consolidated database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

 Creating a SQL file for the consolidated database

The following SQL commands create and insert data into the tables People and Pets in the consolidated database. In addition, synchronization scripts are inserted to produce the desired actions during MobiLink synchronization.

Because this database is an Adaptive Server Anywhere database, it can also be used as a reference database. A reference database that serves as a template for the remote database and the tables and columns of the remote database will be a subset of those found in the reference database.

Copy the following code into a new file and save it as server.sql in your c:\synchtutorial directory.

create table People (

person_id	integer	primary key,

fname	varchar(30),

lname	varchar(40),

notes	varchar(500)

);

create table Pets (

pet_id	integer	primary key,

person_id	integer,

name	varchar( 30 ),

species	varchar( 30 ),

foreign key person_id references People

);

insert

into People

values( 0, 'Alan', 'Able', 'good guy' );

insert

into People

values( 1, 'Betty', 'Best', NULL );

insert

into Pets

values( 0, 0, 'Judy', 'rat' );

insert

into Pets

values( 1, 0, 'Carmel', 'guinea pig' );

insert

into Pets

values( 3, 1, 'Marshall', 'cat' );

commit;

call ml_add_table_script(

'Version1',

'People',

'upload_cursor',

'select person_id, fname, lname from People where

person_id=?'

);

call ml_add_table_script(

'Version1',

'People',

'download_cursor',

'select person_id, fname, lname from People'

);

call ml_add_table_script(

'Version1',

'Pets',

'upload_cursor',

'select pet_id, person_id, name, species from Pets

where pet_id=?'

);

call ml_add_table_script(

'Version1',

'Pets',

'download_cursor',

'select pet_id, person_id, name, species from Pets'

);

commit;

 Explanation of the sample code


Explanation of the sample code
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

        Creating a SQL file for the consolidated database

 Explanation of the sample code

The server.sql sample code creates tables in the consolidated database, inserts data into the tables, and stores synchronization scripts that specify which data is to be uploaded to the consolidated database and downloaded to the remote database.

Create tables

The sample code creates two tables: People and Pets. The People table has the following columns: person_id, fname, lname, and notes. The Pets table has the following columns: pet_id, person_id, name and species.

Insert data

The following is the People table in the consolidated database after data has been inserted:

person_id	fname	lname	notes
0	Alan	Able	good guy
1	Betty	Best	(NULL)
The following is the Pets table in the consolidated database after data has been inserted:

pet_id	person_id	name	species
0	0	Judy	rat
1	0	Carmel	guinea pig
3	1	Marshall	cat
Synchronization scripts

The synchronization scripts indicate that the first three columns in the People table should be uploaded to the consolidated database and downloaded to the remote database, and all four columns in the Pets table are uploaded to the consolidated database and downloaded to the remote database.


Running the synchronization tutorial
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

 Running the synchronization tutorial

After you have created the server.sql file using the sample code in the previous sections, you are ready to begin the tutorial.

In this tutorial, you build a consolidated database, a remote database, and perform synchronization between the two.

 Building the consolidated database

 Extracting the remote database

 Synchronizing the consolidated and remote databases

 Modify the remote database

 Upload changes made to the remote database


Building the consolidated database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

        Running the synchronization tutorial

 Building the consolidated database

Follow these steps to build a consolidated database:

1	Create a new consolidated database.

In your c:\synchtutorial directory, use the following command to create a consolidated database, master.db:

dbinit master.db

2	Start the consolidated database server.

Use the dbeng7 command as follows:

dbeng7 master.db

The database engine starts. The window minimizes automatically once the engine has started successfully.

3	Start Interactive SQL and connect to the consolidated database.

•	In your c:\synchtutorial directory, enter the following command:

start dbisql

•	When the connection dialogue appears, enter master for the name of the database server. Supply the user name DBA and the password SQL. Click OK.

4	Add the database tables and synchronization scripts. To perform this task, use the file server.sql, as described in Creating a SQL file for the consolidated database.

To apply the statements to the master.db database, enter the following command line in Interactive SQL:

•	Choose Run Script from the File menu.

•	Locate the file server.sql, then click Open.

The statements in the file are executed. Your consolidated database now contains two tables with data: People and Pets. In addition, synchronization scripts are stored in the consolidated database. These scripts determine how the data in the upload stream is integrated into the consolidated database and control the preparation of the download stream.

5	Verify that tables have been created and data has been inserted successfully.

•	To display the contents of the People table, enter the following command in the SQL Statements window. Choose Execute from the SQL menu.

select * from People

•	Use the following statement to display the contents of the Pets table.

select * from Pets

6	Create a synchronization template. A synchronization template identifies which tables and columns are to be replicated to a particular server. Use the following statement to create this template.

CREATE SYNCHRONIZATION TEMPLATE testpub

TYPE 'tcpip'

ADDRESS 'host=localhost;port=2439;'

OPTION sv='Version1'

(	TABLE People ( person_id, fname, lname ),

TABLE Pets

);

7	Create a synchronization site. A synchronization site identifies a particular remote database. The description of this site is based on the information in a particular synchronization template. Use the following statement to create a site called demo_sync_site.

CREATE SYNCHRONIZATION SITE 'demo_sync_site'

USING testpub;

In the next section of this tutorial, you will create the appropriate database for this site.

8	Disconnect from the reference database by executing the following SQL statement.

disconnect


Extracting the remote database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

        Running the synchronization tutorial

 Extracting the remote database

1	Ensure that the consolidated database is still running. If it is not, restart the server by entering the following command in your c:\synchtutorial directory.

dbeng7 master.db

2	Extract the remote database.

•	Enter the following command in your c:\synchtutorial directory. Type the entire statement on one line.

mlxtract -c "dbn=master;uid=DBA;pwd=SQL"

-an remote.db

c:\synchtutorial demo_sync_site

This command causes the Sybase database extraction utility to connect to your master database as user DBA and create the database for site demo_sync_site. The new database is called remote.db and is placed in your c:\synchtutorial directory.

3	Shut down the database server.

•	Right-click on the database server icon in the system tray. Select Exit.

4	Start another engine for both the master and remote databases by issuing the following command in your c:\synchtutorial directory.

dbeng7 master.db remote.db

5	Open a new window in Interactive SQL and connect to the remote database.

•	From Interactive SQL, select File [image] New Window.

•	On the Identification tab, supply the user name DBA and the password SQL. On the Database tab, enter the database name remote. Click OK.

When you have successfully connected, the new Interactive SQL window displays.

6	Verify that tables have been created successfully. Note that the tables do not yet contain any data.

•	Enter the following command in Interactive SQL to display the contents of the People table

select * from People

•	Enter the following command in Interactive SQL to display the contents of the Pets table

select * from Pets

7	Disconnect from the remote database by executing the following SQL statement.

disconnect


Synchronizing the consolidated and remote databases
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

        Running the synchronization tutorial

 Synchronizing the consolidated and remote databases

1	If the engine is not still running, start both the master and remote databases by issuing the following command in your c:\synchtutorial directory.

dbeng7 master.db remote.db

2	Create an ODBC data source for the master database. You create this source because the MobiLink synchronization server can connect to the database engine only through ODBC.

•	Open the ODBC Data Source Administrator. From the Windows Start menu, select Programs [image] Sybase [image] SQL Anywhere 7 [image] ODBC Administrator.

•	Add a data source for the master database. Click Add. In the Create New Data Source dialogue, select Adaptive Server Anywhere 7.0, then click Finish.

•	Configure the new data source. Select the ODBC tab and supply the Data source name MobiLink/ASA tutorial. Select the Login tab, then supply the User ID DBA and the password SQL. Select the Database tab and supply the Database file c:\synchtutorial\master.db. Click OK.

•	Click OK again to close the ODBC Data Source Administrator.

3	Start the MobiLink synchronization server.

The following command starts the MobiLink synchronization server and identifies the ODBC data source MobiLink/ASA tutorial as the consolidated database:

start dbmlsrv7 -c "dsn=MobiLink/ASA tutorial"

4	Synchronize the two databases.

Run the command dbmlsync as follows:

dbmlsync -c "dbn=remote;uid=DBA;pwd=SQL"

5	Verify that the data has transferred successfully.

•	Reconnect to the remote database in Interactive SQL.

•	Enter the following command in Interactive SQL to display the contents of the People table

select * from People

•	Enter the following command in Interactive SQL to display the contents of the Pets table

select * from Pets

The People table in the remote database should appear as follows. Note that the remote database lacks the notes column because that column was not mentioned in the synchronization template.

person_id	fname	lname
0	Alan	Able
1	Betty	Best

The Pets table in the remote database should appear as follows.

pet_id	person_id	name	species
0	0	Judy	rat
1	0	Carmel	guinea pig
3	1	Marshall	cat


Modify the remote database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

        Running the synchronization tutorial

 Modify the remote database

In this section, you make some changes to the remote database. Adaptive Server Anywhere uses the synchronization definition to recognize which data must be sent to the consolidated database when you next synchronize.

1	Add a new person to the remote database: In your Interactive SQL window for the remote database, enter the following statement

insert into People values( 2, 'Charles', 'Cutty')

2	Add Charles's pet guinea pig using the following statement.

insert into Pets

values( 4, 2, 'Hershey', 'guinea pig' )

3	Alan gives Carmel the guinea pig to Charles. Execute the following statement to record the transfer.

update Pets

set person_id = 2

where name = 'Carmel'

4	Add a new person.

insert into People values ( 3, 'Jerry', 'Small' );

5	Commit these changes.

commit

6	Verify your changes.

•	Enter the following command in Interactive SQL to display the contents of the People table

select * from People

•	Enter the following command in Interactive SQL to display the contents of the Pets table

select * from Pets

The People table in the remote database should appear as follows.

person_id	fname	lname
0	Alan	Able
1	Betty	Best
2	Charles	Cutty
3	Jerry	Small

The Pets table for both databases should appear as follows.

pet_id	person_id	name	species
0	0	Judy	guinea pig
1	2	Carmel	guinea pig
3	1	Marshall	cat
4	2	Hershey	guinea pig
7	Disconnect from the remote database by executing the following SQL statement.

disconnect


Upload changes made to the remote database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

        Running the synchronization tutorial

 Upload changes made to the remote database

1	Ensure that the MobiLink synchronization server is still running. If it is not, restart it as described previously in section Synchronizing the consolidated and remote databases.

2	Synchronize the two databases.

Run the command dbmlsync as before:

dbmlsync -c "dbn=remote;uid=DBA;pwd=SQL"

3	Open a new window in Interactive SQL and connect to the master database.

•	From Interactive SQL, select File [image] New Window.

•	On the Identification tab, supply the user name DBA and the password SQL. On the Database tab, enter the database name master. Click OK.

When you have successfully connected, the new Interactive SQL window displays.

4	Verify that the databases have been synchronized.

•	Enter the following command in Interactive SQL to display the contents of the People table

select * from People

•	Enter the following command in Interactive SQL to display the contents of the Pets table

select * from Pets

The People table in the master database should appear as follows.

person_id	fname	lname	notes
0	Alan	Able	good guy
1	Betty	Best	(NULL)
2	Charles	Cutty	(NULL)
3	Jerry	Small	(NULL)

Notice that a new row for Charles Cutty is present. A new row for Jerry Small is also present.

The Pets table for both databases should appear as follows.

pet_id	person_id	name	species
0	0	Judy	guinea pig
1	2	Carmel	guinea pig
3	1	Marshall	cat
4	2	Hershey	guinea pig

The entry with a person_id of 3, which prior to synchronization only existed in the consolidated database, now appears in both databases after synchronization.

In addition, the inserts and updates made only to the remote database prior to synchronization now apply to both databases after synchronization. The consolidated database now also has the entries with pet_id 4 and indicates that Charles Cutty now owns Carmel the guinea pig.

5	Close your connections and exit Interactive SQL.

•	Disconnect from the master database and from the remote database by executing the following SQL statement in each Interactive SQL window.

disconnect

•	Exit Interactive SQL.

6	Shutdown the MobiLink synchronization server by issuing the following command.

dbmlstop

7	Shutdown the database server.

•	Right-click on the database server icon in the system tray. Select Exit.


Summary
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 6.  Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial

 Summary

During this tutorial, you accomplished the following tasks.

•	Created a new Adaptive Server database that served as both the consolidated database and the reference database.

•	Created a synchronization template and synchronization site that defined which tables and columns were to be extracted for the remote database.

•	Extracted a remote database, using the original database as the reference database.

•	Started a MobiLink synchronization server, using the original database as the consolidated database, and synchronized the remote database in order to download an initial set of data.

•	Synchronized the remote database again, uploading your changes to the consolidated database.


CHAPTER 7.  Adaptive Server Anywhere Clients
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

 CHAPTER 7.  Adaptive Server Anywhere Clients

About this chapter

This chapter describes how to use Adaptive Server Anywhere as a MobiLink client.

 Introduction

 Synchronization definitions

 Writing synchronization definitions

 Initiating synchronization

 Deployment management

 The reference database

 Extracting the remote databases

 Partitioning data between remote sites

 Temporarily stopping synchronization of deletes

 Customizing the synchronization process


Introduction
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Introduction

Adaptive Server Anywhere databases can serve as remote databases in a MobiLink setup, synchronizing with MobiLink synchronization servers using functionality supplied with the database engine.

Two-way replication

Data can be replicated in both directions. Definition statements, stored within each Adaptive Server Anywhere remote database, specify which data in the client database is to be synchronized with a particular synchronization server. Synchronization scripts, stored in the consolidated database, guide the MobiLink synchronization server in processing uploaded data and selecting data for download to the client.

MobiLink clients initiate synchronization. To synchronize an Adaptive Server Anywhere remote database, use the dbmlsync command-line utility.

During the synchronization process, all synchronized data in the remote database that has changed since the previous synchronization is uploaded to the MobiLink synchronization server. The MobiLink synchronization server incorporates these changes into the consolidated database, then selects consolidated data that is to be sent to the client. When the client has incorporated the downloaded data, it sends a confirmation message to the server, completing the synchronization process.


Synchronization definitions
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Synchronization definitions

To convert an Adaptive Server Anywhere database for use as a MobiLink client, you create a synchronization definition in the remote database. A synchronization definition is a database object describing the data in a remote Adaptive Server Anywhere database that is to be synchronized and the location of a particular MobiLink synchronization server with which to synchronize it. Synchronization definitions are required only in Adaptive Server Anywhere remote databases.

A single Adaptive Server Anywhere database can synchronize with more than one MobiLink synchronization server. To allow synchronization with multiple servers, create one synchronization definition for each server.

Example

To synchronize the Customer and Sales_Order tables in a remote Adaptive Server Anywhere database, you could create the following synchronization definition in the remote database.

CREATE SYNCHRONIZATION DEFINITION testpub

SITE 'demo_sync_site'

TYPE 'tcpip'

ADDRESS 'host=localhost;port=2439;'

OPTION sv='version1'

(table Customer,table Sales_Order);

The SITE clause specifies that this particular MobiLink client is to be known to the MobiLink synchronization server by the unique name demo_sync_site. Synchronization is to occur over a TCP/IP connection. The synchronization server is to use the version1 version of the synchronization scripts when interacting with this client.

Comparison to SQL Remote
Should you already be familiar with Sybase SQL Remote, you will recognize that synchronization definitions are very similar to the SQL Remote concept of publications. The data replicated by SQL Remote is arranged in publications. Each database that shares information in a publication must have a subscription to the publication. Unlike publications, synchronization definitions are required only in the remote database. In addition, unlike publications, synchronization definitions include the connection parameters for one particular MobiLink synchronization server.

Synchronization definitions define which remote data is synchronized

You can choose to synchronize all or any portion of the data in a remote Adaptive Server Anywhere database. You can choose to synchronize entire tables, or you can choose to synchronize only particular columns and rows.

The synchronization definition, located in the remote Adaptive Server Anywhere database, describes the data that is to be replicated and the location of the appropriate MobiLink synchronization server.

Synchronization scripts, stored in the consolidated database, control how the uploaded rows are processed and which rows are downloaded to the remote site. These scripts do not depend on the type of remote database.

A synchronization definition may include data from several database tables. Each table's contribution to a synchronization definition is called an article. Each article may consist of a whole table, or a subset of the rows and columns in a table.

Synchronizing a remote database

Once a remote database has been set up, the two databases must be periodically brought to a state where they both have the same set of information. This process of updating the consolidated and remote databases to be consistent is called synchronization. Synchronization is carried out using the dbmlsync command-line utility.

Altering a synchronized table

A table, once added to a synchronization definition, should not be altered. Altering the table interferes with the synchronization process. Should it be necessary to make such an alteration, this step should be performed immediately following synchronization.

The only way to ensure that the ALTER STATEMENT is executed immediately following synchronization is to place this statement in a script, then execute that script using the -i switch of the dbmlsync command-line utility.


Writing synchronization definitions
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Writing synchronization definitions

The synchronization definition is a database object describing data in a remote Adaptive Server Anywhere database that is to be replicated and the location of a particular MobiLink synchronization server. A synchronization definition is defined only in a remote database. MobiLink consolidated servers are configured using scripts.

A synchronization definition specifies the following pieces of information

•	name    The name of the synchronization definition, known only within the remote database.

•	site    A name that uniquely identifies this particular MobiLink client.

•	type    The type of stream to be used to communicate with the MobiLink synchronization server.

•	address    The parameters necessary to connect to the MobiLink synchronization server.

•	script version    The version of the synchronization scripts the MobiLink synchronization server is to use when synchronizing this client.

•	articles    A description of the data to be synchronized. You can synchronize entire tables, or only particular rows and columns.

The following statement creates a synchronization definition named testpub that defines what data is to be synchronized with site demo_sync_site.

CREATE SYNCHRONIZATION DEFINITION testpub

SITE 'demo_sync_site'

TYPE 'tcpip'

ADDRESS 'host=localhost;port=2439;'

OPTION sv='version1'

(table People( person_id, fname, lname ),table Pets);

Note the following specific components of this statement.

•	The name of this synchronization definition is testpub. This name is only known within the remote database.

•	The name demo_sync_site uniquely identifies this client to the MobiLink synchronization server. This name should appear in the ml_user MobiLink system table, located in the consolidated database.

•	The synchronization is to occur over a TCP/IP connection. The connection parameters appear in a string in the ADDRESS clause.

•	The MobiLink synchronization server is to use the set of synchronization scripts identified by the name version1 when synchronizing this client. This script version name should appear in the ml_script_version MobiLink system table, located in the consolidated database.

•	All columns and rows of the Pets table and the listed columns of the People table are to be synchronized.

The TCP/IP connection parameters, appearing as a string in the address clause, show that the MobiLink synchronization server is listening on port 2439 of the current machine. Only the listed columns of the People table are synchronized. The option clause is included to indicate that the MobiLink synchronization server should use version1 of the synchronization scripts when processing data from this client. The default value of this parameter is default. Notice that the list of columns is also enclosed in parentheses.

  For a complete description of the syntax, see CREATE SYNCHRONIZATION DEFINITION statement.

Comparison to UltraLite clients

If you have developed UltraLite applications for use as MobiLink clients, the following information may be helpful. Many of the elements of a synchronization definition have an UltraLite counterpart.

Adaptive Server Anywhere client	UltraLite client synchronization calls	MobiLink synchronization server
name	data structure identifier	none
site	user name	MobiLink user name
type	stream	connection type
address	connection parameters	location of server
script version (sv)	version	script version
articles	none—all UltraLite tables are synchronized	none
Synchronizing with multiple servers

To synchronize a remote Adaptive Server Anywhere database with multiple MobiLink synchronization servers, create multiple synchronization definitions within the remote database. Each synchronization definition must have a unique site name because, from the point of view of the MobiLink synchronization server, each is a separate logical client.

Synchronizing the same data in one remote database with multiple MobiLink synchronization servers is not presently supported.


Initiating synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Initiating synchronization

MobiLink synchronization is always initiated by the client. In the case of an Adaptive Server Anywhere client, synchronization is initiated by running the dbmlsync utility on the client. This utility connects to a remote Adaptive Server Anywhere database.

You can specify connection parameters for the remote Adaptive Server Anywhere database on the dbmlsync command line using the -c switch. Do not specify the connection parameters for the MobiLink synchronization server. Information in the synchronization definition within the remote database is used to connect to the appropriate MobiLink synchronization server. If you do not specify connection parameters, then dbmlsync displays a connection dialog with fields to supply the connection parameters and startup options.

Permissions for dbmlsync

When dbmlsync connects to a database, it must have permissions to apply all the changes being made. The dbmlsync command line contains the password for this connection. This could present a security issue.

To avoid security problems, you can grant a user REMOTE DBA authority, and use this user ID in the dblmsync connection string. A user ID with REMOTE DBA authority has DBA authority when the connection is made from the dbmlsync utility, but no special authority from any other application.

  This REMOTE DBA authority method is also used by the SQL Remote Message Agent. For more information, see The Message Agent and replication security.

Transaction log files

To prepare the upload stream, the dbmlsync utility requires access to all transaction logs written since the previous synchronization. The transaction-logs directory is the directory that contains previous transaction log files for the remote Adaptive Server Anywhere client database. If the transaction log has been truncated and renamed since the previous synchronization, specify the directory that contains the renamed log files on the command line.

You may omit this parameter only if the working log file has not been truncated and renamed since you last synchronized, or if the dbmlsync utility is run from the directory that contains the renamed log files. Log files are commonly renamed and truncated when backing up the database, so it may be necessary to specify the transaction logs directory if you have backed up the remote database since you last synchronized.

For the same reason, it is essential that old log files be saved until a more recent synchronization has completed successfully.

Example

Suppose that you have remote database named remote. This database, which is currently running on your local machine, contains the appropriate synchronization definition to allow the correct information to be synchronized with the intended MobiLink synchronization server. In addition, assume that the MobiLink synchronization server has been started. You could use the following command to synchronize as user DBA.

dbmlsync -c "dbn=remote;uid=dba;pwd=sql" c:\data

This command assumes that the log files for this database are located in the directory c:\data.

If the remote database contains more than one synchronization definition, you must specify a particular synchronization definition using the -n switch. In particular, you must use this feature if the remote database contains multiple MobiLink clients.

Scheduling synchronization

You can schedule synchronizations at specific time intervals.

  For more information see Scheduling synchronization

You can also use the scheduling tools available on your operating system to run the dbmlsync utility at the required time intervals.

  For a list of the available parameters, see dbmlsync command line.

 Including dbmlsync functionality in an application

 Tuning synchronization

 Concurrency during synchronization


Including dbmlsync functionality in an application
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Initiating synchronization

 Including dbmlsync functionality in an application

Some users may wish to include the features of dbmlsync in their own application rather than provide a separate executable to their customers. You can do this if you are developing in C, using the dbtools.h header file included in the h subdirectory of your SQL Anywhere directory.

The dbtools.h header file includes a description of the a_sync_db structure and the DBSynchronizeLog function, which you need to use in adding this functionality to your application.

  For more information, see DBSynchronizeLog function, and a_sync_db structure.


Tuning synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Initiating synchronization

 Tuning synchronization

MobiLink provides a number of extended options to tune the synchronization process. These extended options can be provided in the CREATE SYNCHRONIZATION DEFINITION statement at the Adaptive Server Anywhere client database, or in the dbmlsync command line . If values are supplied in both places, the command-line overrides the SQL statement.

♦ To specify an extended option (Command line):

•	Supply the option values in the -e command-line option for dbmlsync, in the form option-name=value. For example:

dbmlsync -c "dsn=dsn_name" -e "v=on;sc=low"

  For more information, see dbmlsync command line.

♦ To specify an extended option (SQL):

•	Add the option to the CREATE SYNCHRONIZATION DEFINITION statement in the Adaptive Server Anywhere client database. For example:

CREATE SYNCHRONIZATION DEFINITION syncdef

SITE 'mysite'

ADDRESS 'host=test.internal;port=2439;'

OPTION memory='3m',inc=3k

  For more information, see CREATE SYNCHRONIZATION DEFINITION statement.

or

Add the option to the CREATE SYNCHRONIZATION TEMPLATE or CREATE SYNCHRONIZATION SITE statement in the reference database and then run mlxtract to create the client database.

Using extended options

The extended options provide ways to optimized the performance for accumulating and sending the upload stream to the consolidated database.

•	Increment    If you do not specify an incremental log-processing memory limit, then the whole upload stream is assembled, and then sent in a single transfer to the consolidated database.

If you specify an incremental log-processing memory limit, then once the limit is reached, dbmlsync looks for the next point in the stream at which there are no outstanding partial transactions, and sends the upload at that time. This provides you with a way of limiting memory requirements.

•	Memory    As the upload stream is being assembled, dbmlsync uses a cache to hold the stream. If the upload stream fills the cache, contents are stored temporarily on disk. There is a performance impact of using the disk instead of memory for holding the upload stream.

By default, dbmlsync uses a 1 MB cache. If you are uploading large numbers of changes and have extra memory available, increasing the cache provides improved performance.

•	Schedule    This option instructs dbmlsync to run continuously, and synchronize at specified times.

  For more information on how to specify scheduled times, see Scheduling synchronization.

•	StreamCompression    This option controls how much the upload stream is compressed before being sent to the consolidated database. Compression requires additional processing time, but cuts down on the delivery time: using high compression is therefore especially valuable for speeding up synchronization over slow networks.


Concurrency during synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Initiating synchronization

 Concurrency during synchronization

By default, the dbmlsync utility requires exclusive write access to all tables in the synchronization definition. No other application can modify these tables at the same time. If synchronization is initiated when there are other connections to the remote database, write locks held by these connections can prevent synchronization from proceeding. In this case, synchronization is delayed until the other connections release their locks.

Sometimes, as is often the case for embedded applications, it may be possible to schedule synchronization only when no other operations are occurring in the remote database. Even when the remote database is used by a number of users or applications, it may be possible to find times of no activity during which synchronization can safely occur.

Once synchronization commences, other users are denied write access to the synchronized data. All processes requiring write access to the synchronized data must wait for the synchronization process to complete. The duration of this delay depends upon the amount of data to be exchanged, the speed of the connection to the MobiLink synchronization server, and the load on the server itself.

Forcing other connections to close

In some applications, it is essential that synchronization proceed as planned. In such situations, you can use the dbmlsync -d switch to force the remote database to drop all other connections that are presently using resources required for synchronization.

When you do so, synchronization will proceed almost immediately, but other connected users or applications may be abruptly disconnected. Uncommitted changes are rolled back, so these users or applications must reconnect later to repeat any incomplete transactions.

Permitting concurrency during synchronization

You can permit other applications to obtain access to rows during synchronization by setting the LockTables (short form lt) extended option to OFF in the synchronization definition or on the dbmlsync command line. Even with this setting, rows modified by the synchronization process are still locked, as they would be by any other database connection.

The dbmlsync utility detects rows that are modified by other connections between the upload phase and the download phase.

If a conflict is detected, the download phase is cancelled and the download operations rolled back to avoid overwriting the new change. The dbmlsync utility then retries the synchronization, including the upload step. This time, because the row is present at the beginning of the synchronization process, it is included in the upload stream and therefore not lost.

By default, dbmlsync retries the synchronization after a conflict until no conflict occurs You can customize this behavior by setting the extended option conflictretries (short form cr). The default value for conflictretries is -1, which indicates that dbmlsync should continue retrying until successful. A value of any non-negative integer N indicates that dbmlsync should retry up to N times if not successful.


Deployment management
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Deployment management

To deploy multiple Adaptive Server Anywhere clients, you must first create the required remote databases and fill these databases with initial data. In addition, you must create a synchronization definition in each remote database. This database object specifies the synchronized data, the MobiLink connection parameters, and the client's unique name.

You can create each remote database individually using standard administration tools such as Sybase Central, but Adaptive Server Anywhere also includes specialized tools to facilitate this task.

When developing Adaptive Server Anywhere clients, you will be working with the following tools.

•	A reference database    A reference database is an Adaptive Server Anywhere database that serves as a template of the remote Adaptive Server Anywhere databases.

•	A database extraction utility    An extraction utility called mlxtract creates each remote database based on information in the reference database.

 Creating multiple remote databases

 Troubleshooting deployment


Creating multiple remote databases
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Deployment management

 Creating multiple remote databases

The following procedure allows you to efficiently create a multiple Adaptive Server Anywhere remote databases.

♦ To create Adaptive Server Anywhere client databases

1	Create an Adaptive Server Anywhere reference database.

2	Create one or more synchronization templates in the reference database. Each synchronization template serves as a model of the synchronization definition to be created in one type of remote site.

3	Create one synchronization site for each remote database, giving each site a unique name.

4	Using the mlxtract command-line utility, create each remote database in turn.

  For information about the reference database, see The reference database.

  For information about extracting the remote databases, see Extracting the remote databases.


Troubleshooting deployment
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Deployment management

 Troubleshooting deployment

If you install a new Adaptive Server Anywhere client database, produced for example with mlxtract, over an older version, the synchronization progress information stored in the consolidated database is incorrect.

You can correct this problem by setting the progress column of the ml_user table to 0 (zero) for this user. This is an exceptional case when direct modification of the MobiLink system tables is required. In other cases, you should not directly access the MobiLink system tables.


The reference database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 The reference database

A reference database is an Adaptive Server Anywhere database that serves as the template of the remote Adaptive Server Anywhere databases that you plan to create.

The schema of the reference database must contain the union of the schemas of the remote databases. In other words, each remote database must contain a subset of the tables, columns, and indexes found in the reference database.

The schema of the reference database may, but need not, be similar to the schema of the consolidated database.

In addition to the database schema, you must create two types of database objects within the reference database.

•	synchronization template    A synchronization template is a template of the synchronization definition statements that are to appear in the remote databases. It typically contains all the information in the synchronization definitions, except for the client name, which would normally appear in the SITE clause.

•	synchronization sites    A synchronization site is an object that specifies which synchronization template is to be used when creating a specific client. You create one synchronization site object for each Adaptive Server Anywhere remote database you plan to create.

A typical reference database contains one synchronization template and multiple synchronization sites, one for each remote Adaptive Server Anywhere database. Each synchronization site specifies the MobiLink client name.

Creating templates and sites

A synchronization template is similar to a synchronization definition. Thus, a synchronization template is created in almost the same manner. The major difference is that a template contains no SITE clause, since the client names are specified separately.

CREATE SYNCHRONIZATION TEMPLATE ClientTypeOne

TYPE 'tcpip'

ADDRESS 'host=localhost;port=2439;'

OPTION sv='version1'

(table People( person_id, fname, lname ),table Pets);

Once you have created a template, you can use it to create multiple synchronization sites. For example, the following statement creates a client named demo_sync_site.

CREATE SYNCHRONIZATION SITE demo_sync_site

USING ClientTypeOne

Create one site for each remote database.

Creating different types of sites

A synchronization site can also override information contained in the synchronization template. This feature is useful when a few sites require different settings.

When remote sites differ significantly, you can create a separate synchronization site for each type of client and specify the appropriate template when you create each synchronization site.

 The reference versus the consolidated database


The reference versus the consolidated database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        The reference database

 The reference versus the consolidated database

Do not confuse the reference database with the consolidated database. The consolidated database serves as the master repository of data in your replication system. The reference database is a template from which you can extract remote databases.

The following characteristics differentiate the reference database from the consolidated database.

•	database product    The reference database must be built with Adaptive Server Anywhere. In contrast, MobiLink supports a number of database products in the role of consolidated database, including Sybase Adaptive Server Anywhere, Sybase Adaptive Server Enterprise, Oracle, and IBM DB2.

•	presence of data    The consolidated database is the master repository of information in the synchronization system. In contrast, the reference database need not contain data. Optionally, you can populate the reference database with data that you want the remote databases to contain initially.

•	schema    The schema of the reference data is a template for the remote databases. In contrast, MobiLink technology allows the consolidated database to have a different structure. For example, the data stored in a particular table and column at one client can be stored in a different table and column at another client, and in yet another location at the consolidated database.

Can a consolidated database function as a reference database?

When the following conditions are satisfied, a consolidated database can serve as a reference database. Using one database for both purposes is convenient, as you need maintain only one database instead of two.

•	The consolidated database must be created with Adaptive Server Anywhere.

•	The schema of the consolidated database must be a superset of the union of the schemas at the remote sites. In other words, the tables and columns at each remote site must exist in the consolidated database.


Extracting the remote databases
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Extracting the remote databases

The mlxtract command-line utility is used to create each remote database. Each remote database is created using a unique synchronization site, contained in the reference database.

Run the mlxtract command-line utility once for each remote database. Specify a different synchronization site name is each time. This process is called extracting the remote databases because the remote databases are created from the reference database.

The mlxtract command-line utility unloads a database schema suitable for building a remote Adaptive Server Anywhere database for a named site. It writes an SQL-language command file with the default name reload.sql. This file includes a fully qualified synchronization definition. By default, only the schema and synchronization definition are extracted. Use the -id command-line switch to also extract an initial set of data.

Preparing to extract

You must complete the following tasks before extracting the remote databases.

•	Create a reference database.

•	Define the tables and columns that are to appear in the remote databases.

•	Create one more synchronization template using the CREATE SYNCHRONIZATION TEMPLATE statement.

•	Create one synchronization definition for each remote database using the CREATE SYNCHRONIZATION SITE statement.

♦ To extract a remote database

1	Run the mlxtract command-line utility, specifying the name of the client. The utility writes a reload.sql command file for the named client.

2	Create an Adaptive Server Anywhere database using Sybase Central or the dbinit command-line utility.

3	Start the new database.

4	Connect to the new database from Interactive SQL:

5	Run the reload command file by entering the following statement in the Interactive SQL window:

read path\reload.sql

Optionally, you can use the -an switch for mlxtract to combine these steps into one operation.

The format of Adaptive Server Anywhere database files is independent of both operating system and file system. You can create the database under one operating system, then copy the database and log file to another machine. For example, you could create a database on a Windows machine, then copy it to a UNIX machine and use it with an Adaptive Server Anywhere server running there.

Tip
The database extraction utility is intended to assist in preparing remote databases, but is not a black box solution in all circumstances. To provide custom solutions, you can edit the reload.sql command file. In particular, if you are extracting a very large number of clients, you may find it more efficient to run the mlxtract utility only once, then customize the reload.sql command file for each client.

  For an example of how these commands are used to extract a remote site, see Adaptive Server Anywhere Synchronization using MobiLink - A Tutorial.

 Before extracting a remote database


Before extracting a remote database
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Extracting the remote databases

 Before extracting a remote database

The extraction utility relies on a reference database. A reference database is an Adaptive Server Anywhere database that contains a superset of the tables and columns that will exist at the remote sites. The extraction utility uses the reference database as a template when creating the reload scripts for the remote databases.

In addition, you must define a synchronization template and a synchronization site that describe the requirements of the remote databases. A synchronization template is very similar to a synchronization definition, but instead of defining a complete synchronization definition for the current database, it acts as a template for the creation of remote sites.

You create particular instances of remote sites using the CREATE SYNCHRONIZATION SITE statement. Each site relies on a particular synchronization template. Your reference database can contain more than one synchronization template and many synchronization sites can use the same template. Each synchronization site, however, can use only one template.


Partitioning data between remote sites
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Partitioning data between remote sites

It is common for remote sites to fall into separate categories, each with their own requirements. Consider a sales application. All the sales personnel in one region may require access to a particular set of data, but not require access to information about regions other than their own. Employees in other departments may require data of an entirely different nature. Managers may require data that should not be accessible to their subordinates.

Synchronization templates are typically used to specify fundamentally different sets of data. For example, you can create one template for the sales staff and another template for those employees who do technical support.

You can further fine-tune the data any given remote database will receive by using a conditional clause within the synchronization definition. This feature is useful when remote sites require similar types of information. For example, it can be used to provide sales representatives with only the information relevant to their region.

Example

Assume that you have three different categories of personnel at your company: manager, sales agent, and consultant. All employees in your company that you wish to deploy fall within one of the above categories. The personnel in each category require a different synchronization schema from the personnel in other categories. For example, the managers require a different set of tables from the sales agents and consultants. The sales agents will require a different set of tables from the managers and consultants. The consultants require a different set of tables from the other two groups.

Using templates, you can easily generate and re-generate databases for deployment. If you decide to change the remote databases, for example add a new table, you only need to modify the reference database, then re-extract the remote sites.

Since each group requires a different schema, you should create three different synchronization templates in the reference database, one template for each group. Next, create a synchronization site in the reference database for each remote database. When creating each site, use the template that best suites the user's requirements. Finally, create the remote databases using the mlxtract command-line utility.

  For information on mlxtract, see The extraction command-line utility.


Temporarily stopping synchronization of deletes
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Temporarily stopping synchronization of deletes

Ordinarily, Adaptive Server Anywhere automatically logs any changes to tables or columns that are part of a synchronization definition. These changes are uploaded to the consolidated database during the next synchronization.

There can be circumstances, however, when you wish to delete rows from synchronized data and not have those changes uploaded. This feature can be used to make unusual corrections, for example, but should be used with caution as it effectively disables part of the automatic synchronization functionality. This technique is a practical alternative to deleting the necessary rows using a download_delete_cursor script

When a STOP SYNCHRONIZATION DELETE statement is executed, none of the delete operations subsequently executed on that connection are synchronized. The effect continues until a START SYNCHRONIZATION DELETE statement is executed or until the transaction is terminated by a COMMIT or ROLLBACK statement, whichever comes first. The effects do not nest; that is, subsequent executions of stop synchronization delete after the first will have no additional effect.

♦ To temporarily disable upload of deletes made through a connection

1	Issue the following statement to stop automatic logging of deletes.

STOP SYNCHRONIZATION DELETE

2	Delete rows from the synchronized data, as required, using the DELETE statement. Commit these changes.

3	Restart logging of deletes using the following statement.

START SYNCHRONIZATION DELETE

The deleted rows will not be sent up to the MobiLink synchronization server and hence will not be deleted from the consolidated database.


Customizing the synchronization process
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

 Customizing the synchronization process

The Adaptive Server Anywhere synchronization client dbmlsync provides a set of event hooks that you can use to customize the synchronization process at Adaptive Server Anywhere clients. Each event hook is identified by a stored procedure name. By writing a stored procedure with the supplied name, you program a set of events that are executed during synchronization.

You can use the event hooks to delay synchronization until a specific condition is met (which may depend on the number of changes, on a particular change being made, or on some data-independent condition). Alternatively, you can use the event hooks to synchronize subsets of data that cannot be included in a synchronization definition: one approach would be to create a synchronization definition that is composed of temporary tables, and use the event hook procedures to copy the required data into and out of those tables before and after the synchronization stages.

The event-hook stored procedures are executed on the same connection as the synchronization itself. You must not cause an implicit or explicit commit or rollback within your event-hook procedures.

 Synchronization event hook sequence

 Using event-hook procedures

 Scheduling synchronization


Synchronization event hook sequence
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

 Synchronization event hook sequence

The following description lists each event at an Adaptive Server Anywhere client in order. For example, sp_hook_dbmlsync_abort is the first event hook to be invoked.

In the pseudo-code below, events are followed by the parameters that any procedure associated with that event can accept. For example, the sp_hook_dbmlsync_begin procedure has a single parameter, which is the user name that the application supplied in the synchronization call.

Although the sequence has similarities to the event sequence at the MobiLink synchronization server, there is little overlap in the kind of logic you would want to add to the consolidated and client databases. The two interfaces are therefore separate and distinct.

The following pseudo code outlines the sequence in which events are invoked. The parameters are indicated in square brackets to emphasize that they are not stored procedure arguments: they are values held in a temporary table, discussed in Using event-hook procedures. The procedure sp_hook_dbmlsync_upload_end is called regardless of whether the upload succeeds or fails.

sp_hook_dbmlsync_abort

loop until return codes direct otherwise (

  sp_hook_dbmlsync_abort

  sp_hook_dbmlsync_delay

)

sp_hook_dbmlsync_abort

// start synchronization

sp_hook_dbmlsync_begin

// upload events

 sp_hook_dbmlsync_logscan_begin

sp_hook_dbmlsync_logscan_end

sp_hook_dbmlsync_upload_begin

sp_hook_dbmlsync_upload_end

//Note: No check here for the success of the upload.

// download events

sp_hook_dbmlsync_download_begin

for each table

  sp_hook_dbmlsync_table_begin

  sp_hook_dbmlsync_table_end

next table

sp_hook_dbmlsync_download_end

// end synchronization

sp_hook_dbmlsync_end

The following check tests to determine whether or not the upload succeeds or fails:

CREATE PROCEDURE sp_hook_dbmlsync_upload_end()

BEGIN

  IF EXISTS( SELECT 1

               FROM #hook_dict

              WHERE name  = 'upload_status'

                AND value = 'committed'     ) THEN

      UPDATE sync_params

         SET sync_required = 'N';

  END IF;

END;


Using event-hook procedures
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

 Using event-hook procedures

This section describes some considerations for designing and using event-hook procedures.

 Event-hook procedure owner

 Connections for event-hook procedures

 Event arguments

 Ignoring errors in event-hook procedures

 Do not commit or rollback in event-hook procedures


Event-hook procedure owner
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

          Using event-hook procedures

 Event-hook procedure owner

The event-hook connection calls the stored procedures without qualifying them by owner. The stored procedures must therefore be owned by one of the following:

•	The user name employed on the dbmlsync connection (typically a user with REMOTE DBA authority).

•	A group ID of which the dbmlsync user is a member.


Connections for event-hook procedures
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

          Using event-hook procedures

 Connections for event-hook procedures

Each event-hook procedure is executed on the same connection as the synchronization itself. The following are exceptions:

•	sp_hook_dbmlsync_download_com_error

•	sp_hook_dbmlsync_download_fatal_sql_error

These procedures carry out operations before a synchronization fails. On failure, synchronization actions are rolled back. By operating on a separate connection, you can use these procedures to log information about the failure, without the logging actions being rolled back along with the synchronization actions.


Event arguments
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

          Using event-hook procedures

 Event arguments

The event-hook stored procedures share with dbmlsync a temporary table called #hook_dict. This table has the following columns:

name varchar( 128 ) not null unique,

value varchar( 255 ) not null

For example, one row contains a name of synchronization definition name, and a value that is the name of the particular synchronization definition being synchronized.

There are no arguments to any of the event-hook stored procedures. Instead, event arguments are exchanged by reading and writing the named values from the #hook_dict table.

Before calling any of the stored procedures, dbmlsync checks the #hook_dict table, and adds any unset parameters with default values. Each stored procedure can modify the values in the table, and dbmlsync checks the values after the procedure has terminated, to decide what action to take next.

  For information on the event arguments used by each procedure, see Client event-hook procedures.

Examples

The following sample sp_hook_dbmlsync_delay procedure, illustrates the use of the #hook_dict table to pass arguments. The procedure allows synchronization only outside a scheduled down time of the MobiLink system.

create procedure sp_hook_dbmlsync_delay()

begin

  declare down_time_start time;

  declare is_down_time varchar(128);

  set down_time_start='19:00';

  if abs( datediff( minute,down_time_start,now(*) ) <

    60 ) then

    set is_down_time='60';

  else

    set is_down_time='0';

  end if;

  update #hook_dict set

  value = is_down_time where

  name = 'delay duration'

end

The following examples illustrate how to retrieve and set values in the #hook_dict table

create procedure sp_hook_dbmlsync_begin()

begin

  declare syncdef varchar( 128 );

  select '>>>syncdef = ' || value

  into syncdef

  from #hook_dict

  where name ='synchronization definition name';

  message syncdef type info to console;

end

go

create procedure sp_hook_dbmlsync_delay()

begin

  declare is_down_time varchar( 128 );

  select value

  into is_down_time

  from #hook_dict

  where name = 'delay duration';

  message 'is_down_time = ' || is_down_time

  type info to console;

  if ( is_down_time = '4' ) then

    set is_down_time='0';

    message 'set to zero' type info to console;

  else

    set is_down_time='4';

    message 'set to 4' type info to console;

  end if;

  update #hook_dict set

  value = is_down_time where

  name = 'delay duration';

  update #hook_dict set

  value = '14' where

  name = 'maximum accumulated delay';

end

go


Ignoring errors in event-hook procedures
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

          Using event-hook procedures

 Ignoring errors in event-hook procedures

By default, synchronization stops when an error is encountered in an event-hook procedure. You can instruct the dbmlsync utility to ignore errors that occur in event-hook procedures by supplying the -eh command-line option.


Do not commit or rollback in event-hook procedures
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

          Using event-hook procedures

 Do not commit or rollback in event-hook procedures

The transaction structure of a synchronization is maintained by the dbmlsync utility. Do not carry out COMMIT or ROLLBACK operations within an event-hook procedure: if you do, synchronization will fail.


Scheduling synchronization
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

 Scheduling synchronization

Instead of running dbmlsync in a batch fashion, where it synchronizes and then shuts down, you can set up an Adaptive Server Anywhere client so that dbmlsync runs continuously, synchronizing at predetermined times.

You specify the synchronization schedule as an extended option. It can therefore be specified either on the dbmlsync command line or in the synchronization definition. It can be included in the synchronization definition directly, or by adding it to the synchronization template or site within the reference database, and using mlxtract to produce the Adaptive Server Anywhere client database.

♦ To add scheduling to a synchronization definition:

•	Include the Schedule or sch option in the statement. For example:

CREATE SYNCHRONIZATION DEFINITION mydef

ADDRESS 'host=localhost'

OPTION sch='weekday@11:30am-12:30pm', dir='c:\db\logs'

( TABLE ... )

  For information on adding extended options to synchronization definitions, see CREATE SYNCHRONIZATION DEFINITION statement.

♦ To add scheduling on the dbmlsync command-line:

•	Include the Schedule or sch option on the -e command-line switch. For example:

dbmlsync -e SCH='weekday@11:30am-12:30pm', ...

  For information on adding extended options to the dbmlsync command line, see Adaptive Server Anywhere client synchronization utility.

If scheduled synchronization is specified in either place, dbmlsync does not shut down after synchronizing, but runs continuously. If scheduled synchronization is specified in both the synchronization definition and the command line, the command line receives priority.

 Constructing schedule strings


Constructing schedule strings
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 7.  Adaptive Server Anywhere Clients

        Customizing the synchronization process

          Scheduling synchronization

 Constructing schedule strings

The schedule string format is the same when used in the synchronization SQL statements and in the dbmlsync command line. It is as follows

scheduleStr = { singleSchedule,... | EVERY:hhhh:nn }

singleSchedule = { EVERYDAY | WEEKDAY
| MON | TUE | WED | THU | FRI | SAT | SUN
| dayOfMonth}@hh:nn[aa][-hh:nn[aa]]

Notes

If you specify a single time, synchronization start at that time. For example the following command starts synchronization on Monday at 11:00 am, and then waits until the next Monday at 11:00 am to synchronize again:

dbmlsync -e SCH='MON@11:00am', ...

If you specify an interval, synchronization takes place only once within the specified interval, starting at a random time within the interval. The interval provides a window of time for synchronization so that multiple remote sites with the same schedule definition do not synchronize at exactly the same time. This helps to avoid congestion and improve throughput.

The time interval can include midnight, in which case it extends into the following day. For example, the following is valid:

weekday@11:30pm-12:30am

If dbmlsync starts on Saturday at 12:20am the first synchronization is within the next ten minutes, as the interval is carried over from Friday.

The dbmlsync window displays the schedule status above the progress bar.

The -is command line switch instructs dbmlsync to ignore scheduling.


CHAPTER 8.  Reference
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

 CHAPTER 8.  Reference

About this chapter

This chapter provides reference information about the MobiLink utility programs, the MobiLink synchronization server synchronization scripts, and the SQL statements used when working with Adaptive Server Anywhere clients.

 Utility programs

 MobiLink system tables

 Data-type conversions

 Scripts

 Stored procedures

 SQL statements

 Client event-hook procedures


Utility programs
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

 Utility programs

The following utilities are required to build and synchronize UltraLite applications.

  For information about other Adaptive Server Anywhere utilities, see Database Administration Utilities.

 MobiLink synchronization server

 MobiLink synchronization server stop utility

 Adaptive Server Anywhere client database extraction utility

 Adaptive Server Anywhere client synchronization utility

 MobiLink user-authentication utility

 Elliptic-curve certificate reader utility

 Elliptic-curve certificate generation utility


MobiLink synchronization server
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Utility programs

 MobiLink synchronization server

The MobiLink synchronization server lets you synchronize your remote databases with any ODBC-compliant consolidated database.

Syntax

dbmlsrv7 [ switches ] -c "keyword=value; ..."

Switch	Description
-a	Disable automatic reconnection upon synchronization error.
-bc size	Specify the amount of memory to reserve for blob caching.
-bn size	Specify the maximum number of bytes to consider when comparing blobs.
-c "keyword=value; ..."	Supply ODBC database connection parameters for your reference database
-cn connections	Set maximum number of connections with the consolidated database server.
-cr count	Set maximum number of database connection retries.
-dl	Display log messages on the console.
-o logfile	Log messages to this file.
-os size	Maximum size of output file.
-ot logfile	Truncate file and log output messages to file.
-q	Minimize the synchronization server window
-r retries	Retry deadlocked uploads at most this many times.
-rd delay	Maximum delay, in seconds, before retrying a deadlocked transaction.
-s count	Specify the maximum number of rows to be fetched at once.
-u size	Specify the amount of memory to reserve for caching upload streams.
-ud	On UNIX platforms, run as a daemon.
-vlevels	Controls the type of messages written to the log file.
-w count	Set the number of worker threads.
-wu <number>	Set the maximum number of worker threads.
-x protocol{keyword=value; ...}	Specify the communications protocol.
-zs [ + | - ]	Allow dbmlstop to stop the MobiLink synchronization server.
-zt <Number>	The MobiLink server uses all CPUs available on the machine. The switch -zt allows you to set the number of processors.
-zu [ + | - ]	Allow automatic addition of users when the authenticate_user script is undefined.
Description

The MobiLink synchronization server opens connections, via ODBC, with your consolidated database server. It then accepts connections from remote applications and controls the synchronization process.

Because the MobiLink synchronization server is separate from the database engine, and communicates through an ODBC connection, it is compatible with a variety of database-management systems, including Adaptive Server Anywhere, Adaptive Server Enterprise, Oracle, Microsoft SQL Server, and IBM DB2.

You must supply the connection parameters for the consolidated database using the -c option.

Switches

-a    When an error occurs during synchronization, the MobiLink synchronization server automatically disconnects from the consolidated database, then re-establishes the connection. Some database servers, such as Adaptive Server Anywhere, maintain state information associated with each connection. Reconnecting ensures the following synchronization starts from a known state. When this behavior is not required, you can use this switch to disable it.

-bc size    The amount of memory to use for caching blobs. If more memory is required, the MobiLink synchronization server uses disk space, instead. For this reason, too small a value can degrade performance. To calculate the minimum recommended size, multiply the maximum size of all blob data in any one row by the number of worker threads, then multiply the result by 4.

The size is the amount of memory to reserve in bytes. Use the suffix "k" or "m" to specify units of kilobytes or megabytes, respectively.

-bn size    When two large blobs contain similar or identical values, the operation of comparing them can be expensive due to the amount of data involved. This tells the MobiLink synchronization server to consider only the first size bytes of two blobs when making the comparison. The default is to consider the entire blobs, no matter how big they are.

Under some situations, limiting the maximum amount of data compared can speed synchronization substantially; however, it can also cause errors. For example, if two large blobs differ only in the last few bytes, the MobiLink synchronization server may decide that they are identical when in fact they are not. Choose the value for this option carefully.

-c    The connection string must give the MobiLink synchronization server permission to connect to the consolidated database using an ODBC data source. This parameter is required.

-cn connections    This option specifies the maximum number of connections that the MobiLink synchronization server should make to the consolidated database. The minimum and the default value is one greater than the number of worker threads. A warning is issued if the supplied value is too small. A value much larger than the number of worker threads may speed performance, particularly if connecting to the consolidated database is slow or if multiple script versions are in use.

-cr count    Set the maximum number of times that the MobiLink synchronization server will attempt to connect to the database, before quitting.

-dl    Display messages in the window or on the command line and also in the log file, if specified.

-o logfile    Write all log messages to the specified file.

-os size    The size is the maximum file size for logging output messages, specified in units of bytes. Use the suffix "k" or "m" to specify units of kilobytes or megabytes, respectively. By default, there is no size limit. The minimum size limit is 10 kb.

Before the MobiLink synchronization server logs output messages to a file, it checks the current file size. If the log message will make the file size exceed the specified size, the MobiLink synchronization server renames the output file to yymmddnn.log, where nn is a two-digit integer between 00 and 99 and yymmdd represents the final two digits of the current year, the month, and the day of the month.

This option allows you to manually delete old log files and free up disk space.

-ot logfile    Truncate the log file and then append output messages to it. The default is to send output to the screen.

-q    Minimize the MobiLink synchronization server window.

-r retries    By default, MobiLink synchronization server retries uploads that are deadlocked for a maximum of 10 attempts. If the deadlock is not broken, synchronization fails, since there is no guarantee that the deadlock can be overcome. This option allows an arbitrary retry limit to be set. To stop the server from retrying deadlocked transactions, specify -r 0.

-rd delay    When upload transactions are deadlocked, the MobiLink synchronization server waits a random length of time before retrying each transaction. The random nature of the delay greatly increases the likelihood that future attempts will succeed. This switch allows you to specify the maximum delay in units of seconds. The value 0 (zero) makes retries instantaneous, but larger values are recommended because they yield more successful retries. The default delay value is 30.

-s count    Set the number of rows fetched at one time from the database to count. Set this option to no less than the number of rows specified in the ODBC pre-fetch option, if this option is set. The default value is 10.

-u size    The amount of space, in units of bytes, to reserve for caching upload streams that are being processed. Use the suffix "k" or "m" to specify units of kilobytes or megabytes, respectively. You should consider enlarging this value if your clients upload large streams, or many clients synchronize at once, or both. The suggested size is the maximum expected size of the upload stream multiplied by the number of worker threads. The default value is 500 kb.

-ud    On UNIX platforms, you can run the MobiLink synchronization server as a daemon by supplying the -ud command-line switch.

-v level    This option controls the type of messages written to the log file.

The allowed values of levels and their meanings are as follows. You can use two or more of these options at once. If you specify -v alone, the MobiLink synchronization server writes a minimal amount of information about each synchronization.

•	c    Show the content of each synchronization script when it is invoked. This level implies s.

•	n    Show row-count summaries.

•	r    Display the column values of each row uploaded or downloaded.

•	s    Show the name of each synchronization script as it is invoked.

•	t     Show the translated SQL that results from scripts that are written in ODBC canonical format. This level implies c. The following example shows the automatic translation of a statement for Adaptive Server Anywhere.

I. 02/11 11:02:14. [102]: begin_upload synch2

{ call SynchLogLine( ?, ?, 'begin_upload' ) }

I. 02/11 11:02:14. [102]: Translated SQL:

call SynchLogLine( ?, ?, 'begin_upload' )

The following example shows the translation of the same statement for Microsoft SQL Server.

I. 02/11 11:03:21. [102]: begin_upload synch2

{ call SynchLogLine( ?, ?, 'begin_upload' ) }

I. 02/11 11:03:21. [102]: Translated SQL:

EXEC SynchLogLine ?, ?, 'begin_upload'

-w count    Set the number of worker threads. Each worker thread accepts synchronization requests one at a time. These threads are allocated as follows.

•	A single thread is dedicated to each serial stream.

•	The remaining threads are available for TCP/IP connections.

Each worker thread opens one connection to the consolidated database. The MobiLink synchronization server opens one additional connection for administrative purposes. Hence, the minimum number of connections from the MobiLink synchronization server to the consolidated database is count + 1.

-wu <number>     The -wu <number> command line switch can be used to set the maximum number of worker threads allowed to upload concurrently. The upload requests are processed in first-come, first-serve order. Upload streams are completely read before they are applied. This switch does not limit the number of threads reading upload streams, it only limits the number of threads applying changes to the consolidated database.

When MobiLink receives a synchronization request, it assigns it a free worker thread. Multiple synchronization requests are processed simultaneously, each request handled by a single worker thread. This new switch limits the number of threads applying upload streams to the consolidated database. When a worker thread finishes reading a upload stream, it will wait before applying the upload stream until the total number of threads applying upload streams is below the value of this switch.

-x protocol    Specify communications protocol through which to communicate with remote applications.

The allowed values of protocol and their meanings are as follows:

•	serial    Accept serial connections from applications.

•	tcpip    Accept connections from applications via TCP/IP.

•	http    Accept connections via the standard web protocol. Client applications can pick their HTTP version and the MobiLink synchronization server adjusts on a per-connection basis.

Optionally, you can append a list of semi-colon separated parameters, of the form keyword=value. To append parameters, enclose them in curly braces.

The permitted parameters are as follows:

•	Serial port parameters    These are chosen from the following list:

•	baud=integer    The BAUD rate at which information is to be passed through the serial connection. The default is 19200 BAUD.

•	port=integer    The COM port to use for the serial connection. Typically, the port number is 1, which represents COM1: on a standard PC.

•	security=cipher{keyword=value;...}    All communication through this connection is to be encrypted using the cipher suite specified. You can use only one cipher suite at a time. The only cipher suite presently supported is certicom_tls, Certicom transmission-layer security. The security keywords presently available are certificate, the certificate that is to be used for server authentication, and certificate_password.

A sample certificate named mobilink.crt is included with Adaptive Server Anywhere. The password for this certificate is tJ1#m6+W. This certificate is used by default. Thus, the default certificate name is mobilink.crt and the default certificate password is tJ1#m6+W. This sample certificate is to be used for testing and development work only. The sample server authentication certificate provides no security because the same certificate and password are distributed to all Adaptive Server Anywhere customers. When deploying a secure system, it is essential that you obtain and use your own personal certificate and password. New certificates are available from Certicom.

  For a further explanation, see Transport-layer security.

•	timeout=t    The length of time (in seconds) that the server waits for a serial connection read request before abandoning the connection. This parameter can be useful to ensure that connections are abandoned after a certain amount of time has elapsed. However, short timeout periods can cause the MobiLink synchronization server to issue inappropriate error messages because devices with relatively slow processors can take several minutes to process a large download stream. The default value for the timeout parameter is 300 seconds. The value 0 can be used to specify no timeout.

•	TCP/IP parameters    These are chosen from the following list:

•	host=hostname    The host name or IP number on which the MobiLink synchronization server should listen. The default value is localhost.

•	port=portnumber    The socket port number to on which the MobiLink synchronization server should listen. The port number must be a decimal number that matches the port the MobiLink synchronization server is set up to monitor. The default value for the port parameter is 2439, which is the IANA registered port number for the MobiLink synchronization server.

•	security=cipher{keyword=value;...}    All communication through this connection is to be encrypted using the cipher suite specified. You can use only one cipher suite at a time. The only cipher suite presently supported is certicom_tls, Certicom transmission-layer security. The security keywords presently available are certificate, the certificate that is to be used for server authentication, and certificate_password.

A sample certificate named mobilink.crt is included with Adaptive Server Anywhere. The password for this certificate is tJ1#m6+W. Use of this sample certificate is for testing and development work only. The sample server authentication certificate provides no security because the same certificate and password are distributed to all Adaptive Server Anywhere customers. When deploying a secure system, it is essential that you obtain and use your own personal certificate and password. New certificates are available from Certicom.

  For a further explanation, see Transport-layer security.

•	keep_alive    The TCP/IP-based streams that are used during MobiLink synchronization accept a parameter that allows you to monitor the liveness of a connection. The keep_alive parameter enables liveness checking of a TCP/IP connection.

keep_alive= 0 | 1

The MobiLink server command line would contain the following:

dbmlsrv7 -x tcpip{keep_alive=1} ...

The value 0 turns off TCP/IP liveness checking, and the value 1 enables TCP/IP liveness checking. The default is 0 for backward compatibility. If the network layer does not support TCP/IP liveness checking, this parameter is ignored.

Consult the documentation for your operating system to determine how to configure liveness checking (for example, how often to check, delay times between checks). In particular, look for whether or not the TCP/IP socket option called SO_KEEPALIVE is implemented for your operating system and/or network layer, and how to configure its behavior. For Windows 95 and NT, for example, see the MSDN article Q140325 How to Determine Loss of Client/Server Connection.

•	HTTP stream parameters    These are chosen from the following list:

•	host=hostname    The host name or IP number on which the MobiLink synchronization server should listen. The default value is localhost.

•	port=portnumber    The socket port number on which the MobiLink synchronization server should listen. The port number must be a decimal number that matches the port the MobiLink synchronization server is setup to monitor. The default value for the port parameter is 80.

•	security=cipher{keyword=value;...}    All communication through this connection is to be encrypted using the cipher suite specified. You can use only one cipher suite at a time. The only cipher suite presently supported is certicom_tls, Certicom transmission-layer security. The security keywords presently available are certificate, the certificate that is to be used for server authentication, and certificate_password.

A sample certificate named mobilink.crt is included with Adaptive Server Anywhere. The password for this certificate is tJ1#m6+W. Use of this sample certificate is for testing and development work only. The sample server authentication certificate provides no security because the same certificate and password are distributed to all Adaptive Server Anywhere customers. When deploying a secure system, it is essential that you obtain and use your own personal certificate and password. New certificates are available from Certicom.

  For a further explanation, see Transport-layer security.

•	url_suffix=suffix    The suffix to add to the URL on the first line of each HTTP request. This parameter can be used to help ensure that a particular client connects to the intended server.

•	version=versionnumber    The MobiLink synchronization automatically detects the HTTP version used by a client. This parameter is a string specifying the default version of HTTP to use in case the server cannot detect the method used by the client. You have a choice of 1.0 or 1.1. The default value is 1.1.

-zs    If this is supplied as -zs+, or if it is not supplied, the dbmlstop utility can be used to stop the synchronization server. If the argument is supplied as -zs-, dbmlstop cannot stop the synchronization server.

The default behavior of this option may change in future releases.

-zt    If this is supplied as -zt <number> then the number of processors is the value of the number. The default number of processors is the default number of processors on the machine.

-zu    If this is supplied as -zu+, or if it is not supplied, then unrecognized MobiLink user names are added to the ml_user table on first synchronizing. If the argument is supplied as -zu-, unrecognized user names are prevented from synchronizing.

The default behavior of this option may change in future releases.


MobiLink synchronization server stop utility
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Utility programs

 MobiLink synchronization server stop utility

This utility stops the MobiLink synchronization server if it is currently running.

Syntax

dbmlstop

Description

Running this command stops the MobiLink synchronization server. If any applications are currently synchronizing, these synchronizations are aborted.

Restriction
The MobiLink Synchronization server stop utility can only stop a MobiLink synchronization server that is listening to a TCP/IP socket on the current machine at the default port. In other words, the stop utility only sends the stop message to port 2349 at the address localhost.


Adaptive Server Anywhere client database extraction utility
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Utility programs

 Adaptive Server Anywhere client database extraction utility

Purpose

To extract a remote Adaptive Server Anywhere database from a reference Adaptive Server Anywhere database.

Syntax

mlxtract [ additional switches ] directory site-name

Switch	Description
-ac "keyword=value; ..."	Connect to the database specified in the connect string to do the reload.
-an database	Creates a database file with the same settings as the database being unloaded and automatically reloads it.
-c "keyword=value; ..."	Supply database connection parameters.
-id	Extract schema definition and data.
-it	Extract triggers.
-j count	Iteration count for view-creation statements.
-l level	Perform all extraction operations at specified isolation level.
-o file	Output messages to file.
-p character	Escape character.
-q	Operate quietly: do not print messages or show windows.
-r file	Specify name of generated reload Interactive SQL command file (default "reload.sql").
-u	Unordered data.
-v	Verbose messages.
-x	Use external table loads.
-xf	Exclude foreign keys.
-xp	Exclude stored procedures.
-xv	Exclude views.
-y	Overwrite command file without confirmation.
directory	The directory to which the files are written. This switch is not needed if you use -an or -ac.
site-name	Specify which remote site to generate.
Description

mlxtract is the MobiLink extraction utility for Adaptive Server Anywhere client databases. It is run against an Adaptive Server Anywhere reference database and creates a command file for a remote Adaptive Server Anywhere database.

The command line extraction utility creates a command file and a set of associated data files. The command file can be run against a newly initialized Adaptive Server Anywhere database to create the database objects and load the data for the remote database.

By default, the command file is named reload.sql.

Switches

Reload the data to an existing database (-ac)    You can combine the operation of unloading a database and reloading the results into an existing database using this option.

For example, the following command (which should be entered all on one line) loads a copy of the data for the field_user subscriber into an existing database file named newdemo.db:

mlxtract -c "uid=dba;pwd=sql;dbf=asademo.db" -ac "uid=dba;pwd=sql;dbf=newdemo.db" field_user

If you use this option, no copy of the data is created on disk, so you do not specify an unload directory on the command line. This provides greater security for your data, but at some cost for performance.

Reload the data to a new database (-an)    You can combine the operations of unloading a database, creating a new database, and loading the data using this option.

For example, the following command (which should be entered all on one line) creates a new database file named asacopy.db and copies the schema and data for the field_user subscriber of asademo.db into it:

mlxtract -c "uid=dba;pwd=sql;dbf=asademo.db" -an asacopy.db field_user

If you use this option, no copy of the data is created on disk, so you do not specify an unload directory on the command line. This provides greater security for your data, but at some cost for performance.

Connection parameters (-c)   A set of connection parameters, in a string.

•	mlxtract connection parameters     The user ID should have DBA authority to ensure that the user has permissions on all the tables in the database.

For example, the following statement (which should be typed on one line) extracts a database for remote user ID joe_remote from the asademo database running on the sample_server server, connecting as user ID DBA with password SQL. The data is unloaded into the c:\unload directory.

mlxtract -c "eng=sample_server;dbn=sademo;

uid=dba;pwd=sql" c:\extract joe_remote

Extract both schema definition and data (-id)    By default, only the schema is extracted. Such a database can be initialized with data upon the first connection to a MobiLink synchronization server. This switch provides the alternative of loading the initial data into the reference database and initializing the new database as part of the extraction procedure.

Extract both schema definition and data (-it)    By default, only the schema and synchronization definition are extracted. Triggers are not extracted. This switch provides the option of extracting the triggers present in the reference database.

Iteration count for views (-j)    If there are nested views in the consolidated database, this option specifies the maximum number of iterations to use when extracting the views.

Perform extraction at a specified isolation level (-l)     The default setting is an isolation level of zero. If you are extracting a database from an active server, you should run it at isolation level 3 to ensure that data in the extracted database is consistent with data on the server. Increasing the isolation level may result in large numbers of locks being used by the extraction utility, and may restrict database use by other users.

Output messages to file (-o)    Outputs the messages from the extraction process to a file for later review.

Escape character (-p)    The default escape character (\) can be replaced by another character using this option.

Operate quietly (-q)    Display no messages except errors.

Reload filename (-r)    The default name for the reload command file is reload.sql in the current directory You can specify a different file name with this option.

Output the data unordered (-u)    By default the data in each table is ordered by primary key. Unloads are quicker with the -u switch, but loading the data into the remote database is slower.

Verbose mode (-v)    The name of the table being unloaded and the number of rows unloaded are displayed. The SELECT statement used is also displayed.

Use external loads (-x)    In the reload script, the default is to use the LOAD TABLE statement to load the data into the database. If you choose to use external loads, the Interactive SQL INPUT statement is used instead. The LOAD TABLE statement is faster than INPUT.

INPUT takes the path of the data files relative to the client, while LOAD TABLE takes the path relative to the server.

Exclude foreign key definitions (-xf)    You can use this if the remote database contains a subset of the consolidated database schema, and some foreign key references are not present in the remote database.

Exclude stored procedure (-xp)    Do not extract stored procedures from the database.

Exclude views (-xv)    Do not extract views from the database.

Operate without confirming actions (-y)    Without this option, you are prompted to confirm the replacement of an existing command file.


Adaptive Server Anywhere client synchronization utility
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Utility programs

 Adaptive Server Anywhere client synchronization utility

Use the dbmlsync utility to synchronize remote Adaptive Server Anywhere databases with a consolidated database.

Syntax

dbmlsync [ switches ] [ transaction-logs-directory ]

Switch	Description
-c "keyword=value;..."	Supply database connection parameters.
-d	Drop any other connections to the database whose locks conflict with the articles to be synchronized.
-dl	Display log messages on the console.
-e "keyword=value;..."	Specify extended options.
-i file	Execute file containing SQL statements immediately after synchronization.
-is	Ignore schedule
-k	Close window on completion.
-mn password	New MobiLink password.
-mp password	MobiLink password.
-n name	Synchronization definition name.
-o logfile	Log output messages to this file.
-os size	Maximum size of output file.
-ot logfile	Truncate file and log output messages to file.
-q	Run in minimized window.
-r[a|b]	Upload retry on remote progress.
-v[cp]	Verbose operation.
-x	Rename and restart the transaction log.
Description

Run dbmlsync at the command line to synchronize remote Adaptive Server Anywhere databases with a consolidated database. dbmlsync uses the information in the synchronization definition to locate and connect to the MobiLink synchronization server.

The transaction-logs directory is the directory that contains the transaction log for the Adaptive Server Anywhere client database. You may omit this parameter only if the working log file has not been truncated and renamed since you last synchronized, or if the dbmlsync utility is run from the directory that contains the renamed log files.

You must supply the connection parameters for the Adaptive Server Anywhere client database using the -c option.

If you supply no command-line options, a dialog box appears on which you can specify connection parameters.

  For more information about synchronization definitions, see CREATE SYNCHRONIZATION DEFINITION statement.

Switches

-c    The connection string must give dbmlsync permission to connect to the Adaptive Server Anywhere client database. Commonly, a user ID with REMOTE DBA authority is used.

If you do not supply a -c switch, a connection dialog appears. You can specify the remaining command-line options in the fields of the connection dialog.

-d    During synchronization, unless the locktables extended option is set to OFF, all tables involved in the synchronization definition are locked to prevent any other processes from making changes. Ordinarily, if another process has a lock on one of these tables, the synchronization is delayed until that process releases its lock. Specifying this option forces Adaptive Server Anywhere to drop any other connections to the remote database that hold conflicting locks.

-dl    Display messages in the window or on the command line and also in the log file, if specified.

-e    Specify one or more of the following extended options.

Full Name	Short name	Default	Description
ConflictRetries	cr	-1 (Continue indefinitely)	Number of retries if download fails because of conflicts.
FireTriggers	ft	ON	Fire triggers on download.
Increment	inc	No limit	Upload in increments of specified size.
LockTables	lt	ON	Set to OFF to allow modifications during synchronization
Memory	mem	1 Mb	Memory used for synchronization.
OfflineDirectory	dir	NULL	Path containing offline transaction logs.
Schedule	sch	No schedule	Schedule string. For more information, see Scheduling synchronization.
ScriptsVersion	sv	default	Tells the MobiLink synchronization server to use the scripts for the named schema version, overriding the setting of the synchronization definition option sv.
SendTriggers	st	OFF	Send trigger actions on upload.
StreamCompression	sc	MEDIUM	Compress upload data stream: choose LOW, MEDIUM, or HIGH.
Verbose	v	OFF	Verbose operation.
  For more information on ConflictRetries and LockTables, see Concurrency during synchronization.

-i file    Immediately upon completing synchronization, and before releasing the table locks, execute the SQL script contained in the named file. This option is intended for upgrading applications and making schema changes to deployed, client databases. Schema changes must be accomplished in this manner to ensure all changes are in a compatible format.

-is    Ignore any instructions in the synchronization definition or in the extended options command-line switch to schedule synchronization.

 -k    Close window on completion, if used together with the -o option.

-mn password    Supply a new password for MobiLink user authentication.

  For more information, see Authenticating MobiLink users.

-mp password    Supply a password for MobiLink user authentication. The synchronization definition site name is the MobiLink user name.

  For more information, see Authenticating MobiLink users.

-n name    Name of synchronization definition. You can supply more than one -n option to synchronize more than one synchronization definition.

If synchronizing multiple definitions, the order of operation is as if you carried out the following separate options:

1	Synchronize the first definition.

2	Terminate dbmlsync.

3	Synchronize the second definition.

There are cases where dbmlsync never terminates after synchronizing the first definition, so the second definition will never be synchronized:

•	If schedule options are specified either on the dbmlsync command line or in the first synchronization definition statement, then dbmlsync waits for the next scheduled synchronization instead of exiting.

You can use the -is command-line option when specifying more than one -n switch so that dbmlsync ignores scheduling options.

•	If an sp_hook_dbmlsync_end hook is defined, and the hook always sets the restart parameter to true then dbmlsync repeatedly synchronizes the first definition and never synchronizes the second.

You must be aware of whether or not the sp_hook_dbmlsync_end_hook is defined before specifying multiple -n options.

-o    Append output to a log file. Default is to send output to the screen.

-os size    The size is the maximum file size for logging output messages, specified in units of bytes. Use the suffix "k" or "m" to specify units of kilobytes or megabytes, respectively. By default, there is no size limit. The minimum size limit is 10 kb.

Before the dbmlsync utility logs output messages to a file, it checks the current file size. If the log message will make the file size exceed the specified size, the dbmlsync utility renames the output file to yymmddnn.dbr, where nn is a two-digit integer between 00 and 99 and yymmdd represents the final two digits of the current year, the month, and the day of the month.

This option allows you to manually delete old log files and free up disk space.

-ot logfile    Truncate the log file and then append output messages to it. When the -o switch is specified, the default is to send output to the screen and append them to the log file.

-q    For Windowing operating systems only, starts dbmlsync with a minimized window.

-r    When either the client or consolidated database needs to be restored from a backup, the records of the most recently-transmitted offset in the client transaction log can mismatch between the client and the consolidated database. In this case, the options are to continue upload synchronization from the client database or the consolidated database's record of the last synchronization point. Which one is appropriate depends in part on the synchronization scripts you use.

By default, uploads continue from the offset recorded by the consolidated database. If you use -r or -rb, the upload continues from the offset recorded in the client database as long as the offset recorded in the consolidated database is ahead of that at the client database.

If you use -ra, the upload is retried starting from the offset recorded in the client database even if the offset recorded in the client database is ahead of that recorded in the consolidated database. This option should be used with care. If the offset mismatch is the result of a restore of the consolidated database, changes that happened in the client database in the gap between the two recorded offsets are lost. The -ra option may be useful when the client database transaction log has been truncated and the synchronization definition recreated after the last successful synchronization.

-v    Verbose output. This switch displays the command-line switches and properties of the specified synchronization definition. Also displayed are the SQL statements contained in the messages to the screen. If the -o or -ot switch is used, these messages are also written to a log file.

If you use -vc, the connect string is unhidden in the output. If you use -vp, MobiLink passwords are unhidden in the output.

-x    Rename and restart the transaction log after it has been scanned for outgoing messages. In some circumstances, synchronizing data to a consolidated database can take the place of backing up remote databases, or renaming the transaction log when the database server is shut down.

If backups are not routinely performed at the client database, the transaction log continues to grow. As an alternative to using the -x switch to control transaction log size, you can use an Adaptive Server Anywhere event handler to control the size of the transaction log. For example, the following event handler renames the transaction log at the client database when its size exceeds 5 MB. You can use such an event handler together with the DELETE_OLD_LOGS database option to control the space taken up by transaction logs.

CREATE EVENT RenameLogLimit

TYPE GrowLog

WHERE event_condition( 'LogSize' ) > 5

AT REMOTE

HANDLER

BEGIN

  BACKUP DATABASE DIRECTORY backupdir

  TRANSACTION LOG ONLY

  TRANSACTION LOG RENAME

END

  For more information, see Automating Tasks Using Schedules and Events, and DELETE_OLD_LOGS option.


MobiLink user-authentication utility
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Utility programs

 MobiLink user-authentication utility

Syntax

dbmluser switches

Switch	Description
-c "keyword=value;..."	Supply database connection parameters.
-dl	Display log messages on screen
-o filename	Log output messages to file
-os size	Limit size of output file
-ot filename	Truncate file and log output messages to file
-pc collation-id	Supply database collation ID for character set translation
-pf filename	Read user names and passwords from file
-pp password	Password to add
-pu username	User name to add
-q	Run in minimized window
Description

Add user names and passwords for MobiLink user-authentication. You can also use Sybase Central to add user names and passwords: the command-line utility is useful for automating the task or for batch processing.

Given a user/password pair, the dbmluser utility first attempts to add the user. If the user exists it attempts to update the password for that user.

Switches

-c    The connection string must give the utility permission to connect to the consolidated database using an ODBC data source. This parameter is required.

-dl    Display messages in the window or on the command line and also in the log file, if specified.

-o logfile    Write all log messages to the specified file.

-os size    The size is the maximum file size for logging output messages, specified in units of bytes. Use the suffix "k" or "m" to specify units of kilobytes or megabytes, respectively. By default, there is no size limit. The minimum size limit is 10 kb.

-ot logfile    Truncate the log file and then append output messages to it. The default is to send output to the screen.

-pc    The database collation. This should be one of the Adaptive Server Anywhere collation labels such as those listed in Initialization utility options. For machines using single-byte character sets the default is 1252LATIN1. For machines using multi-byte character sets, the default is SJIS2.

-pf    Read the user names and passwords from the specified file. The file should be a text file containing one user name and password pair on each line, separated by white space.

-pp    Specify password to add. This switch is used together with -pu.

-pu    Specify user name to add. This switch is used together with -pp.

-q    Minimize the MobiLink synchronization server window.


Elliptic-curve certificate reader utility
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Utility programs

 Elliptic-curve certificate reader utility

Use the readcert utility to display values within an elliptic-curve certificate and validate the chain of certificates.

Syntax

readcert certificate-name

Description

When synchronization occurs through a Certicom TLS synchronization stream, the MobiLink synchronization server sends its certificate to the client, as well as the certificate of the entity that signed it, and so on up to a self-signed root. The client checks that the chain is valid and that it trusts the root certificate in the chain.

This utility scans a non-RSA X509 authentication certificate and displays the field values. It then checks that the chain of certificates is valid. A validation error is reported if any of the certificates in the chain have expired, are in the wrong order, or are missing.


Elliptic-curve certificate generation utility
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Utility programs

 Elliptic-curve certificate generation utility

Use the readcert utility to create a new elliptic-curve certificate.

Syntax

gencert [ -c | -s ] [ -r ]

Switch	Description
-c	Generate a certificate authority certificate.
-r	Generate a self-signed root certificate.
-s	Generate a server identity certificate.
Description

This utility creates a new X509 certificate. When first started, it generates an elliptic-curve key pair. It then requests values for the distinguished fields. These fields include the country, state or province, locality, organization, organizational unit, and common name, the serial number, and an expiry date. It then requests the file name of a certificate that is to sign the new certificate.

If no certificate name is supplied, the new certificate becomes a root certificate. If a certificate file name is supplied, gencert reads and validates the certificate chain and requests the name of the file that contains the signer's private key. It then requests the password for that private key.

The then utility requests the password that is to protect the new private key.

This utility writes three different types of files. One file contains only the new certificate. Another contains only the encrypted private key, and a third file contains both the certificate and the encrypted private key.

Often, not all three files are needed. For example, if the certificate is to be a certificate authority, used to sign other certificates, the file that contains only the certificates is distributed as a trusted root certificate to clients. The file containing the encrypted private key is stored securely. In this case, security is improved by storing the private key and the certificate separately, so the third file is not generated.

If, instead, the certificate is to identify a server, the encrypted private key should be stored with the certificate, so the utility writes only the file that contains both pieces of information.

If the signing certificate is not a root certificate, but is instead part of a chain, gencert reads and validates the entire chain before issuing the new certificate.

When generating a server identity certificate, the entire chain is always saved. Otherwise, saving the entire chain is optional.

Switches

-c    Generate a certificate authority certificate. A certificate authority can be used to sign other certificates. By default, generated certificates cannot be used as certificate authorities.

-r    Generate a root certificate. A root certificate is signed only by itself. The default is to prompt for the name of a file that contains the certificate that is to sign the new, generated certificate.

-s    Generate a server identity certificate, used to identify a MobiLink synchronization server, rather than a client. A server identity certificate cannot be a certificate authority, so this switch is incompatible with the -c switch. The default is to generate a client certificate.


MobiLink system tables
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

 MobiLink system tables

The tables used for MobiLink are shown below. Arrows indicate foreign key relations between tables: the arrow leads from the foreign table to the primary table.

These tables are always present in Adaptive Server Anywhere databases and are owned by dbo. They can also be installed in database systems sold by other vendors, for use when the alternate database system is to be used as a MobiLink consolidated database.


Data-type conversions
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

 Data-type conversions

Conversion of data types must take place when a MobiLink synchronization server communicates with a consolidated database that was not made with Adaptive Server Anywhere. The following tables identify these mappings.

 Sybase Adaptive Server Enterprise

 IBM DB2

 Oracle

 Microsoft SQL Server


Sybase Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Data-type conversions

 Sybase Adaptive Server Enterprise

The following table identifies how MobiLink data types are mapped to Adaptive Server Enterprise data types.

MobiLink data type	Sybase ASE data type
bit	bit
tinyint	tinyint
smallint	smallint
int	int
integer	integer
decimal [defaults p=30, s=6]	numeric(30,6)
decimal(128,128)	not supported
numeric [defaults p=30 s=6]	numeric(30,6)
numeric(128,128)	not supported
float	real
real	real
double	float
smallmoney	numeric(10,4)
money	numeric(19,4)
date	datetime
time	datetime
timestamp	datetime
smalldatetime	datetime
datetime	datetime
char(n)	varchar(n)
character(n)	varchar(n)
varchar(n)	varchar(n)
character varying(n)	varchar(n)
long varchar	text
text	text
binary(n)	binary(n)
long binary	image
image	image
bigint	numeric(20,0)


IBM DB2
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Data-type conversions

 IBM DB2

The following table identifies how MobiLink data types are mapped to IBM DB2 data types.

MobiLink data type	IBM DB2 data type
Bit	smallint
Tinyint	smallint
Smallint	smallint
Int	int
Integer	int
Bigint	decimal(20,0)
char(1-254)	varchar(n)
char(255-4000)	varchar(n)
char(4001-32767)	long varchar
Character(1-254)	varchar(n)
Character(255-4000)	varchar(n)
Character(4001-32767)	long varchar
varchar(1-4000)	varchar(n)
varchar(4001-32767)	long varchar
Character varying(1-4000)	varchar(n)
Character varying(4001-32767)	long varchar or CLOB(n)
long varchar	long varchar or CLOB(n)
text	long varchar
binary(1-4000)	varchar for bit data or BLOB(n)
binary(4001-32767)	long varchar for bit data or BLOB(n)
long binary	long varchar for bit data or BLOB(n)
image	long varchar for bit data or BLOB(n)
decimal [defaults p=30, s=6]	decimal(30,6)
numeric [defaults p=30 s=6]	decimal(30,6)
decimal(128, 128)	NOT SUPPORTED
numeric(128, 128)	NOT SUPPORTED
real	real
float	float
double	float
smallmoney	decimal(10,4)
money	decimal(19,4)
date	date
time	time
smalldatetime	timestamp
datetime	timestamp
timestamp	timestamp


Oracle
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Data-type conversions

 Oracle

The following table identifies how MobiLink data types are mapped to Oracle data types.

MobiLink data type	Oracle data type
bit	number(1,0)
tinyint	number(3,0)
smallint	number(5,0)
int	number(11,0)
bigint	number(20,0)
decimal(prec, scale)	number(prec, scale)
numeric(prec, scale)	number(prec, scale)
float	float
real	real
smallmoney	numeric(13,4)
money	number(19,4)
date	date
time	date
timestamp	date
smalldatetime	date
datetime	date
char(n)	if (n > 255) long else varchar(n), or CLOB(n)
varchar(n)	if (n > 2000) long else varchar(n), or CLOB(n)
longchar	long or CLOB(n)
binary(n)	if (n > 255) long raw else raw(n), or BLOB(n)
varbinary(n)	if (n > 255) long raw else raw(n), or BLOB(n)
longbinary	long raw
For Oracle LONG data types to synchronize properly, you must check the Oracle Force Retrieval of Long Columns ODBC option in the ODBC data source configuration dialog.


Microsoft SQL Server
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Data-type conversions

 Microsoft SQL Server

The following table identifies how MobiLink data types are mapped to Microsoft SQL Server data types.

MobiLink data type	Microsoft SQL Server data type
bit	bit
tinyint	tinyint
smallint	smallint
int	int
bigint	numeric(20,0)
decimal [defaults p=30, s=6]	decimal(prec, scale)
numeric [defaults p=30 s=6]	numeric(prec, scale)
float	if (prec) float(prec) else float
real	real
smallmoney	smallmoney
money	money
date	datetime
time	datetime
timestamp	datetime
smalldatetime	datetime
datetime	datetime
char(n)	if (length > 255) text else varchar(length)
character(n)	varchar(n)
varchar(n)	if (length > 255) text else varchar(length)
longchar	text
binary(n)	if (length > 255) image else binary(length)
long binary	image
double	float


Scripts
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

 Scripts

This section lists the scripts in alphabetical order. Arguments are optional.

 authenticate_user connection script

 authenticate_user_hashed connection script

 begin_connection connection script

 begin_download connection script

 begin_download table script

 begin_download_deletes table script

 begin_download_rows table script

 begin_synchronization connection script

 begin_synchronization table script

 begin_upload connection script

 begin_upload table script

 begin_upload_deletes table script

 begin_upload_rows table script

 download_cursor cursor script

 download_delete_cursor cursor script

 end_connection connection script

 end_download connection script

 end_download table script

 end_download_deletes table script

 end_download_rows table script

 end_synchronization connection script

 end_synchronization table script

 end_upload connection script

 end_upload table script

 end_upload_deletes table script

 end_upload_rows table script

 handle_error connection script

 handle_odbc_error connection script

 new_row_cursor cursor script

 old_row_cursor cursor script

 prepare_for_download connection script

 report_error connection script

 report_odbc_error connection script

 resolve_conflict table script

 upload_cursor cursor script


authenticate_user connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 authenticate_user connection script

Function

To implement a custom user-authentication mechanism.

Arguments

auth_status int,
user_name varchar(128),
user_password varchar(128),
user_new_password varchar(128)

Default action

Use MobiLink built-in user-authentication mechanism.

See also

Authenticating MobiLink users

Using a custom user-authentication mechanism

authenticate_user_hashed connection script

begin_synchronization connection script

Description

The MobiLink synchronization server executes this script upon starting each synchronization. It is executed before, and in the same transaction as the begin_synchronization script.

You can use this script to replace the built-in MobiLink authentication mechanism with a custom mechanism. You may want to call into the authentication mechanism of your DBMS, or you may wish to implement features not present in the MobiLink built-in mechanism, such as password expiry or a minimum password-length.

The parameters used in an authenticate_user script are as follows:

1	auth_status    This required parameter indicates the overall success of the authentication, and can be set to one of the following values:

•	1000    Authentication succeeded.

•	2000    Authentication succeeded: password expiring soon.

•	3000    Authentication failed: password expired.

•	4000    Authentication failed.

2	user_name    This optional parameter indicates the user name for authentication purposes.

3	user_password    This optional parameter indicates the password for authentication purposes.

4	user_new_password    This optional parameter indicates a new password, set only when the user changes their password.

Example

A typical authenticate_user script would be a call to a stored procedure that uses the parameters. The order of the parameters in the call must match the order above. For example, in an Adaptive Server Anywhere consolidated database, the format would be as follows:

call my_auth ( ?, ?, ?, ? )

where the first argument is the error code, and so on. The error code is an integer type, and the other parameters are VARCHAR(128).

A Transact-SQL format would be as follows:

execute ? = my_auth( ?, ?, ? )

where the error code is the parameter on the left hand side.

For example, the following Adaptive Server Anywhere stored procedure uses only the user name to authenticate; it has no password check. The procedure checks that the supplied user name is one of the list of employee IDs listed in the ULEmployee table.

CREATE PROCEDURE my_auth(in @user_name varchar(128))

begin

  if exists

    ( select* from ulemployee

      where emp_id = @user_name )

  then

    message 'OK' type info to client;

    return 1000;

  else

    message 'Not OK' type info to client;

    return 4000;

  end if

end


authenticate_user_hashed connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 authenticate_user_hashed connection script

Function

To implement a custom user-authentication mechanism.

Arguments

auth_status int,
user_name varchar(128),
hashed_user_password binary(20),
hashed_new_password binary(20)

Default action

Use MobiLink built-in user-authentication mechanism.

See also

Authenticating MobiLink users

Using a custom user-authentication mechanism

authenticate_user connection script

Description

This script is identical to authenticate_user except for the passwords, which are in the same hashed form as those stored in the ml_user.hashed_password column. Passing the passwords in hashed form provides increased security.

You may wish to use authenticate_user to check the length or form of a new password, and authenticate_user_hashed to store it. When the two scripts return different auth_status codes, the higher value is used.


begin_connection connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_connection connection script

Function

To process any statements at the time the MobiLink synchronization server connects to the consolidated database server.

Arguments

None.

Default action

No action.

See also

end_connection connection script

Description

The MobiLink synchronization server executes this script upon opening each worker-thread connection to the consolidated database server. The MobiLink synchronization server typically opens one or more connections when it is launched. When an application forms or re-forms a connection with the MobiLink synchronization server, the MobiLink synchronization server, in turn, temporarily allocates one connection with the database server for the duration of that synchronization.


begin_download connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_download connection script

Function

To process any statements just before the MobiLink synchronization server commences preparing the download data stream.

Arguments

user_name varchar(128)

Default action

No action.

See also

end_download connection script

Description

The MobiLink synchronization server executes this script as the first step in the processing of downloaded information. Download information is processed in a single transaction. The execution of this script is the first action in this transaction.


begin_download table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_download table script

Function

To process statements related to a specific table just before the MobiLink synchronization server begins preparing the download stream of inserts, updates, and deletions.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

end_download table script

Description

The MobiLink synchronization server executes this script as the first step in the preparing download information. The download information is prepared in a separate transaction. The execution of this script is the first table-specific action in this transaction.

You can have one begin_download script for each table in the remote database.


begin_download_deletes table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_download_deletes table script

Function

To process statements related to a specific table just before preparing a list of rows to be deleted from the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

end_download_deletes table script

begin_download connection script

Description

This script is executed immediately before preparing a list of rows to be deleted from the named table in the remote database.

You can have one begin_download_deletes script for each table in the remote database.


begin_download_rows table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_download_rows table script

Function

To process statements related to a specific table just before preparing a list of rows to be inserted or updated in the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

end_download_rows table script

begin_download connection script

Description

This script is executed immediately before preparing the stream of rows to be inserted or updated in the named table in the remote database.

You can have one begin_download_rows script for each table in the remote database.


begin_synchronization connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_synchronization connection script

Function

To process any statements at the time an application connects to the MobiLink synchronization server in preparation for the synchronization process.

Arguments

user_name varchar(128)

Default action

No action.

See also

end_synchronization connection script

begin_synchronization table script

Description

The MobiLink synchronization server executes this script immediatly after an application preparing to synchronize has formed a connection with the MobiLink synchronization server.

This script is executed within a separate transaction before the upload transaction. It is useful for maintaining statistics.


begin_synchronization table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_synchronization table script

Function

To process statements related to a specific table at the time an application connects to the MobiLink synchronization server in preparation for the synchronization process.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

end_synchronization table script

begin_synchronization connection script

Description

The MobiLink synchronization server executes this script after an application preparing to synchronize has formed a connection with the MobiLink synchronization server, and after the connection level script of the same name.

You can have one begin_synchronization script for each table in the remote database.


begin_upload connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_upload connection script

Function

To process any statements just before the MobiLink synchronization server commences processing the stream of uploaded inserts, updates, and deletions.

Arguments

user_name varchar(128)

Default action

No action.

See also

end_upload connection script

begin_upload table script

Description

The MobiLink synchronization server executes this script as the first step in the processing of uploaded information. Upload information is processed in a single transaction. The execution of this script is the first action in this transaction.


begin_upload table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_upload table script

Function

To process statements related to a specific table just before the MobiLink synchronization server commences processing the stream of uploaded inserts, updates, and deletions.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

end_upload table script

begin_upload connection script

Description

The MobiLink synchronization server executes this script as the first step in the processing of uploaded information. Upload information is processed in a separate transaction. The execution of this script is the first table-specific action in this transaction.

You can have one begin_upload script for each table in the remote database.


begin_upload_deletes table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_upload_deletes table script

Function

To process statements related to a specific table just before deleting rows that were deleted from the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

end_upload_deletes table script

Description

Uploaded information can require deleting rows in the consolidated database. This script is run immediately before applying the changes that result from rows deleted in the remote table named in the second argument.

You can have one begin_upload_deletes script for each table in the remote database.


begin_upload_rows table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 begin_upload_rows table script

Function

To process statements related to a specific table just before applying inserts and updates from the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

end_upload_rows table script

Description

Uploaded information can require inserting or updating rows in the consolidated database. This script is run immediately prior to applying the changes that result from modifications to the remote table named in the second argument.

You can have one begin_upload_rows script for each table in the remote database.


download_cursor cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 download_cursor cursor script

Function

Define a cursor to select rows that are to be downloaded and inserted or updated in the remote database.

Arguments

user_name varchar(128)

Default action

No action, but the UltraLite analyzer generates a SELECT statement based on your reference database that you can use to get started. For each table in the UltraLite database, the UltraLite generator adds two scripts to the reference database. The example_download_cursor and the example_upload_cursor scripts are useful starting points when writing scripts.

See also

upload_cursor cursor script

download_delete_cursor cursor script

Description

The MobiLink synchronization server opens a read-only cursor with which to prepare a list of rows to download to the remote database. This script should contain a suitable SELECT statement.

Unlike the upload cursors, the only argument is the user name. You can use this value if you choose by placing a question mark in your SQL statement. Unlike in the upload_cursor, the use of a question mark is optional.

You can have one download_cursor script for each table in the remote database.

To optimize performance of the download stage of synchronization to UltraLite clients, when the range of primary key values is outside the current rows on the device, you should order the rows in the download cursor by primary key. Downloads of large reference tables, for example, can benefit from this optimization.

Example

The following SELECT statement defines a download cursor that downloads orders that have not yet been approved.

SELECT o.order_id, o.cust_id, o.prod_id, o.emp_id, o.disc, o.quant, o.notes, o.status

FROM ULOrder o, ULEmpCust ec

WHERE o.cust_id = ec.cust_id

AND ec.emp_id = @EmployeeID

AND ( o.last_modified > @LastDownload

OR ec.last_modified > @LastDownload )

AND ( o.status IS NULL

OR o.status != 'Approved' )

AND ( ec.action IS NULL )


download_delete_cursor cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 download_delete_cursor cursor script

Function

Define a cursor to select rows that are to be deleted in the remote database.

Arguments

user_name varchar(128)

Default action

No action.

See also

upload_cursor cursor script

download_cursor cursor script

Description

The MobiLink synchronization server opens a read-only cursor with which to prepare a list of rows to download and insert or update in the remote database. This script must contain a SELECT statement that returns the primary key values of the rows to be deleted from the remote table.

Unlike the upload cursors, the only argument is the user name. You can use this value if you choose by placing a question mark in your SQL statement. Unlike in the upload_cursor, the use of a question mark is optional.

You can have one download_delete_cursor script for each table in the remote database.

Examples

The following SELECT statement defines a download cursor that deletes approved orders in the remote database. The order id column is the only column in the primary key of this table, so only this column is selected.

SELECT order_id

FROM ULOrder

WHERE emp_id = ?

AND status = 'Approved'

AND last_modified > @LastDownload

For compatibility with older versions, the following SELECT statement also defines a download cursor that deletes approved orders in the remote database. This cursor has the same effect, but is less efficient because the database engine must retrieve the extra columns from the database. The extra columns are not included in the download stream. The MobiLink synchronization server simply discards them.

SELECT order_id, cust_id, prod_id, disc,

quant, notes, status

FROM ULOrder

WHERE emp_id = ?

AND status = 'Approved'

AND last_modified > @LastDownload


end_connection connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_connection connection script

Function

To process any statements just before the MobiLink synchronization server closes a connection with the consolidated database server, typically in preparation to shut down.

This script is normally used to complete any actions started by the begin_connection script and free any resources acquired by it.

Arguments

None.

Default action

No action.

See also

begin_connection connection script

Description

You can use the end_connection script to perform an action of your choice just prior to closing of a connection between the MobiLink synchronization server and the consolidated database server.


end_download connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_download connection script

Function

To process any statements just before the MobiLink synchronization server concludes preparation of the download data stream.

Arguments

user_name varchar(128)

Default action

No action.

See also

begin_download connection script

Description

The MobiLink synchronization server executes this script after all rows have been downloaded and confirmation of receipt has been received. Download information is processed in a single transaction. The execution of this script is the last action in this transaction.


end_download table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_download table script

Function

To process statements related to a specific table just after the MobiLink synchronization server concludes preparing the stream of downloaded inserts, updates, and deletions.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

begin_download table script

Description

The MobiLink synchronization server executes this script after all rows have been downloaded and confirmation of receipt has been received. The download information is prepared in a separate transaction. The execution of this script is the last table-specific action in this transaction.

You can have one end_download script for each table in the remote database.


end_download_deletes table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_download_deletes table script

Function

To process statements related to a specific table just after preparing a list of rows to be deleted from the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

begin_download_deletes table script

end_download connection script

Description

This script is executed immediately after preparing a list of rows to be deleted from the named table in the remote database.

You can have one end_download_deletes script for each table in the remote database.


end_download_rows table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_download_rows table script

Function

To process statements related to a specific table just after preparing a list of rows to be inserted or updated in the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

begin_download_rows table script

end_download connection script

Description

This script is executed immediately after preparing the stream of rows to be inserted or updated in the named table in the remote database.

You can have one end_download_rows script for each table in the remote database.


end_synchronization connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_synchronization connection script

Function

To process any statements at the time an application disconnects from the MobiLink synchronization server upon completion of the synchronization process.

Arguments

user_name varchar(128)

Default action

No action.

See also

begin_synchronization connection script

end_synchronization table script

Description

The MobiLink synchronization server executes this script after synchronization is complete and the MobiLink client has returned confirmation of receipt of the download stream.

This script is executed within a separate transaction after the download transaction. It is useful for maintaining statistics.


end_synchronization table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_synchronization table script

Function

To process statements related to a specific table at the time an application disconnects from the MobiLink synchronization server upon completion of the synchronization process.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

begin_synchronization table script

end_synchronization connection script

Description

The MobiLink synchronization server executes this script after an application has synchronized and is about to disconnect from the MobiLink synchronization server, and before the connection level script of the same name.

You can have one end_synchronization script for each table in the remote database.


end_upload connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_upload connection script

Function

To process any statements just after the MobiLink synchronization server concludes processing the stream of uploaded inserts, updates, and deletions.

Arguments

user_name varchar(128)

Default action

No action.

See also

begin_upload connection script

end_upload table script

Description

The MobiLink synchronization server executes this script as the last step in the processing of uploaded information. Upload information is processed in a single transaction. The execution of this script is the last action in this transaction.


end_upload table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_upload table script

Function

To process statements related to a specific table just after the MobiLink synchronization server concludes processing the stream of uploaded inserts, updates, and deletions.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

begin_upload table script

end_upload connection script

Description

The MobiLink synchronization server executes this script as the last step in the processing of uploaded information. Upload information is processed in a separate transaction. The execution of this script is the last table-specific action in this transaction.

You can have one end_upload script for each table in the remote database.


end_upload_deletes table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_upload_deletes table script

Function

To process statements related to a specific table just after applying deletes from the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

begin_upload_deletes table script

Description

Uploaded information can require deleting rows in the consolidated database. This script is run immediately after applying the changes that result from rows deleted in the remote table named in the second argument.

You can have one end_upload_deletes script for each table in the remote database.


end_upload_rows table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 end_upload_rows table script

Function

To process statements related to a specific table just after applying inserts and updates from the specified table in the remote database.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

begin_upload_rows table script

Description

Uploaded information can require inserting or updating rows in the consolidated database. This script is run immediately after applying the changes that result from modifications to the remote table named in the second argument.

You can have one end_upload_rows script for each table in the remote database.


handle_error connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 handle_error connection script

Function

Executed whenever the MobiLink synchronization server encounters a SQL error.

Arguments

action_code int, error_code int, error_message text, user_name varchar(128), table varchar(128)

Default action

The MobiLink synchronization server selects a default action code, which depends on the severity of the error. You can modify the action code in the script, and return a value instructing MobiLink how to proceed. The action code parameter takes one of the following values:

•	1000    Skip the current row and continue processing.

•	3000    Rollback the current transaction and cancel the current synchronization. This is the default action code, and is used when no handle_error script is defined or this script causes an error.

•	4000    Rollback the current transaction, cancel the synchronization, and shut down the server.

The MobiLink synchronization server selects a default action code, which depends on the severity of the error.

See also

report_error connection script

Description

The MobiLink synchronization server executes this script whenever it encounters an error during the synchronization process. The error codes allow you to identify the nature of the error. If the error happened as part of synchronization, the user name is supplied. Otherwise, this value is NULL.

If the error happened while manipulating a particular table, the table name is supplied. Otherwise, this value is NULL. The table name is the name of a table in the remote application. This name may or may not have a direct counterpart in the consolidated database, depending upon the design of the synchronization system.

The action code tells the MobiLink synchronization server what to do next. Before it calls this script, the MobiLink synchronization server sets the action code to a default value, which depends upon the severity of the error. Your script may modify this value. Your script must return an action code.


handle_odbc_error connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 handle_odbc_error connection script

Function

Executed whenever the MobiLink synchronization server encounters an error triggered by the ODBC Driver Manager.

Arguments

action_code int, error_code varchar(5), error_message text, user_name varchar(128), table varchar(128)

Default action

The MobiLink synchronization server selects a default action code, which depends on the severity of the error. You can modify the action code in the script, and return a value instructing MobiLink how to proceed. The action code parameter takes one of the following values:

•	1000    Skip the current row and continue processing.

•	3000    Rollback the current transaction and cancel the current synchronization. This is the default action code, and is used when no handle_error script is defined or this script causes an error.

•	4000    Rollback the current transaction, cancel the synchronization, and shut down the server.

See also

handle_error connection script

report_odbc_error connection script

Description

The MobiLink synchronization server executes this script whenever it encounters an error triggered by the ODBC Driver Manager during the synchronization process. The error codes allow you to identify the nature of the error.

The action code tells the MobiLink synchronization server what to do next. Before it calls this script, the MobiLink synchronization server sets the action code to a default value, which depends upon the severity of the error. Your script may modify this value. Your script must return an action code.

The handle_odbc_error script is called after the handle_error and report_error scripts, and before the report_odbc_error script.

When only one, but not both, error-handling script is defined, the return value from that script decides error behavior.

When both error-handling scripts are defined, the MobiLink synchronization server uses the numerically highest action code.


new_row_cursor cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 new_row_cursor cursor script

Function

Defines the insert cursor that the server uses to insert the new values of rows that were updated in the remote database, but conflict with values presently in the consolidated database.

Arguments

user_name varchar(128)

Default action

No action.

See also

upload_cursor cursor script

old_row_cursor cursor script

Handling conflicts

Description

When a row is updated on a remote database, the MobiLink client saves a copy of the original values. The client sends both old and new values to the MobiLink synchronization server.

When the MobiLink synchronization server receives an updated row, it compares the orginal values with the present values in the consolidated database, using the upload_cursor. If the old uploaded values do not match the current value in the consolidated database, the row conflicts. Instead of updating the row, the MobiLink synchronization server inserts both old and new values into the consolidated database using the old_row_cursor and the new_row_cursor, respectively.

The MobiLink synchronization server uses a cursor to insert the new uploaded values from conflicting rows into the consolidated database. This script contains the SELECT statement used to define this cursor.

It is common practice to use temporary tables to store the old and new versions of conflicting rows. You can create these temporary tables in an earlier script.

You can have one new_row_cursor script for each table in the remote database.

Normally, the columns in the select list must match those in the remote table in both order and type. However, the MobiLink synchronization server permits you to add one extra column. If you do so, the MobiLink synchronization server automatically inserts the user name into the first column, then proceeds to insert the old row values using the remaining columns, as usual.

Examples

•	The following SELECT statement defines a new_row_cursor script suited to the CustDB sample application.

SELECT order_id, cust_id, prod_id, emp_id, disc, quant, notes, status

FROM ULNewOrder

The primary key of the ULOrder table is order_id.

•	The following SELECT statement could instead be used for the same remote table. This variation includes the permitted one extra row. The MobiLink synchronization server automatically stores the user name in the first column.

SELECT user_name, order_id, cust_id, prod_id, emp_id, disc, quant, notes, status

FROM ULNewOrder


old_row_cursor cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 old_row_cursor cursor script

Function

Defines the cursor that the server uses to insert the old values of rows that were updated in the remote database, but conflict with values presently in the consolidated database.

Arguments

user_name varchar(128)

Default action

No action.

See also

upload_cursor cursor script

new_row_cursor cursor script

Description

When a row is updated on a remote database, the MobiLink client saves a copy of the original values. The client sends both old and new values to the MobiLink synchronization server.

When the MobiLink synchronization server receives an updated row, it compares the original values with the present values in the consolidated database, using the upload_cursor. If the old uploaded values do not match the current values in the consolidated database, the row conflicts. Instead of updating the row, the MobiLink synchronization server inserts both old and new values into the consolidated database using the old_row_cursor and the new_row_cursor, respectively.

It is common practice to use temporary tables to store the old and new verions of conflicting rows. You can create these temporary tables in an earlier script.

The MobiLink synchronization server uses a cursor to insert the old uploaded values from conflicting rows into the consolidated database. This script contains the SELECT statement used to define this cursor.

You can have one old_row_cursor script for each table in the remote database.

Normally, the columns in the select list must match those in the remote table in both order and type. However, the MobiLink synchronization server permits you to add one extra column. If you do so, the MobiLink synchronization server automatically inserts the user name into the first column, then proceeds to insert the old row values using the remaining columns, as usual.

Examples

•	The following SELECT statement defines a old_row_cursor script suited to the CustDB sample application.

SELECT order_id, cust_id, prod_id, emp_id, disc, quant, notes, status

FROM ULOldOrder

The primary key of the ULOrder table is order_id.

•	The following SELECT statement could instead be used for the same remote table. This variation includes the permitted one extra row. The MobiLink synchronization server automatically stores the user name in the first column.

SELECT user_name, order_id, cust_id, prod_id, emp_id, disc, quant, notes, status

FROM ULOldOrder


prepare_for_download connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 prepare_for_download connection script

Function

To process any required operations between the upload and download transactions.

Arguments

user_name varchar(128)

Default action

No action.

See also

end_upload connection script

begin_download connection script

Description

The MobiLink synchronization server executes this script as a separate transaction, between the completion of the end_upload event and the start of the begin_download event.


report_error connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 report_error connection script

Function

Executed whenever the MobiLink synchronization server encounters a SQL error, immediately following the handle_error script, whether or not it is defined.

Arguments

action_code int, error_code int, error_message text, user_name varchar(128), table varchar(128)

Default action

None.

See also

handle_error connection script

Description

The MobiLink synchronization server executes this script whenever it encounters an error during the synchronization process and immediately after executing the handle_error script, whether or not it is defined. The error codes allow you to identify the nature of the error. The action code is the value returned by handle_error, or if handle_error is undefined, the default action code selected by the MobiLink synchronization server. If the error happened as part of synchronization, the user name is supplied. Otherwise, this value is NULL.

If the error happened while manipulating a particular table, the table name is supplied. Otherwise, this value is NULL. The table name is the name of a table in the remote application. This name may or may not have a direct counterpart in the consolidated database, depending upon the design of the synchronization system.

This script allows you to log errors and to record the actions selected by the handle_error script. This script is always executed immediately following the completion of handle_error. It is always executed in a separate transaction. All changes made by the script are automatically committed.


report_odbc_error connection script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 report_odbc_error connection script

Function

Executed whenever the MobiLink synchronization server encounters an error triggered by the ODBC Driver Manager, immediately following the handle_odbc_error script, whether or not it is defined.

Arguments

action_code int, error_code varchar(5), error_message text, user_name varchar(128), table varchar(128)

Default action

None.

See also

handle_odbc_error connection script

report_error connection script

Description

The MobiLink synchronization server executes this script whenever it encounters an error triggered by the ODBC Driver Manager during the synchronization process. The error codes allow you to identify the nature of the error. It is executed immediately after the handle_odbc_error script.

The error codes allow you to identify the nature of the error. The action code is the value returned by handle_odbc_error or handle_error. If neither are defined, the default action code is selected by the MobiLink synchronization server.

This script allows you to log errors and to record the actions selected by the handle_odbc_error script. This script is always executed immediately following the completion of handle_odbc_error. It is always executed in a separate transaction. All changes made by the script are automatically committed.


resolve_conflict table script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 resolve_conflict table script

Function

Defines a process for resolving a conflict.

Arguments

user_name varchar(128), table varchar(128)

Default action

No action.

See also

old_row_cursor cursor script

new_row_cursor cursor script

end_upload_rows table script

Description

When a row is updated on a remote database, the MobiLink client saves a copy of the original values. The client sends both old and new values to the MobiLink synchronization server.

When the MobiLink synchronization server receives an updated row, it compares the orginal values with the present values in the consolidated database, using the upload_cursor. If the old uploaded values do not match the current values in the consolidated database, the row conflicts. Instead of updating the row, the MobiLink synchronization server inserts both old and new values into the consolidated database using the old_row_cursor and the new_row_cursor, respectively.

Once the values have been inserted, the MobiLink synchronization server executes this script. It provides the opportunity to resolve the conflict. You can implement any scheme of your choosing.

This script is executed once per conflict.

Alternatively, instead of defining the resolve_conflict script, you can resolve conflicts in a set-oriented fashion by putting conflict-resolution logic in your end_upload_rows script.

You can have one resolve_conflict script for each table in the remote database.


upload_cursor cursor script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Scripts

 upload_cursor cursor script

Function

Defines the cursor that the server uses to insert, update, or delete rows during processing of the upload stream.

Arguments

primary_key_1, primary_key_2, ..., primary_key_n

Default action

No action, but the UltraLite analyzer generates a SELECT statement based on your reference database that you can use to get started. For each table in the UltraLite reference database, the UltraLite generator adds two scripts to the reference database. The example_download_cursor and the example_upload_cursor scripts are useful starting points when writing scripts.

See also

download_cursor cursor script

Description

The MobiLink synchronization server opens a cursor with which to insert, update, or delete rows in the consolidated database based on rows uploaded from a remote application. This script should contain a suitable SELECT statement or call a stored procedure that contains a suitable SELECT statement.

The arguments are the values of each column included in the primary key of the corresponding remote table. You must use these in a WHERE clause, so that the synchronization can identify a unique row in the cursor based on these values. The type and order of the arguments is as defined in the example_upload_cursor script. This order is the same as that in the corresponding table definition in the remote database, which in turn may have been copied from your reference database.

You can have one upload_cursor script for each table in the remote database.

Example

The following SELECT statement defines the upload cursor in the CustDB sample application.

SELECT cust_id, cust_name

FROM ULCustomer

WHERE cust_id = ?

The primary key of the ULCustomer table in the CustDB sample application is the column cust_id. If the corresponding table in the consolidated database is, instead, named Customer, then change the above statement as follows.

SELECT cust_id, cust_name

FROM Customer

WHERE cust_id = ?


Stored procedures
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

 Stored procedures

The script that adds the MobiLink tables to the consolidated database automatically defines the following stored procedures. They may be used to facilitate the process of adding synchronization scripts to the consolidated database.

 ml_add_connection_script

 ml_add_table_script


ml_add_connection_script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Stored procedures

 ml_add_connection_script

Function

Use this stored procedure to facilitate the task of adding connection scripts to the consolidated database.

Arguments

@version char(128),
@event char(128),
@script text

See also

ml_add_table_script

Description

The script is inserted into the ml_script table and the appropriate references are defined to associate this script with event @event and script version @version. If the version name is new, it is automatically inserted into the ml_version table.

Example

call ml_add_connection_script( 'version_1',

'begin_synchronization',

'set @EmployeeID = ?' )


ml_add_table_script
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Stored procedures

 ml_add_table_script

Function

Use this stored procedure to facilitate the task of adding table scripts to the consolidated database.

Arguments

@version char(128),
@name char(128),
@event char(128),
@script text

See also

ml_add_connection_script

Description

The script is inserted into the ml_script table and the appropriate references are defined to associate this script with table @name, event @event, and script version @version. If the version name is new, it is automatically inserted into the ml_version table.

Example

call ml_add_table_script( 'version_1',

'ULCustomer',

'upload_cursor',

'SELECT cust_id, cust_name

FROM ULCustomer WHERE cust_id = ?' )


SQL statements
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

 SQL statements

The following statements are required to synchronize Adaptive Server Anywhere applications.

 ALTER SYNCHRONIZATION DEFINITION statement

 ALTER SYNCHRONIZATION SITE statement

 ALTER SYNCHRONIZATION TEMPLATE statement

 CREATE SYNCHRONIZATION DEFINITION statement

 CREATE SYNCHRONIZATION SITE statement

 CREATE SYNCHRONIZATION TEMPLATE statement

 DROP SYNCHRONIZATION DEFINITION statement

 DROP SYNCHRONIZATION SITE statement

 DROP SYNCHRONIZATION TEMPLATE statement

 START SYNCHRONIZATION DELETE statement

 STOP SYNCHRONIZATION DELETE statement


ALTER SYNCHRONIZATION DEFINITION statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 ALTER SYNCHRONIZATION DEFINITION statement

Function

Use this statement to alter a synchronization definition.

Syntax

ALTER SYNCHRONIZATION DEFINITION SyncDefName
[ SITE SyncSiteName, ]
[ TYPE SyncType, ]
[ ADDRESS MLServerAddress, ]
[ ADD OPTION parameter=value, ... ]
[ MODIFY OPTION parameter=value, ... ]
[ DELETE OPTION parameter, ...
| DELETE ALL OPTION, ]
[ RENAME NewSyncDefName, ]
[ ADD TABLE article-description, ... ]
[ MODIFY TABLE article-description, ... ]
[ DELETE TABLE table-name, ... ]

article-description:
table-name [ ( column-name, ... ) ]
[ WHERE search-condition ]

value:
'string' | integer | "SQL variable name"

Permissions

Must have DBA authority. Requires exclusive access to all tables referred to in the statement.

Side effects

Automatic commit

See also

CREATE SYNCHRONIZATION DEFINITION statement

DROP SYNCHRONIZATION DEFINITION statement

Description

Synchronization definitions are created in Adaptive Server Anywhere database that are to serve as a MobiLink clients. Each definition specifies the site name that uniquely identifies that logical MobiLink client within the MobiLink setup. In addition, each site specifies how to contact the MobiLink synchronization server and which data in the remote database is to be synchronized with the consolidated database.

Use the ALTER SYNCHRONIZATION DEFINITION statement to alter a synchronization definition.

For example, if you wish to make changes to the options and set memory to 3 Mb, you can alter the synchronization definition as follows:

ALTER SYNCHRONIZATION DEFINITION mysharedtables

OPTION memory='3m'

Parameters

Using the following clauses, you can alter the settings in your synchronization definition.

SITE clause    The name that uniquely identifies this remote site within your MobiLink setup.

TYPE clause    The TYPE clause specifies the method of synchronization. The default value is TCP/IP. You may also choose to use HTTP.

ADDRESS clause    The ADDRESS clause specifies the location of the MobiLink synchronization server.

  For a complete list of the available parameters, see CREATE SYNCHRONIZATION DEFINITION statement.

ADD OPTION, MODIFY OPTION, DELETE OPTION AND DELETE ALL OPTION clause    These clauses allow you to add, modify, delete or delete all options. You may specify only one parameter in each clause. You can specify the clauses multiple times to affect more than one option.

The values for each option cannot contain the characters "=" or "," or ";".

For a list of available options, see CREATE SYNCHRONIZATION DEFINITION statement.

Enter options carefully
The database engine will accept any option that you enter without checking for its validity. Therefore, if you misspell an option, the engine will not detect the error and no error message will be given until you run the dbmlsync command to perform synchronization.

RENAME clause    Use this clause to rename your synchronization definition.

ADD TABLE, MODIFY TABLE AND DELETE TABLE clause    You have previously specified, in your CREATE SYNCHRONIZATION DEFINITION statement, the contents to be uploaded to the consolidated database. Use these clauses to make changes to the specification.

Compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Example

•	Alter the mysharedtables synchronization definition. Switch to a different remote site and set different options. In addition, the table Books is also uploaded to the consolidated database and only two columns of the People table are uploaded to the consolidated database.

ALTER SYNCHRONIZATION DEFINITION mysharedtables

SITE 'new_sync_site',

ADD OPTION verbose='on',

MODIFY OPTION memory='3m',

ADD TABLE Books,

MODIFY TABLE People(fname, lname);


ALTER SYNCHRONIZATION SITE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 ALTER SYNCHRONIZATION SITE statement

Function

Use this statement to alter a site within a MobiLink reference database, to be used when extracting remote Adaptive Server Anywhere client databases with the mlxtract command-line utility.

Syntax

ALTER SYNCHRONIZATION SITE SyncSiteName
[ RENAME NewSyncSiteName, ]
[ TYPE SyncType, ]
[ ADDRESS MLServerAddress, ]
[ ADD OPTION parameter=value, ... ]
[ MODIFY OPTION parameter=value, ... ]
[ DELETE OPTION parameter, ...
| DELETE ALL OPTION ]

Parameters

value:
'string' | integer | "variable name"

Permissions

Must have DBA authority.

Side effects

Automatic commit

See also

CREATE SYNCHRONIZATION SITE statement

DROP SYNCHRONIZATION SITE statement

Description

Synchronization templates and synchronization sites are used only when creating remote Adaptive Server Anywhere databases by means of extracting them from a MobiLink reference database.

Each remote database is created from a synchronization site, stored within the reference database. Each synchronization site is based upon a single synchronization template, although many sites can use a single template.

Use the ALTER SYNCHRONIZATION SITE statement to modify the properties of a synchronization site.

Parameters

Using the following clauses, you can alter the settings in your synchronization definition.

SITE clause    The name that uniquely identifies this remote site within your MobiLink setup.

TYPE clause    The TYPE clause specifies the method of synchronization. The default value is tcpip. You may also choose to use http.

ADDRESS clause    The ADDRESS clause specifies the location of the MobiLink synchronization server.

  For a complete list of the available parameters, see CREATE SYNCHRONIZATION DEFINITION statement.

ADD OPTION, MODIFY OPTION, DELETE OPTION AND DELETE ALL OPTION clause    These clauses allow you to add, modify, delete or delete all options. You may specify only one parameter in each clause.

The values for each option cannot contain the characters "=" or "," or ";".

For a list of available options, see CREATE SYNCHRONIZATION SITE statement.

Compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Example

•	Deploy mytemplate to a different remote site and set different options from the ones in the template.

ALTER SYNCHRONIZATION SITE USING mytemplate

SITE 'new_sync_site',

ADD OPTION verbose='on'

MODIFY OPTION memory='3m';


ALTER SYNCHRONIZATION TEMPLATE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 ALTER SYNCHRONIZATION TEMPLATE statement

Function

Use this statement to alter a template within a MobiLink reference database, to be used when extracting remote Adaptive Server Anywhere client databases with the mlxtract command-line utility.

Syntax

ALTER SYNCHRONIZATION TEMPLATE SyncTemplateName,
[ TYPE SyncType, ]
[ ADDRESS MLServerAddress, ]
[ ADD OPTION parameter=value, ... ]
[ MODIFY OPTION parameter=value, ... ]
[ DELETE OPTION parameter, ...
| DELETE ALL OPTION, ]
[ RENAME NewSyncDefName, ]
[ ADD TABLE article-description, ... ]
[ MODIFY TABLE article-description, ... ]
[ DELETE TABLE table-name, ... ]

article-description:
table-name [ ( column-name, ... ) ]
[ WHERE search-condition ]

value:
'string' | integer | "SQL variable name"

Permissions

Must have DBA authority. Requires exclusive access to all tables referred to in the statement.

Side effects

Automatic commit

See also

CREATE SYNCHRONIZATION TEMPLATE statement

DROP SYNCHRONIZATION TEMPLATE statement

Description

Synchronization templates and synchronization sites are used only when creating remote Adaptive Server Anywhere databases by means of extracting them from a MobiLink reference database.

Each remote database is created from a synchronization site, stored within the reference database. Each synchronization site is based upon a single synchronization template, although many sites can use a single template.

Use the ALTER SYNCHRONIZATION TEMPLATE statement to modify the properties of a synchronization template.

Parameters

Using the following clauses, you can alter the configurations in your synchronization definition.

TYPE clause    The TYPE clause specifies the method of synchronization. The default value is tcpip. You may also choose to use http.

ADDRESS clause    The ADDRESS clause specifies the location of the MobiLink synchronization server.

  For a complete list of the available parameters, see CREATE SYNCHRONIZATION DEFINITION statement.

ADD OPTION, MODIFY OPTION, DELETE OPTION AND DELETE ALL OPTION clause    These clauses allow you to add, modify, delete or delete all options. You may specify only one parameter in each clause.

The values for each option cannot contain the characters "=" or "," or ";".

For a list of available options, see CREATE SYNCHRONIZATION TEMPLATE statement.

RENAME clause    Use this clause to rename your synchronization definition.

ADD TABLE, MODIFY TABLE AND DELETE TABLE clause    You have previously specified, in your CREATE SYNCHRONIZATION DEFINITION statement, the contents to be uploaded to the consolidated database. Use these clauses to make changes to the specification.

Standards and compatibility

•	Sybase Adaptive Server Anywhere version 7.0.

Example

•	Alter the mytemplate synchronization template. Set different options. In addition, the table Books is also uploaded to the consolidated database, and only two columns of the People table is uploaded to the consolidated database.

ALTER SYNCHRONIZATION TEMPLATE mytemplate

ADD OPTION verbose='on',

MODIFY OPTION memory='3m',

ADD TABLE Books,

MODIFY TABLE (People(fname,lname));


CREATE SYNCHRONIZATION DEFINITION statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 CREATE SYNCHRONIZATION DEFINITION statement

Function

Use this statement to specify how to register with the MobiLink synchronization server and to identify the contents that are to be uploaded from the remote database to the consolidated database.

Syntax

CREATE SYNCHRONIZATION DEFINITION SyncDefName
SITE SyncSiteName
[ TYPE SyncType ]
ADDRESS MLServerAddress
[ OPTION parameter=value, ... ]
( TABLE article-description, ... )

Parameters

article-description:
table-name [ ( column-name, ... ) ]
[ WHERE search-condition ]

value:
'string' | integer | "SQL variable name"

Permissions

Must have DBA authority. Requires exclusive access to all tables named in the article description.

Side effects

Automatic commit

See also

ALTER SYNCHRONIZATION DEFINITION statement

DROP SYNCHRONIZATION DEFINITION statement

CREATE SYNCHRONIZATION TEMPLATE statement

CREATE SYNCHRONIZATION SITE statement

Description

Synchronization definitions are created in Adaptive Server Anywhere database that are to serve as a MobiLink clients. Each definition specifies the site name that uniquely identifies that logical MobiLink client within the MobiLink setup. In addition, each site specifies how to contact the MobiLink synchronization server and which data in the remote database is to be synchronized with the consolidated database.

Using this statement, you can set options and choose a method of synchronization. In addition, specify the contents that you wish to upload by listing each table, followed by the column list and the WHERE clause. The WHERE clause is a way of defining the subset of rows of a table to be included in a synchronization.

Parameters

SITE clause    The name that uniquely identifies this remote site within your MobiLink setup.

TYPE clause    This clause specifies the method of synchronization. The default value is tcpip. You may also choose to use http.

ADDRESS clause    This clause specifies the location of the MobiLink synchronization server.

Include the following parameter to encrypt all communication with the MobiLink synchronization server.

•	TCP/IP parameters    These are chosen from the following list:

•	host=hostname    The host name or IP number for the machine on which the MobiLink synchronization server is running. The default value is localhost. For Windows CE, the default value is the value of ipaddr in the registry folder Comm\Tcpip\Hosts\ppp_peer. This allows a Windows CE device to connect to a MobiLink synchronization server executing on the desktop machine where the Windows CE device's cradle is connected.

For the Palm Computing Platform, the default value of localhost refers to the device. It is recommended that an explicit host name or IP address be specified.

•	port=portnumber    The socket port number. The port number must be a decimal number that matches the port the MobiLink synchronization server is setup to monitor. The default value for the port parameter is 2439, which is the IANA registered port number for the MobiLink synchronization server.

•	security=cipher{keyword=value;...}    All communication through this connection is to be encrypted using the cipher suite specified. You can use only one cipher suite at a time. The only cipher suite presently supported is certicom_tls, Certicom transmission-layer security. The following security keywords are supported.

•	certificate_company    The UltraLite application only accepts server certificates when the organization field on the certificate matches this value. By default, this field is not checked.

•	certificate_unit    The UltraLite application only accepts server certificates when the organization unit field on the certificate matches this value. By default, this field is not checked.

•	certificate_name    The UltraLite application only accepts server certificates when the common name field on the certificate matches this value. By default, this field is not checked.

•	trusted_certificates    When synchronization occurs through a Certicom TLS synchronization stream, the MobiLink synchronization server sends its certificate to the client, as well as the certificate of the entity that signed it, and so on up to a self-signed root.

The client checks that the chain is valid and that it trusts the root certificate in the chain. This feature allows you to specify which root certificates to trust. By default, a Sybase certificate and a Certicom certificate are the trusted roots.

•	HTTP parameters    These are chosen from the following list:

•	host=hostname    The host name or IP number for the machine on which the MobiLink synchronization server is running. The default value is localhost. For Windows CE, the default value is the value of ipaddr in the registry folder Comm\Tcpip\Hosts\ppp_peer. This allows a Windows CE device to connect to a MobiLink synchronization server executing on the desktop machine where the Windows CE device's cradle is connected.

For the Palm Computing Platform, the default value of localhost refers to the device. It is recommended that an explicit host name or IP address be specified.

•	port=portnumber    The socket port number. The port number must be a decimal number that matches the port the MobiLink synchronization server is setup to monitor. The default value for the port parameter is 2439, which is the IANA registered port number for the MobiLink synchronization server.

•	proxy_host=proxy_hostname    The host name or IP address of the proxy server. The default value is localhost.

•	proxy_port=proxy_portnumber    The port number of the proxy server. The default value is 80.

•	security=cipher{keyword=value;...}    All communication through this connection is to be encrypted using the cipher suite specified. You can use only one cipher suite at a time. The only cipher suite presently supported is certicom_tls, Certicom transmission-layer security. The following security keywords are supported.

•	certificate_company    The UltraLite application only accepts server certificates when the organization field on the certificate matches this value. By default, this field is not checked.

•	certificate_unit    The UltraLite application only accepts server certificates when the organization unit field on the certificate matches this value. By default, this field is not checked.

•	certificate_name    The UltraLite application only accepts server certificates when the common name field on the certificate matches this value. By default, this field is not checked.

•	trusted_certificates    When synchronization occurs through a Certicom TLS synchronization stream, the MobiLink synchronization server sends its certificate to the client, as well as the certificate of the entity that signed it, and so on up to a self-signed root.

The client checks that the chain is valid and that it trusts the root certificate in the chain. This feature allows you to specify which root certificates to trust. By default, a Sybase certificate and a Certicom certificate are the trusted roots.

•	url_suffix=suffix    The suffix to add to the URL on the first line of each HTTP request. When synchronizing through a proxy server, the suffix may be necessary in order to find the MobiLink synchronization server. The default value is MobiLink.

•	version=versionnumber    A string specifying the version of HTTP to use. You have a choice of 1.0 or 1.1. The default value is 1.1.

OPTION clause    The OPTION clause allows you to set the following. Set the appropriate options using option=value in a comma-delimited list.

Below is the list of options available:

Full Name	Short name	Default	Description
ConflictRetries	cr	-1 (Continue indefinitely)	Number of retries if download fails because of conflicts.
FireTriggers	ft	ON	Fire triggers on download.
Increment	inc	No limit	Upload in increments of specified size.
LockTables	lt	ON	Set to OFF to allow modifications during synchronization
Memory	mem	1 Mb	Memory used for synchronization.
OfflineDirectory	dir	NULL	Path containing offline transaction logs.
Schedule	sch	No schedule	Schedule string. For more information, see Scheduling synchronization.
ScriptsVersion	sv	default	Tells the MobiLink synchronization server to use the scripts for the named schema version, overriding the setting of the synchronization definition option sv.
SendTriggers	st	OFF	Send trigger actions on upload.
StreamCompression	sc	MEDIUM	Compress upload data stream: choose LOW, MEDIUM, or HIGH.
Verbose	v	OFF	Verbose operation.
The values for each option cannot contain the characters "=" or "," or ";".

Enter options carefully
The database engine will accept any option that you enter without checking for its validity. Therefore, if you misspell an option, the engine will not detect the error and no error message will be given until you run the dbmlsync command to perform synchronization.

  For information on how the options can be used to tune synchronization, see Tuning synchronization.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Example

•	Use TCP/IP synchronization to upload the row(s) of the Pets table with a pet_id of 2 as well as the person_id, fname, and lname columns of the People table from the remote database to the consolidated database:

CREATE SYNCHRONIZATION DEFINITION mysharedtables

SITE 'demo_sync_site'

TYPE 'tcpip'

ADDRESS 'host=localhost;port=2439;'

OPTION memory='2m', dir='c:\db\logs'

(table People( person_id, fname, lname ),

table Pets WHERE pet_id=2);


CREATE SYNCHRONIZATION SITE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 CREATE SYNCHRONIZATION SITE statement

Function

Use this statement to create a site within a MobiLink reference database, to be used when extracting remote Adaptive Server Anywhere client databases with the mlxtract command-line utility.

Syntax

CREATE SYNCHRONIZATION SITE SyncSiteName
USING SyncTemplateName
[TYPE SyncType]
[ADDRESS MLServerAddress]
[OPTION parameter=value]

Permissions

Must have DBA authority.

Side effects

Automatic commit

See also

ALTER SYNCHRONIZATION SITE statement

DROP SYNCHRONIZATION SITE statement

CREATE SYNCHRONIZATION DEFINITION statement

CREATE SYNCHRONIZATION TEMPLATE statement

Tuning synchronization

Description

Synchronization templates and synchronization sites are used only when creating remote Adaptive Server Anywhere databases by means of extracting them from a MobiLink reference database.

Each remote database is created from a synchronization site, stored within the reference database. Each synchronization site is based upon a single synchronization template, although many sites can use a single template.

Information that is common to many sites should be stored in the synchronization template, rather than be duplicated in each site.

The extraction process not only creates the remote databases, but also creates a synchronization definition using properties of the corresponding synchronization template and site. This information must include the unique name of that MobiLink site within the MobiLink system. In addition, it should specify how to contact the MobiLink synchronization server and which data in the remote database is to be synchronized.

Using this statement to create a separate synchronization site for each remote database. This statement also allows you to override the template settings. For example, you can choose options different than those specified in the template

Parameters

SITE clause    The name that uniquely identifies this remote site within your MobiLink setup.

TYPE clause    The TYPE clause specifies the method of synchronization. The default value is tcpip. You may also choose to use http.

ADDRESS clause    The ADDRESS clause specifies the location of the MobiLink synchronization server. The value of this clause overrides the value in the synchronization template.

  For a complete list of the available parameters, see CREATE SYNCHRONIZATION DEFINITION statement.

OPTION clause    The OPTION clause allows you to set the following options. Set the appropriate options using a comma-delimited list.

The values for each option cannot contain the characters "=" or "," or ";".

Below is the list of options available:

Full Name	Short name	Default	Description
ConflictRetries	cr	-1 (Continue indefinitely)	Number of retries if download fails because of conflicts.
FireTriggers	ft	ON	Fire triggers on download.
Increment	inc	No limit	Upload in increments of specified size.
LockTables	lt	ON	Set to OFF to allow modifications during synchronization
Memory	mem	1 Mb	Memory used for synchronization.
OfflineDirectory	dir	NULL	Path containing offline transaction logs.
Schedule	sch	No schedule	Schedule string. For more information, see Scheduling synchronization.
ScriptsVersion	sv	default	Tells the MobiLink synchronization server to use the scripts for the named schema version, overriding the setting of the synchronization definition option sv.
SendTriggers	st	OFF	Send trigger actions on upload.
StreamCompression	sc	MEDIUM	Compress upload data stream: choose LOW, MEDIUM, or HIGH.
Verbose	v	OFF	Verbose operation.
  For more information, see Tuning synchronization.

  For more information on ConflictRetries and LockTables, see Concurrency during synchronization.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Examples

•	Deploy the template mytemplate to site demo_sync_site. Connect to a different MobiLink synchronization server from the one specified in the template and set the memory option to 3 Mb.

CREATE SYNCHRONIZATION SITE 'demo_sync_site'

USING mytemplate

ADDRESS 'host=test.internal;port=2439;'

OPTION memory='3m';

•	Deploy the template mytemplate to site demo_sync_site using Certicom transmission-layer security.

CREATE SYNCHRONIZATION SITE 'demo_sync_site'

USING mytemplate2

ADDRESS 'host=test.internal;port=2439;

security=certicom_tls'


CREATE SYNCHRONIZATION TEMPLATE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 CREATE SYNCHRONIZATION TEMPLATE statement

Function

Use this statement to create a template within a MobiLink reference database, to be used when extracting remote Adaptive Server Anywhere client databases with the mlxtract command-line utility.

Syntax

CREATE SYNCHRONIZATION TEMPLATE SyncTemplateName
[ TYPE SyncType ]
ADDRESS MLServerAddress
[ OPTION option=value]
( TABLE article-description, ... )

Parameters

article-description:
table-name [ ( column-name, ... ) ]
[ WHERE search-condition ]

value:
'string' | integer | "SQL variable name"

Permissions

Must have DBA authority. Requires exclusive access to all tables referred to in the statement.

Side effects

Automatic commit

See also

ALTER SYNCHRONIZATION TEMPLATE statement

DROP SYNCHRONIZATION TEMPLATE statement

CREATE SYNCHRONIZATION DEFINITION statement

CREATE SYNCHRONIZATION SITE statement

Description

Synchronization templates and synchronization sites are used only when creating remote Adaptive Server Anywhere databases by means of extracting them from a MobiLink reference database.

Each remote database is created from a synchronization site, stored within the reference database. Each synchronization site is based upon a single synchronization template, although many sites can use a single template.

Information that is common to many sites should be stored in the synchronization template, rather than be duplicated in each site.

The extraction process not only creates the remote databases, but also creates a synchronization definition using properties of the corresponding synchronization template and site. This information must include the unique name of that MobiLink site within the MobiLink system. In addition, it should specify how to contact the MobiLink synchronization server and which data in the remote database is to be synchronized.

Use this statement to create a template for each type of remote database.

Parameters

TYPE clause    The TYPE clause specifies the method of synchronization. The default value is tcpip. You may also choose to use http.

ADDRESS clause    The ADDRESS clause specifies the location of the MobiLink synchronization server.

  For a complete list of the available parameters, see CREATE SYNCHRONIZATION DEFINITION statement.

OPTION clause    The OPTION clause allows you to set the following options:

The values for each option cannot contain the characters "=" or "," or ";".

Below is the list of options available:

Full Name	Short name	Default	Description
ConflictRetries	cr	-1 (Continue indefinitely)	Number of retries if download fails because of conflicts.
FireTriggers	ft	ON	Fire triggers on download.
Increment	inc	No limit	Upload in increments of specified size.
LockTables	lt	ON	Set to OFF to allow modifications during synchronization
Memory	mem	1 Mb	Memory used for synchronization.
OfflineDirectory	dir	NULL	Path containing offline transaction logs.
Schedule	sch	No schedule	Schedule string. For more information, see Scheduling synchronization.
ScriptsVersion	sv	default	Tells the MobiLink synchronization server to use the scripts for the named schema version, overriding the setting of the synchronization definition option sv.
SendTriggers	st	OFF	Send trigger actions on upload.
StreamCompression	sc	MEDIUM	Compress upload data stream: choose LOW, MEDIUM, or HIGH.
Verbose	v	OFF	Verbose operation.
  For more information, see Tuning synchronization.

  For more information on ConflictRetries and LockTables, see Concurrency during synchronization.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Example

•	Use TCP/IP synchronization to upload the row(s) of the Pets table with a pet_id of 2 as well as the person_id, fname, and lname columns of the People table from the remote database to the consolidated database:

CREATE SYNCHRONIZATION TEMPLATE mytemplate

TYPE 'tcpip'

ADDRESS 'host=localhost;port=2439;'

OPTION memory='2m', dir='c:\db\logs'

(table People( person_id, fname, lname ),

table Pets WHERE pet_id=2);


DROP SYNCHRONIZATION DEFINITION statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 DROP SYNCHRONIZATION DEFINITION statement

Function

Use this statement to drop a synchronization definition.

Syntax

DROP SYNCHRONIZATION DEFINITION SyncDefName

Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

CREATE SYNCHRONIZATION DEFINITION statement

ALTER SYNCHRONIZATION DEFINITION statement

Description

Synchronization definitions are created in Adaptive Server Anywhere database that are to serve as a MobiLink clients. Each definition specifies the site name that uniquely identifies that logical MobiLink client within the MobiLink setup. In addition, each site specifies how to contact the MobiLink synchronization server and which data in the remote database is to be synchronized with the consolidated database.

Use the DROP SYNCHRONIZATION DEFINITION statement to drop a synchronization definition.

Note, however, that once a synchronization definition has been dropped, outstanding updates (insert, delete, update and alter commands) will not be synchronized.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Example

•	Drop the mysharedtables synchronization definition.

DROP SYNCHRONIZATION DEFINITION mysharedtables;


DROP SYNCHRONIZATION SITE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 DROP SYNCHRONIZATION SITE statement

Function

Use this statement to drop a specific synchronization site.

Syntax

DROP SYNCHRONIZATION SITE SyncSiteName

Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

CREATE SYNCHRONIZATION SITE statement

ALTER SYNCHRONIZATION SITE statement

Description

Synchronization templates and synchronization sites are used only when creating remote Adaptive Server Anywhere databases by means of extracting them from a MobiLink reference database.

Each remote database is created from a synchronization site, stored within the reference database. Each synchronization site is based upon a single synchronization template, although many sites can use a single template.

Use the DROP SYNCHRONIZATION SITE statement to drop a specific synchronization site.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Example

•	The template mytemplate will no longer be deployed to the new_sync_site remote site.

DROP SYNCHRONIZATION SITE new_sync_site;


DROP SYNCHRONIZATION TEMPLATE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 DROP SYNCHRONIZATION TEMPLATE statement

Function

Use this statement to drop a synchronization template.

Syntax

DROP SYNCHRONIZATION TEMPLATE SyncTemplateName

Permissions

Must have DBA authority.

Side effects

Automatic commit. Dropping a synchronization template implicitly drops all sites using that template.

See also

CREATE SYNCHRONIZATION TEMPLATE statement

ALTER SYNCHRONIZATION TEMPLATE statement

Description

Synchronization templates and synchronization sites are used only when creating remote Adaptive Server Anywhere databases by means of extracting them from a MobiLink reference database.

Each remote database is created from a synchronization site, stored within the reference database. Each synchronization site is based upon a single synchronization template, although many sites can use a single template.

Use the DROP SYNCHRONIZATION TEMPLATE statement to drop a synchronization template.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.

Example

•	Drop the mytemplate synchronization template.

DROP SYNCHRONIZATION TEMPLATE mytemplate;


START SYNCHRONIZATION DELETE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 START SYNCHRONIZATION DELETE statement

Function

Use this statement to restart logging of deletes for MobiLink synchronization.

Syntax

START SYNCHRONIZATION DELETE

Permissions

Must have DBA authority.

See also

STOP SYNCHRONIZATION DELETE statement

Description

Ordinarily, Adaptive Server Anywhere automatically logs any changes made to tables or columns that are part of a synchronization template and uploads these changes to the consolidated database during the next synchronization. You can temporarily suspend automatic logging of delete operations using the STOP SYNCHRONIZATION DELETE statement. The START SYNCHRONIZATION DELETE statement allows you to restart the automatic logging.

When a STOP SYNCHRONIZATION DELETE statement is executed, none of the delete operations executed on that connection will be synchronized. The effect continues until a START SYNCHRONIZATION DELETE statement is executed. The effects do not nest; that is, subsequent execution of stop synchronization delete after the first will have no additional effect. A single START SYNCHRONIZATION DELETE statement restarts the logging, regardless of the number of STOP SYNCHRONIZATION DELETE statements preceding it.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.


STOP SYNCHRONIZATION DELETE statement
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        SQL statements

 STOP SYNCHRONIZATION DELETE statement

Function

Use this statement to temporarily stop logging of deletes for MobiLink synchronization.

Syntax

STOP SYNCHRONIZATION DELETE

Permissions

Must have DBA authority.

See also

START SYNCHRONIZATION DELETE statement

Description

Ordinarily, Adaptive Server Anywhere automatically logs any changes made to tables or columns that are part of a synchronization template and uploads these changes to the consolidated database during the next synchronization. This statement allows you to temporarily suspend logging of changes to a remote Adaptive Server Anywhere database.

When a STOP SYNCHRONIZATION DELETE statement is executed, none of the subsequent delete operations executed on that connection will be synchronized. The effect continues until a START SYNCHRONIZATION DELETE statement is executed. The effects do not nest; that is, subsequent execution of stop synchronization delete after the first will have no additional effect. A single START SYNCHRONIZATION DELETE statement restarts the logging, regardless of the number of STOP SYNCHRONIZATION DELETE statements preceding it.

This command can be useful to make corrections to a remote site, but should be used with caution as it effectively disables MobiLink synchronization.

Standards and compatibility

•	Sybase    Adaptive Server Anywhere version 7.0.


Client event-hook procedures
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

 Client event-hook procedures

The following stored procedure names and arguments provide the interface for customizing synchronization at Adaptive Server Anywhere clients. For more information, see Customizing the synchronization process.

The event-hook connection calls the stored procedures without qualifying them by owner. The stored procedures must therefore be owned by one of the following:

•	The user name employed on the dbmlsync connection (typically a user with REMOTE DBA authority).

•	A group ID of which the dbmlsync user is a member.

Caution
Do not perform any COMMIT or ROLLBACK operations in event-hook procedures. The procedures are executed on the same connection as the synchronization, and a COMMIT or ROLLBACK causes the synchronization to fail.

 sp_hook_dbmlsync_abort

 sp_hook_dbmlsync_begin

 sp_hook_dbmlsync_delay

 sp_hook_dbmlsync_download_begin

 sp_hook_dbmlsync_download_com_error

 sp_hook_dbmlsync_download_end

 sp_hook_dbmlsync_download_fatal_sql_error

 sp_hook_dbmlsync_download_sql_error

 sp_hook_dbmlsync_download_table_begin

 sp_hook_dbmlsync_download_table_end

 sp_hook_dbmlsync_end

 sp_hook_dbmlsync_logscan_begin

 sp_hook_dbmlsync_logscan_end

 sp_hook_dbmlsync_upload_begin

 sp_hook_dbmlsync_upload_end


sp_hook_dbmlsync_abort
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_abort

Function

Use this stored procedure to cancel the synchronization process.

Event arguments

abort synchronization  ( in | out )
synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called at the beginning of the sequence of events, and then again after each synchronization delay.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

abort synchronization    If you set the abort synchronization row of the #hook_dict table to true, then dbmlsync terminates immediately after the event.

synchronization definition name    The name of the synchronization definition being synchronized.

Example

The following procedure prevents synchronization during a scheduled maintenance hour between 19:00 and 20:00 each day.

create procedure sp_hook_dbmlsync_abort()

begin

  declare down_time_start time;

  declare is_down_time varchar(128);

  set down_time_start='19:00';

  if abs( datediff( hour,down_time_start,now(*) ) ) < 1

  then

    set is_down_time='true';

  else

    set is_down_time='false';

  end if;

  update #hook_dict set

  value = is_down_time where

  name = 'abort synchronization'

end


sp_hook_dbmlsync_begin
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_begin

Function

Use this stored procedure to add custom actions at the beginning of the synchronization process.

Event arguments

synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called at the beginning of the synchronization process.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.


sp_hook_dbmlsync_delay
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_delay

Function

Use this stored procedure to control when synchronization takes place.

Event arguments

delay duration ( in | out )
maximum accumulated delay ( in | out )
synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called before sp_hook_dbmlsync_begin at the beginning of the synchronization process.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

delay duration    It the procedure sets the delay duration value to zero, then dbmlsync synchronization proceeds. A non-zero delay_duration value specifies the number of seconds before the delay hook is called again.

maximum accumulated delay    If the time since dbmlsync started is greater than the value of maximum accumulated delay, then synchronization proceeds. If dbmlsync is run with a schedule string the total delay time is measured from the more recent of the time dbmlsync started and the end of the last synchronization attempt.

If neither of these two conditions is met, sp_hook_dbmlsync_abort is called, and then sp_hook_dbmlsync_delay is called again.

synchronization definition name    The name of the synchronization definition being synchronized.

Example

The following procedure delays synchronization during a scheduled maintenance hour between 19:00 and 20:00 each day.

create procedure sp_hook_dbmlsync_delay()

begin

  declare down_time_start time;

  declare is_down_time varchar(128);

  set down_time_start='19:00';

  if abs( datediff( minute,down_time_start,now(*) ) ) <

  60 then

    set is_down_time='10';

  else

    set is_down_time='0';

  end if;

  update #hook_dict set

  value = is_down_time where

  name = 'delay duration'

end


sp_hook_dbmlsync_download_begin
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_download_begin

Function

Use this stored procedure to add custom actions at the beginning of the download stage of the synchronization process.

Event arguments

synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called at the beginning of the download stage of the synchronization process.

Actions of this procedure are committed or rolled back when the download stream is committed or rolled back.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.


sp_hook_dbmlsync_download_com_error
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_download_com_error

Function

Use this stored procedure to report communications errors when reading the download stream sent by the MobiLink synchronization server.

Event arguments

synchronization definition name ( in )
table name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is invoked when a communication error is detected during the download phase of synchronization. The download is then terminated.

This procedure executes on a separate connection, so that failures can be logged. Otherwise, the action of logging would be rolled back along with the synchronization actions. If dbmlsync cannot establish a separate connection, the procedure is not called.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.

table name    The table to which updates were being applied when the error occurred. The value is an empty string if dbmlsync is unable to identify the table.


sp_hook_dbmlsync_download_end
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_download_end

Function

Use this stored procedure to add custom actions at the end of the download stage of the synchronization process.

Event arguments

synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called at the end of the download stage of the synchronization process.

Actions of this procedure are committed or rolled back when the download stream is committed or rolled back.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.


sp_hook_dbmlsync_download_fatal_sql_error
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_download_fatal_sql_error

Function

Take action when a synchronization download is about to be rolled back because of a database error.

Event arguments

synchronization definition name ( in )
table name ( in )
SQL error code ( in )

See also

Synchronization event hook architecture

sp_hook_dbmlsync_download_sql_error

Description

If a procedure of this name exists, it is called immediately before a synchronization download is rolled back because of a database error. This occurs whenever an SQL error is encountered that cannot be ignored, or when the sp_hook_dbmlsync_download_sql_error hook has already been called and has chosen not to ignore the error.

This procedure executes on a separate connection, so that failures can be logged. Otherwise, the action of logging would be rolled back along with the synchronization actions. If dbmlsync cannot establish a separate connection, the procedure is not called.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.

table name    The table to which updates were being applied when the error occurred. The value is an empty string if dbmlsync is unable to identify the table.

SQL error code    Identifies the SQL error code returned by the database when the operation failed.


sp_hook_dbmlsync_download_sql_error
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_download_sql_error

Function

Handle database errors reading the download stream sent by the MobiLink synchronization server.

Event arguments

synchronization definition name ( in )
table name ( in )
SQL error code ( in )
continue ( in | out )

See also

Synchronization event hook architecture

sp_hook_dbmlsync_download_fatal_sql_error

Description

If a procedure of this name exists, it is invoked when a database error is detected during synchronization. The procedure is only invoked for errors where it is possible to ignore the error and continue with synchronization. For fatal errors, the sp_hook_dbmlsync_download_fatal_sql_error procedure is called.

Actions of this procedure are committed or rolled back when the download stream is committed or rolled back.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.

table name    The table to which updates were being applied when the error occurred. The value is an empty string if dbmlsync is unable to identify the table.

SQL error code    Identifies the SQL error code returned by the database when the operation failed.

continue    Indicates whether the error should be ignored and synchronization should continue. This parameter should be set to true to ignore the error and continue or false to stop synchronization. When true is returned in this field the update that caused the SQL error is lost.


sp_hook_dbmlsync_download_table_begin
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_download_table_begin

Function

Use this stored procedure to add custom actions immediately before each table is downloaded.

Event arguments

synchronization definition name ( in )
table name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called immediately before any table is to be downloaded.

Actions of this procedure are committed or rolled back when the download stream is committed or rolled back.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.

table name    The table to which updates are about to be applied.


sp_hook_dbmlsync_download_table_end
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_download_table_end

Function

Use this stored procedure to add custom actions immediately after each table is downloaded.

Event arguments

delete count ( in )
synchronization definition name ( in )
table name ( in )
upsert count ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called immediately after any table is to be downloaded.

Actions of this procedure are committed or rolled back when the download stream is committed or rolled back.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

delete count    The number of rows in this table deleted by the download stream.

synchronization definition name    The name of the synchronization definition being synchronized.

table name    The table to which updates have finished being be applied.

upsert count    The number of rows in this table updated or inserted by the download stream.


sp_hook_dbmlsync_end
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_end

Function

Use this stored procedure to add custom actions immediately before synchronization is complete.

Event arguments

synchronization definition name ( in )
exit code ( in | out )
restart ( in | out )

See also

Customizing the synchronization process

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called as the last event during synchronization.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.

exit code    If set to anything other than zero (the default), this represents a synchronization error.

restart    If set to true then, instead of shutting down, dbmlsync begins a new synchronization subject to the same scheduling parameters that applied to the synchronization it just completed. If the field is false (the default) then dbmlsync shuts down or restarts according to its command-line arguments.


sp_hook_dbmlsync_logscan_begin
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_logscan_begin

Function

Use this stored procedure to add custom actions immediately before the transaction log is scanned for upload.

Event arguments

log scan retry ( in )
starting log offset ( in )
synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called immediately before dbmlsync scans the transaction log to assemble the upload stream.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

log scan retry    If this is the first time the transaction log has been scanned for this synchronization, the value is false; otherwise it is true. The log is scanned twice when the MobiLink synchronization server and dbmlsync have different information about where the scanning should begin.

starting log offset    The log offset value where scanning is to begin.

synchronization definition name    The name of the synchronization definition being synchronized.


sp_hook_dbmlsync_logscan_end
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_logscan_end

Function

Use this stored procedure to add custom actions immediately after the transaction log is scanned for upload.

Event arguments

ending log offset ( in )
log scan retry ( in )
starting log offset ( in )
synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called immediately after dbmlsync has scanned the transaction log to assemble the upload stream.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

ending log offset     The log offset value where scanning ended.

log scan retry    If this is the first time the transaction log has been scanned for this synchronization, the value is false; otherwise it is true. The log is scanned twice when the MobiLink synchronization server and dbmlsync have different information about where the scanning should begin.

starting log offset    The log offset value where scanning began.

synchronization definition name    The name of the synchronization definition being synchronized.


sp_hook_dbmlsync_upload_begin
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_upload_begin

Function

Use this stored procedure to add custom actions immediately before the transmission of the upload.

Event arguments

synchronization definition name ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called immediately before dbmlsync sends the upload stream.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.


sp_hook_dbmlsync_upload_end
  Replication and Synchronization Guide

    PART 2. MobiLink Synchronization

      CHAPTER 8.  Reference

        Client event-hook procedures

 sp_hook_dbmlsync_upload_end

Function

Use this stored procedure to add custom actions after dbmlsync has verified receipt of the upload stream by the MobiLink synchronization server.

Event arguments

synchronization definition name ( in )
upload status ( in )

See also

Synchronization event hook architecture

Description

If a procedure of this name exists, it is called immediately after dbmlsync has sent the upload stream and received confirmation of it from the MobiLink synchronization server.

Actions of this procedure are committed immediately after execution.

Parameters

Each parameter is an entry in the #hook_dict table. It is set by dbmlsync before the procedure is called. IN parameters are read-only, while OUT parameters can be modified by the event-hook procedure.

synchronization definition name    The name of the synchronization definition being synchronized.

upload status    Specifies the status returned by the MobiLink synchronization server when dbmlsync attempts to verify receipt of the upload stream. The values currently supported are:

•	retry    The MobiLink synchronization server and dbmlsync had different values for the log offset that the upload stream should start from. The upload stream was not committed by the MobiLink synchronization server. The dbmlsync utility then attempts to send another upload stream starting from a new log offset.

•	committed    The upload stream was received by the MobiLink synchronization server, and committed.

•	failed    The MobiLink synchronization server did not commit the upload stream.


PART 3. SQL Remote
  Replication and Synchronization Guide

 PART 3. SQL Remote

This part describes the concepts, architecture, and features of SQL Remote. The material in this part refers to both SQL Remote for Adaptive Server Anywhere and SQL Remote for Adaptive Server Enterprise.

 CHAPTER 9.  Welcome to SQL Remote

 CHAPTER 10.  SQL Remote Concepts

 CHAPTER 11.  Setting Up SQL Remote

 CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 CHAPTER 14.  Principles of SQL Remote Design

 CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 CHAPTER 17.  Deploying and Synchronizing Databases

 CHAPTER 18.  SQL Remote Administration

 CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

 CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

 CHAPTER 21.  Using SQL Remote with Replication Server

 CHAPTER 22.  Utilities and Options Reference

 CHAPTER 23.  System Objects for Adaptive Server Anywhere

 CHAPTER 24.  System Objects for Adaptive Server Enterprise

 CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 CHAPTER 26.  Command Reference for Adaptive Server Enterprise


CHAPTER 9.  Welcome to SQL Remote
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 9.  Welcome to SQL Remote

About this chapter

This chapter introduces SQL Remote and the documentation.

 About SQL Remote

 About this manual

 New features in 7.0.1

 New features in version 7.0

 New features in version 6.0.3

 New features in version 6.0.2


About SQL Remote
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

 About SQL Remote

SQL Remote is a data-replication technology designed for two-way replication between a consolidated data server and large numbers of remote databases, typically including many mobile databases.

SQL Remote replication is message based, and requires no direct server-to-server connection. An occasional dial-up or e-mail link is sufficient.

Administration and resource requirements at the remote sites are minimal. The time lag between the consolidated and remote databases is configurable, and can range from minutes to hours or days.

Sybase SQL Remote technology is provided in two forms:

•	SQL Remote for Adaptive Server Anywhere    Enables replication between a consolidated Adaptive Server Anywhere database and a large number of remote databases.

•	SQL Remote for Adaptive Server Enterprise    Enables replication between a consolidated Adaptive Server Enterprise database and a large number of remote Adaptive Server Anywhere databases.

This book describes both of these technologies.

In a SQL Remote installation, you must have properly licensed SQL Remote software at each participating database.

  For a detailed introduction to SQL Remote concepts and features, see SQL Remote Concepts.

  For a list of supported operating systems and message links, see Supported Platforms and Message Links.


About this manual
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

 About this manual

This manual describes how to design, build, and maintain SQL Remote installations.

The manual includes the following parts.

•	Introduction to SQL Remote    Replication concepts and features of SQL Remote.

•	Replication Design for SQL Remote    Designing SQL Remote installations.

•	SQL Remote Administration    Deploying SQL Remote databases and administering a running SQL Remote setup.

•	Reference    SQL Remote commands, system tables, and other reference material.

 Platforms and products covered by this manual

 Product installation


Platforms and products covered by this manual
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

        About this manual

 Platforms and products covered by this manual

This documentation applies to all supported platforms of SQL Remote. Not all features are available on all platforms. The operating systems and features you are entitled to use depends on the product you have purchased and your license agreement.

Available formats

The contents of this manual are provided online and in print. In some cases, the print documentation must be purchased separately.

Online documentation most current
The online documentation contains the most current information about SQL Remote. It is more authoritative than the printed manual.


Product installation
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

        About this manual

 Product installation

This section describes installation of SQL Remote for Adaptive Server Enterprise. If you obtained SQL Remote as part of another product, consult the installation instructions for the product you purchased.

♦ To install the SQL Remote software for PC's:

1	Insert the CD-ROM into your CD-ROM drive.

2	If the installation program does not start automatically, start the setup application on the CD-ROM.

3	Follow the instructions in the installation program.

♦ To install the SQL Remote software for UNIX:

•	Consult the instructions for your operating system in the Adaptive Server Anywhere Read Me First booklet.

  If you are using SQL Remote for Adaptive Server Enterprise, you must install SQL Remote into any database you wish to replicate. For information about installing SQL Remote into a database, see Setting Up SQL Remote.


New features in 7.0.1
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

 New features in 7.0.1

SQL Remote version 7.0 includes the following new features.

•	More message links on Novell NetWare    You can now use the FTP and SMTP/POP message links on Novell NetWare.

  For a listing of supported platforms and message links, see Supported operating systems.

•	Enhanced verbose mode    Verbose mode for the Message Agent now writes out full connection information, with user IDs and passwords replaced by asterisks.


New features in version 7.0
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

 New features in version 7.0

SQL Remote version 7.0 includes the following new features.

•	Globally unique primary keys    You can now use a DEFAULT GLOBAL AUTOINCREMENT column in an Adaptive Server Anywhere database, together with a GLOBAL_DATABASE_ID option setting in each database, to guarantee unique primary keys throughout a SQL Remote installation of Adaptive Server Anywhere databases. This is a more convenient method than the more manual primary key pool technique.

  For more information, see Using the default global autoincrement feature.

•	Internal unload for dbxtract    The dbxtract utility now uses the UNLOAD statement introduced in Adaptive Server Anywhere version 7.0 by default, rather than the slower OUTPUT statement. Command-line options have been introduced to allow you to choose a combination of internal (server-side) and external (client-side) unload and load operations.

  For a complete listing of command-line options, see The extraction command-line utility.

 Behavior changes


Behavior changes
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

        New features in version 7.0

 Behavior changes

The following behavior has changed in version 7.0:

•	dbxtract uses internal unload    The default behavior of dbxtract is now to use the UNLOAD statement to unload data on the server side, rather than the OUTPUT statement to unload data on the client side. The -ii, -ix, -xi, -xx command-line options allow you to choose which combination of internal and external operations to use, and replace the options -i and -x available in previous releases.

  For a complete listing of command-line options, see The extraction command-line utility.


New features in version 6.0.3
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

 New features in version 6.0.3

In addition to bug fixes, SQL Remote version 6.0.3 includes the following new features. Some features in Adaptive Server Anywhere that are particularly relevant to SQL Remote are also included in this list:

•	FTP and SMTP/POP support on UNIX    The range of message systems supported on UNIX operating systems has been expanded to include FTP and SMTP/POP.

  For a listing of supported operating and message systems, see Supported Platforms and Message Links.

•	Message link options stored in the database    The message link parameters that control SQL Remote behavior over each message system can now be stored in the database as opposed to the registry. This simplifies deployment and management issues related to message link parameters.

  For more information, see Setting message type control parameters, SET REMOTE OPTION statement, and sp_link_option procedure.

•	Date and time replication formats    You can now specify database options that instruct SQL Remote what format to use when replicating dates and times. These options are SR_time_format, SR_date_format, and SR_timestamp_format.

  For more information, see Replication of dates and times, and SQL Remote options.

•	Message Agent and SQL Remote Open Server run as a daemon    On UNIX operating systems you can run these applications as a daemon using the -ud command-line option.

  For more information, see The Message Agent, and The SQL Remote Open Server.

•	Easier unload and reload of Adaptive Server Anywhere databases    The dbunload utility has been enhanced (-ar command-line option) to allow a single-step unload and reload of a database that can be used whether or not your database is involved in replication.

  For more information, see Unload utility options, and Designing rebuild and extract procedures.

•	Enhanced dblog output    The dblog utility now displays additional summary information, including offset information.

  For more information, see The dblog command-line utility.

•	dbtran utility enhancements    The dbtran command-line utility permits filtering of the transaction log operations to isolate subsets of operations. This is of particular use to SQL Remote administrators.

  For more information, see The dbtran command-line utility.

 Behavior changes

 Upgrade issues


Behavior changes
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

        New features in version 6.0.3

 Behavior changes

The following behavior has changed in version 6.0.3:

•	Message link parameters stored in the database    By default, the message link parameters are now moved into the database when the Message Agent is run for the first time with the new version of the software. If you have software that explicitly accesses these parameters in their old locations external to the database, it will be affected by this change. You can continue using the old behavior by setting the External_remote_options database option to ON.

•	Passwords stored    When a password is entered for a message link, it was not stored in previous versions of the software. As the parameters are now held in the database, a saved password is not held on disk and so is more secure. Passwords are now saved by default. You can continue using the old behavior by setting the Save_remote_passwords option to OFF.


Upgrade issues
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

        New features in version 6.0.3

 Upgrade issues

You can use the version 6.0.3 software with your existing databases.

You must upgrade Adaptive Server Anywhere databases to version 6.0.3 of the software if you wish to take advantage of storing of message link parameters in the database, or if you wish to use the datetime replication options. You must upgrade the SQL Remote tables in your Adaptive Server Enterprise database to be able to use these features.

  For information on upgrading Adaptive Server Anywhere databases, see ALTER DATABASE statement, or The Upgrade utility.

  For information on upgrading Adaptive Server Enterprise databases, see Upgrading SQL Remote for Adaptive Server Enterprise.


New features in version 6.0.2
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 9.  Welcome to SQL Remote

 New features in version 6.0.2

In addition to bug fixes, SQL Remote version 6.0.2 includes the following new features:

•	Performance enhancements    A major enhancement of the Adaptive Server Anywhere Message Agent (dbremote) operational model for scanning the transaction log and sending messages greatly improves the range of achievable replication turnaround times.

Minimum lag times between entering data at one site and its replication to another site were limited in earlier versions to times on the order of ten minutes. With the new operational model, minimum lag times on the order of seconds can be achieved in some circumstances.

When the Message Agent message-sending process runs in continuous mode, it now stays (hovers) at the end of the active transaction log while waiting for more data to be committed, instead of rescanning the transaction log each time. This allows you to poll more frequently, which can significantly reduce time for replication.

  For more information, see Tuning Message Agent performance.

•	SQL Remote message logging    New command-line options allow you to tune message logging from these utilities.

  For more information, see The Message Agent.


CHAPTER 10.  SQL Remote Concepts
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 10.  SQL Remote Concepts

About this chapter

This chapter introduces the concepts, design goals, and features of SQL Remote.

 SQL Remote components

 Publications and subscriptions

 SQL Remote features

 Some sample installations


SQL Remote components
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

 SQL Remote components

The following components are required for SQL Remote:

•	Data server    An Adaptive Server Anywhere or Adaptive Server Enterprise database-management system is required at each site to maintain the data.

•	Message Agent    A SQL Remote Message Agent is required at the consolidated site and at each remote site to send and receive SQL Remote messages.

The Message Agent connects to the data server by a client/server connection. It may run on the same machine as the data server or on a different machine.

•	Database extraction utility    The extraction utility is used to prepare remote databases from a consolidated database, during development and testing, and also at deployment time.

•	Message system client software    SQL Remote uses existing message systems to transport replication messages. A file-sharing "message system" is provided, which does not require client software. Each computer involved in SQL Remote replication using a message system other than file sharing must have that message system installed.

•	Client applications    The applications that work with SQL Remote databases are standard client/server database applications.

 The data server

 Client applications

 The Message Agent

 Message system client


The data server
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

        SQL Remote components

 The data server

The data server may be an Adaptive Server Enterprise or an Adaptive Server Anywhere server. At the remote site the data server is commonly an Adaptive Server Anywhere personal server, but can also be an Adaptive Server Enterprise or Adaptive Server Anywhere server.


Client applications
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

        SQL Remote components

 Client applications

Client applications work with the data in the database. Client applications use one of the client/server interfaces supported by the data server:

•	For Adaptive Server Anywhere, the client application may use ODBC, Embedded SQL, or Sybase Open Client to work with Adaptive Server Anywhere.

•	For Adaptive Server Enterprise, the client application may use one of the Sybase Client Server interfaces, ODBC, or Embedded SQL.

Client applications do not have to know if they are using a consolidated or remote database. From the client application perspective, there is no difference.


The Message Agent
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

        SQL Remote components

 The Message Agent

The SQL Remote Message Agent sends and receives replication messages. It is a client application that sends and receives messages from database to database. The Message Agent must be installed at both the consolidated and at the remote sites.

For Adaptive Server Anywhere, the Message Agent is a program called dbremote.exe on PC operating systems, and dbremote on UNIX.

For Adaptive Server Enterprise, the Message Agent is a program called ssremote.exe on PC operating systems, and ssremote on UNIX.


Message system client
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

        SQL Remote components

 Message system client

If you are using a shared file message system, no message system client is needed.

If you are using an e-mail or other message system, you must have a message system for that client in order to send and receive messages.


Publications and subscriptions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

 Publications and subscriptions

The data that is replicated by SQL Remote is arranged in publications. Each database that shares information in a publication must have a subscription to the publication.

Data is organized into publications

The publication is a database object describing data to be replicated. Remote users of the database who wish to receive a publication do so by subscribing to a publication.

A publication may include data from several database tables. Each table's contribution to a publication is called an article. Each article may consist of a whole table, or a subset of the rows and columns in a table.

Periodically, the changes made to each publication in a database are replicated to all subscribers to that publication. These replications are called publication updates.

Messages are always sent both ways

Remote databases subscribe to publications on the consolidated database so that they can receive data from the consolidated database. To do this, a subscription is created at the consolidated database, identifying the subscriber by name and by the publication they are to receive.

SQL Remote always involves messages being sent two ways. The consolidated database sends messages containing publication updates to remote databases, and remote databases also send messages to the consolidated database.

For example, if data in a publication at a consolidated database is updated, those updates are sent to the remote databases. And even if the data is never updated at the remote database, confirmation messages must still be sent back to the consolidated database, to keep track of the status of the replication.

Both databases subscribe

Messages must be sent both ways, so not only does a remote database subscribe to a publication created at the consolidated database, but the consolidated database must subscribe to a corresponding publication created at the remote database.

When remote database users modify their own copies of the data, their changes are replicated to the consolidated database. When the messages containing the changes are applied at the consolidated database the changes become part of the consolidated database's publication, and are included in the next round of updates to all remote sites (except the one it came from). In this way, replication from remote site to remote site takes place via the consolidated database.

Synchronizing a remote database

When a subscription is initially set up, the two databases must be brought to a state where they both have the same set of information, ready to start replication. This process of setting up a remote database to be consistent with the consolidated database is called synchronization. Synchronization can be carried out manually, but the database extraction utility automates the process. You can run the extraction utility from Sybase Central or as a command-line utility.

The appropriate publication and subscription are created automatically at remote databases when you use the SQL Remote database extraction utility to create a remote database.


SQL Remote features
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

 SQL Remote features

The following features are key to SQL Remote's design.

Support for many subscribers    SQL Remote is designed to support replication with many subscribers to a publication.

This feature is of particular importance for mobile workforce applications, which may require replication to the laptop computers of hundreds or thousands of sales representatives from a single office database.

Transaction log-based replication    SQL Remote replication is based on the transaction log. This enables it to replicate only changes to data, rather than all data, in each update. Also, log-base replication has performance advantages over other replication systems.

The transaction log is the repository of all changes made to a database. SQL Remote replicates changes made to databases as recorded in the transaction log. Periodically, all committed transactions in the consolidated database transaction log belonging to any publication are sent to remote databases. At remote sites, all committed transactions in the transaction log are periodically submitted to the consolidated database.

By replicating only committed transactions, SQL Remote ensures proper transaction atomicity throughout the replication setup and maintains a consistency among the databases involved in the replication, albeit with some time lag while the data is replicated.

Central administration    SQL Remote is designed to be centrally administered, at the consolidated database. This is particularly important for mobile workforce applications, where laptop users should not have to carry out database administration tasks. It is also important in replication involving small offices that have servers but little in the way of administration resources.

Administration tasks include setting up and maintaining publications, remote users, and subscriptions, as well as correcting errors and conflicts if they occur.

Economical resource requirements    The only software required to run SQL Remote in addition to your Adaptive Server Anywhere or Adaptive Server Enterprise DBMS is the Message Agent, and a message system. If you use the shared file link, no message system software is required as long as each remote user ID has access to the directory where the message files are stored.

Memory and disk space requirements have been kept moderate for all components of the replication system, so that you do not have to invest in extra hardware to run SQL Remote.

Multi-platform support    SQL Remote is provided on a number of operating systems and message links.

  For a list of supported environments, see Supported Platforms and Message Links.


Some sample installations
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

 Some sample installations

While SQL Remote can provide replication services in many different environments, its features are designed with the following characteristics in mind:

•	SQL Remote should be a solution even when no administration load can be assigned to the remote databases, as in mobile workforce applications.

•	Data communication among the sites may be occasional and indirect: it need not be permanent and direct.

•	Memory and resource requirements at remote sites are assumed to be at a premium.

The following examples show some typical SQL Remote setups.

 Server-to-laptop replication for mobile workforces

 Server-to-server replication among offices


Server-to-laptop replication for mobile workforces
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

        Some sample installations

 Server-to-laptop replication for mobile workforces

SQL Remote provides two-way replication between a database on an office network and personal databases on the laptop computers of sales representatives. Such a setup may use an e-mail system as a message transport.

The office server may be running a server to manage the company database. The Message Agent at the company database runs as a client application for that server.

The laptop computers may be running Windows 95 or Windows NT, and each sales representative has an Adaptive Server Anywhere personal server to manage their own data.

While away from the office, a sales representative can make a single phone call from their laptop to carry out the following functions:

•	Collect new e-mail.

•	Send any e-mail messages they have written.

•	Collect publication updates from the office server.

•	Submit any local updates, such as new orders, to the office server.

The updates may include, for example, new specials on the products the sales representative handles, or new pricing and inventory information. These are read by the Message Agent on the laptop and applied to the sales rep's database automatically, without requiring any additional action on the sales representative's part.

The new orders recorded by the sales representative are also automatically submitted to the office without any extra action on the part of the sales representative.


Server-to-server replication among offices
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 10.  SQL Remote Concepts

        Some sample installations

 Server-to-server replication among offices

SQL Remote provides two-way replication between database servers at sales offices or outlets and a central company office, without requiring database administration experience at each sales office beyond the initial setup and that required to maintain the server.

SQL Remote is not designed for up-to-the-minute data availability at each site. Instead, it is appropriate where data can be replicated at periods of an hour or so.

Such a setup may use an  e-mail system to carry the replication, if there is already a company-wide e-mail system. Alternatively, an occasional dial-up system and file transfer software can be used to implement a FILE message system.

SQL Remote is easy to configure to allow each office to receive their own set of data. Tables that are of office interest only (staff records, perhaps, if the office is a franchise) may be kept private in the same database as the replicated data.

Layers can be added to SQL Remote hierarchies: for example, each sales office server could act as a consolidated database, supporting remote subscribers who work from that office.


CHAPTER 11.  Setting Up SQL Remote
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 11.  Setting Up SQL Remote

About this chapter

This chapter describes how to add SQL Remote capabilities to your Adaptive Server Enterprise server.

Adaptive Server Enterprise users only
  This chapter is required only for users of SQL Remote for Adaptive Server Enterprise. SQL Remote capability is automatically installed into Adaptive Server Anywhere databases.

This chapter assumes you have already installed the SQL Remote software onto your machine.

 Setup overview

 Preparing your Adaptive Server Enterprise server

 Upgrading SQL Remote for Adaptive Server Enterprise

 Uninstalling SQL Remote


Setup overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

 Setup overview

We call the collection of databases exchanging information using SQL Remote an installation. From a physical point of view, a SQL Remote installation may consist of hundreds or even thousands of databases sharing information; but as SQL Remote keeps the information in each physical database loosely consistent at a transactional level with that in other physical databases, you can also think of the whole installation as a single dispersed database.

Deploying a large-scale SQL Remote installation can involve setting up databases on many machines. While some changes to the design and setup configuration can be made on a running installation, it is highly recommended that you deploy only when you have completed a careful analysis and test of your design.

Setup tasks

Setup of a SQL Remote installation includes the following tasks:

•	Preparing your server for SQL Remote    You must take some steps to configure your Adaptive Server Enterprise to act as a SQL Remote site. These include installing the SQL Remote system objects and the stable queue system objects.

•	Selecting message types    You must decide whether you want to exchange information by file sharing, e-mail, some other message type, or a combination.

•	Ensuring proper permissions are set    Each user in the installation requires permissions on both their own database and on the consolidated database.

•	Extracting remote databases    You must extract an initial copy of each remote database from the consolidated database.

This chapter describes each of these tasks.

All administration is at the consolidated database

Like all SQL Remote administrative tasks, setup is carried out by a database administrator or system administrator at the consolidated database.

The Sybase System Administrator should perform all SQL Remote  configuration tasks. See your Adaptive Server Enterprise documentation for more information about the Adaptive Server Enterprise environment.


Preparing your Adaptive Server Enterprise server
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

 Preparing your Adaptive Server Enterprise server

Before you start

This section assumes the following:

•	You have installed an Adaptive Server Enterprise server that is to contain the SQL Remote database.

•	You have installed the SQL Remote software on your computer. To install the SQL Remote software, run the setup program from the CD-ROM.

•	You have created a database in the Adaptive Server Enterprise server that will take part in your SQL Remote installation.

•	You have system administrator permissions on the Adaptive Server Enterprise server, and database owner permissions in the database.

 Ensuring TEMPDB is large enough

 Installing SQL Remote into a database from Sybase Central

 Command-line installation of the SQL Remote system objects

 Command-line installation of the stable queue


Ensuring TEMPDB is large enough
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

        Preparing your Adaptive Server Enterprise server

 Ensuring TEMPDB is large enough

SQL Remote uses the TEMPDB database for the following purposes:

•	The database extraction utility used to create remote databases uses TEMPDB to hold a temporary set of Adaptive Server Anywhere system tables.

•	The Message Agent creates a temporary table called #remote when it connects to the server.

For these reasons, you should make TEMPDB larger than the 2 Mb default size. The size required depends on the number of tables and columns in your SQL Remote installation, but a size of 10 Mb is generally sufficient.


Installing SQL Remote into a database from Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

        Preparing your Adaptive Server Enterprise server

 Installing SQL Remote into a database from Sybase Central

You can install SQL Remote into a database from the Sybase Central graphical administration tool. Sybase Central is available on the Windows NT and Windows 95 operating systems.

♦ To install SQL Remote into a database from Sybase Central:

1	Connect to Adaptive Server Enterprise from Sybase Central, as a user with system administrator privileges.

  The login_id you use must correspond to the name used by the Message Agent. For more information, see The Message Agent and replication security.

2	Open the Databases folder for the server.

3	Open the SQL Remote folder in the database.

4	In the right pane, double-click Setup SQL Remote, and follow the instructions in the Wizard.


Command-line installation of the SQL Remote system objects
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

        Preparing your Adaptive Server Enterprise server

 Command-line installation of the SQL Remote system objects

For a database in your Adaptive Server Enterprise server to take part in a SQL Remote installation, you must install a number of SQL Remote system tables, views, and stored procedures in your database.

♦ To install the SQL Remote system objects:

1	Locate the SQL Remote initialization script ssremote.sql in your SQL Remote installation directory.

2	Make a backup copy of the ssremote.sql script file. Then add the following two lines to the beginning of ssremote.sql:

use database_name

go

where database_name is the name of the database to take part in SQL Remote replication.

These two lines set the current database to database_name, so that the SQL Remote tables are created in the database_name database. The SQL Remote tables are owned by the database owner.

3	Run the script against your Adaptive Server Enterprise server.

Change to the directory containing the script file and enter the following command line (which should be entered all on one line) to run the script:

isql -S server-name -U login_id -P password -i ssremote.sql -o logfile

where server-name is the name of the Adaptive Server Enterprise, login_id and password correspond to a user with system administrator permissions on the server who owns the database, and logfile is the name of a log file to hold the log information from the script.

  The login_id must correspond to the name used by the Message Agent. For more information, see The Message Agent and replication security.

4	Inspect the log file to confirm that the tables and procedures were created without error.

The script creates a set of SQL Remote system objects in the database.

 The SQL Remote system objects


The SQL Remote system objects
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

        Preparing your Adaptive Server Enterprise server

          Command-line installation of the SQL Remote system objects

 The SQL Remote system objects

The script creates the following objects in the database:

•	SQL Remote system tables    A set of tables used to maintain SQL Remote information. These tables have names beginning with sr_.

•	SQL Remote system views    A set of views that hold the SQL Remote information in a more understandable form. These views have names beginning with sr_, and ending in s.

•	SQL Remote system procedures    A set of stored procedures used to carry out SQL Remote configuration and administration tasks. These procedures have names beginning with sp_, indicating their system management roles.

Caution: Do not edit the SQL Remote system tables
Do not, under any circumstances, alter the SQL Remote system tables directly. Doing so may corrupt the table and make it impossible for SQL Remote to function properly. Use Sybase Central or the SQL Remote system procedures to carry out all system administration tasks.


Command-line installation of the stable queue
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

        Preparing your Adaptive Server Enterprise server

 Command-line installation of the stable queue

The stable queue is a pair of database tables that hold transactions until they are no longer needed by the replication system. Every Adaptive Server Enterprise database participating in a SQL Remote installation needs a stable queue.

  For detailed information about the stable queue, see The stable queue.

The stable queue can exist in the same database as the database taking part in SQL Remote, or in a separate database. Keeping the stable queue in a separate database complicates the backup and recovery plan, but can improve performance by putting the stable queue workload on separate devices and/or a separate Adaptive Server Enterprise server.

♦ To install the stable queue:

1	Locate the stable queue initialization script stableq.sql in your SQL Remote installation directory.

2	Make a backup copy of the stableq.sql script file. Then add the following two lines to the beginning of stableq.sql:

use database_name

go

where database_name is the name of the database that will hold the stable queue.

These two lines set the current database to database_name, so that the stable queue is created in the database_name database. The stable queue tables are owned by the database owner.

3	Run the script against your Adaptive Server Enterprise server.

Change to the directory holding the stable queue script, and enter the following command line (which should be entered all on one line) to run the script:

isql -S server-name -U login_id -P password -i STABLEQ.SQL -o logfile

where server-name is the name of the Adaptive Server Enterprise, login_id and password correspond to a user with system administrator permissions on the server who owns the database, and logfile is the name of a log file to hold the log information from the script.

  The login_id must correspond to the name used by the Message Agent. For more information, see The Message Agent and replication security.

4	Inspect the log file to confirm that the tables and procedures were created without error.


Upgrading SQL Remote for Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

 Upgrading SQL Remote for Adaptive Server Enterprise

This section describes the procedure for upgrading SQL Remote for Adaptive Server Enterprise.

As a SQL Remote installation may consist of a large number of databases, it is generally not practical to upgrade software on all machines at the same time. SQL Remote is designed so that upgrades can be carried out incrementally. It is not important what order SQL Remote machines are upgraded, as the message format is compatible with previous releases.

♦ To upgrade SQL Remote:

1	Back up both the consolidated database and, if it is separate, the stable queue database.

2	Install the new SQL Remote for Adaptive Server Enterprise software.

3	Run the script ssupdate.sql at the consolidated database to upgrade the SQL Remote system tables and procedures.

The ssupdate.sql script is held in your Sybase directory.

4	Run the script squpdate.sql at the stable queue database to upgrade the SQL Remote stable queue tables and procedures.

The squpdate.sql script is held in your Sybase directory.

The software is now upgraded.


Uninstalling SQL Remote
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 11.  Setting Up SQL Remote

 Uninstalling SQL Remote

This section describes how to uninstall the SQL Remote objects from a database, and uninstall the stable queue from a database.

♦ To uninstall the SQL Remote objects from a database:

1	Connect to the database containing the SQL Remote objects, as a user with dbo permissions.

2	Run the sp_drop_sql_remote stored procedure to remove all SQL Remote objects apart from the procedure itself. The sp_drop_sql_remote procedure is installed along with the other SQL Remote objects.

exec sp_drop_sql_remote

go

3	Drop the sp_drop_sql_remote procedure to complete the uninsall procedure.

drop procedure sp_drop_sql_remote

go

♦ To uninstall the stable queue from a database:

1	Connect to the database containing the stable queue, as a user with dbo permissions.

2	Run the sp_queue_drop stored procedure to remove all stable queue objects apart from the procedure itself. The sp_queue_drop procedure is installed along with the other stable queue objects.

exec sp_queue_drop

go

3	Drop the sp_queue_drop procedure itself, to complete the uninstall procedure.

drop procedure sp_queue_drop

go


CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

About this chapter

This chapter guides you through setting up a simple replication system.

 Tutorial overview

 A tutorial using Sybase Central

 Setting up a consolidated database

 Set up the remote database in Sybase Central

 A tutorial using Interactive SQL and DBXTRACT

 Set up the consolidated database

 Set up the remote database

 Start replicating data

 A sample publication


Tutorial overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 Tutorial overview

This tutorial describes how to set up a simple SQL Remote replication system using Adaptive Server Anywhere.

 Tutorial goals

 The database

 Replication goals

 Sybase Central or command-line utilities


Tutorial goals
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Tutorial overview

 Tutorial goals

In the tutorial you act as the system administrator of a consolidated Adaptive Server Anywhere database, and set up a simple replication system. The replication system consists of a simple sales database, with two tables.

The consolidated database holds all of the database, while the remote database has all of one table, but only some of the rows in the other table.

The tutorial takes you through the following steps:

•	Creating a consolidated database on your Adaptive Server Anywhere server.

•	Creating a file-sharing replication system with a single Adaptive Server Anywhere remote database.

•	Replicating data between the two databases.


The database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Tutorial overview

 The database

The tutorial uses a simple two-table database. One table holds information about sales representatives, and the other about customers. The tables are much simpler than you would use in a real database; this allows us to focus just on those issues important for replication.

Database schema

The database schema for the tutorial is illustrated in the figure.

Features to note include the following:

•	Each sales representative is represented by one row in the SalesRep table.

•	Each customer is represented by one row in the Customer table.

•	Each customer is assigned to a single sales representative, and this assignment is built in to the database as a foreign key from the Customer table to the SalesRep table. The relationship between the Customer table and the SalesRep table is many-to-one.

The tables in the database

The tables are described in more detail as follows:

Table	Description
SalesRep	One row for each sales representative that works for the company. The SalesRep table has the following columns: • rep_key   An identifier for each sales representative. This is the primary key. • name   The name of each sales representative. The SQL statement creating this table is as follows: CREATE TABLE SalesRep ( rep_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, PRIMARY KEY (rep_key) )
Customer	One row for each customer that does business with the company. The Customer table includes the following columns: • cust_key   An identifier for each customer. This is the primary key. • name   The name of each customer. • rep_key   An identifier for the sales representative in a sales relationship. This is a foreign key to the SalesRep table. The SQL statement creating this table is as follows: CREATE TABLE Customer ( cust_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, rep_key CHAR(12) NOT NULL, FOREIGN KEY ( rep_key ) REFERENCES SalesRep (rep_key ), PRIMARY KEY (cust_key) )


Replication goals
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Tutorial overview

 Replication goals

The goals of the replication design are to provide each sales representative with the following information:

•	The complete SalesRep table.

•	Those customers assigned to them.

The tutorial describes how to meet this goal using SQL Remote.


Sybase Central or command-line utilities
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Tutorial overview

 Sybase Central or command-line utilities

Use Sybase Central or the command line

The tutorial material is presented twice. One section describes how to set up the installation using the Sybase Central management utility. The second section describes how to set up the installation using command-line utilities: this requires typing commands individually.

Where next?

•	To work through the tutorial using Sybase Central, go to A tutorial using Sybase Central, next.

•	To work through the tutorial entering commands explicitly, go to A tutorial using Interactive SQL and DBXTRACT.


A tutorial using Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 A tutorial using Sybase Central

The following sections are a tutorial describing how to set up a simple SQL Remote replication system in Adaptive Server Anywhere using Sybase Central.

You do not need to enter SQL statements if you are using Sybase Central to administer SQL Remote. A tutorial for those who do not have access to Sybase Central, or who prefer to work with command-line utilities, is presented in A tutorial using Interactive SQL and DBXTRACT. This tutorial contains the SQL statements executed behind the scenes by Sybase Central.

In this tutorial you act as the DBA of the consolidated database, and set up a simple replication system using the file-sharing message link. The simple example is a primitive model for a sales-force automation system, with two tables. One contains a list of sales representatives, and another a list of customers. The tables are replicated in a setup with one consolidated database and one remote database. You can install this example on one computer.

  This tutorial assumes that you have some familiarity with Sybase Central. For an introduction to Sybase Central, see Managing Databases with Sybase Central.

 Preparing for the Sybase Central replication tutorial


Preparing for the Sybase Central replication tutorial
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        A tutorial using Sybase Central

 Preparing for the Sybase Central replication tutorial

This section describes the steps you need to take to prepare for the tutorial. These steps include the following:

•	Create the directories and databases required for the tutorial.

•	Add the tables to the consolidated database.

♦ To prepare for the tutorial:

1	Create a directory to hold the files you make during this tutorial; for example c:\tutorial.

mkdir c:\tutorial

2	Create a subdirectory for each of the two user IDs in the replication system, to hold their messages. Create these subdirectories using the following statements at a system command line:

mkdir c:\tutorial\hq

mkdir c:\tutorial\field

3	The tutorial uses two databases: a consolidated database named hq.db and a remote database named field.db. At this point, you should create the hq database with the Create Database utility in Sybase Central:

•	Start Sybase Central. You will be creating a new database so you do not have to connect to any particular existing database.

•	Open the Utilities folder in the left panel.

•	Double-click Create Database in the right panel. The Create Database wizard is displayed.

•	Create a database with filename c:\tutorial\hq.db.

•	You can use the default settings for this database. Make sure you elect to maintain a transaction log. Replication cannot take place without a transaction log.

An Adaptive Server Anywhere database is simply a file, which can be copied to other locations and computers when necessary.

The next step is to add a pair of tables to the consolidated database.

♦ To add tables to the consolidated database:

1	Connect to the hq database from Sybase Central, with a user ID of DBA and a password of SQL.

2	Click the Tables folder of the hq database.

3	Double-click Add Table, and use the Table Editor to create a table named SalesRep with the following columns:

Key	Column	Data Type	Size/Prec
Primary key	Rep_key	Char	5
	Name	Char	40
You do not need to use the Column Properties or the Advanced Table Properties dialogs. The columns are created by default not allowing NULL.

4	Save the table and close the Table Editor.

5	Double-click Add Table again, and use the Table Editor to create a table named Customer with the following columns:

Key	Column	Data Type	Size/Prec
Primary key	Cust_key	Char	10
	Name	Char	40
	Rep_key	Char	5
Again, you do not need to use the property sheets. The columns are created by default not allowing NULL.

6	Save the table and close the Table Editor.

7	In the Tables folder, open the Customer table container and then open the Foreign Keys folder within this table.

8	Double-click Add Foreign Key. Using the wizard, add a foreign key to the rep_key column of the SalesRep table. You can use the default settings for this foreign key.

You are now ready for the rest of the tutorial.


Setting up a consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 Setting up a consolidated database

This section of the tutorial describes how to prepare the consolidated database of a simple replication system.

Preparing a consolidated database for replication involves the following steps:

1	Create a message type to use for replication.

2	Grant PUBLISH permissions to a user ID to identify the source of outgoing messages.

3	Grant REMOTE permissions to all user IDs that are to receive messages.

4	Create a publication describing the data to be replicated.

5	Create subscriptions describing who is to receive the publication.

You require DBA authority to carry out these tasks.

 Add a SQL Remote message type

 Add the publisher and remote user to the database

 Add publications and subscriptions


Add a SQL Remote message type
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Setting up a consolidated database

 Add a SQL Remote message type

All messages sent as part of replication use a message type. A message type description has two parts:

•	A message link supported by SQL Remote. In this tutorial, we use the FILE link.

•	An address for this message link, to identify the source of outgoing messages.

Adaptive Server Anywhere databases already have message types created, but you need to supply an address for the message type you will use.

♦ To add an address to a message type:

1	From Sybase Central, connect to the HQ database.

2	Open the SQL Remote folder for the HQ database.

3	Within the SQL Remote folder, open the Message Types folder.

4	In the right pane, right-click the FILE message type and choose Properties from the popup menu.

5	Enter a publisher address to provide a return address for remote users. Enter the directory you have created to hold messages for the consolidated database (hq).

The address is taken relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.

6	Click OK to save the message type.


Add the publisher and remote user to the database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Setting up a consolidated database

 Add the publisher and remote user to the database

In SQL Remote's hierarchical replication system, each database may have zero or one database immediately above it (the consolidated database) and zero or more databases immediately below it (remote databases).

In this tutorial, the current database is the consolidated database of a two-level system. It has no database above it, and only one remote database below it.

The following diagram illustrates the two databases:

For any database in a SQL Remote replication setup, there are three permissions that may be granted to identify databases on the hierarchy:

•	PUBLISH permission    Identifies the current database in all outgoing messages

•	REMOTE permission    Identifies each database receiving messages from the current database that is below it on the hierarchy

•	CONSOLIDATE permission    Identifies a database receiving messages from the current database that is directly above it on the hierarchy.

Permissions can only be granted by a user with DBA authority. To carry out these examples you should connect from Sybase Central to the hq database as user ID DBA, with password SQL.

Add a database publisher user ID

Any database, consolidated or remote, that distributes changes to other databases in the replication system is a publisher database. Each database in the replication system is identified by a single user ID. You set that ID for your database by adding a publisher to the database. This section describes setting permissions for the consolidated hq database.

First create a user ID named hq_user, who will be the publisher user ID.

♦ To create a new user as the publisher:

1	Open the Users & Groups folder.

2	Double-click Add User. The New User wizard is displayed.

3	Enter the name hq_user, with password hq_pwd, and click Next.

4	On the next page, ensure that the user is granted Remote DBA authority, making it possible for this user to run the Message Agent. Then click Next.

5	On the final page, check the box identifying this user ID as the publisher. Then click Finish to create the user.

A database can have only one publisher. You can find out who the publisher is at any time by opening the SQL Remote folder.

You can also make an existing user the publisher by right-clicking the user in the Users & Groups folder and choosing Set as Publisher from the popup menu.

Add a remote user

Each remote database is identified in the consolidated database by a user ID with REMOTE permissions. Whether the remote database is a personal database server or a network server with many users, it needs a single user ID to represent it to the consolidated database.

In a mobile workgroup setting, remote users may already be users of the consolidated database, and so no new users would need to be added; although they would need to be set as remote users.

When a remote user is added to a database, the message system they use and their address under that message system need to be stored along with their database user ID.

♦ To add a remote user:

1	Open the Remote Users folder (located within the SQL Remote folder).

2	Double-click Add Remote User.

3	In the wizard, create a remote user with user ID field_user, password field_pwd, message type file, and address field. For the message type and address, select the FILE type and the corresponding address you are using for this user (such as field).

As with the publisher address, the address of the remote user is taken relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.

4	On the next page, ensure that the Send Then Close option is checked. (In many production environments you would not choose Send Then Close, but it is convenient for this tutorial.)

5	On the next page ensure that the Remote DBA authority is checked, so that the user can run the Message Agent.

6	When you have finished all the entries, click Finish to create the remote user.

You have now created the users who will use this system.


Add publications and subscriptions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Setting up a consolidated database

 Add publications and subscriptions

This section describes how to add a publication to a database, and how to add a subscription to that publication for a user. The publication replicates all rows of the table SalesRep and some of the rows of the Customer table.

♦ To add a publication:

1	Click the Publications folder in the SQL Remote folder.

2	Double-click Add Publication. The Publication wizard is displayed.

3	Name the publication SalesRepData on the first page of the wizard.

4	On the next page, click Add Table

5	In the resulting dialog, select SalesRep from the list. Leave the All columns option selected, and click OK to exit the dialog and return to the wizard.

6	Click Add Table again, and select Customer from the list in the dialog. Again, leave the All columns option selected.

7	Leave the dialog open and click the Subscribe Restriction tab. On this tab, choose to subscribe by the column rep_key. Click OK to add the table to the publication.

8	Follow the rest of the instructions in the wizard.

Add a subscription

Each user ID that is to receive changes to a publication must have a subscription to that publication. Subscriptions can only be created for a valid remote user. You need to add a subscription to the SalesRepData publication for the remote database user field_user.

♦ To add a subscription:

1	Open the Publications folder (located within the SQL Remote folder).

2	Right-click the SalesRepData publication and choose Properties from the popup menu.

3	Click the Subscriptions tab.

4	Click Subscribe For and choose to subscribe field_user.

You have now set up the consolidated database.


Set up the remote database in Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 Set up the remote database in Sybase Central

The remote database needs to be created and configured in order to send and receive messages and participate in a SQL Remote setup.

Like the consolidated database, the remote database needs a publisher (in this case, the field_user user ID) to identify the source of outgoing messages, and it needs to have hq_user identified as a user with consolidated permissions. It needs the SalesRepData publication to be created and needs a subscription created for the hq_user user ID.

The remote database also needs to be synchronized with the consolidated database; that is, it needs to have a current copy of the data in order for the replication to start. In this case, there is no data in the publication as yet.

The database extraction utility enables you to carry out all the steps needed to create a remote database complete with subscriptions and required user IDs.

You need to extract a database from the consolidated database for remote user field_user.

♦ To extract a database:

1	Connect to the hq database.

2	Right-click the database and choose Extract Database from the popup menu.

3	Click Next on the first page of the wizard.

4	Choose to Start Subscriptions Automatically, for user field_user.

5	Create the database as file c:\tutorial\field.db, using a transaction log of name field.log in the same directory.

6	Choose to extract all parts of the schema.

7	Leave the other options at their default settings, and create the remote database.

In a proper SQL Remote setup, the remote database field would need to be loaded on to the computer using it, together with an Adaptive Server Anywhere server and any client applications required. For this tutorial, we leave the database where it is and use Interactive SQL to input and replicate data.

You should connect to the field database as DBA and confirm that all the database objects are created. These include the SalesRep and Customer tables, the SalesRepData publication, and the subscription for the consolidated database.

What next?

The system is now ready for replication.

  For the next step, inserting and replicating data, see the section Start replicating data.


A tutorial using Interactive SQL and DBXTRACT
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 A tutorial using Interactive SQL and DBXTRACT

The following sections are a tutorial describing how to set up a simple SQL Remote replication system for users without Windows 95 or Windows NT 3.51 or later, who cannot run Sybase Central. It may also be useful to users of Sybase Central who prefer to use command-line tools or who want to know what Sybase Central is doing behind the scenes.

This tutorial describes the SQL statements for managing SQL Remote, which can be run from Interactive SQL. It also describes how to run the dbxtract command-line utility to extract remote databases from a consolidated database.

In this tutorial you act as the DBA of the consolidated database, and set up a simple replication system using the file-sharing message link. The simple example is a primitive model for a sales-force automation system, with two tables. One contains a list of sales representatives, and another a list of customers. The tables are replicated in a setup with one consolidated database and one remote database. You can install this example on one computer.

 Preparing for the replication tutorial


Preparing for the replication tutorial
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        A tutorial using Interactive SQL and DBXTRACT

 Preparing for the replication tutorial

This section describes the steps you need to take to prepare for the tutorial. These steps include the following:

•	Create the directories and databases required for the tutorial.

•	Add a table to the consolidated database.

♦ To create the databases and directories for the tutorial:

1	Create a directory to hold the files you make during this tutorial; for example c:\tutorial.

mkdir c:\tutorial

2	The tutorial uses two databases: a consolidated database named hq.db and a remote database named field.db. Change to the tutorial directory and create these databases using the following statements at a command line:

dbinit hq.db

dbinit field.db

The database initialization tool for Windows 3.x is dbinitw rather than dbinit. Under Windows 3.x, you should execute the commands from the Program Manager File [image] Run menu or you could make an icon for each command.

3	Create a subdirectory for each of the two user IDs in the replication system. Create these subdirectories using the following statements at a command line:

mkdir c:\tutorial\hq

mkdir c:\tutorial\field

The next step is to add a pair of tables to the consolidated database.

♦ To add the tables to the consolidated database:

1	Connect to hq.db from Interactive SQL with a user ID of DBA and a password of SQL.

2	Execute the following CREATE TABLE statement to create the SalesRep table:

CREATE TABLE SalesRep (

rep_key CHAR(12) NOT NULL,

name CHAR(40) NOT NULL,

PRIMARY KEY ( rep_key )

);

3	Execute the following CREATE TABLE statement to create the Customer table:

CREATE TABLE Customer (

cust_key CHAR(12) NOT NULL,

name CHAR(40) NOT NULL,

rep_key CHAR(12) NOT NULL,

FOREIGN KEY REFERENCES SalesRep,

PRIMARY KEY ( cust_key )

);

You are now ready for the rest of the tutorial.


Set up the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 Set up the consolidated database

This section of the tutorial describes how to set up the consolidated database of a simple replication system.

You require DBA authority to carry out this task.

 Create a SQL Remote message type

 Grant PUBLISH and REMOTE at the consolidated database

 Create publications and subscriptions


Create a SQL Remote message type
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Set up the consolidated database

 Create a SQL Remote message type

All messages sent as part of replication use a message type. A message type description has two parts:

•	A message link supported by SQL Remote. In this tutorial, we use the FILE link.

•	An address for this message link, to identify the source of outgoing messages.

♦ To create the message type:

•	In Interactive SQL, create the file message type using the following statement:

CREATE REMOTE MESSAGE

TYPE file

ADDRESS 'hq'

The address (hq) for a file link is a directory in which files containing the message are placed. It is taken relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.


Grant PUBLISH and REMOTE at the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Set up the consolidated database

 Grant PUBLISH and REMOTE at the consolidated database

In the hierarchical replication system supported by SQL Remote, each database may have one consolidated database immediately above it in the hierarchy and many databases immediately below it on the hierarchy (remote databases).

PUBLISH permission identifies the current database for outgoing messages, and the REMOTE permission identifies each database receiving messages from the current database.

Permissions can only be granted by a user with DBA authority. To carry out these examples you should connect using the Interactive SQL utility to hq as user ID DBA, with password SQL.

GRANT PUBLISH to identify outgoing messages

Each database that distributes its changes to other databases in the replication system is a publisher database. Each database in the replication system that publishes changes to a database is identified by a single user ID. You set that ID for your database using the GRANT PUBLISH statement. This section describes setting permissions for the consolidated database (hq.db).

♦ To create a publisher for the database:

•	Connect to the database using Interactive SQL, and type the following statement:

GRANT CONNECT

TO hq_user

IDENTIFIED BY hq_pwd ;

GRANT PUBLISH TO hq_user ;

You can check the publishing user ID of a database at any time using the CURRENT PUBLISHER special constant:

SELECT CURRENT PUBLISHER

GRANT REMOTE for each database to which you send messages

Each remote database is identified using the GRANT REMOTE statement. Whether the remote database is a personal server or a network server with many users, it needs a single user ID to represent it to the consolidated database.

In a mobile workgroup setting, remote users may already be users of the consolidated database, and so this would require no extra action on the part of the DBA.

The GRANT REMOTE statement identifies the message system to be used when sending messages to the recipient, as well as the address.

♦ To add a remote user:

•	Connect to the database using Interactive SQL, and execute the following statements:

GRANT CONNECT TO field_user

IDENTIFIED BY field_pwd ;

GRANT REMOTE TO field_user

TYPE file ADDRESS 'field' ;

The address string is the directory used to hold messages for field_user, enclosed in single quotes. It is taken relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.


Create publications and subscriptions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Set up the consolidated database

 Create publications and subscriptions

A publication is created using a CREATE PUBLICATION statement. This is a data definition language statement, and requires DBA authority. For the tutorial, you should connect to the hq database as user ID DBA, password SQL, to create a publication.

Set up a publication at the consolidated database

Create a publication named SalesRepData, which replicates all rows of the table SalesRep, and some of the rows of the table Customer.

♦ To create the publication:

•	Connect to the database from Interactive SQL, and execute the following statement:

CREATE PUBLICATION SalesRepData (

TABLE SalesRep,

TABLE Customer SUBSCRIBE BY rep_key

)

Set up a subscription

Each user ID that is to receive changes to the publication must have a subscription. The subscription can only be created for a user who has REMOTE permissions. The GRANT REMOTE statement contains the address to use when sending the messages.

♦ To create the subscription:

•	Connect to the database from Interactive SQL, and execute the following statement:

CREATE SUBSCRIPTION

TO SalesRepData ('rep1')

FOR field_user ;

The value rep1 is the rep_key value we will give to the user field_user in the SalesRep table.

The full CREATE SUBSCRIPTION statement allows control over the data in subscriptions; allowing users to receive only some of the rows in the publication. For more information, see CREATE SUBSCRIPTION statement.

The CREATE SUBSCRIPTION statement identifies the subscriber and defines what they receive. However, it does not synchronize data, or start the sending of messages.


Set up the remote database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 Set up the remote database

The remote database needs to be configured in order to send and receive messages and participate in a SQL Remote setup. Like the consolidated database, the remote database needs a CURRENT PUBLISHER to identify the source of outgoing messages, and it needs to have the consolidated database identified as a subscriber. The remote database also needs the publication to be created and needs a subscription created for the consolidated database. The remote database also needs to be synchronized with the consolidated database; that is, it needs to have a current copy of the data in order for the replication to start.

The dbxtract utility enables you to carry out all the steps needed to create a remote database complete with subscriptions and required user IDs.

 Extract the remote database information

 Load the remote database information


Extract the remote database information
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Set up the remote database

 Extract the remote database information

Leave the hq database running, and change to the tutorial directory.

Type the following command at the system command line (all on one line) to extract a database for the user field_user from the consolidated database:

dbxtract -v -c "dbn=hq;uid=dba;pwd=sql" c:\tutorial field_user

The -v command-line switch produces more verbose output. This is useful during development.

This command assumes the hq database is currently running on the default server. If the database is not running, you should enter a database file parameter in the connection string:

dbf=hq.db

instead of the dbn database name parameter.

  For details of the dbxtract utility and its options, see The extraction command-line utility.

The dbxtract command creates a SQL command file named reload.sql in the current directory and a data file in the c:\tutorial directory. It also starts the subscriptions to the remote user.

The next step is to load these files into the remote database.


Load the remote database information
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Set up the remote database

 Load the remote database information

♦ To load the database information:

1	From the tutorial directory, connect to the remote database field.db from Interactive SQL with a user ID of DBA and a password of SQL.

2	Run the reload.sql command file:

READ C:\tutorial\reload.sql

The reload.sql command file carries out the following tasks:

•	Creates a message type at the remote database.

•	Grants PUBLISH and REMOTE permissions to the remote and consolidated database, respectively.

•	Creates the table in the database. If the table had contained any data before extraction, the command file would fill the replicated table with a copy of the data.

•	Creates a publication to identify the data being replicated.

•	Creates the subscription for the consolidated database, and starts the subscription.

While connected to the field database as DBA, confirm that the tables are created by executing the following statements:

SELECT * FROM SalesRep ;

SELECT * FROM Customer ;

What next?

The system is now ready for replication.

  For the next step, inserting and replicating data, see the section Start replicating data .


Start replicating data
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 Start replicating data

You now have a replication system in place. In this section, data is replicated from the consolidated database to the remote database, and from the remote to the consolidated database.

 Enter data at the consolidated database

 Send data from the consolidated database

 Receive data at the remote database

 Replicate from the remote database to the consolidated database


Enter data at the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Start replicating data

 Enter data at the consolidated database

First, enter some data into the consolidated database.

♦ To enter data at the consolidated database:

1	Connect to the consolidated database hq from the Interactive SQL utility with a user ID of DBA and a password of SQL.

2	Insert two rows into the SalesRep table and commit the insertion by executing the following statement:

INSERT INTO SalesRep (rep_key, name)

VALUES ('rep1', 'Field User') ;

INSERT INTO SalesRep (rep_key, name)

VALUES ('rep2', 'Another User') ;

COMMIT ;

3	Insert two rows into the Customer table and commit the insertion by executing the following statement:

INSERT INTO Customer (cust_key, name, rep_key)

VALUES ('cust1', 'Ocean Sports', 'rep1' ) ;

INSERT INTO Customer (cust_key, name, rep_key)

VALUES ('cust2', 'Sports Plus', 'rep2' ) ;

COMMIT ;

4	Confirm that the data has been entered by executing the following statements:

SELECT *

FROM SalesRep;

SELECT *

FROM Customer;

The next step is to send the relevant rows to the remote database.


Send data from the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Start replicating data

 Send data from the consolidated database

To send the rows to the remote database, you must run the Message Agent at the consolidated database. The dbremote program is the Message Agent for Adaptive Server Anywhere.

♦ To send the data to the remote database:

1	From a command prompt, change to your tutorial directory. For example,

> c:

> cd c:\tutorial

2	Enter the following statement at the command line to run the Message Agent against the consolidated database:

dbremote -c "dbn=hq;uid=dba;pwd=sql"

This command line assumes that the hq database is currently running on the default server. If the database is not running, you must supply a dbf parameter with the database file name instead of the dbn parameter.

  For more information on dbremote command line switches, see The Message Agent.

3	Click Shutdown on the Message Agent window to stop the Message Agent when the messages have been sent. The Message Agent window displays the message Execution completed when all processing is complete.


Receive data at the remote database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Start replicating data

 Receive data at the remote database

To receive the insert statement at the remote database, you must run the Message Agent, dbremote, at the remote database.

♦ To receive data at the remote database:

1	From a command prompt, change to your tutorial directory. For example,

> c:

> cd c:\tutorial

2	Enter the following statement at the command line to run the Message Agent against the field database:

dbremote -c "dbn=field;uid=dba;pwd=sql"

This command line assumes that the field database is currently running on the default server.

  For more information on dbremote command line switches, see The Message Agent.

3	Click Shutdown on the Message Agent window to stop the Message Agent when the messages have been processed. The Message Agent window displays the message Execution completed when all processing is complete.

The Message Agent window displays status information while running. This information can be output to a log file for record keeping in a real setup. You will see that the Message Agent first receives a message from hq, and then sends a message. This return message contains confirmation of successful receipt of the replication update; such confirmations are part of the SQL Remote message tracking system that ensures message delivery even in the event of message system errors.

Verify that the data has arrived

You should now connect to the remote field database using Interactive SQL, and inspect the SalesRep and Customer tables, to see which rows have been received.

♦ To verify that the data has arrived:

1	Connect to the field database using Interactive SQL.

2	Inspect the SalesRep table by executing the following statement:

SELECT * FROM SalesRep

You will see that the SalesRep table contains both rows entered at the consolidated database. This is because the SalesRepData publication included all the data from the SalesRep table.

3	Inspect the Customer table by executing the following statement:

SELECT * FROM Customer

You will also see that the Customer table contains only row (Ocean Sports) entered at the consolidated database. This is because the SalesRepData publication included only those customers assigned to the subscribed Sales Rep.


Replicate from the remote database to the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

        Start replicating data

 Replicate from the remote database to the consolidated database

You should now try entering data at the remote database and sending it to the consolidated database. Only the outlines are presented here.

♦ To replicate data from the remote database to the consolidated database:

1	Connect to the field database from Interactive SQL.

2	Insert a row at the remote database by executing the following statement:

INSERT INTO Customer (cust_key, name, rep_key)

VALUES ('cust3', 'North Land Trading', 'rep1')

3	Commit the insertion by executing the following statement::

COMMIT;

4	With the field.db database running, run the dbremote utility from a command line to send the message to the consolidated database.

dbremote -c "dbn=field;uid=dba;pwd=sql"

5	With the hq.db database running, run the dbremote utility from a command line to receive the message at the consolidated database:

dbremote -c "dbn=hq;uid=dba;pwd=sql"

6	Connect to the consolidated database. Display the Customer table by executing the following statement:

SELECT *

FROM Customer

cust_key	name	rep_key
cust1	Ocean Sports	rep1
cust2	Sports Plus	rep2
cust3	North Land Trading	rep1
In this simple example, there is no protection against duplicate entries of primary key values. SQL Remote does provide for such protection. For information, see the chapters on SQL Remote Design.


A sample publication
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 12.  A Tutorial for Adaptive Server Anywhere Users

 A sample publication

The command file salespub.sql contains a set of statements that creates a publication on the sample database. This publication illustrates several of the points of the tutorial, in more detail.

♦ To add the publication to the sample database:

1	Connect to the sample database from Interactive SQL.

2	In the SQL Statements pane, execute the following statement:

READ path\scripts\salespub.SQL, where path is your Adaptive Server Anywhere installation directory.

The salespub.sql publication adds columns to some of the tables in the sample database, creates a publication and subscriptions, and also adds triggers to resolve update conflicts that may occur.


CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

About this chapter

This chapter presents a tutorial in which you set up a simple SQL Remote replication system between an Adaptive Server Enterprise consolidated database and an Adaptive Server Anywhere remote database, from scratch.

 Introduction

 Setting up SQL Remote using Sybase Central

 Setting up the consolidated database

 Set up the remote database in Sybase Central

 A tutorial using Interactive SQL and ssxtract

 Setting up the consolidated database

 Start replicating data


Introduction
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 Introduction

This chapter presents a tutorial to lead you through setting up a SQL Remote installation. The installation replicates data between an Adaptive Server Enterprise database (the consolidated database) and an Adaptive Server Anywhere database (the remote database).

 Tutorial goals

 The database

 Replication goals


Tutorial goals
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Introduction

 Tutorial goals

In the tutorial you act as the system administrator of a consolidated Adaptive Server Enterprise database, and set up a simple replication system. The replication system consists of a simple sales database, with two tables.

The consolidated database holds all of the database, while the remote database has all of one table, but only some of the rows in the other table.

The tutorial takes you through the following steps:

•	Creating a consolidated database on your Adaptive Server Enterprise server.

•	Creating a file-sharing replication system with a single Adaptive Server Anywhere remote database.

•	Replicating data between the two databases.


The database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Introduction

 The database

The tutorial uses a simple two-table database. One table holds information about sales representatives, and the other about customers. The tables are much simpler than you would use in a real database; this allows us to focus just on those issues important for replication.

Database schema

The database schema for the tutorial is illustrated in the figure.

Features to note include the following:

•	Each sales representative is represented by one row in the SalesRep table.

•	Each customer is represented by one row in the customer table.

•	Each customer is assigned to a single Sales representative, and this assignment is built in to the database as a foreign key from the Customer table to the SalesRep table. The relationship between the Customer table and the SalesRep table is many-to-one.

The tables in the database

The tables are described in more detail as follows:

Table	Description
SalesRep	One row for each sales representative that works for the company. The SalesRep table has the following columns: • rep_key   An identifier for each sales representative. This is the primary key. • name   The name of each sales representative. The SQL statement creating this table is as follows: CREATE TABLE SalesRep ( rep_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, PRIMARY KEY (rep_key) )
Customer	One row for each customer that does business with the company. The Customer table includes the following columns: • cust_key   An identifier for each customer. This is the primary key. • name   The name of each customer. • rep_key   An identifier for the sales representative in a sales relationship. This is a foreign key to the SalesRep table. The SQL statement creating this table is as follows: CREATE TABLE Customer ( cust_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, rep_key CHAR(12) NOT NULL, FOREIGN KEY ( rep_key ) REFERENCES SalesRep (rep_key ), PRIMARY KEY (cust_key) )


Replication goals
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Introduction

 Replication goals

The goals of the replication design are to provide each sales representative with the following information:

•	The complete SalesRep table.

•	Those customers assigned to them.

The tutorial describes how to meet this goal using SQL Remote.

Use Sybase Central or the command line

The tutorial material is presented twice. One section describes how to set up the installation using the Sybase Central management utility. The second section describes how to set up the installation using the Adaptive Server Enterprise and Adaptive Server Anywhere Interactive SQL utilities: this requires typing commands individually.

Where next?

•	To work through the tutorial using Sybase Central, go to Setting up SQL Remote using Sybase Central.

•	To work through the tutorial entering commands explicitly, go to A tutorial using Interactive SQL and ssxtract.


Setting up SQL Remote using Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 Setting up SQL Remote using Sybase Central

The following sections are a tutorial describing how to set up a simple SQL Remote replication system using Sybase Central.

You do not need to enter SQL statements if you are using Sybase Central to administer SQL Remote. A tutorial for those who do not have access to Sybase Central, who prefer to use command-line utilities, or who wish to understand the individual commands executed, is presented in A tutorial using Interactive SQL and ssxtract. The commands described in that section are executed behind the scenes by Sybase Central.

 First steps


First steps
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up SQL Remote using Sybase Central

 First steps

Create a login name and password

To work through the tutorial, you must have system administrator privileges on an Adaptive Server Enterprise server. The tutorial assumes that your login name is the two-letter word sa and that this login name has a password of sysadmin.

Create a database

Create a database named hq on your Adaptive Server Enterprise with sufficient space to hold the tables and data required by the tutorial database. A space of 10 Mb is sufficient.

♦ To create a database from Sybase Central:

1	Connect to the Adaptive Server Enterprise from Sybase Central.

2	Open the Databases folder, and double-click Add database in the right pane.

3	Enter the name hq on the first page of the wizard.

4	Follow the instructions in the wizard.

  For information on how to create databases and assign space to them, see your Adaptive Server Enterprise documentation.

Install SQL Remote

You need to install SQL Remote into the hq database.

♦ To install SQL Remote into the HQ database:

1	Open the hq database container, on the left pane of Sybase Central.

2	Open the SQL Remote folder, double-click Setup SQL Remote, and follow the instructions. For this tutorial, you should install the stable queue in the hq database.

If your TEMPDB database is too small, you may have to add space to it for this to work.

  For a full description of how to install SQL Remote, see Setting Up SQL Remote.

Create directories for messages

Make a directory for the files created in this tutorial. For example:

mkdir c:\tutorial

You should create a directory for each of the two users of the replication system under your tutorial directory:

mkdir c:\tutorial\hq

mkdir c:\tutorial\field

The next step is to add a pair of tables to the consolidated database.

♦ To add tables to the consolidated database:

1	Connect to the hq database from Sybase Central, as a system administrator.

2	Click the User Tables folder of the hq database.

3	Double-click Add Table, and use the Table Editor to create a table named SalesRep with the following columns:

Key	Column	Data Type	Size/Prec
Primary key	rep_key	char	5
	name	char	40
You do not need to use the Advanced Properties window. The columns are created by default not allowing NULL.

4	Double-click Add Table again, and use the Table Editor to create a table named Customer with the following columns:

Key	Column	Data Type	Size/Prec
Primary key	cust_key	char	10
	name	char	40
	rep_key	char	5
Again, you do not need to use the Advanced Properties window. The columns are created by default not allowing NULL.

5	Open the Foreign Keys folder of the Customer table container, and double-click Add Foreign Key. Using the wizard, add a foreign key to the rep_key column of the SalesRep table. You can use the default settings for this foreign key.

You are now ready for the rest of the tutorial.


Setting up the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 Setting up the consolidated database

This section of the tutorial describes how to prepare the consolidated database of a simple replication system.

Preparing a consolidated database for replication involves the following steps:

1	Create a message type to use for replication.

2	Grant PUBLISH permissions to a user ID to identify the source of outgoing messages.

3	Grant REMOTE permissions to all user IDs that are to receive messages.

4	Create a publication describing the data to be replicated.

5	Create subscriptions describing who is to receive the publication.

You should have system administrator authority to carry out these tasks.

 Add a SQL Remote message type

 Create the necessary users and permissions

 Create the publication and subscription


Add a SQL Remote message type
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up the consolidated database

 Add a SQL Remote message type

All messages sent as part of replication use a message type. A message type description has two parts:

•	A message link supported by SQL Remote. In this tutorial, we use the FILE link.

•	An address for this message link, to identify the source of outgoing messages.

Adaptive Server Enterprise databases already have message types created once you install SQL Remote into the database, but you need to supply an address for the message type you will use.

♦ To add an address to a message type:

1	From Sybase Central, open the hq database container.

2	Click the SQL Remote folder on the left panel.

3	Double-click the Message Types folder on the right panel.

4	Double-click the file message type.

5	Enter a publisher address to provide a return address for remote users. Enter hq; the directory you have created to hold messages for the consolidated database.

The address (hq) for a file link is a directory in which files containing the message are placed. It is taken relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.

6	Click OK to save the message type.


Create the necessary users and permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up the consolidated database

 Create the necessary users and permissions

A set of users and permissions are required for SQL Remote installations. In this tutorial, the following are required:

•	A publisher user name.

•	A remote user or subscriber.

This section describes the steps you need to take to create each user and assign them the necessary permissions.

♦ To create the publisher:

1	From Sybase Central, open the container for the hq database.

2	Open the Users folder, and double-click Add User.

3	Create a user named hq_user, mapping the login name to an available login name on your server. In this tutorial, a password of hq_pwd is assumed.

4	Make this user the publisher of the HQ database. Open the SQL Remote folder, and double-click Set Publisher. Select hq_user from the list of users to set it as the publisher.

A database can have only one publisher. You can find out who the publisher is at any time by opening the SQL Remote folder.

Add a remote user

Each remote database is identified in the consolidated database by a user ID with REMOTE permissions. Whether the remote database is a personal server or a network server with many users, it needs a single user ID to represent it to the consolidated database.

In a mobile workgroup setting, remote users may already be users of the consolidated database, and so no new users would need to be added; although they would need to be set as remote users.

When a remote user is added to a database, the message system they use and their address under that message system need to be stored along with their database user ID.

♦ To add a remote user:

1	Double click the SQL Remote folder on the left panel, then click the Remote Users folder on the left panel.

2	If you do not have a login name that you can use for the remote user, open the logins folder directly under the server container, and add a login. The name is unimportant.

Double-click Add Remote User on the right panel. The New Remote User wizard is displayed.

3	Create a remote user with name field_user. For the message type and address, select the FILE type and the corresponding address you are using for this user (such as field).

As with the publisher address, the address of the remote user (field) is a directory relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.

4	On the next page, ensure that the Send Then Close option is checked. (In many production environments you would not choose Send Then Close, but it is convenient for this tutorial.)

5	When you have finished all the entries, click Finish to create the remote user.

You have now created the users who will use this system.


Create the publication and subscription
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up the consolidated database

 Create the publication and subscription

This section describes how to add a publication to a database, and how to add a subscription to that publication for a user. The publication replicates all rows of the table SalesRep and some of the rows of the Customer table.

The first step is to mark the SalesRep and Customer tables for SQL Remote replication. Marking a table for SQL Remote replication enables it to be included in publications.

♦ To mark the tables for SQL Remote replication:

1	Open the SQL Remote folder in the hq database.

2	Open the Remote Tables folder, and double-click Add Remote Table.

3	Select SalesRep from the list of tables. You can leave the Conflict Resolution fields as they are. Click OK to mark the table for SQL Remote replication.

4	Re-open the Table properties window. Select Customer from the list of tables. Again, you can leave the Conflict Resolution fields as they are. Click OK to mark the table for SQL Remote replication.

♦ To add a publication:

1	Click the Publications folder in the SQL Remote folder.

2	Double-click Add Publication. The Publication wizard is displayed.

3	Name the publication SalesRepData on the first page of the wizard.

4	On the next page, click Add Table and select SalesRep from the list. Leave All Columns selected, and press OK to add the table.

Then click Add Table again, and select Customer from the list. Again, leave All Columns selected. Click the Subscribe Restriction tab, and choose to Subscribe by the column rep_key. Click OK to add the table to the publication.

5	Complete the wizard to create the publication.

Add a subscription

Each user ID that is to receive changes to a publication must have a subscription to that publication. Subscriptions can only be created for a valid remote user. You need to add a subscription to the SalesRepData publication for the remote database user field_user.

♦ To add a subscription:

1	Double-click the Publications folder, which is in the SQL Remote folder, so that the SalesRepData publication is displayed in the left panel.

2	Click the Remote Users folder so that remote users are displayed in the right panel.

3	Drag the field_user user from the right panel onto the SalesRepData publication in the left panel. The Create Subscription window is displayed. Enter a value of rep1 in the With Value box. The value rep1 is the rep_key value we will give to the user field_user in the SalesRep table.

At this stage, the subscription is not started—that is, no data will be exchanged. The subscription is started by the database extraction utility.

You have now set up the consolidated database.


Set up the remote database in Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 Set up the remote database in Sybase Central

The remote database needs to be created and configured in order to send and receive messages and participate in a SQL Remote setup.

Like the consolidated database, the remote database needs a publisher (in this case, the field_user user ID) to identify the source of outgoing messages, and it needs to have hq_user identified as a user with consolidated permissions. It needs the SalesRepData publication to be created and needs a subscription created for the hq_user user ID.

The remote database also needs to be synchronized with the consolidated database; that is, it needs to have a current copy of the data in order for the replication to start. In this case, there is no data in the publication as yet.

The database extraction utility enables you to carry out all the steps needed to create a remote database complete with subscriptions and required user IDs.

You need to extract a database from the consolidated database for remote user field_user.

♦ To extract a database:

1	Click the Remote Users folder, which is in the SQL Remote folder.

2	Right-click the field_user remote user, and select Extract Database from the popup menu. The Extraction wizard is displayed.

3	Use the user ID and password that you have used to create the tables and users in the database.

4	On the next page, check Start Subscriptions Automatically, for user field_user. Also, check Create New Remote Database. Adaptive Server Anywhere must be installed for Create New Remote Database to be available.

5	Create the database as file c:\tutorial\field.db, using a transaction log in the same directory.

6	Choose to extract all parts of the schema (the default setting). Leave the other options at their default settings, and create the remote database.

You should connect to the field database as DBA and confirm that all the database objects are created.

♦ To connect to and inspect the remote database:

1	From Sybase Central, choose Tools [image] Connect [image] Sybase Adaptive Server Anywhere.

2	Provide the user ID DBA and the password SQL. These must be typed in upper case, as the database was created as case sensitive. Select the field.db file, and connect.

3	Open the database container, and confirm that the tables and user names are present.

In a proper SQL Remote setup, the remote database field would need to be loaded on to the computer using it, together with an Adaptive Server Anywhere server and any client applications required. For this tutorial, we leave the database where it is and use isql to input and replicate data.

What next?

The system is now ready for replication.

  For the next step, inserting and replicating data, see the section Start replicating data.


A tutorial using Interactive SQL and ssxtract
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 A tutorial using Interactive SQL and ssxtract

The following sections are a tutorial describing how to set up a simple SQL Remote replication system. This version of the tutorial does not use Sybase Central.

This tutorial describes the stored procedures used to configure and manage SQL Remote. It also describes how to run the ssxtract command-line utility to extract remote databases from a consolidated database and the Message Agents to send information between the databases in the replication system.

In this tutorial you act as the administrator of the consolidated database, and set up a simple replication system using the file-sharing message link. The simple example is a primitive model for a sales-force automation system, with two tables. One contains a list of sales representatives, and another a list of customers. The tables are replicated in a setup with one consolidated database and one remote database. You can install this example on one computer.

 First steps


First steps
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        A tutorial using Interactive SQL and ssxtract

 First steps

Create a login name and password

To work through the tutorial, you must have system administrator privileges on an Adaptive Server Enterprise server. The tutorial assumes that your login name is the two-letter word sa and that your password is sysadmin.

The tutorial uses the Adaptive Server Enterprise isql utility. With the login name and password as given above, you can connect to your Adaptive Server Enterprise server using the following command line:

isql -S server-name -U sa -P sysadmin

where server-name is the name of the Adaptive Server Enterprise to which you connect.

Ensure that you have an appropriate login ID and can connect to your server before starting this tutorial.

Create a database

Create a database named hq on your Adaptive Server Enterprise server with sufficient space to hold the tables and data required by the tutorial database. A space of 4 Mb is sufficient.

♦ To create a database:

1	Using isql, connect to the server as a user with system administrator privileges:

isql -S server-name -U sa -P sysadmin

2	Use the master database:

use master

go

3	Create a database named hq. In this example, we use a 5 Mb database with a 5 Mb log, on two different devices:

create database hq

on database_device = 5

log on log_device = 5

go

  For more information on how to create databases and assign space to them, see your Adaptive Server Enterprise documentation.

Install SQL Remote

You need to install SQL Remote into the hq database.

♦ To install SQL Remote into the hq database:

1	If the system administrator login name you are using does not have the hq database as the default database, make a backup copy of the ssremote.sql script from your installation directory, and add the following two lines to the beginning of the script:

use hq

go

2	Change to the tutorial directory. Then, using isql, connect to the server using the hq database, and run the ssremote.sql script from your SQL Remote installation directory. The following command should be entered all on one line:

isql -S server-name -U sa -P sysadmin -i ssremote.sql

3	If the system administrator login name you are using does not have the hq database as the default database, make a backup copy of the stableq.sql script from your installation directory, and add the following two lines to the beginning of the script:

use hq

go

4	Using isql, connect to the server using the hq database, and run the stableq.sql script from your SQL Remote installation directory. The following command should be entered all on one line:

isql -S server-name -U sa -P sysadmin -i stableq.sql

Create directories for messages

Create a directory to hold the files from this tutorial. For example:

mkdir c:\tutorial

You should create a directory for each of the two users of the replication system under your parent directory for this tutorial:

mkdir c:\tutorial\hq

mkdir c:\tutorial\field

The next step is to add a pair of tables to the consolidated database.

♦ To add tables to the consolidated database:

1	Connect to the hq database from isql, as a system administrator.

2	Use the hq database:

use hq

go

3	Create the SalesRep table with the following statement:

create table SalesRep (

rep_key char(12) not null,

name char(40) not null,

primary key (rep_key) )

go

4	Create the Customer table with the following statement:

create table Customer (

cust_key char(12) not null,

name char(40) not null,

rep_key char(12) not null,

primary key (cust_key) )

go

5	Alter the Customer table to add a foreign key to the SalesRep table:

alter table Customer

add foreign key

( rep_key ) references SalesRep

go

You are now ready for the rest of the tutorial.


Setting up the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 Setting up the consolidated database

This section of the tutorial describes how to prepare the consolidated database of a simple replication system.

Preparing a consolidated database for replication involves the following steps:

1	Create a message type to use for replication.

2	Grant PUBLISH permissions to a user ID to identify the source of outgoing messages.

3	Grant REMOTE permissions to all user IDs that are to receive messages.

4	Create a publication describing the data to be replicated.

5	Create subscriptions describing who is to receive the publication.

You should have system administrator authority to carry out these tasks.

 Create the message links and addresses

 Create the necessary users and permissions

 Create the publication and subscription

 Extract the remote database


Create the message links and addresses
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up the consolidated database

 Create the message links and addresses

In this tutorial, messages are exchanged using the shared file link. You must create a FILE message type supplying the address of the consolidated database publisher.

♦ To create the message type:

•	Execute the sp_remote_type stored procedure, using HQ as the address of the consolidated database publisher:

sp_remote_type file, hq

go

The address (hq) for a file link is a directory in which files containing the message are placed. It is taken relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.

With the message type defined, you can now make the necessary users.


Create the necessary users and permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up the consolidated database

 Create the necessary users and permissions

A set of users and permissions are required for SQL Remote installations. In this tutorial, the following are required:

•	A remote user or subscriber, with name field_user.

•	A publisher user name, called hq_user.

This section describes the steps you need to take to create each user and assign them the necessary permissions.

♦ To create the publisher:

1	Add a login called hq_user, with hq as the default database and with system administrator access:

exec sp_addlogin hq_user, hq_pwd, hq

go

exec sp_role 'grant', sa_role, hq_user

go

2	Add the login name as a user to the HQ database:

use hq

go

exec sp_adduser hq_user

go

3	Make this user the publisher of the HQ database:

exec sp_publisher hq_user

go

Add a remote user

Each remote database is identified in the consolidated database by a user ID with REMOTE permissions. Whether the remote database is a single-user server or a database server with many users, it needs a single user ID to represent it to the consolidated database.

In a mobile workgroup setting, remote users may already be users of the consolidated database, and so no new users would need to be added; although they would need to be set as remote users.

When a remote user is added to a database, the message system they use and their address under that message system need to be stored along with their database user ID.

♦ To create the subscriber:

1	If you do not have a login name that you can use for the remote user, add a login:

exec sp_addlogin field_user, field_pwd, hq

go

2	Add a user to the hq database:

exec sp_adduser field_user

go

3	Grant the user remote permissions. Execute the sp_grant_remote stored procedure, using field_user as the user name, file as the message type, and the appropriate directory as the address:

exec sp_grant_remote field_user, file, field

go

As with the publisher address, the address of the remote user (field) is a directory relative to the SQLRemote environment variable or registry entry. As you have not set this value, the address is taken relative to the directory from which the Message Agent is run. You should run the Message Agent from your tutorial directory for the addresses to be interpreted properly.

  For information about setting the SQLRemote value, see Setting message type control parameters.


Create the publication and subscription
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up the consolidated database

 Create the publication and subscription

The remaining task is to define the data to be replicated. To do this, you must first create a publication, which defines the available data, and then create a subscription for field_user, which defines the data that user is sharing.

In Adaptive Server Enterprise, they are created with the sp_create_publication procedure, which creates an empty publication, and the sp_add_article procedure, which adds articles to the procedure. Also, each table must be marked for replication before it can be included in a publication.

♦ To create the publication:

1	Create an empty publication:

exec sp_create_publication SalesRepData

go

2	Mark both the SalesRep table and the Customer table for publication:

exec sp_add_remote_table SalesRep

go

exec sp_add_remote_table Customer

go

3	Add the whole SalesRep table to the SalesRepData publication:

exec sp_add_article SalesRepData, SalesRep

go

4	Add the Customer table to the SalesRepData publication, using the rep_key column to partition the table. The following statement should be typed all on one line, except for the go:

exec sp_add_article SalesRepData, Customer, NULL, 'rep_key'

go

Add a subscription

Each user ID that is to receive changes to a publication must have a subscription to that publication. Subscriptions can only be created for a valid remote user. You need to add a subscription to the SalesRepData publication for the remote database user field_user.

♦ To create a subscription:

•	Create a subscription to SalesRepData for field_user, with a subscription value of rep1:

exec sp_subscription 'create', SalesRepData, field_user, 'rep1'

go

At this stage, the subscription is not started—that is, no data will be exchanged. The subscription is started by the database extraction utility.


Extract the remote database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Setting up the consolidated database

 Extract the remote database

There are three stages to creating a remote Adaptive Server Anywhere database using the remote database extraction utility:

•	Extract the schema and data into a set of files. You do this using the ssxtract command-line utility.

•	Create an Adaptive Server Anywhere database.

•	Load the schema and data into the database.

Extracting the schema and data

With all the information included, the next step is to extract an Adaptive Server Anywhere database for user field_user. The following command line (entered all on one line, from the tutorial directory) carries out this procedure:

ssxtract -v -c "eng=server-name; dbn=hq;uid=sa;pwd=sysadmin" C:\tutorial\field field_user

The command-line arguments have the following meaning.

•	-v    Verbose mode. For development work, this provides additional output.

•	-c    Connection string argument. The connection string is supplied in double quotes following the -c.

•	eng=server-name    Specifies the server to which the extraction utility is to connect.

•	dbn=hq    Specifies the database on the server to use; in this case hq.

•	uid=sa    The login ID to use to log on to the database.

•	pwd=sysadmin    The password to use to log on to the database.

•	C:\tutorial\field    The directory in which to place files holding the data.

•	field_user    The user ID for which to extract the database.

  For more information on extraction utility command-line switches, see The extraction command-line utility

Running this command produces the following files:

•	Reload script    The reload script is named reload.sql, and is placed in the current directory.

•	Data files    Files containing data to load into the database. In this case, these files are empty.

Creating an Adaptive Server Anywhere database

You can create an Adaptive Server Anywhere database using the dbinit command-line utility. A simple Adaptive Server Anywhere database is a file, unlike Adaptive Server Enterprise databases.

You should create the Adaptive Server Anywhere database so that it is compatible with Adaptive Server Enterprise database behavior, unless you have set options in your Adaptive Server Enterprise server that are different from the default.

♦ To create a database file named field.db:

•	Enter the following command from the c:\tutorial\field directory:

dbinit -b -c -k field.db

The -b switch forces use of blank padding in string comparisons. The -c switch enforces case sensitivity for string comparisons. The -k switch makes the system catalog more compatible with Adaptive Server Enterprise.

Loading the data into the database

You can load the data into the database using the Adaptive Server Anywhere Interactive SQL utility or the rtsql command-line utility. rtsql is an alternative to Interactive SQL for batch processes only, and is provided for the runtime database.

♦ To load the data into the database using Interactive SQL:

1	Start an Adaptive Server Anywhere server running on the field database:

dbeng7 field.db

2	Connect to the server using the Interactive SQL utility:

dbisql -c "eng=field;dbn=field;uid=DBA;pwd=SQL"

The user ID and password must be entered in upper case, as the Adaptive Server Anywhere database was created as case-sensitive.

3	Load the data using the READ command:

READ C:\TUTORIAL\RELOAD.SQL

♦ To load the data into the database as a batch process:

1	Start an Adaptive Server Anywhere server running on the field database:

dbeng7 field.db

2	Run the script from Interactive SQL:

dbisql -c "eng=field;dbn=field;uid=DBA;pwd=SQL" reload.sql

The user ID and password must be entered in upper case, as the Adaptive Server Anywhere database was created as case-sensitive.

What next?

The system is now ready for replication.

  For the next step, inserting and replicating data, see the section Start replicating data.


Start replicating data
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

 Start replicating data

You now have a replication system in place. In this section, data is replicated from the consolidated database to the remote database, and from the remote to the consolidated database.

 Enter data at the consolidated database

 Send data from the consolidated database

 Receive data at the remote database

 Replicate from the remote database to the consolidated database


Enter data at the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Start replicating data

 Enter data at the consolidated database

In this section we enter data into the SalesRep and Customer tables at the consolidated (Adaptive Server Enterprise) database, and replicate this data to the Adaptive Server Anywhere database.

♦ To enter data at the Adaptive Server Enterprise database:

1	Connect to the Adaptive Server Enterprise server from isql:

isql -S server-name -U sa -P sysadmin

2	Ensure you are using the hq database, and enter a series of rows:

use hq

go

insert into SalesRep (rep_key, name)

values ('rep1', 'Field User')

go

insert into SalesRep (rep_key, name)

values ('rep2', 'Another User')

go

insert into Customer (cust_key, name, rep_key)

values ('cust1', 'Ocean Sports', 'rep1')

go

insert into Customer (cust_key, name, rep_key)

values ('cust2', 'Sports Plus', 'rep2')

go

commit

go

Ocean Sports is assigned to Field User, and Sports Plus is assigned to Another User. You must commit the changes, as SQL Remote replicates only committed changes.

Having entered the data at the consolidated database, you now need to send the relevant rows to the remote Adaptive Server Anywhere database.


Send data from the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Start replicating data

 Send data from the consolidated database

To send the rows to the remote database, you must run the Message Agent at the consolidated database. The ssremote program is the Message Agent for Adaptive Server Enterprise.

♦ To replicate the data from Adaptive Server Enterprise:

1	Enter the following statement (on a single line) at the command line to run the Message Agent against the consolidated database:

ssremote -c "eng=server-name;dbn=hq;uid=sa;pwd=sysadmin"

2	Click Shutdown on the Message Agent window to stop the Message Agent when the messages have been sent.


Receive data at the remote database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Start replicating data

 Receive data at the remote database

To receive the insert statement at the remote database, you must run the Message Agent, dbremote, at the remote database.

♦ To receive the data at Adaptive Server Anywhere:

1	With the database server running, receive the data using the Message Agent for Adaptive Server Anywhere:

dbremote -c "eng=field;dbn=field;uid=DBA;pwd=SQL"

  For more information on dbremote command line switches, see The Message Agent.

2	Click Shutdown on the Message Agent window to stop the Message Agent when the messages have been processed.

The Message Agent window displays status information while running. This information can be output to a log file for record keeping in a production setup.

The Message Agent first receives a message from hq, and then sends a message. This return message contains confirmation of successful receipt of the replication update; such confirmations are part of the SQL Remote message tracking system that ensures message delivery even in the event of message system errors.

Verify that the data has arrived

You should now connect to the remote field database using Interactive SQL, and inspect the SalesRep and Customer tables, to see which rows have been received.

♦ To verify that the data has arrived:

1	Connect to the field database using Interactive SQL.

2	Inspect the SalesRep table by typing the following statement:

SELECT * FROM SalesRep

You will see that the SalesRep table contains both rows entered at the consolidated database. This is because the SalesRepData publication included all the data from the SalesRep table.

3	Inspect the Customer table by typing the following statement:

SELECT * FROM Customer

You will see that the Customer table contains only one row (Ocean Sports) entered at the consolidated database. This is because the SalesRepData publication included only those customers assigned to the subscribed Sales Rep.


Replicate from the remote database to the consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 13.  A Tutorial for Adaptive Server Enterprise Users

        Start replicating data

 Replicate from the remote database to the consolidated database

You should now try entering data at the remote database and sending it to the consolidated database. Only the outlines are presented here.

♦ To replicate data from the remote database to the consolidated database:

1	Connect to the field database from Interactive SQL.

2	INSERT a row at the remote database. For example

INSERT INTO Customer (cust_key, name, rep_key)

VALUES ('cust3', 'North Land Trading', 'rep1')

3	COMMIT the row.:

COMMIT;

4	With the field.db database running, run dbremote to send the message to the consolidated database.

dbremote -c "eng=field;dbn=field;uid=DBA;pwd=SQL"

(For Windows 3.x, run the dbremotw equivalent.)

5	Run ssremote to receive the message at the consolidated database:

ssremote -c "eng=server-name;dbn=hq;uid=sa;pwd=sysadmin"

6	Connect to the consolidated database and display  the Customer table. This now has three rows:

SELECT *

FROM Customer

cust_key	name	rep_key
cust1	Ocean Sports	rep1
cust2	Sports Plus	rep2
cust3	North Land Trading	rep1
In this simple example, there is no protection against duplicate entries of primary key values. SQL Remote does provide for such protection. For information, see the chapters on SQL Remote Design.


CHAPTER 14.  Principles of SQL Remote Design
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 14.  Principles of SQL Remote Design

About this chapter

This chapter describes general issues and principles for designing a SQL Remote installation.

  For system-specific details, see the chapters SQL Remote Design for Adaptive Server Enterprise and SQL Remote Design for Adaptive Server Anywhere.

 Design overview

 How statements are replicated

 How data types are replicated

 Who gets what?

 Replication errors and conflicts


Design overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

 Design overview

This chapter describes general publication design issues that you must address when designing a SQL Remote installation. It also describes how SQL Remote replicates data.

Design at the consolidated database

Like all SQL Remote administrative tasks, design is carried out by a database administrator or system administrator at the consolidated database.

The Adaptive Server Enterprise System Administrator or database administrator should perform all SQL Remote configuration tasks.

 Ensuring compatible databases

 Using compatible sort orders and character sets


Ensuring compatible databases
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        Design overview

 Ensuring compatible databases

You should ensure that all databases participating in a SQL Remote installation are compatible in terms of sort orders, character sets, and database option settings.

If your installation includes both Adaptive Server Enterprise and Adaptive Server Anywhere databases, you should ensure your Adaptive Server Anywhere databases are created in an Adaptive Server Enterprise-compatible fashion.

  For a full description of how to create Enterprise-compatible Adaptive Server Anywhere databases, see "Creating a Transact-SQL-compatible database", in the chapter "Using Transact-SQL with Adaptive Server Anywhere", in the Adaptive Server Anywhere User's Guide. This section provides a brief description only.

♦ To create an Enterprise-compatible Adaptive Server Anywhere database using Sybase Central:

•	The Create Database wizard provides an button that sets each of the available choices to emulate Adaptive Server Enterprise. This is the simplest way to create a Transact-SQL-compatible database.

♦ To create an Enterprise-compatible Adaptive Server Anywhere database from the command line:

1	Ensure trailing blanks are ignored    You can do this using the dbinit -b command-line switch.

2	Ensure the dbo user ID is set    If you have a database that already has a user ID named dbo, then you can transfer the ownership of the Adaptive Server Anywhere Transact-SQL system views to another user ID. You can do this using the dbinit -g command-line switch.

3	Remove historical system views You can do this with the dbinit -k command-line switch.

4	Make the database case sensitive You can do this with the dbinit -c command-line switch.

The following command creates a case-sensitive database named test.db in the current directory, using the current dbo user, ignoring trailing blanks, and removing historical system views:

dbinit -b -c -k test.db


Using compatible sort orders and character sets
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        Design overview

 Using compatible sort orders and character sets

The SQL Remote Message Agent does not perform any character set conversions.

Character sets in Adaptive Server Anywhere installations

For an Adaptive Server Anywhere installation, the character set and collation used by the consolidated database must be the same as the remote databases. For information about supported character sets, see Database Collations and International Languages.

Character sets in Adaptive Server Enterprise installations

The Open Client/Open Server libraries perform character set conversions between SSREMOTE and Adaptive Server Enterprise whenever the LOCALES.DAT character set is different from the Adaptive Server Enterprise character set. Both character sets must be installed on the Adaptive Server Enterprise server and conversion must be supported.

Character sets in mixed installations

The locales.dat settings (which are used by all Open Client applications) must match the remote Adaptive Server Anywhere settings.

The following table provides recommended matches between Adaptive Server Enterprise and Adaptive Server Anywhere character sets. The matches are not all complete.

Adaptive Server Anywhere collation name	Open Client / Open Server name	Open Client / Open Server case-sensitive sort order	Open Client / Open Server case-insensitive sort order
default	cp850	dictionary_cp850	nocase_cp850
850	cp850	dictionary_cp850	nocase_cp850
437	cp437	dictionary_cp437	nocase_cp437
852	cp852	bin_cp852	bin_cp852
860	cp860	bin_cp860	bin_cp860
437LATIN1	cp437	dictionary_cp437	nocase_cp437
437ESP	cp437	espdict_cp437	espnocs_cp437
437SVE	cp437	bin_cp437	bin_cp437
819CYR	iso_1	bin_iso_1	bin_iso_1
819DAN	iso_1	bin_iso_1	bin_iso_1
819ELL	iso_1	bin_iso_1	bin_iso_1
819ESP	iso_1	espdict_iso_1	espnocs_iso_1
819ISL	iso_1	bin_iso_1	bin_iso_1
819LATIN1	iso_1	dictionary_iso_1	nocase_iso_1
819LATIN2	iso_1	bin_iso_1	bin_iso_1
819NOR	iso_1	bin_iso_1	bin_iso_1
819RUS	iso_1	bin_iso_1	bin_iso_1
819SVE	iso_1	bin_iso_1	bin_iso_1
819TRK	iso_1	bin_iso_1	bin_iso_1
850CYR	cp850	bin_cp850	bin_cp850
850DAN	cp850	scandict_cp850	scannocp_cp850
850ELL	cp850	bin_cp850	bin_cp850
850ESP	cp850	espdict_cp850	espnocs_cp850
850ISL	cp850	scandict_cp850	scannocp_cp850
850LATIN1	cp850	dictionary_cp850	nocase_cp850
850LATIN2	cp850	bin_cp850	bin_cp850
850NOR	cp850	scandict_cp850	scannocp_cp850
850RUS	cp850	bin_cp850	bin_cp850
850SVE	cp850	scandict_cp850	scannocp_cp850
850TRK	cp850	bin_cp850	bin_cp850
852LATIN2	cp852	bin_cp852	bin_cp852
852CYR	cp852	bin_cp852	bin_cp852
855CYR	cp855	cyrdict_cp855	cynocs_cp855
857TRK	cp857	bin_cp857	bin_cp857
860LATIN1	cp860	bin_cp860	bin_cp860
866RUS	cp866	rusdict_cp866	rusnocs_cp866
869ELL	cp869	bin_cp869	bin_cp869
SJIS	sjis	bin_sjis	bin_sjis
SJIS2	sjis	bin_sjis	bin_sjis
EUC_JAPAN	eucjis	bin_eucjis	bin_eucjis
EUC_CHINA	eucgb	bin_eucgb	bin_eucgb
EUC_TAIWAN	eucb5	bin_big5	bin_big5
EUC_KOREA	eucksc	bin_eucksc	bin_eucksc
UTF8	utf8	bin_utf8	bin_utf8


How statements are replicated
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

 How statements are replicated

SQL Remote replication is based on the transaction log, enabling it to replicate only changes to data, rather than all data, in each update. When we say that SQL Remote replicates data, we really mean that SQL Remote replicates SQL statements that modify data.

Only committed transactions are replicated

SQL Remote replicates only statements in committed transactions, to ensure proper transaction atomicity throughout the replication setup and maintain a consistency among the databases involved in the replication, albeit with some time lag while the data is replicated.

Primary keys

When an UPDATE or a DELETE is replicated, SQL Remote uses the primary key columns to uniquely identify the row being updated or deleted. All tables being replicated must have a declared primary key or uniqueness constraint. A unique index is not sufficient. The columns of the primary key are used in the WHERE clause of replicated updates and deletes. If a table has no primary key, the WHERE clause refers to all columns in the table.

An UPDATE is not always an UPDATE

When a simple INSERT statement is entered at one database, it is sent to other databases in the SQL Remote setup as an INSERT statement. However, not all statements are replicated exactly as they are entered by the client application. This section describes how SQL Remote replicates SQL statements. It is important to understand this material if you are to design a robust SQL Remote installation.

The Message Agent is the component that carries out the replication of statements.

 Replication of inserts and deletes

 Replication of updates

 Replication of procedures

 Replication of triggers

 Replication of data definition statements


Replication of inserts and deletes
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        How statements are replicated

 Replication of inserts and deletes

INSERT and DELETE statements are the simplest replication case. SQL Remote takes each INSERT or DELETE operation from the transaction log, and sends it to all sites that subscribe to the row being inserted or deleted.

If only a subset of the columns in the table is subscribed to, the INSERT statements sent to subscribers contains only those columns.

The Message Agent ensures that statements are not replicated to the user that initially entered them.


Replication of updates
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        How statements are replicated

 Replication of updates

UPDATE statements are not replicated exactly as the client application enters them. This section describes two ways in which the replicated UPDATE statement may differ from the entered UPDATE statement.

UPDATE statements replicated as INSERTS or DELETES

If an UPDATE statement has the effect of removing a row from a given remote user's subscription, it is sent to that user as a DELETE statement. If an UPDATE statement has the effect of adding a row to a given remote user's subscription, it is sent to that user as an INSERT statement.

The figure illustrates a publication, where each subscriber subscribes by their name:

An UPDATE that changes the Rep value of a row from Marc to Ann is replicated to Marc as a DELETE statement, and to Ann as an INSERT statement.

This reassignment of rows among subscribers is sometimes called territory realignment, because it is a common feature of sales force automation applications, where customers are periodically reassigned among representatives.

UPDATE conflict detection

An UPDATE statement changes the value of one or more rows from some existing value to a new value. The rows altered depend on the WHERE clause of the UPDATE statement.

When SQL Remote replicates an UPDATE statement, it does so as a set of single-row updates. These single-row statements can fail for one of the following reasons:

•	The row to be updated does not exist    Each row is identified by its primary key values, and if a primary key has been altered by some other user, the row to be updated is not found.

In this case, the UPDATE does not update anything.

•	The row to be updated differs in one or more of its columns    If one of the values expected to be present has been changed by some other user, an update conflict occurs.

At remote databases, the update takes place regardless of the values in the row.

At the consolidated database, SQL Remote allows conflict resolution operations to take place. Conflict resolution operations are held in a trigger or stored procedure, and run automatically when a conflict is detected.

In Adaptive Server Anywhere, the conflict resolution trigger runs before the update, and the update .proceeds when the trigger is finished. In Adaptive Server Enterprise, the conflict resolution procedure runs after the update has been applied.

•	A table without a primary key or uniqueness constraint refers to all columns in the WHERE clause of replicated updates    When two users update the same row, replicated updates will not update anything and databases will become inconsistent. All replicated tables should have a primary key or uniqueness constraint and the columns in the constraint should never be updated.


Replication of procedures
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        How statements are replicated

 Replication of procedures

Any replication system is faced with a choice between two options when replicating a stored procedure call:

•	Replicate the procedure call    A corresponding procedure is executed at the replicate site, or

•	Replicate the procedure actions    The individual actions (INSERTs, UPDATEs, DELETEs and so on) of the procedure are replicated.

SQL Remote replicates procedures by replicating the actions of a procedure. The procedure call is not replicated.


Replication of triggers
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        How statements are replicated

 Replication of triggers

Trigger replication in SQL Remote is different for the Adaptive Server Enterprise Message Agent and the Adaptive Server Anywhere Message Agent.

Trigger replication from Adaptive Server Enterprise

From Adaptive Server Enterprise, trigger actions are replicated. You must ensure that triggers are not fired in the remote Adaptive Server Anywhere databases. If the trigger were fired, its actions would be executed twice.

The Adaptive Server Anywhere FIRE_TRIGGERS database option prevents triggers from being fired. If you set this option for the user ID used by the Message Agent, be careful to not use this user ID for other purposes.

An alternative approach to preventing trigger execution, available only for Adaptive Server Anywhere, is to use the following condition around the body of your triggers:

IF CURRENT REMOTE USER IS NULL

This make execution conditional on whether the current user is the Message Agent.

Trigger replication from Adaptive Server Anywhere

By default, the Message Agent for Adaptive Server Anywhere does not replicate actions performed by triggers; it is assumed that the trigger is defined remotely. This avoids permissions issues and the possibility of each action occurring twice. There are some exceptions to this rule:

•	Conflict resolution trigger actions     The actions carried out by conflict resolution, or RESOLVE UPDATE, triggers are replicated from a consolidated database to all remote databases, including the one that sent the message causing the conflict.

•	Replication of BEFORE triggers     Some BEFORE triggers can produce undesirable results when using SQL Remote, and so BEFORE trigger actions that modify the row being updated are replicated, before UPDATE actions.

You must be aware of this behavior when designing your installation. For example, a BEFORE UPDATE that bumps a counter column in the row to keep track of the number of times a row is updated would double count if replicated, as the BEFORE UPDATE trigger will fire when the UPDATE is replicated. To prevent this problem, you must ensure that, at the subscriber database, the trigger is not present or does not carry out the replicated action. Also, a BEFORE UPDATE that sets a column to the time of the last update will get the time the UPDATE is replicated as well.

An option to replicate trigger actions

The Adaptive Server Anywhere Message Agent has a command-line switch that causes it to replicate all trigger actions when sending messages. This is the dbremote -t switch.

If you use this switch, you must ensure that the trigger actions are not carried out twice at remote databases, once by the trigger being fired at the remote site, and once by the explicit application of the replicated actions from the consolidated database.

To ensure that trigger actions are not carried out twice, you can wrap an IF CURRENT REMOTE USER IS NULL ... END IF statement around the body of the triggers or you can set the Adaptive Server Anywhere Fire_triggers option to OFF for the Message Agent user ID.


Replication of data definition statements
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        How statements are replicated

 Replication of data definition statements

Data definition statements (CREATE, ALTER, DROP, and others that modify database objects) are not replicated by SQL Remote unless they are entered while in passthrough mode.

  For information about passthrough mode for Adaptive Server Anywhere, see Using passthrough mode.


How data types are replicated
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

 How data types are replicated

Long binary or character data, and datetime data, need special consideration.

 Replication of blobs

 Replication of dates and times


Replication of blobs
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        How data types are replicated

 Replication of blobs

Blobs are LONG VARCHAR, LONG BINARY, TEXT, and IMAGE data types: values that are longer than 256 characters.

Adaptive Server Anywhere replication

SQL Remote includes a special method for replicating blobs between Adaptive Server Anywhere databases.

The Message Agent uses a variable in place of the value in the INSERT or UPDATE statement that is being replicated. The value of the variable is built up by a sequence of statements of the form

SET vble = vble || 'more_stuff'

This makes the size of the SQL statements involving long values smaller, so that they fit within a single message. The SET statements are separate SQL statements, so that the blob is effectively split over several SQL Remote messages.

Adaptive Server Enterprise replication

Blobs can be replicated to and from Adaptive Server Enterprise as long as they fit into the Message Agent memory.

Sybase Open Client CTLIB applications that manipulate the CS_IODESC structure must not set the log_on_update member to FALSE.

Using the Verify_threshold option to minimize message size

The Verify_threshold database option can prevent long values from being verified (in the VERIFY clause of a replicated UPDATE). The default value for the option is 1000. If the data type of a column is longer than the threshold, old values for the column are not verified when an UPDATE is replicated. This keeps the size of SQL Remote messages down, but has the disadvantage that conflicting updates of long values are not detected.

There is a technique allowing detection of conflicts when Verify_threshold is being used to reduce the size of messages. Whenever a "blob" is updated, a last_modified column in the same table should also be updated. Conflicts can then be detected because the old value of the last_modified column is verified.

Using a work table to avoid redundant updates

Repeated updates to a blob should be done in a "work" table, and the final version should be assigned to the replicated table. For example, if a document in progress is updated 20 times throughout the day and the Message Agent is run once at the end of the day, all 20 updates are replicated. If the document is 200 kb in length, this causes 4 Mb of messages to be sent.

The better solution is to have a document_in_progress table. When the user is done revising a document, the application moves it from the document_in_progress table to the replicated table. The results in a single update (200 kb of messages).

Controlling replication of blobs

The Adaptive Server Anywhere BLOB_THRESHOLD option allows further control over the replication of long values. Any value longer than the BLOB_THRESHOLD option is replicated as a blob. That is, it is broken into pieces and replicated in chunks, before being reconstituted by using a SQL variable and concatenating the pieces at the recipient site.

By setting BLOB_THRESHOLD to a high value in remote Adaptive Server Anywhere databases, blobs are not broken into pieces, and operations can be applied to Adaptive Server Enterprise by the Message Agent. Each SQL statement must fit within a message, so this only allows replication of small blobs.


Replication of dates and times
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        How data types are replicated

 Replication of dates and times

When date or time columns are replicated, the Message Agent uses the setting of the SR_Date_Format, SR_Time_Format, and SR_Timestamp_Format database options to format the date.

For example, the following option setting instructs the Message Agent to send a date of May 2, 1987 as 1987-05-02.

SET OPTION SR_Date_Format = 'yyyy-mm-dd'

  For more information, see SQL Remote options.

The following points may be useful when replicating dates and times:

•	The time, date, and timestamp formats must be consistent throughout the installation.

•	If the consolidated database is an Adaptive Server Anywhere database, ensure that the order of year, month, and day used for the date and timestamp formats matches the setting of the DATE_ORDER database option.

You can change the DATE_ORDER option for the duration of each connection.

•	If the consolidated database is an Adaptive Server Enterprise database, ensure that the order of year, month, and day in the SQL Remote settings is consistent with the dateformat setting in the Adaptive Server Enterprise database.

♦ To find the dateformat settings on an Adaptive Server Enterprise database:

1	Login to the Adaptive Server Enterprise database from isql using the login ID used by ssremote. In this example, we use ssr for this login ID.

2	Issue the following command:

select *

from master..syslogins

where name = 'ssr'

go

Adaptive Server Enterprise returns the default language for the ssr user.

3	If ssr uses the default language (us_english) then the default dateformat is YMD. If the language is different from the default, enter the following command:

sp_helplanguage language-name

where language-name is the language in use by the ssr user. The information displayed includes the default date format for the language.


Who gets what?
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

 Who gets what?

Each time a row in a table is inserted, deleted, or updated, a message has to be sent to those subscribed to the row. In addition, an update may cause the subscription expression to change, so that the statement is sent to some subscribers as a delete, some as an update, and some as an insert.

  For details of what statements get sent to which subscribers, see How statements are replicated. For details on subscriptions, see the following two chapters.

This section describes how SQL Remote sends the right operations to the right recipients.

The task of determining who gets what is divided between the database server and the Message Agent. The engine handles those aspects that are to do with publications, while the Message Agent handles aspects to do with subscriptions.

Adaptive Server Anywhere actions

Adaptive Server Anywhere evaluates the subscription expression for each update made to a table that is part of a publication. It adds the value of the expression to the log, both before and after the update.

Not the subscriber list
Adaptive Server Enterprise does not evaluate or enter into the log a list of subscribers. The subscription expression (a property of the publication) is evaluated and entered. All handling of subscribers is left to the Message Agent.

For a table that is part of more than one publication, the subscription expression is evaluated before and after the update for each publication.

The addition of information to the log can affect performance in the following cases:

•	Expensive expressions    When a subscription expression is expensive to evaluate, it can affect performance.

•	Many publications    When a table belongs to many publications, many expressions must be evaluated. In contrast, the number of subscriptions is irrelevant.

•	Many-valued expressions    Some expressions are many-valued. This can lead to much additional in formation in the transaction log, with a corresponding effect on performance.

Adaptive Server Enterprise actions

In a SQL Remote for Adaptive Server Enterprise publication, the subscription expression must be a column. The subscription column contains either a single value or a comma-separated list of values.

Not the subscriber list
Adaptive Server Enterprise does not enter into the log a list of subscribers. The column value is entered. All handling of subscribers is left to the Message Agent.

When a table is marked for replication using sp_add_remote_table (which calls sp_setreplicate), Adaptive Server Enterprise places an entire before image of the row in the transaction log for deletes, and entire after image for inserts, and both images for updates. This means that the before and after values of the subscription column are available.

Message Agent actions

The Message Agent reads the evaluated subscription expressions or subscription column entries from the transaction log, and matches the before and after values against the subscription value for each subscriber to the publication. In this way, the Message Agent can send the correct operations to each subscriber.

While large numbers of subscribers do not have any impact on server performance, they can impact Message Agent performance. Both the work in matching subscription values against large numbers of subscription values, and the work in sending the messages, can be demanding.


Replication errors and conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

 Replication errors and conflicts

SQL Remote is designed to allow databases to be updated at many different sites. Careful design is required to avoid replication errors, especially if the database has a complicated structure. This section describes the kinds of errors and conflict that can occur in a replication setup; subsequent sections describe how you can design your publications to avoid errors and manage conflicts.

Delivery errors not discussed here
This section does not discuss issues related to message delivery failures. For information on delivery errors and how they are handled, see The message tracking system

 Replication errors

 Replication conflicts

 Tracking SQL errors


Replication errors
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        Replication errors and conflicts

 Replication errors

Replication errors fall into the following categories:

•	Duplicate  primary key errors    Two users INSERT a row using the same primary key values, or one user updates a primary key and a second user inserts a primary key of the new value. The second operation to reach a given database in the replication system fails because it would produce a duplicate primary key.

•	Row not found errors    A user DELETES a row (that is, the row with a given primary key value). A second user UPDATES or DELETES the same row at another site.

In this case, the second statement fails, as the row is not found.

•	Referential integrity errors    If a column containing a foreign key is included in a publication, but the associated primary key is not included, the extraction utility leaves the foreign key definition out of the remote database so that INSERTS at the remote database will not fail.

This can be solved by including proper defaults into the table definitions.

Also, referential integrity errors can occur when a primary table has a SUBSCRIBE BY expression and the associated foreign table does not: rows from the foreign table may be replicated, but the rows from the primary table may be excluded from the publication.


Replication conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        Replication errors and conflicts

 Replication conflicts

Replication conflicts are different from errors. Properly handled, conflicts are not a problem in SQL Remote.

•	Conflicts    A user updates a row. A second user updates the same row at another site. The second user's operation succeeds, and SQL Remote allows a trigger to be fired (Adaptive Server Anywhere) or a procedure to be called (Adaptive Server Enterprise) to resolve these conflicts in a way that makes sense for the data being changed.

Conflicts will occur in many installations. SQL Remote allows appropriate resolution of conflicts as part of the regular operation of a SQL Remote setup, using triggers and procedures.

  For information about how SQL Remote handles conflicts as they occur, see the following chapters.


Tracking SQL errors
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 14.  Principles of SQL Remote Design

        Replication errors and conflicts

 Tracking SQL errors

SQL errors in replication must be designed out of your setup. SQL Remote includes an option to help you track errors in SQL statements, but this option is not intended to resolve such errors.

By setting the Replication_error option, you can specify a stored procedure to be called by the Message Agent when a SQL error occurs. By default no procedure is called.

♦ To set the Replication_error option in Adaptive Server Anywhere:

•	Issue the following statement:

SET OPTION

remote-user.Replication_error

= 'procedure-name'

where remote-user is the user ID on the Message Agent command line, and procedure-name is the procedure called when a SQL error is detected.

♦ To set the Replication_error option in Adaptive Server Enterprise:

•	Issue the following statement:

exec sp_remote_option Replication_error, procedure-name

go

where procedure-name is the procedure called when a SQL error is detected.

Replication error procedure requirements

The replication error procedure must have a single argument of type CHAR, VARCHAR, or LONG VARCHAR. The procedure is called once with the SQL error message and once with the SQL statement that causes the error.


CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

About this chapter

This chapter describes how to design a SQL Remote installation when the consolidated database is an Adaptive Server Anywhere database.

Similar material for Adaptive Server Enterprise
Many of the principles of publication design are the same for Adaptive Server Anywhere and Adaptive Server Enterprise, but there are differences in commands and capabilities. There is a large overlap between this chapter and the corresponding chapter for Adaptive Server Enterprise users, SQL Remote Design for Adaptive Server Enterprise.

 Design overview

 Creating publications

 Publication design for Adaptive Server Anywhere

 Partitioning tables that do not contain the subscription expression

 Sharing rows among several subscriptions

 Managing conflicts

 Ensuring unique primary keys

 Creating subscriptions


Design overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Design overview

Designing a SQL Remote installation includes the following tasks:

•	Designing publications    The publications determine what information is shared among which databases.

•	Designing subscriptions    The subscriptions determine what information each user receives.

•	Implementing the design    Creating publications and subscriptions for all users in the system.

All administration is at the consolidated database

Like all SQL Remote administrative tasks, design is carried out by a database administrator or system administrator at the consolidated database.

The Adaptive Server Anywhere Database Administrator should perform all SQL Remote configuration tasks.


Creating publications
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Creating publications

This section describes how to create simple publications consisting of whole tables, or of column-wise subsets of tables; these tables are also called articles. You can perform these tasks using Sybase Central or with the CREATE PUBLICATION statement in Interactive SQL.

All publications in Sybase Central appear in the Publications folder (located within the SQL Remote folder). Any articles you create for that publication appear within the publication container. With Sybase Central, you do not need to know the SQL syntax in order to create publications or articles.

  Simple publications are also discussed in the chapter A Tutorial for Adaptive Server Anywhere Users.

 Publishing a whole table

 Publishing some of the columns in a table

 Publishing a set of tables

 Publishing some of the rows from a table

 Altering existing publications

 Dropping publications

 Notes on publications


Publishing a whole table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

 Publishing a whole table

The simplest publication you can make consists of a single article, which consists of a single, entire table.

♦ To create a publication that includes all the rows and columns of a single table (Sybase Central):

1	Connect to the database as a user with DBA authority.

2	Open the Publications folder and launch the Add Publication wizard.

3	Type a name for the new publication. Click Next.

4	On the Tables tab, select a table from the list of Matching tables. Click Add. The table appears in the list of Selected tables on the right.

5	Click Finish.

♦ To create a publication that includes all the rows and columns of a single table (SQL):

1	Connect to the database as a user with DBA authority.

2	Execute a CREATE PUBLICATION statement that specifies the name of the publication and the table you want to publish.

Example

•	The following statement creates a publication that publishes the whole customer table:

CREATE PUBLICATION pub_customer (

TABLE customer

)

  See also

•	CREATE PUBLICATION statement

•	Altering existing publications


Publishing some of the columns in a table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

 Publishing some of the columns in a table

You can create a publication that contains only some of the columns of a table. An article that contains only some of the columns of a table is called a column-wise partitioning of the table. An article that contains only some of the rows of a table is  called a row-wise partitioning of the table; for more information about row-wise partitioning, see Publishing some of the rows from a table. Articles can be both column-wise and row-wise partitions of a table.

You create a publication that contains all the rows, but only some of the columns, of a table in Sybase Central or by specifying a list of columns in the CREATE PUBLICATION statement.

♦ To create a publication that includes all the rows and some of the columns of a table (Sybase Central):

1	Connect to the database as a user with DBA authority.

2	Open the Publications folder and launch the Add Publication wizard.

3	Type a name for the new publication. Click Next.

4	On the Tables tab, select a table from the list of Matching tables. Click Add. The table is added to the list of Selected tables on the right.

5	On the Columns tab, double-click the table's icon to expand the list of available columns. Select each column you want to publish and click Add. The selected columns appear on the right.

6	Click Finish.

♦ To create a publication that includes all the rows and some of the columns of a table (SQL):

1	Connect to the database as a user with DBA authority.

2	Execute a CREATE PUBLICATION statement that specifies the publication name, the table name, and the names of the columns.

Example

•	The following statement creates a publication that publishes all rows of the id, company_name, and city columns of the customer table:

CREATE PUBLICATION pub_customer (

TABLE customer (

id,

company_name,

city )

)

  See also

•	CREATE PUBLICATION statement

•	Conditions for valid articles

•	Altering existing publications


Publishing a set of tables
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

 Publishing a set of tables

When you publish a set of tables, a separate article is required for each table in the publication. You can use Sybase Central for this task, or you can specify a set of tables in a CREATE PUBLICATION statement.

♦ To create a publication that includes a set of tables (Sybase Central):

1	Connect to the database as a user with DBA authority.

2	Open the Publications folder and launch the Add Publication wizard.

3	Type a name for the new publication. Click Next.

4	On the Tables tab, select a table from the list of Matching tables. Click Add. The table appears in the list of Selected tables on the right.

5	Repeat the previous step to add each additional table. The order of the tables is not important.

6	Click Finish.

♦ To create a publication that includes a set of tables (SQL):

1	Connect to the database as a user with DBA authority.

2	Execute a CREATE PUBLICATION statement that specifies the publication name and the tables involved.

Example

•	The following statement creates a publication including all columns and rows in each of a set of tables from the Adaptive Server Anywhere sample database:

CREATE PUBLICATION sales (

TABLE customer,

TABLE sales_order,

TABLE sales_order_items,

TABLE product

)

Not all the tables in the database have been published. For example, subscribers receive the sales_order table, but not the employee table.

Notes

•	In the sample database, the sales_order and employee tables are related by a foreign key (sales_rep in the sales_order table is a foreign key to the emp_id column in the employee table). Although this could lead to referential integrity problems in the remote database, they are easily avoided by using the database extraction utility.

•	A slightly different publication design (including an article that contains enough of the employee table to satisfy the foreign key relationship) would make the publication more robust; for this section we are publishing whole tables only.

  See also

•	CREATE PUBLICATION statement

•	Designing to avoid referential integrity errors

•	Altering existing publications


Publishing some of the rows from a table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

 Publishing some of the rows from a table

There are two ways of including only some of the rows in a publication:

•	WHERE clause    You can use a WHERE clause to include a subset of rows in an article. All subscribers to the publication containing this article receive the rows that satisfy the WHERE clause.

•	Subscription expression    You can use a subscription expression to include a different set of rows in different subscriptions to publications containing the article.

You can combine a WHERE clause and a subscription expression in an article. You can specify them in Sybase Central or in a CREATE PUBLICATION statement.

Use the Subscription expression when different subscribers to a publication are to receive different rows from a table. The Subscription expression is the most powerful method of partitioning tables.

Use the WHERE clause to exclude the same set of rows from all subscriptions to a publication.

 Publishing a subset of rows using a WHERE clause

 Publishing a subset of rows using a subscription expression


Publishing a subset of rows using a WHERE clause
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

          Publishing some of the rows from a table

 Publishing a subset of rows using a WHERE clause

You can specify a WHERE clause to include in the publication only the rows that satisfy the WHERE conditions.

♦ To create a publication using a WHERE clause (Sybase Central):

1	Connect to the database as a user with DBA authority.

2	Open the Publications folder and launch the Add Publication wizard.

3	Type a name for the new publication. Click Next.

4	On the Tables tab, select a table from the list of Matching tables. Click Add. The table is added to the list of Selected tables on the right.

5	On the Where tab, select the table then type the search condition in the lower box. Optionally, you can use the Insert dialog to assist you in formatting the search condition.

6	Click Finish.

♦ To create a publication using a WHERE clause (SQL):

1	Connect to the database as a user with DBA authority.

2	Execute a CREATE PUBLICATION statement that includes the rows you wish to include in the publication and a WHERE condition.

Examples

•	The following statement creates a publication that publishes the id, company_name, city, and state columns of the customer table, for the customers marked as active in the status column.

CREATE PUBLICATION pub_customer (

TABLE customer (

id,

company_name,

city,

state )

WHERE status = 'active'

)

In this case, the status column is not included in the publication. It must therefore have a default value so that inserts at remote databases will not fail at the consolidated database.

•	The following is a single-article publication sending relevant order information to Samuel Singer, a sales rep:

CREATE PUBLICATION pub_orders_samuel_singer (

TABLE sales_order WHERE sales_rep = 856

)

  See also

•	CREATE PUBLICATION statement

•	Altering existing publications

•	Publishing a subset of rows using a subscription expression


Publishing a subset of rows using a subscription expression
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

          Publishing some of the rows from a table

 Publishing a subset of rows using a subscription expression

You can specify a subscription expression to include a different set of rows in different subscriptions to publications containing the article.

For example, in a mobile workforce situation, a sales publication may be wanted where each sales rep subscribes to their own sales orders, enabling them to update their sales orders locally and replicate the sales to the consolidated database.

Using the WHERE clause model, a separate publication for each sales rep would be needed: the following publication is for sales rep Samuel Singer: each of the other sales reps would need a similar publication.

CREATE PUBLICATION pub_orders_samuel_singer (

TABLE sales_order

WHERE sales_rep = 856

)

To address the needs of setups requiring large numbers of different subscriptions, SQL Remote allows a subscription expression to be associated with an article. Subscriptions receive rows depending on the value of a supplied expression.

Benefits of subscription expressions

Publications using a subscription expression are more compact, easier to understand, and provide better performance than maintaining several WHERE clause publications. The database server must add information to the transaction log, and scan the transaction log to send messages, in direct proportion to the number of publications. The subscription expression allows many different subscriptions to be associated with a single publication, whereas the WHERE clause does not.

♦ To create an article using a subscription expression (Sybase Central):

1	Connect to the database as a user with DBA authority.

2	Open the Publications folder and launch the Add Publication wizard.

3	Type a name for the new publication. Click Next.

4	On the Tables tab, select a table from the list of Matching tables. Click Add. The table is added to the list of Selected tables on the right.

5	On the Subscribe By tab, choose the a table then, in the lower box, type the a column name.

6	Click Finish.

♦ To create an article using a subscription expression (SQL):

1	Connect to the database as a user with DBA authority.

2	Execute a CREATE PUBLICATION statement that includes the expression you wish to use as a match in the subscription expression.

Examples

•	The following statement creates a publication that publishes the id, company_name, city, and state columns of the customer table, and which matches the rows with subscribers according to the value of the state column:

CREATE PUBLICATION pub_customer (

TABLE customer (

id,

company_name,

city,

state )

SUBSCRIBE BY state

)

•	The following statements subscribe two employees to the publication: Ann Taylor receives the customers in Georgia (GA), and Sam Singer receives the customers in Massachusetts (MA).

CREATE SUBSCRIPTION

TO pub_customer ('GA')

FOR Ann_Taylor ;

CREATE SUBSCRIPTION

TO pub_customer ('MA')

FOR Sam_Singer

Users can subscribe to more than one publication, and can have more than one subscription to a single publication.

  See also

•	CREATE PUBLICATION statement

•	Partitioning tables that do not contain the subscription expression

•	Creating subscriptions

•	Publishing a subset of rows using a WHERE clause

•	Altering existing publications


Altering existing publications
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

 Altering existing publications

After you have created a publication, you can alter it by adding, modifying, or deleting articles, or by renaming the publication. If an article is modified, the entire specification of the modified article must be entered.

You can perform these tasks using Sybase Central or with the ALTER PUBLICATION statement in Interactive SQL.

♦ To modify the properties of existing publications or articles (Sybase Central):

1	Right-click the publication or article and choose Properties from the popup menu.

2	Configure the desired properties.

♦ To add articles (Sybase Central):

1	Open the Publications folder (located within the SQL Remote folder).

2	Open the publication container.

3	Double-click Add Article.

4	In the New Article dialog, do the following:

•	On the Tables tab, choose a table and the number of columns.

•	On the Where restriction tab, enter a WHERE clause (if desired).

•	On the Subscribe restriction tab, create a subscription expression (if desired).

5	Click OK to create the article.

♦ To remove articles (Sybase Central):

1	Open the Publications folder (located within the SQL Remote folder).

2	Open the publication container.

3	Right-click the article you want to delete and choose Delete from the popup menu.

♦ To modify an existing publication (SQL):

1	Connect to a database with DBA authority.

2	Execute an ALTER PUBLICATION statement.

Example

•	The following statement adds the customer table to the pub_contact publication.

ALTER PUBLICATION pub_contact (

ADD TABLE customer

)

  See also

•	ALTER PUBLICATION statement

•	Publishing a subset of rows using a WHERE clause

•	Publishing a subset of rows using a subscription expression

•	For a description of all property sheets in Sybase Central, see Property Sheet Descriptions.


Dropping publications
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

 Dropping publications

You can drop a publication using either Sybase Central or the DROP PUBLICATION statement. If you drop a publication, all subscriptions to that publication are automatically deleted as well.

You must have DBA authority to drop a publication.

♦ To delete a publication (Sybase Central):

1	Open the Publications folder (located within the SQL Remote folder).

2	Right-click the desired publications and choose Delete from the popup menu.

♦ To delete a publication (SQL):

1	Connect to a database.

2	Execute a DROP PUBLICATION statement.

Example

The following statement drops the publication named pub_orders.

DROP PUBLICATION pub_orders

  See also

•	DROP PUBLICATION statement


Notes on publications
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Creating publications

 Notes on publications

•	The different publication types described above can be combined. A single publication can publish a subset of columns from a set of tables, and use both a WHERE clause to select a set of rows to be replicated and a subscription expression to partition rows by subscription.

•	DBA authority is required to create publications.

•	Publications can be altered and dropped only by the DBA.

•	Altering publications in a running SQL Remote setup is likely to cause replication errors, and could lead to loss of data in the replication system unless carried out with care.

•	Views cannot be included in publications.

•	Stored procedures cannot be included in publications. For a discussion of how SQL Remote replicates procedures and triggers, see Replication of procedures .

•	For other considerations of referential integrity, see the section Designing to avoid referential integrity errors.


Publication design for Adaptive Server Anywhere
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Publication design for Adaptive Server Anywhere

Once you understand how to create simple publications, you must think about proper publication design. Sound design is an important part of building a successful SQL Remote installation. This section helps set out the principles of sound design as they apply to SQL Remote for Adaptive Server Anywhere.

Similar material for Adaptive Server Enterprise
Many of the principles of publication design are the same for Adaptive Server Anywhere and Adaptive Server Enterprise, but there are differences in commands and capabilities. There is a large overlap between this section and the corresponding section for Adaptive Server Enterprise users, Publication design for Adaptive Server Enterprise.

 Design issues overview

 Conditions for valid articles

 Design tips for performance


Design issues overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Publication design for Adaptive Server Anywhere

 Design issues overview

Each subscription must be a complete relational database

A remote database shares with the consolidated database the information in their subscriptions. The subscription is both a subset of the relational database held at the consolidated site, and also a complete relational database at the remote site. The information in the subscription is therefore subject to the same rules as any other relational database:

•	Foreign key relationships must be valid    For every entry in a foreign key, a corresponding primary key entry must exist in the database.

The database extraction utility ensures that the CREATE TABLE statements for remote databases do not have foreign keys defined to tables that do not exist remotely.

•	Primary key uniqueness must be maintained    There is no way of checking what new rows have been entered at other sites, but not yet replicated. The design must prevent users at different sites adding rows with identical primary-key values, as this would lead to conflicts when the rows are replicated to the consolidated database.

Transaction integrity must be maintained in the absence of locking

The data in the dispersed database (which consists of the consolidated database and all remote databases) must maintain its integrity in the face of updates at all sites, even though there is no system-wide locking mechanism for any particular row.

•	Locking conflicts must be prevented or resolved    In a SQL Remote installation, there is no method for locking rows across all databases to prevent different users from altering the rows at the same time. Such conflicts must be prevented by designing them out of the system or must be resolved in an appropriate manner at the consolidated database.

These key features of relational databases must be incorporated into the design of your publications and subscriptions. This section describes principles and techniques for sound design.


Conditions for valid articles
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Publication design for Adaptive Server Anywhere

 Conditions for valid articles

All columns in the primary key must be included in the article.

Supporting INSERTS at remote databases

For INSERT statements at a remote database to replicate correctly to the consolidated database, you can exclude from an article only columns that can be left out of a valid INSERT statement. These are:

•	Columns that allow NULL.

•	Columns that have defaults.

If you exclude any column that does not satisfy one of these requirements, INSERT statements carried out at a remote database will fail when replicated to the consolidated database.

Using BEFORE triggers as an alternative
An exception to this case is when the consolidated database is an Adaptive Server Anywhere database, and a BEFORE trigger has been written to maintain the columns that are not included in the INSERT statement.


Design tips for performance
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Publication design for Adaptive Server Anywhere

 Design tips for performance

This section presents a check list for designing high performance SQL Remote installations.

•	Keep the number of publications small    In particular, try not to reference the same table in many different publications.

The work the database server needs to do is proportional to the number of publications. Keeping the number low and making effective use of subscriptions lightens the load on the database server.

When operations occur on a table, the database server and the Message Agent must do some work for each publication that contains the table. Having one publication for each remote user will drastically increase the load on the database server. It is much better to have a few publications that use SUBSCRIBE BY and have subscriptions for each remote user. The database server does no additional work when more subscriptions are added for a publication. The Message Agent is designed to work efficiently with a large number of subscriptions.

•	Group publications logically    For example, if there is a table that every remote user requires, such as a price list table, make a separate publication for that table. Make one publication for each table where the data can be partitioned by a column value.

•	Use subscriptions effectively    When remote users receive similar subsets of the consolidated database, always use publications that incorporate SUBSCRIBE BY expressions. Do not create a separate publication for each remote user.

•	Pay attention to Update Publication Triggers    In particular:

•	Use the NEW / OLD SUBSCRIBE BY syntax.

•	Tune the SELECT statements to ensure they are accessing the database efficiently.

•	Monitor the transaction log size    The larger the transaction log, the longer it takes the Message Agent to scan it. Rename the log regularly and use the DELETE_OLD_LOGS option.


Partitioning tables that do not contain the subscription expression
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Partitioning tables that do not contain the subscription expression

In many cases, the rows of a table need to be partitioned even when the subscription expression does not exist in the table.

 The Contact example

 Partitioning the Customer table in the Contact example

 Partitioning the Contact table in the Contact example

 Territory realignment in the Contact example


The Contact example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Partitioning tables that do not contain the subscription expression

 The Contact example

The Contact database illustrates why and how to partition tables that do not contain the subscription expression.

Example

Here is a simple database that illustrates the problem.

Each sales representative sells to several customers. At some customers there is a single contact, while other customers have several contacts.

The tables in the database

The three tables are described in more detail as follows:

Table	Description
SalesRep	All sales representatives that work for the company. The SalesRep table has the following columns: • rep_key   An identifier for each sales representative. This is the primary key. • name   The name of each sales representative. The SQL statement creating this table is as follows: CREATE TABLE SalesRep ( rep_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, PRIMARY KEY (rep_key) )
Customer	All customers that do business with the company. The Customer table includes the following columns: • cust_key   An identifier for each customer. This is the primary key. • name   The name of each customer. • rep_key   An identifier for the sales representative in a sales relationship. This is a foreign key to the SalesRep table. The SQL statement creating this table is as follows: CREATE TABLE Customer ( cust_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, rep_key CHAR(12) NOT NULL, FOREIGN KEY REFERENCES SalesRep, PRIMARY KEY (cust_key) )
Contact	All individual contacts that do business with the company. Each contact belongs to a single customer. The Contact table includes the following columns: • contact_key   An identifier for each contact. This is the primary key. • name   The name of each contact. • cust_key   An identifier for the customer to which the contact belongs. This is a foreign key to the Customer table. The SQL statement creating this table is: CREATE TABLE Contact ( contact_key  CHAR(12) NOT NULL, name  CHAR(40) NOT NULL, cust_key  CHAR(12) NOT NULL, FOREIGN KEY  REFERENCES Customer, PRIMARY KEY  (contact_key) )
Replication goals

The goals of the design are to provide each sales representative with the following information:

•	The complete SalesRep table.

•	Those customers assigned to them, from the Customer table.

•	Those contacts belonging to the relevant customers, from the Contact table.


Partitioning the Customer table in the Contact example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Partitioning tables that do not contain the subscription expression

 Partitioning the Customer table in the Contact example

The Customer table can be partitioned using the rep_key value as a subscription expression. A publication that includes the SalesRep and Customer tables would be as follows:

CREATE PUBLICATION SalesRepData (

TABLE SalesRep

TABLE Customer SUBSCRIBE BY rep_key

)


Partitioning the Contact table in the Contact example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Partitioning tables that do not contain the subscription expression

 Partitioning the Contact table in the Contact example

The Contact table must also be partitioned among the sales representatives, but contains no reference to the sales representative rep_key value. How can the Message Agent match a subscription value against rows of this table, when rep_key is not present in the table?

To solve this problem, you can use a subquery in the Contact article that evaluates to the rep_key column of the Customer table. The publication then looks like this:

CREATE PUBLICATION SalesRepData (

TABLE SalesRep

TABLE Customer

SUBSCRIBE BY rep_key

TABLE Contact

SUBSCRIBE BY (SELECT rep_key

FROM Customer

WHERE Contact.cust_key = Customer.cust_key )

)

The WHERE clause in the subscription expression ensures that the subquery returns only a single value, as only one row in the Customer table has the cust_key value in the current row of the Contact table.

  For an Adaptive Server Enterprise consolidated database, the solution is different. For more information, see Partitioning tables that do not contain the subscription column.


Territory realignment in the Contact example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Partitioning tables that do not contain the subscription expression

 Territory realignment in the Contact example

In territory realignment, rows are reassigned among subscribers. In the present case, territory realignment is the reassignment of rows in the Customer table, and by implication also the Contact table, among the Sales Reps.

When a customer is reassigned to a new sales rep, the Customer table is updated. The UPDATE is replicated as an INSERT or a or a DELETE to the old and new sales representatives, respectively, so that the customer row is properly transferred to the new sales representative.

  For information on the way in which Adaptive Server Anywhere and SQL Remote work together to handle this situation, see Who gets what?.

When a customer is reassigned, the Contact table is unaffected. There are no changes to the Contact table, and consequently no entries in the transaction log pertaining to the Contact table. In the absence of this information, SQL Remote cannot reassign the rows of the Contact table along with the Customer.

This failure will cause referential integrity problems: the Contact table at the remote database of the old sales representative contains a cust_key value for which there is no longer a Customer.

Use triggers to maintain Contacts

The solution is to use a trigger containing a special form of UPDATE statement, which does not make any change to the database tables, but which does make an entry in the transaction log. This log entry contains the before and after values of the subscription expression, and so is of the proper form for the Message Agent to replicate the rows properly.

The trigger must be fired BEFORE operations on the row. In this way, the BEFORE value can be evaluated and placed in the log. Also, the trigger must be fired FOR EACH ROW rather than for each statement, and the information provided by the trigger must be the new subscription expression. The Message Agent can use this information to determine which subscribers receive which rows.

Trigger definition

The trigger definition is as follows:

CREATE TRIGGER UpdateCustomer

BEFORE UPDATE ON Customer

REFERENCING NEW AS NewRow

   OLD as OldRow

FOR EACH ROW

BEGIN

// determine the new subscription expression

// for the Customer table

UPDATE Contact

PUBLICATION SalesRepData

OLD SUBSCRIBE BY ( OldRow.rep_key )

NEW SUBSCRIBE BY ( NewRow.rep_key )

WHERE cust_key = NewRow.cust_key;

END;

A special UPDATE statement for publications

The UPDATE statement in this trigger is of the following special form:

UPDATE table-name

PUBLICATION publication-name

{ SUBSCRIBE BY subscription-expression |

OLD SUBSCRIBE BY old-subscription-expression

NEW SUBSCRIBE BY new-subscription-expression }

WHERE search-condition

Here is what the UPDATE statement clauses mean:

The table-name indicates the table that must be modified at the remote databases.

The publication-name indicates the publication for which subscriptions must be changed.

The value of subscription-expression is used by the Message Agent to determine both new and existing recipients of the rows. Alternatively, you can provide both OLD and NEW subscription expressions.

The WHERE clause specifies which rows are to be transferred between subscribed databases.

Notes on the trigger

•	If the trigger uses the following syntax:

UPDATE table-name

PUBLICATION pub-name

SUBSCRIBE BY sub-expression

WHERE search-condition

the trigger must be a BEFORE trigger. In this case, a BEFORE UPDATE trigger. In other contexts, BEFORE DELETE and BEFORE INSERT are necessary.

•	If the trigger uses the alternate syntax:

UPDATE table-name

PUBLICATION publication-name

OLD SUBSCRIBE BY old-subscription-expression

NEW SUBSCRIBE BY new-subscription-expression }

WHERE search-condition

The trigger can be a BEFORE or AFTER trigger.

•	The UPDATE statement lists the publication and table that is affected. The WHERE clause in the statement describes the rows that are affected. No changes are made to the data in the table itself by this UPDATE, it makes entries in the transaction log.

•	The subscription expression in this example returns a single value. Subqueries returning multiple values can also be used. The value of the subscription expression must the value after the UPDATE.

In this case, the only subscriber to the row is the new sales representative. In Sharing rows among several subscriptions, we see cases where there are existing as well as new subscribers.

Information in the transaction log

Here we describe the information placed in the transaction log. Understanding this helps in designing efficient publications.

•	Assume the following data:

•	SalesRep table

rep_key	Name
rep1	Ann
rep2	Marc
•	Customer table

cust_key	name	rep_key
cust1	Sybase	rep1
cust2	ASA	rep2
•	Contact table

contact_key	name	cust_key
contact1	David	cust1
contact2	Stefanie	cust2
•	Now apply the following territory realignment Update statement

UPDATE Customer

SET rep_key = 'rep2'

WHERE cust_key = 'cust1'

The transaction log would contain two entries arising from this statement: one for the BEFORE trigger on the Contact table, and one for the actual UPDATE to the Customer table.

SalesRepData - Publication Name

rep1 - BEFORE list

rep2 - AFTER list

UPDATE Contact

SET contact_key = 'contact1',

    name = 'David',

    cust_key = 'cust1'

WHERE contact_key = 'contact1'

SalesRepData - Publication Name

rep1 - BEFORE list

rep2 - AFTER list

UPDATE Customer

SET rep_key = 'rep2'

WHERE cust_key = 'cust1'

The Message Agent scans the log for these tags. Based on this information it can determine which remote users get an INSERT, UPDATE or DELETE.

In this case, the BEFORE list was rep1 and the AFTER list is rep2. If the before and after list values are different, the rows affected by the UPDATE statement have "moved" from one subscriber value to another. This means the Message Agent will send a DELETE to all remote users who subscribed by the value rep1 for the Customer record cust1 and send an INSERT to all remote users who subscribed by the value rep2.

If the BEFORE and AFTER lists are identical, the remote user already has the row and an UPDATE will be sent.


Sharing rows among several subscriptions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Sharing rows among several subscriptions

There are cases where a row may need to be included in several subscriptions. For example, we may have a many-to-many relationship. In this section, we use a case study to illustrate how to handle this situation.

 The Policy example

 Territory realignment with a many-to-many relationship

 Using the Subscribe_by_remote option with many-to-many relationships


The Policy example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Sharing rows among several subscriptions

 The Policy example

The Policy database illustrates why and how to partition tables when there is a many-to-many relationship in the database.

Example database

Here is a simple database that illustrates the problem.

Each sales representative sells to several customers, and some customers deal with more than one sales representative. In this case, the relationship between Customer and SalesRep is thus a many-to-many relationship.

The tables in the database

The three tables are described in more detail as follows:

Table	Description
SalesRep	All sales representatives that work for the company. The SalesRep table has the following columns: • rep_key   An identifier for each sales representative. This is the primary key. • name   The name of each sales representative. The SQL statement creating this table is as follows: CREATE TABLE SalesRep ( rep_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, PRIMARY KEY (rep_key) );
Customer	All customers that do business with the company. The Customer table includes the following columns: • cust_key   A primary key column containing an identifier for each customer • name   A column containing the name of each customer The SQL statement creating this table is as follows: CREATE TABLE Customer ( cust_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, PRIMARY KEY (cust_key) );
Policy	A three-column table that maintains the many-to-many relationship between customers and sales representatives. The Policy table has the following columns: • policy_key   A primary key column containing an identifier for the sales relationship. • cust_key   A column containing an identifier for the customer representative in a sales relationship. • rep_key   A column containing an identifier for the sales representative in a sales relationship. The SQL statement creating this table is as follows. CREATE TABLE Policy ( policy_key CHAR(12) NOT NULL, cust_key CHAR(12) NOT NULL, rep_key CHAR(12) NOT NULL, FOREIGN KEY ( cust_key ) REFERENCES Customer ( cust_key ) FOREIGN KEY ( rep_key ) REFERENCES SalesRep (rep_key ), PRIMARY KEY ( policy_key ) );
Replication goals

The goals of the replication design are to provide each sales representative with the following information:

•	The entire SalesRep table.

•	Those rows from the Policy table that include sales relationships involving the sales rep subscribed to the data.

•	Those rows from the Customer table listing customers that deal with the sales rep subscribed to the data.

New problems

The many-to-many relationship between customers and sales representatives introduces new challenges in maintaining a proper sharing of information:

•	We have a table (in this case the Customer table) that has no reference to the sales representative value that is used in the subscriptions to partition the data.

Again, this problem is addressed by using a subquery in the publication.

•	Each row in the Customer table may be related to many rows in the SalesRep table, and shared with many sales representatives databases.

Put another way, the rows of the Contact table in Partitioning tables that do not contain the subscription expression were partitioned into disjoint sets by the publication. In the present example there are overlapping subscriptions.

To meet the replication goals we again need one publication and a set of subscriptions. In this case, we use two triggers to handle the transfer of customers from one sales representative to another.

 The publication


The publication
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Sharing rows among several subscriptions

          The Policy example

 The publication

A single publication provides the basis for the data sharing:

CREATE PUBLICATION SalesRepData (

TABLE SalesRep,

TABLE Policy SUBSCRIBE BY rep_key,

TABLE Customer SUBSCRIBE BY (

SELECT rep_key FROM Policy

WHERE Policy.cust_key =

Customer.cust_key

),

);

The subscription statements are exactly as in the previous example.

How the publication works

The publication includes part or all of each of the three tables. To understand how the publication works, it helps to look at each article in turn:

•	SalesRep table    There are no qualifiers to this article, so the entire SalesRep table is included in the publication.

...

TABLE SalesRep,

...

•	Policy table    This article uses a subscription expression to specify a column used to partition the data among the sales reps:

...

TABLE Policy

SUBSCRIBE BY rep_key,

...

The subscription expression ensures that each sales rep receives only those rows of the table for which the value of the rep_key column matches the value provided in the subscription.

The Policy table partitioning is disjoint: there are no rows that are shared with more than one subscriber.

Customer table    A subscription expression with a subquery is used to define the partition. The article is defined as follows:

...

TABLE Customer SUBSCRIBE BY (

SELECT rep_key

FROM Policy

WHERE Policy.cust_key =

Customer.cust_key

),

...

The Customer partitioning is non-disjoint: some rows are shared with more than one subscriber.

Multiple-valued subqueries in publications

The subquery in the Customer article returns a single column (rep_key) in its result set, but may return multiple rows, corresponding to all those sales representatives that deal with the particular customer. When a subscription expression has multiple values, the row is replicated to all subscribers whose subscription matches any of the values. It is this ability to have multiple-valued subscription expressions that allows non-disjoint partitionings of a table.


Territory realignment with a many-to-many relationship
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Sharing rows among several subscriptions

 Territory realignment with a many-to-many relationship

The problem of territory realignment (reassigning rows among subscribers) requires special attention, just as in the section Territory realignment in the Contact example.

You need to write triggers to maintain proper data throughout the installation when territory realignment (reassignment of rows among subscribers) is allowed.

How customers are transferred

In this example, we require that a customer transfer be achieved by deleting and inserting rows in the Policy table.

To cancel a sales relationship between a customer and a sales representative, a row in the Policy table is deleted. In this case, the Policy table change is properly replicated to the sales representative, and the row no longer appears in their database. However, no change has been made to the Customer table, and so no changes to the Customer table are replicated to the subscriber.

In the absence of triggers, this would leave the subscriber with incorrect data in their Customer table. The same kind of problem arises when a new row is added to the Policy table.

Using Triggers to solve the problem

The solution is to write triggers that are fired by changes to the Policy table, which include a special syntax of the UPDATE statement. The special UPDATE statement makes no changes to the database tables, but does make an entry in the transaction log that SQL Remote uses to maintain data in subscriber databases.

A BEFORE INSERT trigger

Here is a trigger that tracks INSERTS into the Policy table, and ensures that remote databases contain the proper data.

CREATE TRIGGER InsPolicy

BEFORE INSERT ON Policy

REFERENCING NEW AS NewRow

FOR EACH ROW

BEGIN

UPDATE Customer

PUBLICATION SalesRepData

SUBSCRIBE BY (

SELECT rep_key

FROM Policy

WHERE cust_key = NewRow.cust_key

UNION ALL

SELECT NewRow.rep_key

)

WHERE cust_key = NewRow.cust_key;

END;

A BEFORE DELETE trigger

Here is a corresponding trigger that tracks DELETES from the Policy table:

CREATE TRIGGER DelPolicy

BEFORE DELETE ON Policy

REFERENCING OLD AS OldRow

FOR EACH ROW

BEGIN

UPDATE Customer

PUBLICATION SalesRepData

SUBSCRIBE BY (

SELECT rep_key

FROM Policy

WHERE cust_key = OldRow.cust_key

AND Policy_key <> OldRow.Policy_key

)

WHERE cust_key = OldRow.cust_key;

END;

Some of the features of the trigger are the same as in the previous section. The major new features are that the INSERT trigger contains a subquery, and that this subquery can be multi-valued.

Multiple-valued subqueries

The subquery in the BEFORE INSERT trigger is a UNION expression, and can be multi-valued:

...

SELECT rep_key

FROM Policy

WHERE cust_key = NewRow.cust_key

UNION ALL

SELECT NewRow.rep_key

...

•	The second part of the UNION is the rep_key value for the new sales representative dealing with the customer, taken from the INSERT statement.

•	The first part of the UNION is the set of existing sales representatives dealing with the customer, taken from the Policy table.

This illustrates the point that the result set of the subscription query must be all those sales representatives receiving the row, not just the new sales representatives.

The subquery in the BEFORE DELETE trigger is multi-valued:

...

SELECT rep_key

FROM Policy

WHERE cust_key = OldRow.cust_key

AND rep_key <> OldRow.rep_key

...

•	The subquery takes rep_key values from the Policy table. The values include the primary-key values of all those sales reps who deal with the customer being transferred (WHERE cust_key = OldRow.cust_key), with the exception of the one being deleted (AND rep_key <> OldRow.rep_key).

This again emphasizes that the result set of the subscription query must be all those values matched by sales representatives receiving the row following the DELETE.

Notes

•	Data in the Customer table is not identified with an individual subscriber (by a primary key value, for example) and is shared among more than one subscriber. This allows the possibility of the data being updated in more than one remote site between replication messages, which could lead to replication conflicts. You can address this issue either by permissions (allowing only certain users the right to update the Customer table, for example) or by adding RESOLVE UPDATE triggers to the database to handle the conflicts programmatically.

•	UPDATES on the Policy table have not been described here. They should either be prevented, or a BEFORE UPDATE trigger is required that combines features of the BEFORE INSERT and BEFORE DELETE triggers shown in the example.


Using the Subscribe_by_remote option with many-to-many relationships
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Sharing rows among several subscriptions

 Using the Subscribe_by_remote option with many-to-many relationships

When the Subscribe_by_remote option is ON, operations from remote databases on rows with a subscribe by value of NULL or an empty string will assume the remote user is subscribed to the row. By default, the Subscribe_by_remote option is set to ON. In most cases, this setting is the desired setting.

The Subscribe_by_remote option solves a problem that otherwise would arise with some publications, including the Policy example. This section describes the problem, and how the option automatically avoids it.

The publication uses a subquery for the Customer table subscription expression, because each Customer may belong to several Sales Reps:

CREATE PUBLICATION SalesRepData (

TABLE SalesRep,

TABLE Policy SUBSCRIBE BY rep_key,

TABLE Customer SUBSCRIBE BY (

SELECT rep_key FROM Policy

WHERE Policy.cust_key =

Customer.cust_key

),

);

Marc Dill is a Sales Rep who has just arranged a policy with a new customer. He inserts a new Customer row and also inserts a row in the Policy table to assign the new Customer to himself.

As the INSERT of the Customer row is carried out by the Message Agent at the consolidated database, Adaptive Server Anywhere records the subscription value in the transaction log, at the time of the INSERT.

Later, when the Message Agent scans the log, it builds a list of subscribers from the subscription expression, and Marc Dill is not on the list, as the row in the Policy table assigning the customer to him has not yet been applied. If Subscribe_by_remote were set to OFF, the result would be that the new Customer is sent back to Marc Dill as a DELETE operation.

As long as Subscribe_by_remote is set to ON, the Message Agent assumes the row belongs to the Sales Rep that inserted it, the INSERT is not replicated back to Marc Dill, and the replication system is intact.

If Subscribe_by_remote is set to OFF, you must ensure that the Policy row is inserted before the Customer row, with the referential integrity violation avoided by postponing checking to the end of the transaction.


Managing conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Managing conflicts

An UPDATE conflict occurs when the following sequence of events takes place:

1	User 1 updates a row at remote site 1.

2	User 2 updates the same row at remote site 2.

3	The update from User 1 is replicated to the consolidated database.

4	The update from User 2 is replicated to the consolidated database.

When the SQL Remote Message Agent replicates UPDATE statements, it does so as a separate UPDATE for each row. Also, the message contains the old row values for comparison. When the update from user 2 arrives at the consolidated database, the values in the row are not those recorded in the message.

Default conflict resolution

By default, the UPDATE still proceeds, so that the User 2 update (the last to reach the consolidated database) becomes the value in the consolidated database, and is replicated to all other databases subscribed to that row.

In general, the default method of conflict resolution is that the most recent operation (in this case that from User 2) succeeds, and no report is made of the conflict. The update from User 1 is lost. SQL Remote also allows custom conflict resolution, using a trigger to resolve conflicts in a way that makes sense for the data being changed.

Conflict resolution does not apply to primary key updates
UPDATE conflicts do not apply to primary key updates. You should not update primary keys in a SQL Remote installation. Primary key conflicts must be excluded from the installation by proper design.

This section describes how you can build conflict resolution into your SQL Remote installation at the consolidated database.

 How SQL Remote handles conflicts

 Implementing conflict resolution

 Using conflict resolution triggers

 Conflict resolution examples

 Designing to avoid referential integrity errors

 Designing triggers to avoid errors


How SQL Remote handles conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

 How SQL Remote handles conflicts

When a conflict is detected

SQL Remote replication messages include UPDATE statements as a set of single row updates, each with a VERIFY clause that includes values prior to updating.

An UPDATE conflict is detected by the database server as a failure of the VERIFY clause values to match the rows in the database.

Conflicts are detected and resolved by the Message Agent, but only at a consolidated database. When an UPDATE conflict is detected in a message from a remote database, the Message Agent causes the database server to take two actions:

1	Any conflict resolution (RESOLVE UPDATE) triggers are fired.

2	The UPDATE is applied.

UPDATE statements are applied even if the VERIFY clause values do not match, whether or not there is a RESOLVE UPDATE trigger.

Conflict resolution can take several forms. For example:

•	In some applications, resolution could mean reporting the conflict into a table.

•	You may wish to keep updates made at the consolidated database in preference to those made at remote sites.

•	Conflict resolution can be more sophisticated, for example in resolving inventory numbers in the face of goods deliveries and orders.

  The method of conflict resolution is different at an Adaptive Server Enterprise consolidated database. For more information, see How SQL Remote handles conflicts.


Implementing conflict resolution
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

 Implementing conflict resolution

This section describes what you need to do to implement custom conflict resolution in SQL Remote for Adaptive Server Anywhere. The concepts are the same in SQL Remote for Adaptive Server Enterprise, but the implementation is different.

SQL Remote allows you to define conflict resolution triggers to handle UPDATE conflicts. Conflict resolution triggers are fired only at a consolidated database, when messages are applied by a remote user. When an UPDATE conflict is detected at a consolidated database, the following sequence of events takes place.

1	Any conflict resolution triggers defined for the operation are fired.

2	The UPDATE takes place.

3	Any actions of the trigger, as well as the UPDATE, are replicated to all remote databases, including the sender of the message that triggered the conflict.

In general, SQL Remote for Adaptive Server Anywhere does not replicate the actions of triggers: the trigger is assumed to be present at the remote database. Conflict resolution triggers are fired only at consolidated databases, and so their actions are replicated to remote databases.

4	At remote databases, no RESOLVE UPDATE triggers are fired when a message from a consolidated database contains an UPDATE conflict.

5	The UPDATE is carried out at the remote databases.

At the end of the process, the data is consistent throughout the setup.

UPDATE conflicts cannot happen where data is shared for reading, but each row (as identified by its primary key) is updated at only one site. They only occur when data is being updated at more than one site.


Using conflict resolution triggers
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

 Using conflict resolution triggers

This section describes how to use RESOLVE UPDATE, or conflict resolution triggers.

UPDATE statements with a VERIFY clause

Conflict resolution triggers are fired by the failure of values in the VERIFY clause of an UPDATE statement to match the values in the database before the update. An UPDATE statement with a VERIFY clause takes the following form:

UPDATE table-list

SET column-name = expression, ...

[ FROM table-list ]

[ VERIFY (column-name, ...)

VALUES ( expression, ...) ]

[ WHERE search-condition ]

The VERIFY clause compares the values of specified columns to a set of expected values, which are the values that were present in the publisher database when the UPDATE statement was applied there.

The verify clause is useful only for single-row updates. However, multi-row update statements entered at a database are replicated as a set of single-row updates by the Message Agent, so this imposes no constraints on client applications.

Conflict resolution trigger syntax

The syntax for a RESOLVE UPDATE trigger is as follows:

CREATE TRIGGER trigger-name

RESOLVE UPDATE

OF column-name ON table-name

[ REFERENCING [ OLD AS old_val ]

[ NEW AS new_val ]

[ REMOTE AS remote_val ] ]

FOR EACH ROW

BEGIN

...

END

RESOLVE UPDATE triggers fire before each row is updated. The REFERENCING clause allows access to the values in the row of the table to be updated (OLD), to the values the row is to be updated to (NEW) and to the rows that should be present according to the VERIFY clause (REMOTE). Only columns present in the VERIFY clause can be referenced in the REMOTE AS clause; other columns produce a "column not found" error.

Using the VERIFY_ALL_
COLUMNS option

The database option VERIFY_ALL_COLUMNS is OFF by default. If it is set to ON, all columns are verified on replicated updates, and a RESOLVE UPDATE trigger is fired whenever any column is different. If it is set to OFF, only those columns that are updated are checked.

Setting this option to ON makes messages bigger, because more information is sent for each UPDATE.

If this option is set at the consolidated database before remote databases are extracted, it will be set at the remote databases also.

You can set the VERIFY_ALL_COLUMNS option either for the PUBLIC group or just for the user contained in the Message Agent connection string.

Using the CURRENT REMOTE USER special constant

The CURRENT REMOTE USER special constant holds the user ID of the remote user sending the message. This can be used in RESOLVE UPDATE triggers that place reports of conflicts into a table, to identify the user producing a conflict.


Conflict resolution examples
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

 Conflict resolution examples

This section describes some ways of using RESOLVE UPDATE triggers to handle conflicts.

 Resolving date conflicts

 Resolving inventory conflicts

 Reporting conflicts


Resolving date conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

          Conflict resolution examples

 Resolving date conflicts

Suppose a table in a contact management system has a column holding the most recent contact with each customer.

One representative talks with a customer on a Friday, but does not upload his changes to the consolidated database until the next Monday. Meanwhile, a second representative meets the customer on the Saturday, and updates the changes that evening.

There is no conflict when the Saturday UPDATE is replicated to the consolidated database, but when the Monday UPDATE arrives it finds the row already changed.

By default, the Monday UPDATE would proceed, leaving the column with the incorrect information that the most recent contact occurred on Friday.

Update conflicts on this column should be resolved by inserting the most recent date in the row.

Implementing the solution

The following RESOLVE UPDATE trigger chooses the most recent of the two new values and enters it in the database.

CREATE TRIGGER contact_date RESOLVE UPDATE

ON contact

REFERENCING OLD AS old_name

NEW AS new_name

FOR EACH ROW

BEGIN

IF new_name.contact_date <

old_name.contact_date THEN

SET new_name.contact_date

= old_name.contact_date

END IF

END

If the value being updated is later than the value that would replace it, the new value is reset to leave the entry unchanged.


Resolving inventory conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

          Conflict resolution examples

 Resolving inventory conflicts

Consider a warehouse system for a manufacturer of sporting goods. There is a table of product information, with a quantity column holding the number of each product left in stock. An update to this column will typically deplete the quantity in stock or, if a new shipment is brought in, add to it.

A sales representative at a remote database enters an order, depleting the stock of small tank top tee shirts by five, from 28 to 23, and enters this in on her database. Meanwhile, before this update is replicated to the consolidated database, a new shipment of tee shirts comes in, and the warehouse enters the shipment, adding 40 to the quantity column to make it 68.

The warehouse entry gets added to the database: the quantity column now shows there are 68 small tank-top tee shirts in stock. When the update from the sales representative arrives, it causes a conflict-Adaptive Server Anywhere detects that the update is from 28 to 23, but that the current value of the column is 68.

By default, the most recent UPDATE succeeds, and the inventory level is set to the incorrect value of 23.

In this case the conflict should be resolved by summing the changes to the inventory column to produce the final result, so that a final value of 63 is placed into the database.

Implementing the solution

A suitable RESOLVE UPDATE trigger for this situation would add the increments from the two updates. For example:

CREATE TRIGGER resolve_quantity

RESOLVE UPDATE OF quantity

ON "DBA".product

REFERENCING OLD AS old_name

NEW AS new_name

REMOTE AS remote_name

FOR EACH ROW

BEGIN

SET new_name.quantity =	new_name.quantity

+ old_name.quantity

- remote_name.quantity

END

This trigger adds the difference between the old value in the consolidated database (68) and the old value in the remote database when the original UPDATE was executed (28) to the new value being sent, before the UPDATE is implemented. Thus, new_val.quantity becomes 63 (= 23 + 68 - 28), and this value is entered into the quantity column.

Consistency is maintained at the remote database as follows:

1	The original remote UPDATE changed the value from 28 to 23.

2	The warehouse's entry is replicated to the remote database, but fails as the old value is not what was expected.

3	The changes made by the RESOLVE UPDATE trigger are replicated to the remote database.


Reporting conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

          Conflict resolution examples

 Reporting conflicts

In some cases, you may not want to alter the default way in which SQL Remote resolves conflicts; you may just want to report the conflicts by storing them in a table. In this way, you can look at the conflict table to see what, if any, conflicts have occurred, and if necessary take action to resolve the conflicts.


Designing to avoid referential integrity errors
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

 Designing to avoid referential integrity errors

The tables in a relational database are related through foreign key references. The referential integrity constraints applied as a consequence of these references ensure that the database remains consistent. If you wish to replicate only a part of a database, there are potential problems with the referential integrity of the replicated database.

By paying attention to referential integrity issues while designing publications you can avoid these problems. This section describes some of the more common integrity problems and suggests ways to avoid them.

Unreplicated referenced table errors

The sales publication described in Publishing a set of tables includes the sales_order table:

CREATE PUBLICATION pub_sales (

TABLE customer,

TABLE sales_order,

TABLE sales_order_items,

TABLE product

)

The sales_order table has a foreign key to the employee table. The id of the sales rep is a foreign key in the sales_order table referencing the primary key of the employee table. However, the employee table is not included in the publication.

If the publication is created in this manner, new sales orders would fail to replicate unless the remote database has the foreign key reference removed from the sales_order table.

If you use the extraction utility to create the remote databases, the foreign key reference is automatically excluded from the remote database, and this problem is avoided. However, there is no constraint in the database to prevent an invalid value from being inserted into the sales_rep_id column of the sales_order table, and if this happens the INSERT will fail at the consolidated database. To avoid this problem, you can include the employee table (or at least its primary key) in the publication.


Designing triggers to avoid errors
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Managing conflicts

 Designing triggers to avoid errors

Actions performed by triggers are not replicated: triggers that exist at one database in a SQL Remote setup are assumed by the replication procedure to exist at other databases in the setup. When an action that fires a trigger at the consolidated database is replicated at the replicate site, the trigger is automatically fired. By default, the database extraction utility extracts the trigger definitions, so that they are in place at the remote database also.

If a publication includes only a subset of a database, a trigger at the consolidated database may refer to tables or rows that are present at the consolidated database, but not at the remote databases. You can design your triggers to avoid such errors by making actions of the trigger conditional using an IF statement. The following list suggests some ways in which triggers can be designed to work on consolidated and remote databases.

•	Have actions of the trigger be conditional on the value of CURRENT PUBLISHER. In this case, the trigger would not execute certain actions at the remote database.

•	Have actions of the trigger be conditional on the object_id function not returning NULL. The object_id function takes a table or other object as argument, and returns the ID number of that object or NULL if the object does not exist.

•	Have actions of the trigger be conditional on a SELECT statement which determines if rows exist.

The RESOLVE UPDATE trigger is a special trigger type for the resolution of UPDATE conflicts, and is discussed in the section Conflict resolution examples. The actions of RESOLVE UPDATE triggers are replicated to remote databases, including the database that caused the conflict.


Ensuring unique primary keys
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Ensuring unique primary keys

Primary-key values must be unique. When all users are connected to the same database, there is no problem keeping unique values. If a user tries to re-use a value, the INSERT statement fails.

The situation is different in a replication system because users are connected to many databases. A potential problem arises when two users, connected to different databases, insert a row using the same primary-key value. Each of their statements succeeds because the value is unique in each database.

However, problems arise in a replication system when two users, connected to separate databases, INSERT a row using the same primary-key value. The second INSERT to reach a given database in the replication system fails. As SQL Remote is a replication system for occasionally connected users, there can be no locking mechanism across all databases in the installation. It is necessary to design your SQL Remote installation so that primary-key duplication errors do not occur.

For primary-key errors to be designed out of SQL Remote installations, the primary keys of tables that may be modified at more than one site must be guaranteed unique. There are several ways of achieving this goal. This chapter describes two general, economical, and reliable methods.

1	Using the default global autoincrement feature of Adaptive Server Anywhere.

2	Using the primary-key pools to maintain a list of unused, unique primary-key values at each site.

You can use these techniques either separately or together to avoid duplicate values.

 Using the default global autoincrement feature

 Using primary-key pools

 The primary-key pool table

 Replicating the primary-key pool

 Filling and replenishing the key pool

 Adding new customers

 Primary-key pool summary


Using the default global autoincrement feature
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

 Using the default global autoincrement feature

In Adaptive Server Anywhere, you can set the default column value to be GLOBAL AUTOINCREMENT. You can use this default for any column in which you want to maintain unique values, but it is particularly useful for primary keys.

When you specify this default, the domain of values for that column is partitioned. The size of each partition can be specified in parentheses immediately following the AUTOINCREMENT key word. This value may be any positive integer, although the partition size is generally chosen so that the supply of numbers within any one partition will rarely, if ever, be exhausted. If the column is of type BIGINT or UNSIGNED BIGINT, the default partition size is 2**32 = 4294967296; for columns of other types the default partition size is 2**16 = 65536.

  For more information on GLOBAL AUTOINCREMENT, see CREATE TABLE statement.

Value depends on Global_database_id

To make use of this default, the value of the public option Global_database_id in each database must be set to a unique, positive integer. This value uniquely identifies the database and indicates from which partition default values are to be assigned. The range of allowed values is n p + 1 to (n + 1) p, where n is the value of the public option Global_database_id and p is the partition size. For example, if the partition size is 1000 and Global_database_id is set to 3, then the range is from 3001 to 4000.

If the previous value is less than (n + 1) p, the next default value will be one greater than the previous largest value in column. If the column contains no values, the first default value is n p + 1.

If the public option Global_database_id is set to zero, a null value is inserted into the column. Should null values not be permitted, the attempt to insert the row causes an error. This situation arises, for example, if the column is contained in the table's primary key. The public option Global_database_id is set to zero by default.

Null default values are also generated when the supply of values within the partition has been exhausted. In this case, a new value of Global_database_id should be assigned to the database to allow default values to be chosen from another partition. Attempting to insert the null value causes an error if the column does not permit nulls. To detect that the supply of unused values is low and handle this condition, create an event of type GlobalAutoincrement.

Should the values in a particular partition become exhausted, you can assign a new database id to that database. You can assign new database id numbers in any convenient manner. However, one possible technique is to maintain a pool of unused database id values. This pool is maintained in the same manner as a pool of primary keys.

You can set an event handler to automatically notify the database administrator (or carry out some other action) when the partition is nearly exhausted. For more information, see Defining trigger conditions for events.

  For more information, see GLOBAL_DATABASE_ID option.

  For further information on pools, see Using primary-key pools.

 Setting the Global_database_id value


Setting the Global_database_id value
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

          Using the default global autoincrement feature

 Setting the Global_database_id value

Each database in the installation must have a different value of GLOBAL_DATABASE_ID to ensure unique primary key values, and these values must be spaced widely enough apart that the pool available to each database is large enough for your application.

If you use the extraction utility to create your remote databases, you can write a stored procedure to automate the task. If you create a stored procedure named sp_hook_dbxtract_begin, it is called automatically by the extraction utility. Before the procedure is called, the extraction utility creates a temporary table named #hook_dict, with the following contents:

name	value
extracted_db_global_id	user ID being extracted
If you write your sp_hook_dbxtract_begin procedure to modify the value column of the row, that value is used as the GLOBAL_DATABASE_ID option of the extracted database, and marks the beginning of the range of primary key values for GLOBAL DEFAULT AUTOINCREMENT values.

Example

Consider extracting a database for remote user user2 with a user_id of 101. If you do not define an sp_hook_dbxtract_begin procedure, the extracted database will have Global_database_id set to 101.

If you define a sp_hook_dbxtract_begin procedure, but it does not modify any rows in the #hook_dict then the option will still be set to 101.

If you set up the database as follows:

set option "PUBLIC"."Global_database_id" = '1';

create table extract_id ( next_id integer not null) ;

insert into extract_id values( 1 );

create procedure sp_hook_dbxtract_begin

as

    declare @next_id  integer

    update extract_id set next_id = next_id + 1000

    select @next_id = (next_id )

    from extract_id

    commit

    update #hook_dict

    set value = @next_id

    where name = 'extracted_db_global_id'

Then each extracted or re-extracted database will get a different Global_database_id. The first starts at 1001, the next at 2001, and so on.

To assist in debugging procedure hooks, dbxtract outputs the following when it is set to operate in verbose mode:

•	the procedure hooks found

•	the contents of #hook_dict before the procedure hook is called

•	the contents of #hook_dict after the procedure hook is called.


Using primary-key pools
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

 Using primary-key pools

The primary-key pool is a table that holds a set of primary-key values for each database in the SQL Remote installation. Each remote user receives their own set of primary-key values. When a remote user inserts a new row into a table, they use a stored procedure to select a valid primary key from the pool. The pool is maintained by periodically running a procedure at the consolidated database that replenishes the supply.

The method is described using a simple example database consisting of sales representatives and their customers. The tables are much simpler than you would use in a real database; this allows us to focus just on those issues important for replication.


The primary-key pool table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

 The primary-key pool table

The pool of primary keys is held in a separate table. The following CREATE TABLE statement creates a primary-key pool table:

CREATE TABLE KeyPool (

table_name VARCHAR(40) NOT NULL,

value INTEGER NOT NULL,

location CHAR(12) NOT NULL,

PRIMARY KEY (table_name, value),

);

The columns of this table have the following meanings:

Column	Description
table_name	Holds the names of tables for which primary-key pools must be maintained. In our simple example, if new sales representatives were to be added only at the consolidated database, only the Customer table needs a primary-key pool and this column is redundant. It is included to show a general solution.
value	Holds a list of primary-key values. Each value is unique for each table listed in table_name.
location	An identifier for the recipient. In some setups, this could be the same as the rep_key value of the SalesRep table. In other setups, there will be users other than sales representatives and the two identifiers should be distinct.
For performance reasons, you may wish to create an index on the table:

CREATE INDEX KeyPoolLocation

ON KeyPool (table_name, location, value);


Replicating the primary-key pool
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

 Replicating the primary-key pool

You can either incorporate the key pool into an existing publication, or share it as a separate publication. In this example, we create a separate publication for the primary-key pool.

♦ To replicate the primary-key pool (SQL):

1	Create a publication for the primary-key pool data.

CREATE PUBLICATION KeyPoolData (

TABLE KeyPool SUBSCRIBE BY location

);

2	Create subscriptions for each remote database to the KeyPoolData publication.

CREATE SUBSCRIPTION

TO KeyPoolData( 'user1' )

FOR user1;

CREATE SUBSCRIPTION

TO KeyPoolData( 'user2' )

FOR user2;

...

The subscription argument is the location identifier.

In some circumstances it makes sense to add the KeyPool table to an existing publication and use the same argument to subscribe to each publication. Here we keep the location and rep_key values distinct to provide a more general solution.

  See also

•	CREATE PUBLICATION statement

•	CREATE SUBSCRIPTION statement


Filling and replenishing the key pool
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

 Filling and replenishing the key pool

Every time a user adds a new customer, their pool of available primary keys is depleted by one. The primary-key pool table needs to be periodically replenished at the consolidated database using a procedure such as the following:

CREATE PROCEDURE ReplenishPool()

BEGIN

FOR EachTable AS TableCursor

CURSOR FOR

SELECT table_name

AS CurrTable, max(value) as MaxValue

FROM KeyPool

GROUP BY table_name

DO

FOR EachRep AS RepCursor

CURSOR FOR

SELECT location

AS CurrRep, count(*) as NumValues

FROM KeyPool

WHERE table_name = CurrTable

GROUP BY location

DO

// make sure there are 100 values.

// Fit the top-up value to your

// requirements

WHILE NumValues < 100 LOOP

SET MaxValue = MaxValue + 1;

SET NumValues = NumValues + 1;

INSERT INTO KeyPool

(table_name, location, value)

VALUES

(CurrTable, CurrRep, MaxValue);

END LOOP;

END FOR;

END FOR;

END;

This procedure fills the pool for each user up to 100 values. The value you need depends on how often users are inserting rows into the tables in the database.

The ReplenishPool procedure must be run periodically at the consolidated database to refill the pool of primary-key values in the KeyPool table.

The ReplenishPool procedure requires at least one primary key value to exist for each subscriber, so that it can find the maximum value and add one to generate the next set. To initially fill the pool you can insert a single value for each user, and then call ReplenishPool to fill up the rest. The following example illustrates this for three remote users and a single consolidated user named Office:

INSERT INTO KeyPool VALUES( 'Customer', 40, 'user1' );

INSERT INTO KeyPool VALUES( 'Customer', 41, 'user2' );

INSERT INTO KeyPool VALUES( 'Customer', 42, 'user3' );

INSERT INTO KeyPool VALUES( 'Customer', 43, 'Office');

CALL ReplenishPool();

Cannot use a trigger to replenish the key pool
You cannot use a trigger to replenish the key pool, as trigger actions are not replicated.


Adding new customers
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

 Adding new customers

When a sales representative wants to add a new customer to the Customer table, the primary key value to be inserted is obtained using a stored procedure. This example shows a stored procedure to supply the primary key value, and also illustrates a stored procedure to carry out the INSERT.

The procedures takes advantage of the fact that the Sales Rep identifier is the CURRENT PUBLISHER of the remote database.

•	NewKey procedure    The NewKey procedure supplies an integer value from the key pool and deletes the value from the pool.

CREATE PROCEDURE NewKey(

IN @table_name VARCHAR(40),

OUT @value INTEGER )

BEGIN

DECLARE NumValues INTEGER;

SELECT count(*), min(value)

INTO NumValues, @value

FROM KeyPool

WHERE table_name = @table_name

AND location = CURRENT PUBLISHER;

IF NumValues > 1 THEN

DELETE FROM KeyPool

WHERE table_name = @table_name

AND value = @value;

ELSE

// Never take the last value, because

// ReplenishPool will not work.

// The key pool should be kept large enough

// that this never happens.

SET @value = NULL;

END IF;

END;

•	NewCustomer procedure    The NewCustomer procedure inserts a new customer into the table, using the value obtained by NewKey to construct the primary key.

CREATE PROCEDURE NewCustomer(

IN customer_name CHAR( 40 ) )

BEGIN

DECLARE new_cust_key INTEGER ;

CALL NewKey( 'Customer', new_cust_key );

INSERT

INTO Customer (

cust_key,

name,

location

)

VALUES (

'Customer ' ||

CONVERT (CHAR(3), new_cust_key),

customer_name,

CURRENT PUBLISHER

);

);

END

You may want to enhance this procedure by testing the new_cust_key value obtained from NewKey to check that it is not NULL, and preventing the insert if it is NULL.


Primary-key pool summary
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

        Ensuring unique primary keys

 Primary-key pool summary

The primary-key pool technique requires the following components:

•	Key pool table    A table to hold valid primary-key values for each database in the installation.

•	Replenishment procedure    A stored procedure keeps the key pool table filled.

•	Sharing of key pools    Each database in the installation must subscribe to its own set of valid values from the key pool table.

•	Data entry procedures    New rows are entered using a stored procedure that picks the next valid primary key value from the pool and delete that value from the key pool.


Creating subscriptions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 15.  SQL Remote Design for Adaptive Server Anywhere

 Creating subscriptions

To subscribe to a publication, each subscriber must be granted REMOTE permissions and a subscription must also be created for that user. The details of the subscription are different depending on whether or not the publication uses a subscription expression.

Working with subscriptions in Sybase Central

♦ To create and manage subscriptions in Sybase Central

1	Open the Publications folder (located within the SQL Remote folder).

2	Right-click a publication and choose Properties from the popup menu.

3	Click the Subscriptions tab and configure the appropriate settings:

•	To subscribe a remote user to the publication, click Subscribe For and enter the desired values in the resulting dialog.

•	To unsubscribe a remote user, select the user in the list and click Unsubscribe.

•	To manually start, stop, or synchronize subscriptions, click either Start Now, Stop Now, or Synchronize Now. The subscriptions are affected as soon as you click the button. Subsequently clicking Cancel on the property sheet does not cancel your start/stop/synchronize action.

Tips
You can also manage subscriptions on the SQL Remote tab of a remote user's property sheet. Remote users appear in two locations: in the Users & Groups folder and in the Remote Users folder (located within the SQL Remote folder).

For a description of all property sheets in Sybase Central, see Property Sheet Descriptions.

Subscriptions with no subscription expression

To subscribe a user to a publication, if that publication has no subscription expression, you need the following information:

•	User ID    The user who is being subscribed to the publication. This user must have been granted remote permissions.

•	Publication name    The name of the publication to which the user is being subscribed.

The following statement creates a subscription for a user ID SamS to the pub_orders_samuel_singer publication, which was created using a WHERE clause:

CREATE SUBSCRIPTION

TO pub_orders_samuel_singer

FOR SamS

Subscriptions with a subscription expression

To subscribe a user to a publication, if that publication does have a subscription expression, you need the following information:

•	User ID    The user who is being subscribed to the publication. This user must have been granted remote permissions.

•	Publication name    The name of the publication to which the user is being subscribed.

•	Subscription value    The value that is to be tested against the subscription expression of the publication. For example, if a publication has the name of a column containing an employee ID as a subscription expression, the value of the employee ID of the subscribing user must be provided in the subscription. The subscription value is always a string.

The following statement creates a subscription for Samuel Singer (user ID SamS, employee ID 856) to the pub_orders publication, defined with a subscription expression sales_rep, requesting the rows for Samuel Singer's own sales:

CREATE SUBSCRIPTION

TO pub_orders ( '856' )

FOR SamS

Starting a subscription

In order to receive and apply updates properly, each subscriber needs to have an initial copy of the data. The synchronization process is discussed in Synchronizing databases.

  See also

•	CREATE SUBSCRIPTION statement

•	Property Sheet Descriptions


CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

About this chapter

This chapter describes how to design a SQL Remote installation when the consolidated database is at an Adaptive Server Enterprise server.

Similar material for Adaptive Server Anywhere
Many of the principles of publication design are the same for Adaptive Server Anywhere and Adaptive Server Enterprise, but there are differences in commands and capabilities. There is a large overlap between this chapter and the corresponding chapter for Adaptive Server Anywhere users, SQL Remote Design for Adaptive Server Anywhere.

 Design overview

 Creating publications

 Publication design for Adaptive Server Enterprise

 Partitioning tables that do not contain the subscription column

 Sharing rows among several subscriptions

 Managing conflicts

 Ensuring unique primary keys

 Creating subscriptions


Design overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Design overview

Designing a SQL Remote installation includes the following tasks:

•	Designing publications    The publications determine what information is shared among which databases.

•	Designing subscriptions    The subscriptions determine what information each user receives.

•	Implementing the design    Creating publications and subscriptions for all users in the system.

All administration is at the consolidated database

Like all SQL Remote administrative tasks, design is carried out by a database administrator or system administrator at the consolidated database. The Sybase System Administrator should perform all SQL Remote configuration tasks.

  For more information about the Adaptive Server Enterprise environment, see your Adaptive Server Enterprise documentation.


Creating publications
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Creating publications

In this section

This section describes how to create simple publications consisting of whole tables, or of column-wise subsets of tables.

  Simple publications are also discussed in the chapter A Tutorial for Adaptive Server Enterprise Users.

 Creating publications for Adaptive Server Enterprise using Sybase Central

 Creating whole-table articles

 Creating articles containing some of the columns in a table

 Creating articles containing some of the rows in a table

 Notes on articles


Creating publications for Adaptive Server Enterprise using Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Creating publications

 Creating publications for Adaptive Server Enterprise using Sybase Central

In Sybase Central, you can add a publication to a database from within the SQL Remote folder. The SQL Remote folder is displayed inside a database container.

♦ To create a publication from Sybase Central:

1	Click the Publications folder, which is inside the SQL Remote folder.

2	Double-click Add Publication. The Publication Wizard is displayed.

3	Follow the instructions in the Wizard.

  For more information, see the Sybase Central online Help.

With Sybase Central, you do not need to know the SQL syntax in order to create publications. The remainder of this section discusses different kinds of publication that can be created. It describes the SQL syntax needed for these publications. However, each of the publications can also be created from Sybase Central.


Creating whole-table articles
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Creating publications

 Creating whole-table articles

The simplest type of article is one that includes all the rows and columns of a database table.

♦ To create an article that includes all the rows and columns of a table:

1	Mark the table for replication. You do this by executing the sp_add_remote_table procedure:

sp_add_remote_table table-name

2	Add the table to the publication. You do this by executing the sp_add_article procedure:

sp_add_article publication-name, table-name

Example

•	The following commands add the table SalesRep to the SalesRepData publication:

sp_add_remote_table 'SalesRep'

sp_add_article 'SalesRepData', 'SalesRep'

go


Creating articles containing some of the columns in a table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Creating publications

 Creating articles containing some of the columns in a table

To create an article that includes only some of the columns from a table, you need to list the columns that you wish to include, using sp_add_article_col. If no columns are listed, the article includes all columns of the table.

♦ To create an article that includes some of the columns and all the rows of a table:

1	Mark the table for replication. You do this by executing the sp_add_remote_table procedure:

sp_add_remote_table table-name

go

2	Add the table to the publication. You do this by executing the sp_add_article procedure:

sp_add_article publication-name, table-name

go

The sp_add_article procedure adds a table to a publication. By default, all columns of the table are added to the publication. If you wish to add only some of the columns, you must use the sp_add_article_col procedure to specify which columns you wish to include.

3	Add individual columns to the publication. You do this by executing the sp_add_article_col procedure for each column:

sp_add_article_col publication-name,

table-name,

column-name

go

Example

•	The following commands add only the rep_key column of the table SalesRep to the SalesRepData publication:

sp_add_remote_table 'SalesRep'

sp_add_article 'SalesRepData',

'SalesRep'

sp_add_article_col 'SalesRepData',

'SalesRep',

'rep_key'

go


Creating articles containing some of the rows in a table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Creating publications

 Creating articles containing some of the rows in a table

There are two ways of including only some of the rows from a table in an article:

•	WHERE clause    You can use a WHERE clause to include a subset of rows in an article. All subscribers to the publication containing this article receive the rows that satisfy the WHERE clause.

•	subscription column    You can use a subscription column to include a different set of rows in different subscriptions to publications containing the article.

Allowed clauses

In SQL Remote for Adaptive Server Enterprise, the following limitations apply to each of these cases:

•	WHERE clause limitations    The only form of WHERE clause supported is the following:

WHERE column-name IS NOT NULL.

•	Subscription column    SQL Remote for Adaptive Server Anywhere supports expressions other than column names. For Adaptive Server Enterprise, the subscription expression must be a column name.

When to use WHERE and SUBSCRIBE BY

You should use a subscription expression when different subscribers to a publication are to receive different rows from a table. The subscription expression is the most powerful method of partitioning tables.

 Creating an article using a WHERE clause

 Creating an article using a subscription column


Creating an article using a WHERE clause
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Creating publications

          Creating articles containing some of the rows in a table

 Creating an article using a WHERE clause

The WHERE clause is used to exclude a set of rows from all subscriptions to a publication.

♦ To create an article using a WHERE clause:

1	If you have not already done so, mark the table for replication. You do this by executing the sp_add_remote_table procedure:

sp_add_remote_table table_name

2	Add the table to the publication. You do this by executing the sp_add_article procedure: Specify the column name corresponding to the WHERE column IS NOT NULL clause in the third argument to the procedure:

sp_add_article publication_name,

table_name,

column_name

Do not specify IS NOT NULL; it is implicit. Specify the column name only.

3	If you wish to include only a subset of the columns in the table, specify the columns using the sp_add_article_col procedure. You must include the column specified in your WHERE clause in the article.

Example

•	The following set of statements create a publication containing a single article, which includes only those rows of test_table for which column col_1 is not null:

sp_create_publication test_pub

sp_add_remote_table test_table

sp_add_article test_pub, test_table, col_1

go


Creating an article using a subscription column
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Creating publications

          Creating articles containing some of the rows in a table

 Creating an article using a subscription column

The subscription column is used when rows are to be shared among many remote databases.

♦ To create an article using a subscription column:

1	If you have not already done so, mark the table for replication. You do this by executing the sp_add_remote_table procedure:

sp_add_remote_table table_name

2	Add the table to the publication. You do this by executing the sp_add_article procedure: Specify the column name you wish to use as a subscription expression in the fourth argument to the procedure:

sp_add_article publication_name, table_name, NULL, column_name

You must include the NULL entry to avoid adding a WHERE clause.

3	If you wish to include only a subset of the columns in the table, specify the columns using the sp_add_article_col procedure. You must include the column specified in your subscription expression in the article.

Example

•	The following set of statements create a publication containing a single article, which supports subscriptions based on the value of column col_1:

sp_create_publication test_pub

sp_add_remote_table test_table

sp_add_article test_pub,

test_table,

NULL,

col_1

go


Notes on articles
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Creating publications

 Notes on articles

•	You can combine a WHERE clause and a subscription expression in an article.

•	All columns in the primary key must be included in any article.

•	You must not include a subset of columns in an article unless either:

•	The remaining columns have default values or allow NULLs.

•	No inserts are carried out at remote databases. Updates would not cause problems as long as they do not change primary key values.

If you include a subset of columns in an article in situations other than these, INSERT statements at the consolidated database will fail.


Publication design for Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Publication design for Adaptive Server Enterprise

Once you understand how to create simple publications, you must think about proper design of publications. This section describes the issues involved in designing publications, and how to take steps towards sound design.

 Design issues overview

 Conditions for valid articles


Design issues overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Publication design for Adaptive Server Enterprise

 Design issues overview

Each subscription must be a complete relational database

A remote database shares with the consolidated database the information in their subscriptions. The subscription is both a subset of the relational database held at the consolidated site, and also a complete relational database at the remote site. The information in the subscription is therefore subject to the same rules as any other relational database:

•	Foreign key relationships must be valid    For every entry in a foreign key, a corresponding primary key entry must exist in the database.

The database extraction utility ensures that the CREATE TABLE statements for remote databases do not have foreign keys defined to tables that do not exist remotely.

•	Primary key uniqueness must be maintained    There is no way of checking what new rows have been entered at other sites, but not yet replicated. The design must prevent users at different sites adding rows with identical primary key values, as this would lead to conflicts when the rows are replicated to the consolidated database.

Transaction integrity must be maintained in the absence of locking

The data in the dispersed database (which consists of the consolidated database and all remote databases) must maintain its integrity in the face of updates at all sites, even though there is no system-wide locking mechanism for any particular row.

•	Locking conflicts must be prevented or resolved    In a SQL Remote installation, there is no method for locking rows across all databases to prevent different users from altering the rows at the same time. Such conflicts must be prevented by designing them out of the system or must be resolved in an appropriate manner at the consolidated database.

These key features of relational databases must be incorporated into the design of your publications and subscriptions. This section describes principles and techniques for sound design.


Conditions for valid articles
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Publication design for Adaptive Server Enterprise

 Conditions for valid articles

All columns in the primary key must be included in the article.

Supporting INSERTS at remote databases

For INSERT statements at a remote database to replicate correctly to the consolidated database, you can exclude from an article only columns that can be left out of a valid INSERT statement. These are:

•	Columns that allow NULL.

•	Columns that have defaults.

If you exclude any column that does not satisfy one of these requirements, INSERT statements carried out at a remote database will fail when replicated to the consolidated database.

Conditions on rows

There are two ways of including only some of the rows in a publication:

•	WHERE clause    You can use a WHERE clause to include a subset of rows in an article. All subscribers to the publication containing this article receive the rows that satisfy the WHERE clause.

In SQL Remote for Adaptive Server Enterprise, the only supported WHERE clause is

WHERE column-name IS NOT NULL

•	Subscription columns    You can use a subscription column to include a different set of rows in different subscriptions to publications containing the article.

  For more information on restrictions on rows, see Creating articles containing some of the rows in a table.


Partitioning tables that do not contain the subscription column
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Partitioning tables that do not contain the subscription column

In many cases, the rows of a table need to be partitioned even when the subscription column does not exist in the table. This section describes how to handle this case, using an example.

 The Contact example

 Territory realignment in the Contact example

 Partitioning the Customer table in the Contact example

 Adding a subscription-list column to the Contact table

 Maintaining the subscription-list column

 Tuning extraction performance


The Contact example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Partitioning tables that do not contain the subscription column

 The Contact example

The Contact database illustrates why and how to partition tables that do not contain the subscription column.

Example

Here is a simple database that illustrates the problem. We call this database the Contact database, because it contains a Contact table in addition to the two tables described earlier in this chapter.

Each sales representative sells to several customers. At some customers there is a single contact, while other customers have several contacts.

The tables in the database

The three tables are described in more detail as follows:

Table	Description
SalesRep	All sales representatives that work for the company. The SalesRep table has the following columns: • rep_key   An identifier for each sales representative. This is the primary key. • name   The name of each sales representative. The SQL statement creating this table is as follows: CREATE TABLE SalesRep ( rep_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, PRIMARY KEY (rep_key) ) go
Customer	All customers that do business with the company. The Customer table includes the following columns: • cust_key   An identifier for each customer. This is the primary key. • name   The name of each customer. • rep_key   An identifier for the sales representative in a sales relationship. This is a foreign key to the SalesRep table. The SQL statement creating this table is as follows: CREATE TABLE Customer ( cust_key CHAR(12) NOT NULL, name CHAR(40) NOT NULL, rep_key CHAR(12) NOT NULL, FOREIGN KEY ( rep_key ) REFERENCES SalesRep, PRIMARY KEY (cust_key) ) go
Contact	All individual contacts that do business with the company. Each contact belongs to a single customer. The Contact table includes the following columns: • contact_key   An identifier for each contact. This is the primary key. • name   The name of each contact. • cust_key   An identifier for the customer to which the contact belongs. This is a foreign key to the Customer table. The SQL statement creating this table is: CREATE TABLE Contact ( contact_key  CHAR(12) NOT NULL, name  CHAR(40) NOT NULL, cust_key  CHAR(12) NOT NULL, FOREIGN KEY (cust_key) REFERENCES Customer, PRIMARY KEY  (contact_key) ) go
Replication goals

The goals of the design are to provide each sales representative with the following information:

•	The complete SalesRep table.

•	Those customers assigned to them, from the Customer table.

•	Those contacts belonging to the relevant customers, from the Contact table.

•	Maintenance of proper information when Sales Representative territories are realigned.


Territory realignment in the Contact example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Partitioning tables that do not contain the subscription column

 Territory realignment in the Contact example

In territory realignment, rows are reassigned among subscribers. In the current example, territory realignment involves reassigning customers among the sales representatives. It is carried out by updating the rep_key column of the Customer table.

The UPDATE is replicated as an INSERT or a DELETE to the old and new sales representatives, respectively, so that the customer row is properly transferred to the new sales representative.

No log entries for the Contact table when territories realigned

When a customer is reassigned, the Contact table is unaffected. There are no changes to the Contact table, and consequently no entries in the transaction log pertaining to the Contact table. In the absence of this information, SQL Remote cannot reassign the rows of the Contact table along with the Customer. This failure would cause referential integrity problems: the Contact table at the remote database of the old sales representative contains a cust_key value for which there is no longer a Customer.

In this section, we describe how to reassign the rows of the Contact table.


Partitioning the Customer table in the Contact example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Partitioning tables that do not contain the subscription column

 Partitioning the Customer table in the Contact example

The Customer table can be partitioned using the rep_key value as a subscription column. A publication that includes the SalesRep and Customer tables would be as follows:

exec sp_add_remote_table 'SalesRep'

exec sp_add_remote_table 'Customer'

go

exec sp_create_publication 'SalesRepData'

go

exec sp_add_article 'SalesRepData', 'SalesRep'

exec sp_add_article SalesRepData,

Customer, NULL,

'rep_key'

go


Adding a subscription-list column to the Contact table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Partitioning tables that do not contain the subscription column

 Adding a subscription-list column to the Contact table

The Contact table must also be partitioned among the sales representatives, but contains no reference to the sales representative rep_key value.

Add a subscription-list column

To solve this problem in Adaptive Server Enterprise, you must add a column to the Contact table containing a comma-separated list of subscription values to the row. ( In the present case, there can only be a single subscription value.) The column can be maintained using triggers, so that applications against the database are unaffected by the presence of the column. We call this column a subscription-list column.

When a row in the Customer table is inserted, updated or deleted, a trigger updates rows in the Contact table. In particular, the trigger updates the subscription-list column. As the Contact table is marked for replication, the before and after image of the row is recorded in the log.

Log entries are values, not subscribers
Although in this case the values entered correspond to subscribers, it is not a list of subscribers that is entered in the log. The server handles only information about publications, and the Message Agent handles all information about subscribers. The values entered in the log are for comparison to the subscription value in each subscription. For example, if rows of a table were divided among sales representatives by state or province, the state or province value would be entered in the transaction log.

A subscription-list column is a column added to a table for the sole purpose of holding a comma-separated list of subscribers. In the present case, there can only be a single subscriber to each row of the Contact table, and so the subscription-list column holds only a single value.

  For a discussion of the case where the subscription-list column can hold many values, see Sharing rows among several subscriptions.

Contact table definition

In the case of the Contact table, the table definition would be changed to the following:

CREATE TABLE Contact (

contact_key CHAR( 12 ) NOT NULL,

name CHAR( 40 ) NOT NULL,

cust_key CHAR( 12 ) NOT NULL,

subscription_list CHAR( 12 ) NULL,

FOREIGN KEY ( cust_key )

REFERENCES Customer ( cust_key ),

PRIMARY KEY ( contact_key )

)

go

The additional column is created allowing NULL, so that existing applications can continue to work against the database without change.

The subscription_list column holds the rep_key value corresponding to the row with primary key value cust_key in the Customer table. A set of triggers handles maintenance of the subscription_list column.

  For an Adaptive Server Anywhere consolidated database, the solution is different. For more information, see Partitioning tables that do not contain the subscription expression.


Maintaining the subscription-list column
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Partitioning tables that do not contain the subscription column

 Maintaining the subscription-list column

In order to keep the subscription_list column up to date, triggers are needed for the following operations:

•	INSERT on the Contact table.

•	UPDATE on the Contact table.

•	UPDATE on the Customer table.

The UPDATE of the Customer table addresses the territory realignment problem, where customers are assigned to different Sales Reps.

An INSERT trigger for the Contact table

The trigger for an INSERT on the Contact table sets the subscription_list value to the corresponding rep_key value from the Customer table:

CREATE TRIGGER set_contact_sub_list

ON Contact

FOR INSERT

AS

BEGIN

UPDATE Contact

SET Contact.subscription_list = (

SELECT rep_key

FROM Customer

WHERE Contact.cust_key = Customer.cust_key )

WHERE Contact.contact_key IN (

SELECT contact_key

FROM inserted

)

END

The trigger updates the subscription_list column for those rows being inserted; these rows being identified by the subquery

SELECT contact_key

FROM inserted

An UPDATE trigger for the Contact table

The trigger for an UPDATE on the Contact table checks to see if the cust_key column is changed, and if it has updates the subscription_list column.

CREATE TRIGGER update_contact_sub_list

ON Contact

FOR UPDATE

AS

IF UPDATE ( cust_key )

BEGIN

UPDATE Contact

SET subscription_list = Customer.rep_key

FROM Contact, Customer

WHERE Contact.cust_key=Customer.cust_key

END

The trigger is written using a join; a subquery could also have been used.

An UPDATE trigger for the Customer table

The following trigger handles UPDATES of customers, transferring them to a new Sales Rep:

CREATE TRIGGER transfer_contact_with_customer

ON Customer

FOR UPDATE

AS

IF UPDATE ( rep_key )

BEGIN

UPDATE Contact

SET Contact.subscription_list = (

SELECT rep_key

FROM Customer

WHERE Contact.cust_key = Customer.cust_key )

WHERE Contact.contact_key IN (

SELECT cust_key

FROM inserted

)

END


Tuning extraction performance
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Partitioning tables that do not contain the subscription column

 Tuning extraction performance

When extracting or synchronizing a user, the subscription-list column can cause performance problems as it necessitates a full table scan.

If you are extracting databases for many users, and performance is a problem for you, you can use a subscription view to improve performance. The view must contain a subquery, which is used for extraction and synchronization only, and is ignored during log scanning. The tables involved still need to have triggers defined to maintain the subscription-list column.

♦ To create a subscription view:

1	Design a query that uses a subquery to select the proper rows for a subscription from a table.

For example, continuing the example from the preceding sections, the following query selects the rows of the Contact table for a user subscribed by rep_key value rep5:

SELECT *

FROM Contact

WHERE 'rep5' = (SELECT rep_key

FROM Customer

WHERE cust_key = Contact.cust_key )

2	Create a view that contains this subquery. For example:

CREATE VIEW Contact_sub_view AS

SELECT *

FROM dbo.Contact

WHERE 'repxx' = ( SELECT rep_key

FROM dbo.Customer

WHERE cust_key = dbo.Contact.cust_key )

In this view definition, it does not matter what value you use on the left hand side of the WHERE clause (repxx in the example above). The replication tools use the subquery for extraction and synchronization only. Rows for which the SUBSCRIBE BY value is equal to the subquery result set are extracted or synchronized.

3	Give the name of the view as a parameter to sp_add_article or sp_modify_article:

exec sp_add_remote_table 'Contact'

go

exec sp_add_article SalesRepData,

'Contact',

NULL,

'subscription_list',

'Contact_sub_view'

The subscription_list column is used for log scanning and the subquery is used for extraction and synchronization.

  For more information, see Tuning extraction performance for shared rows, sp_add_article procedure, and sp_modify_article procedure.


Sharing rows among several subscriptions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Sharing rows among several subscriptions

There are cases where a row may need to be included in several subscriptions. For example, if instead of the many-to-one relationship between customers and sales representatives that we had above, we may have a many-to-many relationship.

 The Policy example

 Maintaining the subscription-list column

 Tuning extraction performance for shared rows

 Using the Subscribe_by_remote option with many-to-many relationships


The Policy example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Sharing rows among several subscriptions

 The Policy example

The Policy database illustrates why and how to partition tables when there is a many-to-many relationship in the database.

Example database

Here is a simple database that illustrates the problem.

The Policy table has a row for each of a set of policies. Each policy is drawn up for a customer by a particular sales representative. There is a many-to-many relationship between customers and sales representatives, and there may be several policies drawn up between a particular rep/customer pair.

Any row in the Customer table may need to be shared with none, one, or several sales representatives.

 Solving the problem

 The publication


Solving the problem
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Sharing rows among several subscriptions

          The Policy example

 Solving the problem

To support this case, you need to write triggers to build a comma-delimited list of values to store in a redundant subscription-list column of the Customer table, and include this column as the subscription column when adding the Customer table to the publication. The row is shared with any subscription for which the subscription value matches any of the values in the subscription-list column.

The database, with the subscription-list column included, is as follows:

Adaptive Server Enterprise VARCHAR columns are limited to 255 characters, and this limits the number of values that can be stored in the comma-delimited list.

Table definitions

The table definitions are as follows:

CREATE TABLE SalesRep (

rep_key CHAR( 12 ) NOT NULL,

name CHAR( 40 ) NOT NULL,

PRIMARY KEY ( rep_key )

)

go

CREATE TABLE Customer (

cust_key CHAR( 12 ) NOT NULL,

name CHAR( 40 ) NOT NULL,

subscription_list VARCHAR( 255 ) NULL,

PRIMARY KEY ( cust_key )

)

go

CREATE TABLE Policy (

policy_key	INTEGER NOT NULL,

cust_key CHAR( 12 ) NOT NULL,

rep_key CHAR( 12 ) NOT NULL,

FOREIGN KEY	( cust_key )

REFERENCES Customer (cust_key ),

FOREIGN KEY (rep_key )

REFERENCES SalesRep ( rep_key ),

PRIMARY KEY	(policy_key)

)

Notes:

•	The subscription_list column in the Customer table allows NULLs so that customers can be added who do not have any sales representatives in the subscription_list column.


The publication
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Sharing rows among several subscriptions

          The Policy example

 The publication

The publication for this database can be created by the following set of statements:

//Mark the tables for replication

exec sp_add_remote_table 'SalesRep'

exec sp_add_remote_table 'Policy'

exec sp_add_remote_table 'Customer'

go

// Create an empty publication

exec sp_create_publication 'SalesRepData'

//Add the Sales Rep table to the publication

exec sp_add_article 'SalesRepData', 'SalesRep'

//Add the Policy table to the publication

exec sp_add_article 'SalesRepData', 'Policy', NULL, 'rep_key'

// Add the Customer table to the publication.

// Subscribe by the subscription_list column

// Exclude the subscription_list column

exec sp_add_article 'SalesRepData', 'Customer', NULL, 'subscription_list'

exec sp_add_article_col 'SalesRepData', 'Customer', 'cust_key'

exec sp_add_article_col 'SalesRepData', 'Customer', 'name'

go

Subscriptions to this publication take the following form:

exec sp_subscription 'create',

'SalesRepData',

'userID',

'rep_key'

go

where userID identifies the subscriber, and rep_key is the subscription column, which is the value of the rep_key column in the SalesRep table.


Maintaining the subscription-list column
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Sharing rows among several subscriptions

 Maintaining the subscription-list column

You need to write a procedure and a set of triggers to maintain the subscription-list column added to the Customer table. This section describes these objects.

Stored procedure

The following procedure is used to build the subscription-list column, and is called from the triggers that maintain the subscription_list column.

CREATE PROCEDURE SubscribeCustomer @cust_key CHAR(12)

AS

BEGIN

--  Rep returns the rep list for customer @cust_key

DECLARE Rep CURSOR FOR

SELECT DISTINCT RTRIM( rep_key )

FROM Policy

WHERE cust_key = @cust_key

DECLARE @rep_key    CHAR(12)

DECLARE @subscription_list   VARCHAR(255)

-- build comma-separated list of rep_key

-- values for this Customer

OPEN Rep

FETCH Rep INTO @rep_key

IF @@sqlstatus = 0 BEGIN

SELECT @subscription_list = @rep_key

WHILE 1=1 BEGIN

FETCH Rep INTO @rep_key

IF @@sqlstatus != 0 BREAK

SELECT @subscription_list =

@subscription_list + ',' + @rep_key

END

END

ELSE BEGIN

SELECT @subscription_list = ''

END

-- update the subscription_list in the

-- Customer table

UPDATE Customer

SET subscription_list = @subscription_list

WHERE cust_key = @cust_key

END

Notes:

•	The procedure takes a Customer key as input argument.

•	Rep is a cursor for a query that lists each of the Sales Representatives with which the customer has a contract.

•	The WHILE loop builds a VARCHAR(255) variable holding the comma-separated list of Sales Representatives.

Triggers

The following trigger updates the subscription_list column of the Customer table when a row is inserted into the Policy table.

CREATE TRIGGER InsPolicy

ON Policy

FOR INSERT

AS

BEGIN

-- Cust returns those customers inserted

DECLARE Cust CURSOR FOR

SELECT DISTINCT cust_key

FROM inserted

DECLARE @cust_key CHAR(12)

OPEN Cust

-- Update the rep list for each Customer

-- with a new rep

WHILE 1=1 BEGIN

FETCH Cust INTO @cust_key

IF @@sqlstatus != 0 BREAK

EXEC SubscribeCustomer @cust_key

END

END

The following trigger updates the subscription_list column of the Customer table when a row is deleted from the Policy table.

CREATE TRIGGER DelPolicy

ON Policy

FOR DELETE

AS

BEGIN

-- Cust returns those customers deleted

DECLARE Cust CURSOR FOR

SELECT DISTINCT cust_key

FROM deleted

DECLARE @cust_key CHAR(12)

OPEN Cust

-- Update the rep list for each Customer

-- losing a rep

WHILE 1=1 BEGIN

FETCH Cust INTO @cust_key

IF @@sqlstatus != 0 BREAK

EXEC SubscribeCustomer @cust_key

END

END

Excluding the subscription-list column from the publication

The subscription-list column should be excluded from the publication, as inclusion of the column leads to excessive updates being replicated.

For example, consider what happens if there are many policies per customer. If a new Sales Representative is assigned to a customer, a trigger fires to update the subscription-list column in the Customer table. If the subscription-list column is part of the publication, then one update for each policy will be replicated to all sales reps that are assigned to this customer.

Triggers at the consolidated database only

The values in the subscription-list column are maintained by triggers. These triggers fire at the consolidated database when the triggering inserts or updates are applied by the Message Agent. The triggers must be excluded from the remote databases, as they maintain a column that does not exist.

You can use the sp_user_extraction_hook procedure to exclude only certain triggers from a remote database on extraction. The procedure is called as the final part of an extraction. By default, it is empty.

♦ To customize the extraction procedure to omit certain triggers:

1	Ensure the quoted_identifier option is set to ON:

set quoted_identifier on

go

2	Any temporary tables referenced in the procedure must exist, or the CREATE PROCEDURE statement will fail. The temporary tables referenced in the following procedure are available in the ssremote.sql script. Copy any required table definitions from the script and execute the CREATE TABLE statements, so they exist on the current connection, before creating the procedure.

3	Create the following procedure:

CREATE PROCEDURE sp_user_extraction_hook

AS

BEGIN

  -- We do not want to extract the INSERT and

  -- DELETE triggers created on the Policy table

  -- that maintain the subscription_list

  -- column, since we do not include that

  -- column in the publication.

  -- If these objects were extracted the

  -- INSERTs would fail on the remote database

  -- since they reference a column

  -- ( subscription_list ) that does not exist.

  DELETE FROM #systrigger

  WHERE table_id = object_id( 'Policy' )

  -- Do not create any procedures

  DELETE FROM #sysprocedure

  WHERE proc_name = 'SubscribeCustomer'

END

go


Tuning extraction performance for shared rows
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Sharing rows among several subscriptions

 Tuning extraction performance for shared rows

When extracting or synchronizing a user, the subscription-list column can cause performance problems as it necessitates a full table scan.

If you are extracting databases for many users, and performance is a problem for you, you can use a subscription view to improve performance. The view must contain a subquery, which is used for extraction and synchronization only, and is ignored during log scanning. The tables involved still need to have triggers defined to maintain the subscription-list column.

♦ To create a subscription view:

1	Design a query that uses a subquery to select the proper rows for a subscription from a table.

For example, continuing the example from the preceding sections, the following query selects the rows of the Contact table for a user subscribed by rep_key value rep5:

SELECT *

FROM Contact

WHERE 'rep5' = (SELECT rep_key

FROM Customer

WHERE cust_key = Contact.cust_key )

2	Create a view that contains this subquery. For example:

CREATE VIEW Customer_sub_view AS

SELECT *

FROM dbo.Customer

WHERE 'repxx' IN ( SELECT rep_key

FROM dbo.Policy

WHERE dbo.Policy.cust_key = dbo.Customer.cust_key )

In this view definition, it does not matter what value you use on the left hand side of the WHERE clause (repxx in the example above). The replication tools use the subquery for extraction and synchronization only. Rows for which the SUBSCRIBE BY value is in the subquery result set are extracted or synchronized.

3	Give the name of the view as a parameter to sp_add_article or sp_modify_article:

exec sp_add_article SalesRepData,

'Customer',

NULL,

'subscription_list',

'Customer_sub_view'

The subscription_list column is used for log scanning and the subquery is used for extraction and synchronization.

  For more information, see Tuning extraction performance, sp_add_article procedure, and sp_modify_article procedure.


Using the Subscribe_by_remote option with many-to-many relationships
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Sharing rows among several subscriptions

 Using the Subscribe_by_remote option with many-to-many relationships

When the SUBSCRIBE_BY_REMOTE option is ON, operations that arrive from remote databases on rows with a subscribe by value of NULL or '' will assume the remote user is subscribed to the row. By default, the SUBSCRIBE_BY_REMOTE option is set to ON. In most cases, this setting is the desired setting.

The SUBSCRIBE_BY_REMOTE option solves a problem that otherwise would arise with publications including the Policy example. This section describes how the option automatically avoids the problem.

The database uses a subscription-list column for the Customer table, because each Customer may belong to several Sales Reps:

Marc Dill is a Sales Rep who has just arranged a policy with a new customer. He inserts a new Customer row and also inserts a row in the Policy table to assign the new Customer to himself. Assuming that the subscription-list column is not included in the publication, the operation at Marc's remote database is as follows:

As the INSERT of the Customer row is carried out by the Message Agent at the consolidated database, Adaptive Server Enterprise records the subscription value in the transaction log, at the time of the INSERT.

Later, when the Message Agent scans the log, it builds a list of subscribers to the new row, using the subscription value stored in the log, and Marc Dill is not on that list. If SUBSCRIBE_BY_REMOTE were set to OFF, the result would be that the new Customer is sent back to Marc Dill as a DELETE operation.

As long as SUBSCRIBE_BY_REMOTE is set to ON, the Message Agent assumes that, as the subscription-list column is NULL, the row belongs to the Sales Rep that inserted it. As a result, the INSERT is not replicated back to Marc Dill, and the replication system is intact.

You can use a trigger, which executes after the INSERT, to maintain the subscription-list column.


Managing conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Managing conflicts

An UPDATE conflict occurs when the following sequence of events takes place:

1	User 1 updates a row at remote site 1.

2	User 2 updates the same row at remote site 2.

3	The update from User 1 is replicated to the consolidated database.

4	The update from User 2 is replicated to the consolidated database.

When the SQL Remote Message Agent replicates UPDATE statements, it does so as a separate UPDATE for each row. Also, the message contains the old row values for comparison. When the update from user 2 arrives at the consolidated database, the values in the row are not those recorded in the message.

Default conflict resolution

By default, the UPDATE still proceeds, so that the User 2 update (the last to reach the consolidated database) becomes the value in the consolidated database, and is replicated to all other databases subscribed to that row. In general, the default method of conflict resolution is that the most recent operation (in this case that from User 2) succeeds, and no report is made of the conflict. The update from User 1 is lost.

SQL Remote also allows custom conflict resolution, using a stored procedure to resolve conflicts in a way that makes sense for the data being changed.

Conflicts do not apply to primary keys

UPDATE conflicts do not apply to primary key updates. If the column being updated is a primary key, then when the update from User 2 arrives at the consolidated database, no row will be updated.

This section describes how you can build conflict resolution into your SQL Remote installation at the consolidated database.

 How SQL Remote handles conflicts

 Implementing conflict resolution

 A first conflict resolution example

 A second conflict resolution example

 Designing to avoid referential integrity errors


How SQL Remote handles conflicts
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Managing conflicts

 How SQL Remote handles conflicts

When a conflict is detected

SQL Remote replication messages include UPDATE statements as a set of single row updates, each including the values prior to updating.

An UPDATE conflict is detected by the database server as a failure of the values to match the rows in the database.

Conflicts are detected and resolved by the Message Agent, but only at a consolidated database. When an UPDATE conflict is detected in a message from a remote database, the Message Agent causes the database server to take two actions:

1	The UPDATE is applied.

2	Any conflict resolution procedures are called.

UPDATE statements are applied even if the VERIFY clause values do not match, whether or not there is a resolve update procedure.

  The method of conflict resolution is different at an Adaptive Server Anywhere consolidated database. For more information, see How SQL Remote handles conflicts.


Implementing conflict resolution
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Managing conflicts

 Implementing conflict resolution

This section describes what you need to do to implement custom conflict resolution in SQL Remote.

Required objects

For each table on which you wish to resolve conflicts, you must create three database objects to handle the resolution:

•	An old value table    To hold the values that were stored in the table when the conflicting message arrived.

•	A remote value table    To hold the values stored in the table at the remote database when the conflicting update was applied, as determined from the message.

•	A stored procedure    To carry out actions to resolve the conflict.

These objects need to exist only in the consolidated database, as that is where conflict resolution occurs. They should not be included in any publications.

Naming the objects

When a table is marked for replication, using the sp_add_remote_table or sp_modify_remote_table stored procedure, optional parameters specify the names of the conflict resolution objects.

The sp_add_remote_table and sp_modify_remote_table procedures take one compulsory argument, which is the name of the table being marked for replication. It takes three additional arguments, which are the names of the objects used to resolve conflicts. For example, the syntax for sp_add_remote_table is:

exec sp_add_remote_table table_name

[ , resolve_procedure  ]

[ , old_row_table ]

[ , remote_row_table ]

You must create each of the three objects resolve_procedure, old_row_table, and remote_row_table. These three are discussed in turn.

•	old_row_table    This table must have the same column names and data types as the table table_name, but should not have any foreign keys. When a conflict occurs, a row is inserted into old_row_table containing the values of the row in table_name being updated before the UPDATE was applied. Once resolve_procedure has been run, the row is deleted.

As the Message Agent applies updates as a set of single-row updates, the table only ever contains a single row.

•	remote_row_table    This table must have the same column names and data types as the table table_name, but should not have any foreign keys. When a conflict occurs, a row is inserted into remote_row_table containing the values of the row in table_name from the remote database before the UPDATE was applied. Once resolve_procedure has been run, the row is deleted.

As the Message Agent applies updates as a set of single-row updates, the table only ever contains a single row.

•	resolve_procedure    This procedure carries out whatever actions are required to resolve a conflict, which may include altering the value in the row or reporting values into a separate table.

Once these objects are created, you must run the sp_add_remote_table or sp_modify_remote_table procedure to flag them as conflict resolution objects for a table.

Limitations

•	At an Adaptive Server Enterprise database, conflict resolution will not work on a table with more than 128 columns while the VERIFY_ALL_COLUMNS option is set to ON. Even if VERIFY_ALL_COLUMNS is set to OFF, if an UPDATE statement updates more than 128 columns, conflict resolution will not work.


A first conflict resolution example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Managing conflicts

 A first conflict resolution example

In this example, conflicts in the Customer table in the two-table example used in the tutorials are reported into a table for later review.

The database

The two-table database is as follows:

Goals of the conflict resolution

The conflict resolution will report conflicts on updates to the name column in the Customer table into a separate table named ConflictLog.

The conflict resolution objects

The conflict resolution tables are defined as follows:

CREATE TABLE OldCustomer(

cust_key CHAR( 12 ) NOT NULL,

name CHAR( 40 ) NOT NULL,

rep_key CHAR( 5 ) NOT NULL,

PRIMARY KEY ( cust_key )

)

CREATE TABLE RemoteCustomer(

cust_key CHAR( 12 ) NOT NULL,

name CHAR( 40 ) NOT NULL,

rep_key CHAR( 5 ) NOT NULL,

PRIMARY KEY ( cust_key )

)

Each of these tables has exactly the same columns and data types as the Customer table itself. The only difference in their definition is that they do not have a foreign key to the SalesRep table.

The conflict resolution procedure reports conflicts into a table named ConflictLog, which has the following definition:

CREATE TABLE ConflictLog (

conflict_key numeric(5, 0) identity not null,

lost_name char(40) not null ,

won_name char(40) not null ,

primary key ( conflict_key )

)

The conflict resolution procedure is as follows:

CREATE PROCEDURE ResolveCustomer

AS

BEGIN

DECLARE @cust_key CHAR(12)

DECLARE @lost_name CHAR(40)

DECLARE @won_name CHAR(40)

// Get the name that was lost

// from OldCustomer

SELECT @lost_name=name,

@cust_key=cust_key

FROM OldCustomer

// Get the name that won

// from Customer

SELECT @won_name=name

FROM Customer

WHERE cust_key = @cust_key

INSERT INTO ConflictLog ( lost_name, won_name )

VALUES ( @lost_name, @won_name )

END

This resolution procedure does not use the RemoteCustomer table.

How the conflict resolution works

The stored procedure is the key to the conflict resolution. It works as follows:

1	Obtains the @lost_name value from the OldCustomer table, and also obtains a primary key value so that the real table can be accessed.

The @lost_name value is the value that was overridden by the conflict-causing UPDATE.

2	Obtains the @won_name value from the Customer table itself. This is the value that overrode @lost_name. The stored procedure runs after the update has taken place, which is why the value is present in the Customer table. This behavior is different from SQL Remote for Adaptive Server Anywhere, where conflict resolution is implemented in a BEFORE trigger.

3	Adds a row into the ConflictLog table containing the @lost_name and @won_name values.

4	After the procedure is run, the rows in the OldCustomer and RemoteCustomer tables are deleted by the Message Agent. In this simple example, the RemoteCustomer row was not used.

Testing the example

♦ To test the example:

1	Create the tables and the procedure in the consolidated database, and add them as conflict resolution objects to the Customer table.

2	Insert and commit a change at the consolidated database. For example:

UPDATE Customer

SET name = 'Sea Sports'

WHERE cust_key='cust1'

go

COMMIT

go

3	Insert and commit a different change to the same line at the remote database. For example:

UPDATE Customer

SET name = 'C Sports'

WHERE cust_key='cust1'

go

COMMIT

go

4	Replicate the change from the remote to the consolidated database, by running the Message Agent at the remote database to send the message, and then at the consolidated database to receive and apply the message.

5	At the consolidated database, view the Customer table and the ConflictLog table. The Customer table contains the value from the remote database:

cust_key	name	rep_key
cust1	C Sports	rep1
The ConflictLog table has a single row, showing the conflict:

conflict_key	lost_name	won_name
1	Sea Sports	C Sports


A second conflict resolution example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Managing conflicts

 A second conflict resolution example

This example shows a slightly more elaborate example of resolving a conflict, based on the same situation as the previous example, discussed in A first conflict resolution example.

Goals of the conflict resolution

In this case, the conflict resolution has the following goals:

•	Disallow the update from a remote database. The previous example allowed the update.

•	Report the name of the remote user whose update failed, along with the lost and won names.

The conflict resolution objects

In this case, the ConflictLog table has an additional column to record the user ID of the remote user. The table is as follows:

CREATE TABLE ConflictLog (

conflict_key numeric(5, 0) identity not null,

lost_name char(40) not null ,

won_name char(40) not null ,

remote_user char(40) not null ,

primary key ( conflict_key )

)

The stored procedure is more elaborate. As the update will be disallowed, rather than allowed, the lost_name value now refers to the value arriving in the message. It is first applied, but then the conflict resolution procedure replaces it with the value that was previously present.

The stored procedure uses data from the temporary table #remote. In order to create a procedure that references a temporary table you first need to create that temporary table. The statement is as follows:

CREATE TABLE #remote (

current_remote_user varchar(128),

current_publisher varchar(128)

)

This table is created in TEMPDB, and exists only for the current session. The Message Agent creates its own #remote table when it connects, and uses it when the procedure is executed.

CREATE PROCEDURE ResolveCustomer

AS

BEGIN

DECLARE @cust_key CHAR(12)

DECLARE @lost_name CHAR(40)

DECLARE @won_name CHAR(40)

DECLARE @remote_user varchar(128)

-- Get the name that was present before

-- the message was applied, from OldCustomer

-- This will "win" in the enx

SELECT @won_name=name,

@cust_key=cust_key

FROM OldCustomer

-- Get the name that was applied by the

-- Message Agent from Customer. This will

-- "lose" in the end

SELECT @lost_name=name

FROM Customer

WHERE cust_key = @cust_key

-- Get the remote user value from #remote

SELECT @remote_user = current_remote_user

FROM #remote

-- Report the problem

INSERT INTO ConflictLog ( lost_name,

won_name, remote_user )

VALUES ( @lost_name, @won_name, @remote_user )

-- Disallow the update from the Message Agent

-- by resetting the row in the Customer table

UPDATE Customer

SET name = @won_name

WHERE cust_key = @cust_key

END

Notes

There are several points of note here:

•	The user ID of the remote user is stored by the Message Agent in the current_remote_user column of the temporary table #remote.

•	The UPDATE from the Message Agent is applied before the procedure runs, so the procedure has to explicitly replace the values. This is different from the case in SQL Remote for Adaptive Server Anywhere, where conflict resolution is carried out by BEFORE triggers.

Testing the example

♦ To test the example:

1	Create the tables and the procedure in the consolidated database, and add them as conflict resolution objects to the Customer table.

2	Insert and commit a change at the consolidated database. For example:

UPDATE Customer

SET name = 'Consolidated Sports'

WHERE cust_key='cust1'

go

COMMIT

go

3	Insert and commit a different change to the same line at the remote database. For example:

UPDATE Customer

SET name = 'Field Sports'

WHERE cust_key='cust1'

go

COMMIT

go

4	Replicate the change from the remote to the consolidated database, by running the Message Agent at the remote database to send the message, and then at the consolidated database to receive and apply the message.

5	At the consolidated database, view the Customer table and the ConflictLog table. The Customer table contains the value from the consolidated database:

cust_key	name	rep_key
cust1	Consolidated Sports	rep1
The ConflictLog table has a single row, showing the conflict and recording the value entered at the remote database:

conflict_key	lost_name	won_name	remote_user
1	Field Sports	Consolidated Sports	field_user
6	Run the Message Agent again at the remote database. This receives the corrected update from the consolidated database, so that the name of the customer is set to Consolidated Sports here as well.


Designing to avoid referential integrity errors
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Managing conflicts

 Designing to avoid referential integrity errors

The tables in a relational database are related through foreign key references. The referential integrity constraints applied as a consequence of these references ensure that the database remains consistent. If you wish to replicate only a part of a database, there are potential problems with the referential integrity of the replicated database.

Referential integrity errors stop replication
If a remote database receives a message that includes a statement that cannot be executed because of referential integrity constraints, no further messages can be applied to the database (because they come after a message that has not yet been applied), including passthrough statements, which would sit in the message queue.

By paying attention to referential integrity issues while designing publications you can avoid these problems. This section describes some of the more common integrity problems and suggests ways to avoid them.

Unreplicated referenced table errors

Consider the following SalesRepData publication:

exec sp_add_remote_table 'SalesRep'

exec sp_create_publication 'SalesRepData'

exec sp_add_article 'SalesRepData', 'SalesRep'

go

If the SalesRep table had a foreign key to another table (say, Employee) that was not included in the publication, inserts or updates to SalesRep would fail to replicate unless the remote database had the foreign key reference removed.

If you use the extraction utility to create the remote databases, the foreign key reference is automatically excluded from the remote database, and this problem is avoided. However, there is no constraint in the database to prevent an invalid value from being inserted into the rep_id column of the SalesRep table, and if this happens the INSERT will fail at the consolidated database. To avoid this problem, you could include the Employee table (or at least its primary key) in the publication.


Ensuring unique primary keys
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Ensuring unique primary keys

Users at physically distinct sites can each INSERT new rows to a table, so there is an obvious problem ensuring that primary key values are kept unique.

If two users INSERT a row using the same primary key values, the second INSERT to reach a given database in the replication system will fail. As SQL Remote is a replication system for occasionally-connected users, there can be no locking mechanism across all databases in the installation. It is necessary to design your SQL Remote installation so that primary key errors do not occur.

For primary key errors to be designed out of SQL Remote installations; the primary keys of tables that may be modified at more than one site must be guaranteed unique. There are several ways of achieving this goal. This chapter describes a general, economical and reliable method that uses a pool of primary key values for each site in the installation.

Overview of primary key pools

The primary key pool is a table that holds a set of primary key values for each database in the SQL Remote installation. Each remote user receives their own set of primary key values. When a remote user inserts a new row into a table, they use a stored procedure to select a valid primary key from the pool. The pool is maintained by periodically running a procedure at the consolidated database that replenishes the supply.

The method is described using a simple example database consisting of sales representatives and their customers. The tables are much simpler than you would use in a real database; this allows us to focus just on those issues important for replication.

 The primary key pool

 Replicating the primary key pool

 Filling and replenishing the key pool

 Adding new customers

 Testing the key pool

 Primary key pool summary


The primary key pool
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Ensuring unique primary keys

 The primary key pool

The pool of primary keys is held in a separate table. The following CREATE TABLE statement creates a primary key pool table:

CREATE TABLE KeyPool (

table_name VARCHAR(40) NOT NULL,

value INTEGER NOT NULL,

location VARCHAR(6) NOT NULL,

PRIMARY KEY (table_name, value),

)

go

The columns of this table have the following meanings:

Column	Description
table_name	Holds the names of tables for which primary key pools must be maintained. In our simple example, if new sales representatives were to be added only at the consolidated database, only the Customer table needs a primary key pool and this column is redundant. It is included to show a general solution.
value	Holds a list of primary key values. Each value is unique for each table listed in table_name.
location	In some setups, this could be the same as the rep_key value of the SalesRep table. In other setups, there will be users other than sales representatives and the two identifiers should be distinct.
For performance reasons, you may wish to create an index on the table:

CREATE INDEX KeyPoolLocation

ON KeyPool (table_name, location, value)

go


Replicating the primary key pool
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Ensuring unique primary keys

 Replicating the primary key pool

You can either incorporate the key pool into an existing publication, or share it as a separate publication. In this example, we create a separate publication for the primary key pool.

♦ To replicate the primary key pool:

1	Create a publication for the primary key pool data.

sp_create_publication 'KeyPoolData'

go

sp_add_remote_table 'KeyPool'

go

sp_add_article 'KeyPoolData', 'KeyPool',

NULL, 'location'

go

2	Create subscriptions for each remote database to the KeyPoolData publication.

sp_subscription 'create',

KeyPoolData,

field_user,

rep1

go

The subscription argument is the location identifier.

In some circumstances it makes sense to add the KeyPool table to an existing publication and use the same argument to subscribe to each publication. Here we keep the location and rep_key values distinct to provide a more general solution.


Filling and replenishing the key pool
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Ensuring unique primary keys

 Filling and replenishing the key pool

Every time a user adds a new customer, their pool of available primary keys is depleted by one. The primary key pool table needs to be periodically replenished at the consolidated database using a procedure such as the following:

CREATE PROCEDURE ReplenishPool AS

BEGIN

DECLARE @CurrTable  VARCHAR(40)

DECLARE @MaxValue   INTEGER

DECLARE EachTable   CURSOR FOR

SELECT table_name, max(value)

FROM KeyPool

GROUP BY table_name

DECLARE @CurrLoc    VARCHAR(6)

DECLARE @NumValues  INTEGER

DECLARE EachLoc	    CURSOR FOR

SELECT location, count(*)

FROM KeyPool

WHERE table_name = @CurrTable

GROUP BY location

OPEN EachTable

WHILE 1=1 BEGIN

FETCH EachTable INTO @CurrTable, @MaxValue

IF @@sqlstatus != 0 BREAK

OPEN EachLoc

WHILE 1=1 BEGIN

FETCH EachLoc INTO @CurrLoc, @NumValues

IF @@sqlstatus != 0 BREAK

-- make sure there are 10 values

WHILE @NumValues < 10 BEGIN

SELECT @MaxValue = @MaxValue + 1

SELECT @NumValues = @NumValues + 1

INSERT INTO KeyPool

 (table_name, location, value)

VALUES (@CurrTable, @CurrLoc, @MaxValue)

END

END

CLOSE EachLoc

END

CLOSE EachTable

END

go

This procedure fills the pool for each user up to ten values. You may wish to use a larger value in a production environment. The value you need depends on how often users are inserting rows into the tables in the database.

The ReplenishPool procedure must be run periodically at the consolidated database to refill the pool of primary key values in the KeyPool table.

The ReplenishPool procedure requires at least one primary key value to exist for each subscriber, so that it can find the maximum value and add one to generate the next set. To initially fill the pool you can insert a single value for each user, and then call ReplenishPool to fill up the rest. The following example illustrates this for three remote users and a single consolidated user named Office:

INSERT INTO KeyPool VALUES( 'Customer', 40, 'rep1' )

INSERT INTO KeyPool VALUES( 'Customer', 41, 'rep2' )

INSERT INTO KeyPool VALUES( 'Customer', 42, 'rep3' )

INSERT INTO KeyPool VALUES( 'Customer', 43, 'Office')

EXEC ReplenishPool

go

Cannot use a trigger to replenish the key pool
You cannot use a trigger to replenish the key pool, as no actions are replicated to the remote database performing the original operation, including trigger actions.


Adding new customers
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Ensuring unique primary keys

 Adding new customers

When a sales representative wants to add a new customer to the Customer table, the primary key value to be inserted is obtained using a stored procedure. This example shows a stored procedure to supply the primary key value, and also illustrates a stored procedure to carry out the INSERT.

The procedures takes advantage of the fact that the Sales Rep identifier is the CURRENT PUBLISHER of the remote database.

•	NewKey procedure    The NewKey procedure supplies an integer value from the key pool and deletes the value from the pool.

CREATE PROCEDURE NewKey

@TableName VARCHAR(40),

@Location VARCHAR(6),

@Value INTEGER OUTPUT AS

BEGIN

DECLARE @NumValues INTEGER

SELECT @NumValues = count(*),

 @Value = min(value)

FROM KeyPool

WHERE table_name = @TableName

AND location = @Location

IF @NumValues > 1

DELETE FROM KeyPool

WHERE table_name = @TableName

AND value = @Value

ELSE

-- Never take the last value,

-- because RestorePool will not work.

-- The key pool should be kept large

-- enough so this never happens.

SELECT @Value = NULL

END

•	NewCustomer procedure    The NewCustomer procedure inserts a new customer into the table, using the value obtained by NewKey to construct the primary key.

CREATE PROCEDURE NewCustomer @name VARCHAR(40),

@loc VARCHAR(6) AS

BEGIN

DECLARE @cust  INTEGER

DECLARE @cust_key  VARCHAR(12)

EXEC NewKey 'Customer', @loc, @cust output

SELECT @cust_key = 'cust' +

convert( VARCHAR(12), @cust )

INSERT INTO Customer (cust_key, name, rep_key )

VALUES ( @cust_key, @name, @loc )

END

You may want to enhance this procedure by testing the @cust value obtained from NewKey to check that it is not NULL, and preventing the insert if it is NULL.


Testing the key pool
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Ensuring unique primary keys

 Testing the key pool

♦ To test the primary key pool:

1	Re-extract a remote database using the field_user user ID.

2	Try this sample INSERT at the remote and consolidated sites:

EXEC NewCustomer 'Great White North', rep1


Primary key pool summary
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

        Ensuring unique primary keys

 Primary key pool summary

The primary key pool technique requires the following components:

•	Key pool table    A table to hold valid primary key values for each database in the installation.

•	Replenishment procedure    A stored procedure keeps the key pool table filled.

•	Sharing of key pools    Each database in the installation must subscribe to its own set of valid values from the key pool table.

•	Data entry procedures    New rows are entered using a stored procedure that picks the next valid primary key value from the pool and delete that value from the key pool.


Creating subscriptions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 16.  SQL Remote Design for Adaptive Server Enterprise

 Creating subscriptions

To subscribe to a publication, each subscriber must be granted REMOTE permissions and a subscription must also be created for that user. The details of the subscription are different depending on whether or not the publication uses a subscription column.

Subscriptions with no subscription column

To subscribe a user to a publication, if that publication has no subscription column, you need the following information:

•	User ID    The user who is being subscribed to the publication. This user must have been granted remote permissions.

•	Publication name    The name of the publication to which the user is being subscribed.

The following statement creates a subscription for a user ID SamS to the pub_orders_samuel_singer publication, which was created without using a subscription column:

sp_subscription 'create',

'pub_orders_samuel_singer',

'SamS'

Subscriptions with a subscription column

To subscribe a user to a publication, if that publication does have a subscription column, you need the following information:

•	User ID    The user who is being subscribed to the publication. This user must have been granted remote permissions.

•	Publication name    The name of the publication to which the user is being subscribed.

•	Subscription value    The value that is to be tested against the subscription column of the publication. For example, if a publication has the name of a column containing an employee ID as a subscription column, the value of the employee ID of the subscribing user must be provided in the subscription. The subscription value is always a string.

The following statement creates a subscription for Samuel Singer (user ID SamS, employee ID 856) to the pub_orders publication, defined with a subscription column sales_rep, requesting the rows for Samuel Singer's own sales:

sp_subscription create,

pub_orders,

SamS,

'856'

Starting a subscription

In order to receive and apply updates properly, each subscriber needs to have an initial copy of the data. The synchronization process is discussed in Synchronizing databases.


CHAPTER 17.  Deploying and Synchronizing Databases
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 17.  Deploying and Synchronizing Databases

About this chapter

This chapter describes the steps you need to take to deploy and synchronize a SQL Remote replication installation.

 Deployment overview

 Test before deployment

 Synchronizing databases

 Using the extraction utility

 Synchronizing data over a message system


Deployment overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

 Deployment overview

When you have completed the design phase of a SQL Remote system, the next step is to create and deploy the remote databases and applications.

Deployment tasks

In some cases, deployment is a major undertaking. For example, if you have a large number of remote users in a sales force automation system, deployment involves the following steps:

1	Building an Adaptive Server Anywhere database for each remote user, with their own initial copy of the data.

2	Installing the database, together with the Adaptive Server Anywhere database server, the SQL Remote Message Agent, and client application, on each user's machine.

3	Ensuring that the system is properly configured, with correct user names, Message Agent connection strings, permissions, and so on.

In the case of large-scale deployments, remote sites are most commonly Adaptive Server Anywhere databases, and this chapter focuses on this case.

Topics covered

This chapter covers the following topics:

•	Creating remote databases    Before you can deploy a SQL Remote system, you must create a remote database for each remote site.

Most of the description focuses on creating remote Adaptive Server Anywhere databases.

•	Synchronizing data    Synchronization of a database is the setting up of  the initial copy of data in the remote database.


Test before deployment
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

 Test before deployment

Thorough testing of your SQL Remote system should be carried out before deployment, especially if you have a large number of remote sites.

When you are in the design and setup phase, you can alter many facets of the SQL Remote setup. Altering publications, message types, writing triggers to resolve update conflicts are all easy to do.

Once you have deployed a SQL Remote application, the situation is different. A SQL Remote setup can be seen as a single dispersed database, spread out over many sites, maintaining a loose form of consistency. The data may never be in exactly the same state in all databases in the setup at once, but all data changes are replicated as complete transactions around the system over time. Consistency is built in to a SQL Remote setup through careful publication design, and through the reconciliation of UPDATE conflicts as they occur.

Upgrading and resynchronization

Once a SQL Remote setup is deployed and is running, it is not easy to tinker with. An upgrade to a SQL Remote installation needs to be carried out with the same care as an initial deployment. This applies also to upgrading maintenance releases of the Adaptive Server Enterprise or Adaptive Server Anywhere database software. Any such software upgrade needs to be tested for compatibility before deployment.

Making changes to a database schema at one database within the system can cause failures because of incompatible database objects. The passthrough mode does allow schema changes to be sent to some or all databases in a SQL Remote setup, but must still be used with care and planning.

The loose consistency in the dispersed database means that updates are always in progress: you cannot generally stop changes being made to all databases, make some changes to the database schema, and restart.

Without careful planning, changes to a database schema will produce errors throughout the installation, and will require all subscriptions to be stopped and resynchronized. Resynchronization involves loading new copies of the data in each remote database, and for more than a few subscribers is a time-consuming process involving work interruptions and possible loss of data.

 Changes to avoid on a running system


Changes to avoid on a running system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Test before deployment

 Changes to avoid on a running system

The following are examples of changes that should not be made to a deployed and running SQL Remote setup. From the list, you will see that there is a class of changes that are permissive, and these are generally permissible, while other changes are restrictive, and must be avoided.

The following changes must be avoided, except under the conditions stated:

•	Change the publisher for the consolidated database.

•	Make restrictive changes to tables, such as dropping a column or altering a column to not allow NULL values. Changes that include the column or including NULL entries may already be being sent in messages around the SQL Remote setup, and will fail.

•	Alter a publication. Publication definitions must be maintained at both local and remote sites, and changes that rely on the old publication definition may already be being sent in messages around the SQL Remote setup.

You can make permissive changes, such as adding a new table or column, as long as you use passthrough to ensure that the new table or column exists in the remote database and in the publication at the remote database.

•	Drop a subscription. This can be done only if you use passthrough deletes to remove the data at the remote site.

•	Unload and reload an Adaptive Server Anywhere database.

If an Adaptive Server Anywhere database is participating in replication, it cannot be unloaded and reloaded without re-synchronizing the database. Replication is based on the transaction log, and when a database is unloaded and reloaded, the old transaction log is no longer available. For this reason, good backup practices are especially important when participating in replication.

An Adaptive Server Enterprise database can be unloaded and reloaded as long as the system is quiet and the transaction log is fully scanned. The page_id and row_id rows in the sr_queue_state table of the stable queue must be reset.


Synchronizing databases
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

 Synchronizing databases

What is synchronization?

SQL Remote replication is carried out using the information in the transaction log, but there are two circumstances where SQL Remote deletes all existing rows from those tables of a remote database that form part of a publication, and copies the publication's entire contents from the consolidated database to the remote site. This process is called synchronization.

When to synchronize

Synchronization is used under the following circumstances:

•	When a subscription is created at a consolidated database a synchronization is carried out, so that the remote database starts off with a database in the same state as the consolidated database.

•	If a remote database gets corrupt or gets out of step with the consolidated database, and cannot be repaired using SQL passthrough mode, synchronization forces the remote site database back in step with the consolidated site.

How to synchronize

Synchronizing a remote database can be done in the following ways:

•	Use the database extraction utility    This utility creates a schema for a remote Adaptive Server Anywhere database, and synchronizes the remote database. This is generally the recommended procedure.

•	Manual synchronization    Synchronize the remote database manually by loading from files, using the PowerBuilder pipeline, or some other tool.

•	Synchronize over the message system    Synchronize the remote database via the message system using the SYNCHRONIZE SUBSCRIPTION statement (Adaptive Server Anywhere ) or sp_subscription 'synchronize' procedure (Adaptive Server Enterprise).

Caution
Do not execute SYNCHRONIZE SUBSCRIPTION or sp_subscription 'synchronize' at a remote database.

 Mixed operating systems and database extraction

 Notes on synchronization and extraction


Mixed operating systems and database extraction
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Synchronizing databases

 Mixed operating systems and database extraction

In many installations, the consolidated server will be running on a different operating system than the remote databases.

Adaptive Server Anywhere databases can be copied from one file or operating system to another. This allows you flexibility in how you carry out your initial synchronization of databases.

Example

For example, you may be running an Adaptive Server Enterprise server on a UNIX system that holds the consolidated database, but wish to deploy remote databases on laptop computers running Windows 95.

In this circumstance, you have several options for the platforms on which you extract the database, including the following, assuming you have the requisite software:

•	Run the extraction utility on UNIX to create the reload script and data files. Copy the script and data files to a Windows 95 machine. Create the Adaptive Server Anywhere databases and load them up with the schema and data on Windows 95.

•	Run the extraction utility on UNIX to create the reload script and data files. Create the Adaptive Server Anywhere databases and load them up with the schema and data on the same UNIX platform, and then copy the database files onto Windows 95 machines for deployment.

•	Run the extraction utility on Windows 95, and carry out all database creation and other tasks on the Windows 95 operating system.


Notes on synchronization and extraction
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Synchronizing databases

 Notes on synchronization and extraction

•	Extracting large numbers of subscriptions, or synchronizing subscriptions to large, frequently-used tables, can slow down database access for other users. You may wish to extract such subscriptions when the database is not in heavy use. This happens automatically if you use a SEND AT clause with a quiet time specified.

•	Synchronization applies to an entire subscription. There is currently no straightforward way of synchronizing a single table.

•	For Adaptive Server Enterprise, Sybase Central does not display subscriptions as started until the Message Agent first runs against the database.

  For performance tips for Adaptive Server Enterprise users using a subscription-list column, see Tuning extraction performance and Tuning extraction performance for shared rows.


Using the extraction utility
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

 Using the extraction utility

The extraction utility is an aid to creating remote Adaptive Server Anywhere databases. It cannot be used to create remote Adaptive Server Enterprise databases.

Running the extraction utility

The extraction utility can be accessed in the following ways:

•	From Sybase Central.

•	As a command-line utility. This is the dbxtract command-line utility (Adaptive Server Anywhere), or the ssxtract command-line utility (Adaptive Server Enterprise).

Caution
Do not run the Message Agent while running the extraction utility. The results are unpredictable.

 Creating a database from the reload files

 Before extracting a database

 Using the extraction utility from Sybase Central

 Designing an efficient extraction procedure

 Extracting groups

 Limits to using the extraction utility

 Using the extraction utility for Adaptive Server Enterprise


Creating a database from the reload files
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

 Creating a database from the reload files

The command-line utility unloads a database schema and data suitable for building a remote Adaptive Server Anywhere  database for a named subscriber. It produces a SQL command file with default name reload.sql and a set of data files. You can use these files to create a remote Adaptive Server Anywhere database.

Editing of reload.sql may be needed
The database extraction utility is intended to assist in preparing remote databases, but is not intended as a black box solution for all circumstances. You should edit the reload.sql command file as needed when creating remote databases.

♦ To create a remote database from the reload file:

1	Create an Adaptive Server Anywhere database using one of the following:

•	the Sybase Central Create Database wizard (located in the Utilities folder)

•	the dbinit command-line utility

2	Connect to the database from the Interactive SQL utility, and run the reload.sql command file. The following statement entered in the Interactive SQL command window runs the reload.sql command file:

read path\reload.sql

where path is the path of the reload command file.

When used from Sybase Central, the extraction utility carries out the database unloading task, in the same way that dbxtract or ssxtract does, and then takes the additional step of creating the new database.

The extraction utility does not use a message system. The reload file (ssxtract/dbxtract) or database (from Sybase Central) is created in a directory accessible from the current machine. Synchronizing many subscriptions over a message link can produce heavy message traffic and, if the message system is not completely reliable, it may take some time for all the messages to be properly received at the remote sites.


Before extracting a database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

 Before extracting a database

You must complete the following tasks before using the extraction utility at a consolidated database.

•	Create message types for replication.

•	Add a publisher user ID to the database.

•	Add remote users to the database.

•	Add the publication to the database.

•	Created a subscription for the remote users.

•	If you need to specify message link parameters, you must have set them.

  For a description of how to carry out these steps, see the tutorial in the chapter A Tutorial for Adaptive Server Anywhere Users. For a description of setting message link parameters, see Setting message type control parameters.

When you use the extraction utility to create a remote database, the user for which you are creating the database receives the same permissions they have in the consolidated database. Further, if the user is a member of any groups on the consolidated database, those group IDs are created in the remote database with the permissions they have in the consolidated database.


Using the extraction utility from Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

 Using the extraction utility from Sybase Central

This section describes how to extract a database for a remote user from the current consolidated database.

When you complete the extraction wizard, it does the following on your machine:

•	Creates the remote database

•	Extracts (unloads) the relevant structures and/or data from the consolidated database to files

•	Loads those files into the newly created remote database

♦ To extract a database for a remote user

1	Open the Utilities folder (located within the server folder).

2	In the right pane, double-click Extract Database.

3	Follow the instructions of the wizard.

Notes

•	You can also access this wizard by clicking Tools [image] Adaptive Server Anywhere [image] Extract Database.

•	If you use the wizard to extract a non-running database, it is only able to unload the structure and data for you. It cannot create the remote database and reload it. For this reason, we recommend that you always extract from a consolidated database that you are connected to in Sybase Central.

•	You can also invoke the extraction wizard for a particular database or for a particular remote user - Sybase Central automatically fills in the appropriate entries in the wizard.

•	The extraction wizard always extracts (synchronizes) the remote database using the WITH SYNCHRONIZATION option. In those rare cases where you don't want to use this option, you must use the DBXTRACT command-line utility instead.

For more information

For information about the extraction utility options, available as command-line options or as choices presented by the extraction wizard, see Extraction utility options.


Designing an efficient extraction procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

 Designing an efficient extraction procedure

It is very inefficient to create a large number of remote databases by running the extraction utility for each one. You can make the process much more efficient. This section describes one  way of making the process more efficient.

  For performance tips for Adaptive Server Enterprise users using a subscription-list column, see Tuning extraction performance and Tuning extraction performance for shared rows.

There are several potential causes of inefficiency in a large-scale extraction process:

•	The extraction utility extracts one database at a time, including the schema and data for each user. Commonly, many users share a common schema, and only the data differs. The brute force method of running the extraction utility for each user repeats large amounts of work unnecessarily. Extracting schema and data separately can help with this problem.

•	Running from Sybase Central, the extraction utility creates a new database for each user. If subscribers share a common schema, you could create a single database, with schema but no data, and copy the file.

•	By default, the extraction utility runs at isolation level zero. If you are extracting a database from an active server, you should run it at isolation level 3 (see Extraction utility options) to ensure that data in the extracted database is consistent with data on the server.

Running at isolation level 3 may hamper others' turnaround time on the server because of the large number of locks required. It is recommended that you run the extraction utility when the server is not busy, or run it against a copy of the database.

An efficient approach to extracting many databases

One approach that avoids these problems is as follows:

1	Make a copy of the consolidated database, and at the same time start the subscriptions from the live database. Messages will now start being sent to subscribers, even though they have no database and will not receive them yet.

To start several subscriptions within a single transaction, use the REMOTE RESET statement (Adaptive Server Anywhere ) or sp_remote procedure (Adaptive Server Enterprise).

2	Extract the remote databases from the copy of the database. As the database is a copy, there are no locking and concurrency problems. For a large number of remote databases, this process may take several days.

3	As each remote database is created, it is out of date, but its user can receive and apply messages that have been being sent from the live consolidated database, to bring themselves up to date.

This solution interferes with the production database only during the first step. The copy must be made at isolation level three if the database is in use, and uses large numbers of locks. Also, the subscriptions must be started at the same time that the copy is made. Any operations that take place between the copy and the starting of the subscriptions would be lost, and could lead to errors at remote databases.


Extracting groups
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

 Extracting groups

If the remote user is a group user ID, the extraction utility extracts all the user IDs of members of that group. You can use this feature to all multiple users on each remote database, using different user IDs, without requiring a custom extraction process.

When a database is extracted for a user, all message link parameters for that user and the groups of which the user is a member are extracted.


Limits to using the extraction utility
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

 Limits to using the extraction utility

While the extraction utility is the recommended way of creating and synchronizing remote databases from a consolidated databases, there are some circumstances where it cannot be used, and you must synchronize remote databases manually. This section describes some of those cases.

•	Cannot create Adaptive Server Enterprise remote databases    The extraction utility can only be used for Adaptive Server Anywhere remote databases.

•	Additional tables at the remote database    Remote databases can have tables not present at their consolidated database as long as these tables do not take part in replication. Of course, the extraction utility cannot extract such tables from a consolidated database.

•	Adaptive Server Enterprise/Adaptive Server Anywhere differences    Some features in Adaptive Server Enterprise are not present in Adaptive Server Anywhere. The extraction utility carries out a mapping onto similar features, but the mapping is not complete.

  For more information on Adaptive Server Enterprise/Adaptive Server Anywhere issues, see Using the extraction utility for Adaptive Server Enterprise.

•	Extracting procedures and views    By default, the extraction utility extracts all stored procedures and views from the database. While some of these views and procedures are likely to be required at the remote site, others may not be required—they may refer only to parts of the database that are not included in the remote site.

After running the extraction utility, you should edit the reload script and remove unnecessary views and procedures.

•	Using the extraction utility in multi-tiered setups     To understand the role of the extraction utility in multi-tiered arrangements, consider a three-tiered SQL Remote setup.

This setup is illustrated in the following diagram.

From the consolidated database at the top level, you can use the extraction utility to create the second-level databases. You can then add remote users to these second-level databases, and use the extraction utility from each second-level database to create the remote databases. However, if you have to re-extract the second-level databases from the top-level consolidated database, you will delete the remote users that were created, along with their subscriptions and permissions, and will have to rebuild those users. The exception is if you resynchronize data only, in which case you can use the extraction utility to replace the data in the database, without replacing the schema.


Using the extraction utility for Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

 Using the extraction utility for Adaptive Server Enterprise

The extraction utility for Adaptive Server Enterprise takes an Adaptive Server Enterprise database schema, and produces an Adaptive Server Anywhere database. There are several limitations and techniques specific to this tool.

 Adaptive Server Enterprise features unsupported in Adaptive Server Anywhere

 Customizing the system tables


Adaptive Server Enterprise features unsupported in Adaptive Server Anywhere
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

          Using the extraction utility for Adaptive Server Enterprise

 Adaptive Server Enterprise features unsupported in Adaptive Server Anywhere

There are some features in Adaptive Server Enterprise that are either not supported or are only partially supported in Adaptive Server Anywhere. The extraction utility handles some of these features partially, and some not at all.

  For a full description of Adaptive Server Enterprise/Adaptive Server Anywhere compatibility, see the part Transact-SQL Compatibility, in the Adaptive Server Anywhere User's Guide.

Features not supported in ssxtract include the following:

•	Grouped procedures    Adaptive Server Anywhere does not support procedure groups, and they are not extracted by ssxtract.

•	Named constraints and defaults    Adaptive Server Anywhere does not support named constraints and named defaults. Any such objects are extracted directly as constraints and defaults that apply to a single object, and the name is lost.

•	Roles    ssxtract extracts roles using the Adaptive Server Anywhere concept of groups. It creates a group with the named role, and assigns users to it.

•	Passwords    If the user for whom a database is being extracted does not have an entry in SYSLOGINS, no password is extracted. If the user does have a login ID, a dummy password is extracted.

•	NCHAR, NVARCHAR    These data types are extracted as CHAR and VARCHAR, with NULLS allowed.

•	timestamp columns    Although Adaptive Server Anywhere does provide a timestamp column, it is a different data type from that of Adaptive Server Enterprise. Timestamp columns are not extracted.


Customizing the system tables
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

        Using the extraction utility

          Using the extraction utility for Adaptive Server Enterprise

 Customizing the system tables

The objects that are to be loaded into an Adaptive Server Anywhere database are described in the system catalog. The extraction utility for Adaptive Server Enterprise first creates a set of Adaptive Server Anywhere system tables in TEMPDB, and fills them with data from the Adaptive Server Enterprise catalog. It then unloads this set of tables to provide the reload script that in turn builds an Adaptive Server Anywhere database.

There may be cases where you wish to change the content of the Adaptive Server Anywhere system tables held in TEMPDB. SQL Remote provides a place for you to do that.

The stored procedure that creates and fills the Adaptive Server Anywhere system objects in TEMPDB is called sp_populate_sql_anywhere. As its final operation, this procedure calls a procedure called sp_user_extraction_hook. This procedure, by default, does nothing. If you wish to customize the extraction procedure, you can do so by writing  a suitable sp_user_extraction_hook procedure.


Synchronizing data over a message system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 17.  Deploying and Synchronizing Databases

 Synchronizing data over a message system

Creating subscriptions

A subscription is created at a consolidated Adaptive Server Enterprise database using the sp_subscription procedure with a first argument of create.

Creating a subscription defines the data to be received. It does not synchronize a subscription (provide an initial copy of the data) or start (exchange messages) a subscription.

Synchronizing subscriptions

Synchronizing a subscription causes the Message Agent to send a copy of all rows in the subscription to the subscriber. It assumes that an appropriate database schema is in place. At an Adaptive Server Anywhere consolidated database, subscriptions are synchronized using the SYNCHRONIZE SUBSCRIPTION statement. At an Adaptive Server Enterprise consolidated database, subscriptions are synchronized using the sp_subscription procedure with a first argument of synchronize.

When synchronization messages are received at a subscriber database, the Message Agent replaces the current contents of the database with the new copy. Any data at the subscriber that is part of the subscription, and which has not been replicated to the consolidated database, is lost. Once synchronization is complete, the subscription is started by the Message Agent using the START SUBSCRIPTION statement or sp_subscription procedure with a first argument of start.

Large volume of messages may result
Synchronizing databases over a message system may lead to large volumes of messages. In many cases, it is preferable to use the extraction process to synchronize a database locally without placing this burden on the message system.

Synchronizing subscriptions during operation

If a remote database becomes out of step with the consolidated database, and cannot be brought back in step using the SQL passthrough capabilities of SQL Remote, synchronizing the subscription forces the remote database into step with the consolidated database by copying the rows of the subscription from the consolidated database over the contents at the remote database.

Data loss on synchronization
  Any data in the remote database that is part of the subscription, but which has not been replicated to the consolidated database, is lost when the subscription is synchronized. You may wish to unload or back up the remote database using Sybase Central or, for Adaptive Server Anywhere, the dbunload utility before synchronizing the database.


CHAPTER 18.  SQL Remote Administration
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 18.  SQL Remote Administration

About this chapter

This chapter describes general issues and principles for administering a running SQL Remote installation.

  For system-specific details, see the chapters Administering SQL Remote for Adaptive Server Enterprise and Administering SQL Remote for Adaptive Server Anywhere.

 Management overview

 Managing SQL Remote permissions

 Using message types

 Running the Message Agent

 Tuning Message Agent performance

 Encoding and compressing messages

 The message tracking system


Management overview
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

 Management overview

This chapter describes administration issues for SQL Remote installations.

Administration of a deployed and running SQL Remote setup is carried out at a consolidated database.

•	Permissions    As a SQL Remote installation includes many different physical databases, a consistent scheme for users having permissions on remote and consolidated databases is necessary. A section of this chapter describes the considerations you need to make when assigning users permissions.

•	Configuring message systems    Each message system that is used in a SQL Remote installation has control parameters and other settings that must be set up. These settings are discussed in this chapter.

•	The Message Agent    The Message Agent is responsible for sending and receiving messages. While some details of how the Message Agent operates and the configuration options for it, are different for Adaptive Server Anywhere and Adaptive Server Enterprise, some concepts and methods are common to both. These common features are discussed here.

•	Message tracking    Administering a SQL Remote installation means managing large numbers of messages being handed back and forth among many databases. A section on the SQL Remote message tracking system is included to help you understand what the messages contain, when they are sent, how they are applied, and so on.

•	Log management    SQL Remote obtains the data to send from the transaction log. Consequently, proper management of the transaction log, and proper backup procedures, are essential for a smoothly running SQL Remote installation. While many details depend on the server you are running, the generic issues are discussed in this chapter.

•	Passthrough mode    This is a method for directly intervening at a remote site from a consolidated database. This method is discussed in this chapter.


Managing SQL Remote permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

 Managing SQL Remote permissions

Users of a database involved in SQL Remote replication are identified by one of the following sets of permissions:

•	PUBLISH    A single user ID in a database is identified as the publisher for that database. All outgoing SQL Remote messages, including both publication updates and receipt confirmations, are identified by the publisher user ID. Every database in a SQL Remote setup must have a single publisher user ID, as every database in a SQL Remote setup sends messages.

•	REMOTE    All recipients of messages from the current database, or senders of messages to the current database, who are immediately lower on the SQL Remote hierarchy than the current database must be granted REMOTE permissions.

•	CONSOLIDATE    At most one user ID may be granted CONSOLIDATE permissions in a database. CONSOLIDATE permissions identifies a database immediately above the current database in a SQL Remote setup. Each database can have only one consolidated database directly above it.

Information about these permissions are held in the SQL Remote system tables, and are independent of other database permissions.

 Granting and revoking PUBLISH permissions

 Granting and revoking REMOTE and CONSOLIDATE permissions

 Assigning permissions in multi-tier installations


Granting and revoking PUBLISH permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Managing SQL Remote permissions

 Granting and revoking PUBLISH permissions

When a database sends a message, a user ID representing that database is included with the message to identify its source to the recipient. This user ID is the publisher user ID of the database. A database can have only one publisher. You can find out who the publisher is at any time in Sybase Central by opening the SQL Remote folder.

A publisher is required even for read-only remote databases within a replication system, as even these databases send confirmations to the consolidated database to maintain information about the status of the replication. The GRANT PUBLISH statement for remote Adaptive Server Anywhere databases is carried out automatically by the database extraction utility.

Granting and revoking PUBLISH permissions from Sybase Central

You can grant PUBLISH permissions from Sybase Central. You must connect to the database as a user with full system or database administrator permissions.

♦ To create a new user as the publisher (Sybase Central):

1	Open the Users & Groups folder.

2	Double-click Add User.

3	On the first page of the wizard, enter a name and password and click Next.

4	On the next page, ensure that the user is granted Remote DBA authority; this enables the user ID to run the Message Agent. Then click Next.

5	On the final page, check the box identifying this user ID as the publisher. Then click Finish to create the user.

♦ To make an existing user the publisher (Sybase Central):

•	Do one of the following:

•	In the Users & Groups folder, right-click a user and choose Set as Publisher from the popup menu.

•	In the SQL Remote folder, double-click Set Publisher. Choose a user in the resulting dialog and click OK to set that user as the database publisher.

You can also revoke PUBLISH permissions from Sybase Central.

♦ To revoke PUBLISH permissions (Sybase Central):

•	Do one of the following:

•	In the Users & Groups folder, right-click the user who has granted PUBLISH permissions and choose Revoke Publisher from the popup menu.

•	In the SQL Remote folder, right-click the user who has granted PUBLISH permissions and choose Revoke Publisher from the popup menu.

Granting and revoking PUBLISH permissions [Adaptive Server Anywhere]

For Adaptive Server Anywhere, PUBLISH permissions are granted using the GRANT PUBLISH statement:

GRANT PUBLISH TO userid ;

The userid is a user with CONNECT permissions on the current database. For example, the following statement grants PUBLISH permissions to user S_Beaulieu:

GRANT PUBLISH TO S_Beaulieu

The REVOKE PUBLISH statement revokes the PUBLISH permissions from the current publisher:

REVOKE PUBLISH FROM userid

Granting and revoking PUBLISH permissions [Adaptive Server Enterprise]

For Adaptive Server Enterprise, PUBLISH permissions are granted using the sp_publisher procedure:

sp_publisher userid

The userid is a user with CONNECT permissions on the current database. For example, the following statement grants PUBLISH permissions to user S_Beaulieu:

exec sp_publisher 'S_Beaulieu'

go

The database is set to have no publisher by executing the sp_publisher procedure with no argument:

exec sp_publisher

go

Notes on PUBLISH permissions

•	To see the publisher user ID for an Adaptive Server Anywhere database outside Sybase Central, use the CURRENT PUBLISHER special constant. The following statement retrieves the publisher user ID:

SELECT CURRENT PUBLISHER

•	To see the publisher user ID for an Adaptive Server Enterprise database outside Sybase Central, use the following statement:

SELECT name

FROM sysusers

WHERE uid = ( SELECT user_id

FROM sr_publisher )

go

•	If PUBLISH permissions is granted to a user ID with GROUP permissions, it is not inherited by members of the group.

•	PUBLISH permissions carry no authority except to identify the publisher in outgoing messages.

•	For messages sent from the current database to be received and processed by a recipient, the publisher user ID must have REMOTE or CONSOLIDATE permissions on the receiving database.

•	The publisher user ID for a database cannot also have REMOTE or CONSOLIDATE permissions on that database. This would identify them as both the sender of outgoing messages and a recipient of such messages.

•	Changing the user ID of a publisher at a remote database will cause serious problems for any subscriptions that database is involved in, including loss of information. You should not change a remote database publisher user ID unless you are prepared to resynchronize the remote user from scratch.

•	Changing the user ID of a publisher at a consolidated database while a SQL Remote setup is operating will cause serious problems, including loss of information. You should not change the consolidated database publisher user ID unless you are prepared to close down the SQL Remote setup and resynchronize all remote users.


Granting and revoking REMOTE and CONSOLIDATE permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Managing SQL Remote permissions

 Granting and revoking REMOTE and CONSOLIDATE permissions

REMOTE and CONSOLIDATE permissions are very similar. Each database receiving messages from the current database must have an associated user ID on the current database that is granted one of REMOTE or CONSOLIDATE permissions. This user ID represents the receiving database in the current database.

Databases directly below the current database on a SQL Remote hierarchy are granted REMOTE permissions, and the at most one database above the current database in the hierarchy is granted CONSOLIDATE permissions.

Setting REMOTE and CONSOLIDATE permissions

For Adaptive Server Anywhere, the GRANT REMOTE and GRANT CONSOLIDATE statements identify the message system and address to which replication messages must be sent.

For Adaptive Server Enterprise, the sp_grant_remote procedure sets REMOTE permissions, and the sp_grant_consolidate procedure sets CONSOLIDATE permissions.

CONSOLIDATE permissions must be granted even from read-only remote databases to the consolidated database, as receipt confirmations are sent back from the remote databases to the consolidated database. The GRANT CONSOLIDATE statement at remote Adaptive Server Anywhere databases is executed automatically by the database extraction utility.

 Granting REMOTE permissions

 Selecting a send frequency

 Granting CONSOLIDATE permissions

 Revoking REMOTE and CONSOLIDATE permissions


Granting REMOTE permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Managing SQL Remote permissions

          Granting and revoking REMOTE and CONSOLIDATE permissions

 Granting REMOTE permissions

Each remote database must be represented by a single user ID in the consolidated database. This user ID must be granted REMOTE permissions to identify their user ID and address as a subscriber to publications.

Granting REMOTE permissions accomplishes several tasks:

•	It identifies a user ID as a remote user.

•	It specifies a message type to use for exchanging messages with this user ID.

•	It provides an address to where messages are to be sent.

•	It indicates how often messages should be sent to the remote user.

Granting REMOTE permissions is also referred to as adding a remote user to the database.

Sybase Central example

You can add a remote user to a database using Sybase Central. Remote users and groups appear in two locations in Sybase Central: in the Users & Groups folder, and in the Remote Users folder (located within the SQL Remote folder).

By default, remote users are created with remote DBA authority. Since the message agent for access to the remote database requires this authority, you shouldn't revoke it.

You cannot create a new remote user until at least one message type is defined in the database.

While you can grant remote permissions to a group, those remote permissions do not automatically apply to users in the group (unlike table permissions, for example). To do this, you must explicitly grant remote permissions to each user in the group. Otherwise, remote groups behave exactly like remote users (and are categorized as remote users).

♦ To add a new user to the database as a remote user (Sybase Central):

1	Open the Remote Users folder (located within the SQL Remote folder).

2	Double-click Add Remote User and follow the instructions in the wizard.

♦ To make an existing user or group remote (Sybase Central):

1	Open the Users & Groups folder.

2	Right-click the user or group you want to make remote and choose Set Remote from the popup menu.

3	In the resulting dialog, select the message type from the list, enter an address, choose the frequency of sending messages, and click OK to make the user a remote user.

  For descriptions of the dialogs, see Change User to a Remote User dialog and Change Group to a Remote Group dialog.

Adaptive Server Anywhere example

The following statement grants remote permissions to user S_Beaulieu, with the following options:

•	Use an SMTP e-mail system

•	Send messages to e-mail address s_beaulieu@acme.com:

•	Send message daily, at 10 pm.

GRANT REMOTE TO S_Beaulieu

TYPE smtp

ADDRESS 's_beaulieu@acme.com'

SEND AT '22:00'

Adaptive Server Enterprise example

The following statement grants remote permissions to user S_Beaulieu with the following options:

•	Use the file-sharing system to exchange messages.

•	Place messages in the directory beaulieu under the address root directory.

The address root directory (for both Adaptive Server Anywhere and Adaptive Server Enterprise) is indicated by the SQLREMOTE environment variable, if it is set. Alternatively, it is indicated by the Directory setting in the FILE message control parameters (held in the registry or INI file).

•	Send messages every twelve hours:

exec sp_grant_remote 'S_Beaulieu',

'file',

'beaulieu',

'SEND EVERY',

'12:00'

go


Selecting a send frequency
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Managing SQL Remote permissions

          Granting and revoking REMOTE and CONSOLIDATE permissions

 Selecting a send frequency

There are three alternatives for the setting the frequency with which messages are sent. The three alternatives are:

•	SEND EVERY    A frequency can be specified in hours and minutes.

When any user with SEND EVERY set is sent messages, all users with the same frequency are sent messages also. For example, all remote users who receive updates every twelve hours are sent updates at the same times, rather than being staggered. This reduces the number of times the Adaptive Server Anywhere transaction log or Adaptive Server Enterprise stable queue has to be processed. You should use as few unique frequencies as possible.

SQL Remote is not intended for up-to-the-minute replication. Frequencies of less than ten minutes are not recommended.

•	SEND AT    A time of day, in hours and minutes.

Updates are started daily at the specified time. It is more efficient to use as few distinct times as possible than to stagger the sending times. Also, choosing times when the database is not busy minimizes interference with other users.

•	Default setting (no SEND clause)    If any user has no SEND AT or SEND EVERY clause, the Message Agent sends messages every time it is run, and then stops: it runs in batch mode.

Setting the send frequency in Sybase Central

In Sybase Central, you can specify the send frequency in the following ways:

•	When you make an existing user or group remote. For more information, see Granting REMOTE permissions.

•	On the SQL Remote tab of the property sheet of a remote user or group. You can access the property sheet by right-clicking the remote user or group and choosing Properties from the popup menu. For a full description, see Remote Users properties.


Granting CONSOLIDATE permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Managing SQL Remote permissions

          Granting and revoking REMOTE and CONSOLIDATE permissions

 Granting CONSOLIDATE permissions

In the remote database, the publish and subscribe user IDs are inverted compared to the consolidated database. The subscriber (remote user) in the consolidated database becomes the publisher in the remote database. The publisher of the consolidated database becomes a subscriber to publications from the remote database, and is granted CONSOLIDATE permissions.

At each remote database, the consolidated database must be granted CONSOLIDATE permissions. When you produce a remote database by running the database extraction utility, the GRANT CONSOLIDATE statement is executed automatically at the remote database.

Adaptive Server Anywhere example

The following Adaptive Server Anywhere  statement grants CONSOLIDATE permissions to the hq_user user ID, using the VIM e-mail system:

GRANT CONSOLIDATE TO hq_user

TYPE vim

ADDRESS 'hq_address'

There is no SEND clause in this statement, so the default is used and messages will be sent to the consolidated database every time the Message Agent is run.

Adaptive Server Enterprise example

The following Adaptive Server Enterprise statement grants CONSOLIDATE permissions to user hq_user, using the file message link:

exec sp_grant_consolidate 'hq_user', 'file', address

go


Revoking REMOTE and CONSOLIDATE permissions
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Managing SQL Remote permissions

          Granting and revoking REMOTE and CONSOLIDATE permissions

 Revoking REMOTE and CONSOLIDATE permissions

A user can be removed from a SQL Remote installation by revoking their REMOTE permissions. When you revoke remote permissions from a user or group, you revert that user or group to a normal user/group. You also automatically unsubscribe that user or group from all publications.

Revoking permissions from Sybase Central

You can revoke REMOTE permissions on both Adaptive Server Enterprise and Adaptive Server Anywhere from Sybase Central.

♦ To revoke REMOTE permissions (Sybase Central):

1	Open either the Users & Groups folder or the Remote Users folder (located within the SQL Remote folder).

2	Right-click the remote user or group and choose Revoke Remote from the popup menu.

Revoking permissions in Adaptive Server Anywhere

REMOTE and CONSOLIDATE permissions can be revoked from a user using the REVOKE statement. The following statement revokes REMOTE permission from user S_Beaulieu.

REVOKE REMOTE FROM S_Beaulieu

DBA authority is required to revoke REMOTE or CONSOLIDATE access.

Revoking permissions in Adaptive Server Enterprise

REMOTE permissions can be revoked from a user using the sp_revoke_remote procedure. This procedure takes a single argument, which is the user ID of the user. The following statement revokes REMOTE permission from user S_Beaulieu.

exec sp_revoke_remote 'S_Beaulieu'

go


Assigning permissions in multi-tier installations
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Managing SQL Remote permissions

 Assigning permissions in multi-tier installations

Special considerations are needed for assigning permissions in multi-tier installations. The permissions in a three-level SQL Remote setup are summarized in the following diagrams. In each diagram one database is shaded; the diagram shows the permissions that need to be granted in that database for the user ID representing each of the other databases. The phrase "No permissions" means that the database is not granted any permissions in the shaded database.

The following picture shows SQL Remote permissions, as granted at the consolidated site of a three-tier installation.

The following picture shows SQL Remote permissions, as granted at an internal site of a three-tier installation.

The following picture shows SQL Remote permissions, as granted at an internal site of a three-tier installation.

Granting the appropriate PUBLISH and CONSOLIDATE permissions at remote databases is done automatically by the database extraction utility.


Using message types
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

 Using message types

SQL Remote supports several different systems for exchanging messages. The message systems supported by SQL Remote are:

•	file    Storage of message files in directories on a shared file system for reading by other databases.

•	ftp    Storage of message files in directories accessible by a file transfer protocol (ftp) link.

•	mapi    Microsoft's messaging API (MAPI) link, used in Microsoft Mail and other electronic mail systems.

•	smtp    Internet Simple Mail Transfer Protocol (SMTP/POP), used in Internet e-mail.

•	vim    Lotus's Vendor Independent Messaging (VIM), used in Lotus Notes and cc:Mail.

A database can exchange messages using one or more of the available message systems.

Operating system availability

Not all message systems are supported on all operating systems for which SQL Remote is available. The links are implemented as DLLs on Windows 3.x, Windows 95, and Windows NT.

  For a listing of which message systems are supported on which operating system, see Supported Platforms and Message Links.

For more information

•	For more information on the file message system, see The file message system.

•	For more information on the ftp message system, see The ftp message system.

•	For more information on the smtp message system, see The SMTP message system.

•	For more information on the mapi message system, see The MAPI message system.

•	For more information on the vim message system, see The VIM message system.

 Working with message types

 Setting message type control parameters

 The file message system

 The ftp message system

 The SMTP message system

 The MAPI message system

 The VIM message system


Working with message types
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

 Working with message types

Each message type definition includes the type name (file, ftp, smtp, mapi, or vim) and also the address of the publisher under that message type. The publisher address at a consolidated database is used by the database extraction utility as a return address when creating remote databases. It is also used by the Message Agent to identify where to look for incoming messages for the file system.

The address supplied with a message type definition is closely tied to the publisher ID of the database. Valid addresses are considered in following sections.

Before you can use a message system, you must set the publisher's address.

 Using Sybase Central to work with message types

 Using commands to work with message types


Using Sybase Central to work with message types
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

          Working with message types

 Using Sybase Central to work with message types

You can create and alter message types in Sybase Central. Message types appear in the Message Types folder (located within the SQL Remote folder).

You must have DBA authority to create and alter message types.

♦ To add a message type (Sybase Central):

1	Connect to a database.

2	Open the SQL Remote folder for that database.

3	Within the SQL Remote folder, open the Message Types folder.

4	Double-click Add Message Type.

5	In the resulting dialog, enter a message type name. The name should correspond to a message-type DLL already installed in your Adaptive Server Anywhere directory.

6	Enter a publisher address and click OK to save the definition in the database.

If you wish to change the publisher's address, you can do so by altering a message type. You cannot change the name of an existing message type; instead, you must delete it and create a new message type with the new name.

♦ To alter a message type (Sybase Central):

1	Open the SQL Remote folder for a database.

2	Within the SQL Remote folder, open the Message Types folder.

3	In the right pane, right-click the message type you wish to alter and select Properties from the popup menu.

4	On the property sheet, configure the various options.

If you wish to drop a message type from the installation, you can do so.

♦ To drop a message type (Sybase Central):

1	Open the SQL Remote folder for a database.

2	Within the SQL Remote folder, open the Message Types folder.

3	In the right pane, right-click the message type you wish to alter and select Delete from the popup menu.

  See also

•	Property Sheet Descriptions


Using commands to work with message types
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

          Working with message types

 Using commands to work with message types

♦ To create a message type (SQL):

1	Make sure you have decided on an address for the publisher under the message type.

2	Execute a CREATE REMOTE MESSAGE TYPE command.

For Adaptive Server Anywhere, the CREATE REMOTE MESSAGE TYPE statement has the following syntax:

CREATE REMOTE MESSAGE TYPE type-name
ADDRESS address-string

For Adaptive Server Enterprise, use the sp_remote_type procedure. This procedure takes the following arguments:

sp_remote_type type-name, address-string

In these statements, type-name is one of the message systems supported by SQL Remote, and address-string is the publisher's address under that message system.

If you wish to change the publisher's address, you can do so by altering the message type.

♦ To alter a message type (SQL):

1	Make sure you have decided on a new address for the publisher under the message type.

2	Execute an ALTER REMOTE MESSAGE TYPE statement.

For Adaptive Server Anywhere, the ALTER REMOTE MESSAGE TYPE statement has the following syntax:

ALTER REMOTE MESSAGE TYPE type-name
ADDRESS address-string

For Adaptive Server Enterprise, use the sp_remote_type procedure in the same way as creating a message type. This procedure takes the following arguments:

sp_remote_type type-name, address-string

In these statements, type-name is one of the message systems supported by SQL Remote, and address-string is the publisher's address under that message system.

You can also drop message types if they are no longer used in your installation. This has the effect of removing the publisher's address from the definition.

♦ To drop a message type (SQL):

•	Execute a DROP REMOTE MESSAGE TYPE statement.

For Adaptive Server Anywhere, the DROP REMOTE MESSAGE TYPE statement has the following syntax:

DROP REMOTE MESSAGE TYPE type-name

For Adaptive Server Enterprise, use the sp_drop_remote_type procedure in the same way as creating a message type. This procedure takes the following arguments:

sp_drop_remote_type type-name

In these statements, type-name is one of the message systems supported by SQL Remote.

  See also

•	CREATE REMOTE MESSAGE TYPE statement

•	ALTER REMOTE MESSAGE TYPE statement

•	DROP REMOTE MESSAGE TYPE statement


Setting message type control parameters
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

 Setting message type control parameters

Each message link has several parameters that govern aspects of its behavior. The parameters differ from message system to message system, but all are managed in the same way.

When you first use the Message Agent for a particular message link, it displays a dialog box showing a set of parameters that control the behavior of the link. These parameters may be a user ID for the message system, a host name where ftp messages are held, and so on. The parameters you enter are saved by the Message Agent. You can also set these parameters explicitly.

Message link parameters stored in the database

The message control parameters are held in the database. You can set the options as follows:

♦ To set a message control parameter (Adaptive Server Anywhere):

•	Execute the following statement:

SET REMOTE link-name OPTION
[username.]option-name = option-value

♦ To set a message control parameter (Adaptive Server Enterprise):

•	Execute the following statement:

exec sp_link_option link-name, [username],
option-name, option-value

You can see the current message link parameters by querying the sys.sysremoteoptions view (Adaptive Server Anywhere) or the sr_remoteoptions view (Adaptive Server Enterprise).

Holding the message link parameters on disk

Earlier versions of this software stored the message link parameters outside the database. You can still use this method, but storing the parameters inside the database is recommended unless you have specific reasons to choose otherwise.

The message link control parameters are stored in the following places:

•	Windows 95/98 and Windows NT    In the registry, at the following location:

\\HKEY_CURRENT_USER

\Software

\Sybase

\SQL Remote

The parameters for each message link go in a key under the SQL Remote key, with the name of the message link (4, smtp, and so on).

•	NetWare    You should create a file named dbremote.ini in the sys:\system directory to hold the FILE system directory setting. This file is not a Windows-format INI file: it must consist of a single line, holding only the directory name.

For example, if the directory is user:\dbr43, then the dbremote.ini file would contain the following:

user:\dbr43

•	UNIX    The FILE system directory setting is held in the SQLREMOTE environment variable.

The sqlremote environment variable holds a path that can be used as an alternative to one of the control parameters for the file sharing system.

The parameters available for each message system are discussed in the following sections. Each section describes a single message system.

When the Message Agent loads a message link, the link uses the settings of the current publisher or, of a setting is not specified, of groups to which the publisher belongs.  On Windows 95/98 or Windows NT, the first time a version of the Message Agent is run that supports storing the message link parameters in the database, it copies the link options from the registry to the database.


The file message system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

 The file message system

SQL Remote can be used even if you do not have a message system in place, by using the file message system.

Addresses in the file message system

The file message system is a simple file-sharing system. A file address for a remote user is a subdirectory into which all their messages are written. To retrieve messages from their "inbox", an application reads the messages from the directory containing the user's files. Return messages are sent to the address (written to the directory) of the consolidated database.

When running as an NT service make sure that the account under which the Message Agent is running has permissions to read and write all necessary directories. This is often a problem when accessing network drives.

Root directory for addresses

The file system addresses are typically subdirectories of a shared directory that is available to all SQL Remote users, whether by modem or on a local area network. Each user should have a registry entry, initialization file entry, or SQLREMOTE environment variable pointing to the shared directory.

You can also use the file system to put the messages in directories on the consolidated and remote machines. A simple file transfer mechanism can then be used to exchange the files periodically to effect replication.

FILE message control parameters

The FILE message system uses the following control parameters:

•	Directory    This is set to the directory under which the messages are stored. The setting is an alternative to the SQLREMOTE environment variable.

•	Debug    This is set to either YES or NO, with the default being NO. When set to YES, all file system calls made by the FILE link are displayed.

The FILE section of the sqlany.ini file (Windows 3.x) has the following entries:

[ FILE ]

Directory=path

Debug={ yes | no }

On NetWare, you should create a file named dbremote.ini in the sys:\system directory to hold the directory setting.


The ftp message system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

 The ftp message system

Addresses for ftp

In the ftp message system, messages are stored in directories under a root directory on an ftp host. The ftp host and the root directory are specified by message system control parameters held in the registry or initialization file, and the address of each user is the subdirectory where their messages are held.

  For a list of operating systems for which ftp is supported, see Supported operating systems.

FTP message control parameters

The ftp message system uses the following control parameters:

•	host    The host name of the computer where the messages are stored. This can be a host name (such as ftp.powersoft.com) or an IP address (such as 192.138.151.66).

•	user    The user name for accessing the ftp host.

•	password    The password for accessing the ftp host.

•	root_directory    The root directory within the ftp host site, under which the messages are stored.

•	port    Usually not required. This is the IP port number used for the Ftp connection.

•	debug    This is set to either YES or NO, with the default being NO. When set to YES, debugging output is displayed.

•	active_mode    This is set to either YES or NO, with the default being NO (passive mode).

 Troubleshooting ftp problems


Troubleshooting ftp problems
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

          The ftp message system

 Troubleshooting ftp problems

Most problems with the FTP message link are network setup issues. This section contains a list of tests you can try to troubleshoot problems.

Set the DEBUG message control parameter    Looking over the debug output should indicate whether you are connecting to the FTP server. If you are connecting, it will indicate which FTP commands are failing.

Ping the ftp server    If the FTP link is not able to connect to the FTP server try testing your systems network configuration; If your system has the ping command try typing the following command:

ping ftp-server-name

You should see output indicating the IP address of the server and the ping (round trip) time to the server. If you can not ping the server than you have a network configuration problem, and you should contact you network administrator.

Check that passive mode works    If the FTP link is connecting to the FTP server, but is unable to open a data connection, make sure that an FTP client can use passive mode to transfer data with the server.

Passive mode is the preferred transfer mode and the default for the FTP message link. In passive mode all data transfer connections are initiated by the client, in this case the message link. In Active mode the server initiates all data connections. If your FTP server is sitting behind an incorrectly configured firewall you may not be able to use the default passive transfer mode. In this situation the firewall blocks socket connections to the FTP server on ports other than the FTP control port.

Using an FTP user program that allows you to set the transfer mode between active and passive, set the transfer mode to passive and try to upload/download a file. If the client you are using cannot transfer the file without using active mode than you should either reconfigure the firewall and FTP server to allow passive mode transfers or set the active_mode message control parameter to YES. Active mode transfers may not work in all network configurations. For example: if your client is sitting behind an IP masquerading gateway incoming connections may fail depending on you gateway software.

Check permissions and directory structures    If the FTP server is connecting and having problems getting directory listings or manipulating files; make sure your permissions are set up correctly and the directories that you need exist.

Log into the FTP server using an FTP program. Change directories to the location stored in the root_directory parameter. If the directories you need do not show up, the root_directory control parameter may be wrong or the directories may not exist.

Test permissions by fetching a file in your message directory and uploading a file to the consolidated databases directory. If you get errors your FTP server permissions are set up incorrectly.


The SMTP message system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

 The SMTP message system

The Simple Mail Transfer Protocol (SMTP) is used in Internet e-mail products.

With the SMTP system, SQL Remote sends messages using Internet mail. The messages are encoded to a text format and sent in an e-mail message to the target database. The messages are sent using an SMTP server, and retrieved from a POP server: this is the way that many e-mail programs send and receive messages.

  For a list of operating systems for which SMTP is supported, see Supported operating systems.

SMTP addresses and user IDs

To use SQL Remote and an SMTP message system, each database participating in the setup requires a SMTP address, and a POP3 user ID and password. These are distinct identifiers: the SMTP address is the destination of each message, and the POP3 user ID and password are the name and password entered by a user when they connect to their mail box.

Separate e-mail account recommended
It is recommended that a separate POP e-mail account be used for SQL Remote messages.

Troubleshooting

If you can not get the SMTP Link to work try connecting to the SMTP/POP3 server from the same machine on which the Message Agent is running using the same account and password. Use an Internet e-mail program that supports SMTP/POP3 and make sure to disable the program once the SMTP message link is working.

SMTP message control parameters

Before the Message Agent connects to the message system to send or receive messages, the user must either have a set of control parameters already set on their machine, or must fill in a window with the needed information. This information is needed only on the first connection. It is saved and used as the default entries on subsequent connects.

The SMTP message system uses the following control parameters:

•	local_host    This is the name of the local computer. It is useful on machines where SQL Remote is unable to determine the local host name. The local host name is needed to initiate a session with any SMTP server. In most network environments, the local host name can be determined automatically and this entry is not needed.

•	TOP_supported    SQL Remote uses a POP3 command called TOP when enumerating incoming messages. The TOP command may not be supported by all POP servers. Setting this entry to NO will use the RETR command, which is less efficient but will work with all POP servers. The default is YES.

•	smtp_host    This is the name of the computer on which the SMTP server is running. It corresponds to the SMTP host field in the SMTP/POP3 login dialog.

•	pop3_host    This is the name of the computer on which the POP host is running. It is commonly the same as the SMTP host. It corresponds to the POP3 host field in the SMTP/POP3 login dialog.

•	pop3_userid    This is used to retrieve mail. The POP user ID corresponds to the user ID field in the SMTP/POP3 login dialog. You must obtain a user ID from your POP host administrator.

•	pop3_password    This is used to retrieve mail. It corresponds to the password field in the SMTP/POP3 login dialog. If all of these five fields are set, the login dialog is not displayed.

•	Debug    When set to YES, displays all SMTP and POP3 commands and responses. This is useful for troubleshooting SMTP/POP support problems. Default is NO.

The SMTP section of the sqlany.ini file (Windows 3.x) has the following entries:

[SMTP]

smtp_host=smtp_host

pop3_host=pop3_host

pop3_userid=userid

pop3_password=password

Debug={ yes | no }

 Sharing SMTP/POP addresses


Sharing SMTP/POP addresses
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

          The SMTP message system

 Sharing SMTP/POP addresses

The database should have its own e-mail account for SQL Remote messages, separate from personal e-mail messages intended for reading. This is because many e-mail readers will collect e-mail in the following manner:

1	Connect to the POP Host and download all messages.

2	Delete all messages from POP Host

3	Disconnect from POP Host.

4	Read mail from the local file or from memory

This causes a problem, as the e-mail program downloads and deletes all of the SQL Remote e-mail messages as well as personal messages. If you are certain that your e-mail program will not delete unread messages from the POP Host then you may share an e-mail address with the database as long as you take care not to delete or alter the database messages.

These messages are easy to recognize, as they are filled with lines of seemingly random text.


The MAPI message system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

 The MAPI message system

The Message Application Programming Interface (MAPI) is used in several popular e-mail systems, such as Microsoft Mail and later versions of Lotus cc:Mail. SQL Remote supports the MAPI message system under Windows 3.x, Windows 95/98, and Windows NT.

  For a list of operating systems for which MAPI is supported, see Supported operating systems.

MAPI addresses and user IDs

To use SQL Remote and a MAPI message system, each database participating in the setup requires a MAPI user ID and address. These are distinct identifiers: the MAPI address is the destination of each message, and the MAPI user ID is the name entered by a user when they connect to their mail box.

MAPI message and the e-mail inbox

Although SQL Remote messages may arrive in the same mail box as e-mail intended for reading, they do not in general show up in your e-mail inbox.

SQL Remote sends application-defined messages, which MAPI identifies and hides when the mailbox is opened. In this way, users can use the same e-mail address and same connection to receive their personal e-mail and their database updates, yet the SQL Remote messages do not interfere with the mail intended for reading.

If a message is routed via the Internet, the special message type information is lost. The message then does show up in the recipient's mailbox.

MAPI message control parameters

The MAPI message system uses the following control parameters:

•	Debug    When set to YES, displays all MAPI calls and the return codes. This is useful for troubleshooting MAPI support problems. Default is NO.

•	Force_Download     (default YES) controls if the MAPI_FORCE_DOWNLOAD flag is set when calling MapiLogon. This might be useful when using remote mail software that dials when this flag is set.

•	IPM_Receive    This can be set to YES or NO (default NO). If set to YES, the MAPI link receives IPM messages, which are visible in the mailbox. If set to NO, the MAPI link receives IPC messages, which are not visible in the mailbox. This may be useful if your MAPI provider does not support IPC messages. Also, it may be useful when receiving messages over the Internet. In this case, the sender might not be using MAPI or the IPC attributes are have been lost.

•	IPM_Send    This can be set to YES or NO (default NO). If set to YES, the MAPI link sends IPM messages, which are visible in the mailbox. If set to NO, the MAPI link sends IPC messages, which are not visible in the mailbox. This may be useful if your MAPI provider does not support IPC messages.

•	Profile    Use the specified Microsoft Exchange profile. You should use this if you are running the Message Agent as a service.

The MAPI section of the sqlany.ini file (Windows 3.x) has the following entries:

[ MAPI ]

IPM_Send={yes |no }

IPM_Receive={ yes |no }

Force_Download={yes |no }

Debug={yes | no}


The VIM message system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Using message types

 The VIM message system

The Vendor Independent Messaging system (VIM) is used in Lotus Notes and in some releases of Lotus cc:Mail.

To use SQL Remote and a VIM message system, each database participating in the setup requires a VIM user ID and address. These are distinct identifiers: the VIM address is the destination of each message, and the VIM user ID is the name entered by a user when they connect to their mail box.

  For a list of operating systems for which VIM is supported, see Supported operating systems.

VIM message control parameters

The VIM message system uses the following control parameters:

•	Path    This corresponds to the Path field in the cc:Mail login dialog. It is not applicable to and is ignored under Lotus Notes.

•	Userid    This corresponds to the User ID field in the cc:Mail login dialog.

•	Password    This corresponds to the Password field in the cc:Mail login dialog. If all of Path, Userid, and Password are set, the login dialog is not displayed.

•	Debug    When set to YES, displays all VIM calls and the return codes. This is useful for troubleshooting VIM support problems. Default is NO.

•	Receive_All    When set to YES, the Message Agent checks all messages to see if they are SQL Remote messages. When set to NO (the defaut), the Message Agent looks only for messages of the application-defined type SQLRemoteData. This leads to improved performance in Notes.

Setting ReceiveAll to YES is useful in setups where the message type is lost, reset, or never set. This includes setups including cc:Mail messages, or over the Internet.

•	Send_VIM_Mail    When set to YES, the Message Agent sends messages compatible with Adaptive Server Anywhere releases before 5.5.01, and compatible with cc:Mail. If this is set to YES, you should ensure that Receive_All is set to YES also.

The VIM section of the sqlany.ini file (Windows 3.x) has the following entries:

[ VIM ]

Path=path

Userid=userid

Password=password

Debug={yes | no}

Receive_All = {yes | no}

Send_VIM_Mail = {yes | no}


Running the Message Agent
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

 Running the Message Agent

The SQL Remote Message Agent is a key component in SQL Remote replication. The Message Agent handles both the sending and receiving of messages. It carries out the following functions:

•	It processes incoming messages, and applies them in the proper order to the database.

•	It scans the transaction log or stable queue at each publisher database, and translates the log entries into messages for subscribers.

•	It parcels the log entries up into messages no larger than a fixed maximum size (50,000 bytes by default), and sends them to subscribers.

•	It maintains the message tracking information in the system tables, and manages the guaranteed transmission mechanism.

Executable names

On Windows operating systems, the Message Agent for Adaptive Server Enterprise is named ssremote.exe, and the Message Agent for Adaptive Server Anywhere is named dbremote.exe. On UNIX operating systems, the names are ssremote and dbremote, respectively.

  The Message Agent for Adaptive Server Enterprise uses a stable queue to hold transactions until they are no longer needed. For more information on the stable queue, see How the Message Agent for Adaptive Server Enterprise works.

 Message Agent batch and continuous modes

 Connections used by the Message Agent

 Replication system recovery procedures

 Ensuring consistent Message Agent settings

 The Message Agent and replication security


Message Agent batch and continuous modes
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Running the Message Agent

 Message Agent batch and continuous modes

The Message Agent can be run in one of two modes:

•	Batch mode    In batch mode, the Message Agent starts, receives and sends all messages that can be received and sent, and then shuts down.

Batch mode is useful at occasionally-connected remote sites, where messages can only be exchanged with the consolidated database when the connection is made: for example, when the remote site dials up to the main network.

•	Continuous mode    In continuous mode, the Message Agent periodically sends messages, at times specified in the properties of each remote user. When it is not sending messages, it receives messages as they arrive.

Continuous mode is useful at consolidated sites, where messages may be coming in and going out at any time, to spread out the workload and to ensure prompt replication.

The options available depend on the send frequency options selected for the remote users. Sending frequency options are described in Selecting a send frequency.

♦ To run the Message Agent in continuous mode:

1	Ensure that every user has a sending frequency specified. The sending frequency is specified by a SEND AT or SEND EVERY option in the GRANT REMOTE statement (Adaptive Server Anywhere) or sp_grant_remote procedure (Adaptive Server Enterprise).

2	Start the Message Agent without using the -b command-line switch.

♦ To run the Message Agent in batch mode:

•	Either:

•	Have at least one remote user who has neither a SEND AT nor a SEND EVERY option in their remote properties, or

•	Start the Message Agent using the -b command-line switch.


Connections used by the Message Agent
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Running the Message Agent

 Connections used by the Message Agent

The Message Agent uses a number of connections to the database server. These are:

•	One global connection, alive all the time the Message Agent is running.

•	One connection for scanning the log. This connection is alive during the scan phase only.

•	One connection for executing commands from the log-scanning thread. This connection is alive during the scan phase only.

•	One connection for the stable queue (Adaptive Server Enterprise only). This connection is alive during the scan and send phases.

•	One connection for processing synchronize subscription requests. This connection is alive during the send phase only.

•	One connection for each worker thread. These connections are alive during the receive phase only.


Replication system recovery procedures
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Running the Message Agent

 Replication system recovery procedures

SQL Remote replication places new requirements on data recovery practices at consolidated database sites. Standard backup and recovery procedures enable recovery of data from system or media failure. In a replication installation, even if such recovery is achieved, the recovered database can be out of synch with remote databases. This can require a complete resynchronization of remote databases, which can be a formidable task if the installation involves large numbers of databases.

In short, recovery of the consolidated database from a failure at the consolidated site is only part of the task of recovering the entire replication installation.

Protection of the replication system against media failures has two aspects:

•	Backup and log management    Solid backup procedures and log management procedures for the consolidated database server are  an essential part of recovery plans. Backup procedures protect against media failure on the database device. Using a transaction log mirror protects against media failure on the transaction log device.

  For more information about backup and log management procedures, see the sections Transaction log and backup management and Adaptive Server Enterprise transaction log and backup management.

•	Message Agent configuration    The Message Agent command-line options provide ways for you to tune Message Agent behavior to match your backup and recovery requirements.

Message Agent configuration is discussed in the following pages.

Replicating only backed-up transactions

By default, the Message Agent processes all committed transactions. When the Message Agent is run with the -u command-line switch, only transactions that have been backed up by the database backup commands are processed.

For Adaptive Server Anywhere, transaction log backup is carried out using Sybase Central or the dbbackup command-line utility, or off-line copying and renaming of the log file. For Adaptive Server Enterprise, transaction log backup is carried out using the dump transaction statement.

By sending only backed-up transactions, the replication installation is protected against media failure on the transaction log. Maintaining a mirrored transaction log also accomplishes this goal.

The -u switch provides additional protection against total site failure, if backups are carried out to another site.


Ensuring consistent Message Agent settings
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Running the Message Agent

 Ensuring consistent Message Agent settings

Some Message Agent settings need to be the same throughout an installation, and so should be set before deployment. This section lists the settings that need to be the same.

•	Maximum message length    The maximum message length for SQL Remote messages has a default value of 50K. This is configurable, using the Message Agent -l command-line switch. However, the maximum message length must be the same for each Message Agent in the installation, and may be restricted by operating system memory allocation limits.

Received messages that are longer than the limit are deleted as corrupt messages.

  For details of this setting, see The Message Agent.


The Message Agent and replication security
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Running the Message Agent

 The Message Agent and replication security

Messages sent by the SQL Remote Message Agent have a very simple encryption that protects against casual snooping. However, the encryption scheme is not intended to provide full protection against determined efforts to decipher them.


Tuning Message Agent performance
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

 Tuning Message Agent performance

Who needs to read this section?    If performance is not a problem at your site, you do not need to read this section.

There are several options you can use to tune the performance of the Message Agent. This section describes those options.

Sending messages and receiving messages are two separate processes. The major performance issues for these two processes are different.

•	Replication throughput    The major bottleneck for total throughput of SQL Remote sites is generally receiving messages from many remote databases and applying them to the database at the consolidated site. You can control this step by tuning the receive process of the Message Agent at the consolidated site.

•	Replication turnaround    The time lag from when data is entered at one site to when it appears at other sites is the turnaround time for replication. You can control this time lag.

 Tuning throughput by controlling Message Agent threading

 Tuning throughput by caching messages

 Tuning incoming message polling

 Tuning the message sending process


Tuning throughput by controlling Message Agent threading
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

 Tuning throughput by controlling Message Agent threading

It is assumed in this section that you are tuning the performance of a Message Agent that is running in continuous mode at a consolidated site.

Worker threads can be used by the Message Agent to apply incoming messages from remote users. This can improve throughput by allowing messages to be applied in parallel rather than serially.

Setting the number of worker threads

The number of worker threads is set on the Message Agent command line, using the -w switch. The following command line starts the Message Agent for Adaptive Server Enterprise with twenty worker threads applying messages:

ssremote -c "eng=..." -w 20

The default is to use no worker threads, so that all messages are applied serially. The maximum number of worker threads is 50.

Performance benefits from worker threads

For the Message Agent for Adaptive Server Anywhere, the performance advantage will be most significant when the server is on a system with a striped drive array.

For Adaptive Server Enterprise, the Message Agent will benefit even more if the Server is used with multiple engines configured.

What messages are applied in parallel

When worker threads are being used, messages from different remote users are applied in parallel. Messages from a single remote user are applied serially. For example, ten messages from a single remote user will be applied by a single worker thread in the correct order.

Deadlock is handled by re-applying the rolled back transaction at a later time.

Reading messages from the message system is single-threaded. Messages are read and the header information is examined (to determine the remote user and the correct order of application) before passing them off to worker threads to be applied.

Building messages and sending messages is single-threaded.

Open Client version

To use multiple worker threads with the Adaptive Server Enterprise Message Agent, you need to be using Open Client version 11.1 or above.

The Message Agent prints a message and then does not use worker threads when pre-11.1 versions are being used. The Open Client version is displayed in the first few lines of the Message Agent output.


Tuning throughput by caching messages
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

 Tuning throughput by caching messages

The Message Agent caches incoming messages in a configurable area of memory as it reads them.

Specifying the message cache size

The size of the message cache is specified on the Message Agent command line, using the -m command-line switch.

The -m option specifies the maximum amount of memory to be used by the Message Agent for building messages. The allowed size can be specified as n (in bytes), nK, or nM. The default is 2048K (2M).

Example

The following command line starts an Adaptive Server Anywhere Message Agent using twelve Megabytes of memory as a message cache:

dbremote -c "eng=..." -m 12M

How messages are cached

When transactions are large, or messages arrive out of order, they are stored in memory by the Message Agent until the message is to be applied. This caching of messages prevents rereading of out-of-order messages from the message system , which may lower performance on large installations. It is especially important when messages are being read over a WAN (such as Remote Access Services or POP3 through a modem). It also avoids contention between worker threads reading messages (a single threaded task) because the message contents are cached.

When the memory usage specified using the -m switch is exceeded, messages are flushed in a least-recently-used fashion.

This switch is provided primarily for customers considering a single consolidated database for thousands of remote databases.


Tuning incoming message polling
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

 Tuning incoming message polling

When running a Message Agent in continuous mode, typically at a consolidated database site, you can control how often it polls for incoming messages, and how "patient" it is in waiting for messages that arrive out of order before requesting that the message be resent. Tuning these aspects of the behavior can have a significant effect on performance in some circumstances.

Issues to consider

The issues to consider when tuning the message-receiving process are similar to those when tuning the message-sending process.

•	Regular messages    Your choices dictate how often the Message Agent polls for incoming messages from remote databases.

•	Resend requests    You can control how many polls to wait until an out-of-order message arrives, before requesting that it be resent.

•	Processing incoming messages    If your polling period for incoming messages is too long, compared to the frequency with which messages are arriving, you could end up with messages sitting in the queue, waiting to be processed. If your polling period is too short, you will waster resources polling when no messages are in the queue.

  For more information on the message sending process, see Tuning the message sending process.

 Polling interval

 Requesting resends

 Example


Polling interval
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

          Tuning incoming message polling

 Polling interval

By default, a Message Agent running in continuous mode polls one minute after finishing the previous poll, to see whether new messages have arrived. You can configure the polling interval using the -rd command-line option.

The default polling interval from the end of one poll to the start of another is one minute. You can poll more frequently using a value in seconds, as in the following command line:

dbremote -rd 30s

Alternatively, you can poll less frequently, as in the following command line, which polls every five minutes:

dbremote -rd 5

Setting a very small interval may have some detrimental impact on overall system throughput, for the following reasons:

•	Each poll of the mail server (if you are using e-mail) places a load on your message system. Too-frequent polling may affect your message system and produce no benefits.

•	If you do not modify the Message Agent patience before it assumes that an out of sequence message is lost, and requests it be sent again, you can flood your system with resend requests.

In general, you should not use a very small polling interval unless you have a specific reason for requiring a very quick response time for messages.

Setting larger intervals may provide a better overall throughput of messages in your system, at the cost of waiting somewhat longer for each message to be applied. In many SQL Remote installations, optimizing turnaround time is not the primary concern.


Requesting resends
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

          Tuning incoming message polling

 Requesting resends

If, when the Message Agent polls for incoming messages, one message is missing from a sequence, the Message Agent does not immediately request that the message be resent. Instead, it has a default patience of one poll.

If the next message expected is number 6 and message 7 is found, the Message Agent takes no action until the next poll. Then, if no new message for that user is found, it issues a resend request.

You can change the number of polls for which the Message Agent waits before sending a request using the -rp command-line option. This option is often used in conjunction with the -rd option that sets the polling interval.

For example, if you have a very small polling interval, and a message system that does not preserver the order in which messages arrive, it may be very common for out-of-sync messages to arrive only after two or three polls have been completed. In such a case, you should instruct the Message Agent to be more patient before sending a resend request, by increasing the -rp value. If you do not do this, a large number of unnecessary resend requests may be sent.


Example
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

          Tuning incoming message polling

 Example

Suppose there are two remote users, named user1 and user2, and suppose the Message Agent command line is as follows:

dbremote -rd 30s -rp 3

In the following sequence of operations, messages are marked as userX.n so that user1.5 is the sixth message from user1. The Message Agent expects messages to start at number 1 for both users.

At time 0 seconds:

1	The Message Agent reads user1.1, user2.4

2	The Message Agent applies user1.1

3	The Message Agent patience is now user1: N/A, user2: 3, as an out of sequence message has arrived from user 2.

At time 30 seconds:

1	The Message Agent reads: no new messages

2	The Message Agent applies: none

3	The Message Agent patience is now user1: N/A, user2: 2

At time 60 seconds:

1	The Message Agent reads: user1.3

2	The Message Agent applies: no new messages

3	The Message Agent patience: user1: 3, user2: 1

At time 90 seconds:

1	The Message Agent reads: user1.4

2	The Message Agent applies: none

3	The Message Agent patience user1: 3, user2: 0

4	The Message Agent issues resend to user2.

When a user receives a new message, it resets the Message Agent patience even if that message is not the one expected.


Tuning the message sending process
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

 Tuning the message sending process

The turnaround time for replication is governed by how often each sites sends messages and how often each site polls for incoming messages. To achieve a small time lag between data entry and data replication, you can set a small value for the -sd Message Agent command-line option, which controls the frequency for polling to see if more data needs to be sent.

Issues to consider

The issues to consider when tuning the message-sending process are similar to those when tuning the incoming-message polling frequency:

•	Regular messages    Your choices dictate how often updates are sent to remote databases.

•	Resend requests    When a remote user requests that a message be resent, the Message Agent needs to take special action that can interrupt regular message sending. You can control the urgency with which these resend requests are processed.

•	Number and size of messages    If you send messages very frequently, there is more chance of small messages being sent. Sending messages less frequently allows more instructions to be grouped in a single message. If a large number of small messages is a concern for your message system, then you may have to avoid using very small polling periods.

  For more information on tuning polling for the incoming-messages, see Tuning incoming message polling.

 Polling interval

 Resending messages


Polling interval
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

          Tuning the message sending process

 Polling interval

You control the interval to wait between polls for more data from the transaction log to send using the -sd command-line option, which has a default of one minute. The following example sets the polling interval to 30 seconds:

dbremote -sd 30s ...

Alternatively, you can poll less frequently, as in the following command line, which polls every five minutes:

dbremote -sd 5

Setting a very small interval may have some detrimental impact on overall system throughput, for the following reasons:

•	Too-frequent polling produces many short messages. If the message load places a strain on your message system, throughput could be affected.

Setting larger intervals may provide a better overall throughput of messages in your system, at the cost of waiting somewhat longer for each message to be applied. In many SQL Remote installations, optimizing turnaround time is not the primary concern.


Resending messages
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Tuning Message Agent performance

          Tuning the message sending process

 Resending messages

When a user requests that a message be resent, the message has to be retrieved from early in the transaction log. Going back in the transaction log to retrieve this message and send it causes the Message Agent to interrupt the regular sending process. If you are tuning your SQL Remote installation for optimum performance, you must balance the urgency of sending requests for resent messages with the priority of processing regular messages.

The -ru command-line option controls the urgency of the resend requests. The value for the parameter is a time in minutes (or in other units if you add s or h to the end of the number), with a default of zero.

To help the Message Agent  delay processing resend requests until more have arrived before interrupting the regular message sending activity, set this option to a longer time.

The following command line waits one hour until processing a resend request.

dbremote -ru 1h ...

If you do not specify the -ru option, then a default value is picked by the Message Agent, based on the send interval of the users that have requested that data be resent. The elapsed time between receiving a resend request for a user and rescanning the log does not exceed half of the send interval for that user.


Encoding and compressing messages
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

 Encoding and compressing messages

As messages pass through e-mail and other message systems, there is a danger of them becoming corrupted. For example, some message systems use certain characters or character combinations as control characters.

Message size affects the efficiency with which messages pass through a system. Compressed messages can be processed more efficiently by a message system than uncompressed messages. On the other hand, carrying out compression can itself take a significant amount of time.

SQL Remote encoding and compression

SQL Remote has a message encoding and compression scheme built in to the Message Agent. The scheme provides the following features:

•	Compatibility    The system can be set up to be compatible with previous versions of the software.

•	Compression    You can select a level of compression for your messages.

•	Encoding    SQL Remote encodes messages to ensure that they pass through message systems uncorrupted. The encoding scheme can be customized to provide extra features.

Settings for compatibility

To be compatible with previous versions of the software, you should set the database option COMPRESSION to be -1 (minus one) at each database running the Version 6 software. This setting ensures that messages are sent out in a format compatible with older versions of the software.

Upgrading SQL Remote

If you upgrade the consolidated database Message Agent first, you should set its COMPRESSION database option to -1. As each remote site in your replication system is upgraded to Version 6, you can change its setting of the COMPRESSION option to a value between 0 (no compression) and 9 (maximum compression). This allows you to take advantage of compression features on messages being sent to the consolidated database. Once all remote sites are upgraded, you can set the consolidated site Message Agent COMPRESSION option to a value other than -1.

In addition, setting COMPRESSION to a value other than -1 allows you to take advantage of the Version 6 message encoding improvements.

 The encoding scheme

 Creating custom encoding schemes


The encoding scheme
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Encoding and compressing messages

 The encoding scheme

The default message-encoding behavior of SQL Remote is as follows:

•	For message systems that can use binary message formats, no encoding is carried out.

•	Some message systems, including SMTP, VIM, and MAPI, require text-based message formats. For these systems, an encoding DLL (dbencod.dll for Adaptive Server Anywhere and ssencod.dll for Adaptive Server Enterprise) translates messages into a text format before sending. The message format is unencoded at the receiving end using the same DLL.

•	You can instruct SQL Remote to use a custom encoding scheme. The tools for building a custom encoding scheme are described in the following section.

•	If the COMPRESSION database option is set to -1, then a Version 5 compatible encoding is carried out for all message systems.


Creating custom encoding schemes
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        Encoding and compressing messages

 Creating custom encoding schemes

You can implement a custom encoding scheme by building a custom encoding DLL. You could use this DLL to apply special features required for a particular messages system, or to collect statistics, such as how many messages or how many bytes were sent to each user.

The header file dbrmt.h, installed into the h subdirectory of your installation directory, provides an application programming interface for building such a scheme.

To instruct SQL Remote to use your DLL for a particular message system, you must make a registry entry for that system. The registry entry should be made in the following location:

Software

    \Sybase

         \SQL Remote

              \message-system

                     \encode_dll

where message-system is one of the SQL Remote message systems (file, smtp, and so on). You should set this registry entry to the name of your encoding DLL.

Encoding and decoding must be compatible
If you implement a custom encoding, you must make sure that the DLL is present at the receiving end, and that the DLL is in place to decode your messages properly.


The message tracking system
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

 The message tracking system

SQL Remote has a message tracking system to ensure that all replicated operations are applied in the correct order, no operations are missed, and no operation is applied twice.

Message system failures may lead to replication messages not reaching their destination, or reaching it in a corrupt state. Also, messages may arrive at their destination in a different order from that in which they were sent. This section describes the SQL Remote system for detecting and correcting message system errors, and for ensuring correct application of messages.

If you are using an e-mail message system, you should confirm that e-mail is working properly between the two machines if SQL Remote messages are not being sent and received properly.

The SQL Remote message tracking system is based on status information maintained in the remoteuser SQL Remote system table. The table is maintained by the Message Agent. The Message Agent at a subscriber database sends confirmation to the publisher database to ensure that remoteuser is maintained properly at each end of the subscription.

For Adaptive Server Anywhere, the remoteuser table is the sys.sysremoteuser system table. For Adaptive Server Enterprise, this is the sr_remoteuser table.

 Status information in the remoteuser table

 Tracking messages by transaction log offsets

 Handling of lost or corrupt messages


Status information in the remoteuser table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        The message tracking system

 Status information in the remoteuser table

The remoteuser SQL Remote system table contains a row for each subscriber, with status information for messages sent to and received by that subscriber. At the consolidated database, remoteuser contains a row for each remote user. At each remote database, remoteuser contains a single row maintaining information for the consolidated database. (Recall that the consolidated database subscribes to publications from the remote database.)

The remoteuser SQL Remote system table at each end of a subscription is maintained by the Message Agent.


Tracking messages by transaction log offsets
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        The message tracking system

 Tracking messages by transaction log offsets

The message-tracking status information takes the form of offsets in the transaction logs of the publisher and subscriber databases. Each COMMIT is marked in the transaction log by a well-defined offset. The order of transactions can be determined by comparing their offset values.

Message ordering

When messages are sent, they are ordered by the offset of the last COMMIT of the preceding message. If a transaction spans several messages, there is a serial number within the transaction to order the messages correctly. The default maximum message size is 50,000 bytes, but you can use the Message Agent -l command-line switch to change this setting.

Sending messages

The log_sent column holds the local transaction log offset for the latest message sent to the subscriber. When the Message Agent sends a message, it sets the log_sent value to the offset of the last COMMIT in the message. Once the message has been received and applied at the subscribed database, confirmation is sent back to the publisher. When the publisher Message Agent receives the confirmation, it sets the confirm_sent column for that subscriber with the local transaction log offset. Both log_sent and confirm_sent are offsets in the local database transaction log, and confirm_sent cannot be a later offset than log_sent.

Receiving messages

When the Message Agent at a subscriber database receives and applies a replication update, it updates the log_received column with the offset of the last COMMIT in the message. The log_received column at any subscriber database therefore contains a transaction log offset in the publisher database's transaction log. After the operations have been received and applied, the Message Agent sends confirmation back to the publisher database and also sets the confirm_received value in the local SYSREMOTEUSER table. The confirm_received column at any subscriber database contains a transaction log offset in the publisher database's transaction log.

Subscriptions are two-way

SQL Remote subscriptions are two-way operations: each remote database is a subscriber to publications of the consolidated database and the consolidated database subscribes to a matching publication from each remote database. Therefore, the remoteuser SQL Remote system tables at the consolidated and remote database hold complementary information.

The Message Agent applies transactions and updates the log_received value atomically. If a message contains several transactions, and a failure occurs while a message is being applied, the log_received value corresponds exactly to what has been applied and committed.

Resending messages

The remoteuser SQL Remote table contains two other columns that handle resending messages. The resend_count and rereceive_count columns are retry counts that are incremented when messages get lost or deleted for some reason.

In general, the log_send column has the same value as the log_sent column. However, if the log_send has a value that is greater than log_sent, the Message Agent sends messages to the subscriber immediately on its next run.


Handling of lost or corrupt messages
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 18.  SQL Remote Administration

        The message tracking system

 Handling of lost or corrupt messages

When messages are received at a subscriber database, the Message Agent applies them in the correct order (determined from the log offsets) and sends confirmation to the publisher. If a message is missing, the Message Agent increments the local value of rereceive_count, and requests that it be resent. Other messages present or en route are not applied.

The request from a subscriber to resend a message increments the resend_count value at the publisher database, and also sets the publisher's log_sent value to the value of confirm_sent. This resetting of the log_sent value causes operations to be resent.

Users cannot reset log_sent
The log_sent value cannot be reset by a user, as it is in a system table.

Message identification

Each message is identified by three values:

•	Its resend_count.

•	The transaction log offset of the last COMMIT in the previous message.

•	A serial number within transactions, for transactions that span messages.

Messages with a resend_count value smaller than rereceive_count are not applied; they are deleted. This ensures that operations are not applied more than once.


CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

About this chapter

This chapter details set-up, and management issues for SQL Remote administrators using Adaptive Server Anywhere as a consolidated database.

 Running the Message Agent

 Error reporting and handling

 Transaction log and backup management

 Using passthrough mode


Running the Message Agent
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

 Running the Message Agent

This section describes how to run the Message Agent for Adaptive Server Anywhere.

  For information on features of the Message Agent that are common to Adaptive Server Anywhere and Adaptive Server Enterprise, see SQL Remote Administration.

 Starting the Message Agent

 Running the Message Agent as a service

 The Message Agent and replication security


Starting the Message Agent
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Running the Message Agent

 Starting the Message Agent

The Message Agent has a set of command-line switches that control its behavior. The only command-line switch that is required for the Message Agent to run is the connection parameters switch (-c).

  For more information on connection parameters, see Connection parameters.

Verbose keyword	Short form	Argument
DatabaseFile	DBF	string
DatabaseName	DBN	string
DatabaseSwitches	DBS	string
EngineName	ENG	string
Password	PWD	string
Start	Start	string
Userid	UID	string


Running the Message Agent as a service
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Running the Message Agent

 Running the Message Agent as a service

If you are running the Message Agent in continuous mode (not batch mode), on Windows NT or Windows 95, you may wish to keep the Message Agent running all the time that the server is running.

You can do this by running the Message Agent as a service under Windows NT or Windows 95. A service for Windows NT can be configured to keep running even when the current user logs out, and to start as soon as the operating system is started.

  For a full description of running programs as services, see Running the Database Server.


The Message Agent and replication security
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Running the Message Agent

 The Message Agent and replication security

In the tutorials in the previous chapter, the Message Agent was run using a user ID with DBA permissions. The operations in the messages are carried out from the user ID specified in the Message Agent connection string; by using the user ID DBA, you can be sure that the user has permissions to make all the changes.

In many situations, distributing the DBA user ID and password to all remote database users is an unacceptable practice for security and data privacy reasons. SQL Remote provides a solution that enables the Message Agent to have full access to the database in order to make any changes contained in the messages without creating security problems.

A special permission, REMOTE DBA, has the following properties:

•	No distinct permissions when not connected from the Message Agent    A user ID granted REMOTE DBA authority has no extra privileges on any connection apart from the Message Agent. Therefore, even if the user ID and password for a REMOTE DBA user is widely distributed, there is no security problem. As long as the user ID has no permissions beyond CONNECT granted on the database, no one can use this user ID to access data in the database.

•	Full DBA permissions from the Message Agent    When connecting from the Message Agent, a user ID with REMOTE DBA authority has full DBA permissions on the database.

Using REMOTE DBA permission

A suggested practice is to grant REMOTE DBA authority at the consolidated database to the publisher and to each remote user. When the remote database is extracted, the remote user becomes the publisher of the remote database, and is granted the same permissions they were granted on the consolidated database, including the REMOTE DBA authority which enables them to use this user ID in the Message Agent connection string. Adopting this procedure means that there are no extra user IDs to administer, and each remote user needs to know only one user ID to connect to the database, whether from the Message Agent (which then has full DBA authority) or from any other client application (in which case the REMOTE DBA authority grants them no extra permissions).

Granting REMOTE DBA permission

You can grant REMOTE DBA permissions to a user ID named dbremote as follows:

GRANT REMOTE DBA

TO dbremote

IDENTIFIED BY dbremote

In Adaptive Server Anywhere, you can add the REMOTE DBA authority to a remote user by checking the appropriate option in the New Remote User Wizard.


Error reporting and handling
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

 Error reporting and handling

This section describes how errors are reported and handled by the Message Agent.

 Default error handling

 Ignoring errors

 Implementing error handling procedures


Default error handling
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Error reporting and handling

 Default error handling

The default action taken by the Message Agent when an error occurs is to record the fact in its log output. The Message Agent sends log output to a window or a log file recording its operation. By default, log output is sent to the window only; the -o command-line option sends output to a log file as well.

The Message Agent may print more information in the output log than in the window. The Message Agent log includes the following:

•	Listing of messages applied.

•	Listing of failed SQL statements.

•	Listing of other errors.

UPDATE conflicts are not errors

UPDATE conflicts are not errors, and so are not reported in the Message Agent output.

  For more information on the log file, see The Message Agent.


Ignoring errors
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Error reporting and handling

 Ignoring errors

There may be exceptional cases where you wish to allow an error encountered by the Message Agent when applying SQL statements to go unreported. This may arise when you know the conditions under which the error occurs and are sure that it does not produce inconsistent data and that its consequences can safely be ignored.

To allow errors to go unreported, you can create a BEFORE trigger on the action that causes the known error. The trigger should signal the REMOTE_STATEMENT_FAILED SQLSTATE (5RW09) or SQLCODE (-288) value.

For example, if you wish to quietly fail INSERT statements on a table that fail because of a missing referenced column, you could create a BEFORE INSERT trigger that signals the REMOTE_STATEMENT_FAILED SQLSTATE when the referenced column does not exist. The INSERT statement fails, but the failure is not reported in the Message Agent log.


Implementing error handling procedures
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Error reporting and handling

 Implementing error handling procedures

SQL Remote allows you to carry out some other process in addition to logging a message if an error occurs. The Replication_error database option allows you to specify a stored procedure to be called by the Message Agent when an error occurs. By default no procedure is called.

The procedure must have a single argument of type CHAR, VARCHAR, or LONG VARCHAR. The procedure is called twice: once with the error message and once with the SQL statement that causes the error.

While the option allows you to track and monitor errors in replication, you must still design them out of your setup: this option is not intended to resolve such errors.

For example, the procedure could insert the errors into a table with the current time and remote user ID, and this information can then replicate back to the consolidated database. An application at the consolidated database can create a report or send e-mail to an administrator when errors show up.

  For information on setting the REPLICATION_ERROR option, see SQL Remote options.

 Example: e-mailing notification of errors


Example: e-mailing notification of errors
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Error reporting and handling

          Implementing error handling procedures

 Example: e-mailing notification of errors

You may wish to receive some notification at the consolidated database when the Message Agent encounters errors. This section demonstrates a method to send Email messages to an administrator when an error occurs.

A stored procedure

The stored procedure for this example is called sp_LogReplicationError, and is owned by the user cons. To cause this procedure to be called in the event of an error, set the Replication_error database option using Interactive SQL or Sybase Central:

SET OPTION PUBLIC.Replication_error =

'cons.sp_LogReplicationError'

The following stored procedure implements this notification:

CREATE PROCEDURE cons.sp_LogReplicationError

(IN error_text LONG VARCHAR)

BEGIN

DECLARE current_remote_user CHAR(255);

SET current_remote_user = CURRENT REMOTE USER;

// Log the error

INSERT INTO cons.replication_audit

( remoteuser, errormsg)

VALUES

( current_remote_user, error_text);

COMMIT WORK;

//Now notify the dba an error has occurred

// using email. We only want this information if 	// the error occurred on the consolidated database

// We want the email to contain the error strings 	// the Message Agent is passing to the procedure

IF CURRENT PUBLISHER = 'cons' THEN

CALL sp_notify_dba( error_text );

END IF

END;

The stored procedure calls another stored procedure to manage the sending of Email:

CREATE PROCEDURE sp_notify_dba(in msg long varchar)

BEGIN

DECLARE rc INTEGER;

rc=call xp_startmail(mail_user='davidf');

//If successful logon to mail

IF rc=0 THEN

rc=call xp_sendmail(

recipient='Doe, John; John, Elton',

subject='SQL Remote Error',

"message"=msg);

//If mail sent successfully, stop

IF rc=0 THEN

call xp_stopmail()

END IF

END IF

END;

An audit table

An audit table could be defined as follows:

CREATE TABLE replication_audit (

id 	INTEGER DEFAULT AUTOINCREMENT,

pub	CHAR(30) DEFAULT CURRENT PUBLISHER,

remoteuser	CHAR(30),

errormsg	LONG VARCHAR,

timestamp 	DATETIME DEFAULT CURRENT TIMESTAMP,

PRIMARY KEY (id,pub)

);

The columns have the following meaning:

Column	Description
pub	Current publisher of the database (lets you know at what database it was inserted)
remoteuser	Remote user applying the message (lets you know what database it came from)
errormsg	Error message passed to the Replication_error procedure
Here is a sample insert into the table from the above error:

INSERT INTO cons.replication_audit

(	id,

pub,

remoteuser,

errormsg,

"timestamp")

VALUES

(	1,

'cons',

'sales',

'primary key for table ''reptable'' is not unique (-193)',

'1997/apr/21 16:03:13.836')

COMMIT WORK

Since Adaptive Server Anywhere supports calling external DLLs from stored procedures you can also design a paging system, instead of using Email.

An example of an error

For example, if a row is inserted at the consolidated using the same primary key as one inserted at the remote, the Message Agent displays the following errors:

Received message from "cons" (0-0000000000-0)

SQL statement failed: (-193) primary key for table 'reptable' is not unique

INSERT INTO cons.reptable(id,text,last_contact)

VALUES (2,'dave','1997/apr/21 16:02:38.325')

COMMIT WORK

The messages that arrived in Doe, John and Elton, John's email each had a subject of SQL Remote Error:

primary key for table 'reptable' is not unique (-193)

INSERT INTO cons.reptable(id,text,last_contact) VALUES (2,'dave','1997/apr/21 16:02:52.605')


Transaction log and backup management
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

 Transaction log and backup management

The importance of good backup practices

Replication depends on access to operations in the transaction log, and access to old transaction logs is sometimes required. This section describes how to set up backup procedures at the consolidated and remote databases to ensure proper access to old transaction logs.

It is crucial to have good backup practices at SQL Remote consolidated database sites. A lost transaction log could easily mean having to re-extract remote users. At the consolidated database site, a transaction log mirror is recommended.

  For information on transaction log mirrors and other backup procedure information, see Backup and Data Recovery.

Ensuring access to old transactions

All transaction logs must be guaranteed available until they are no longer needed by the replication system.

In many setups, users of remote databases may receive updates from the office server every day or so. If some messages get lost or deleted, and have to be resent by the message-tracking system, it is possible that changes made several days ago will be required. If a remote user takes a vacation, and messages have been lost in the meantime, changes weeks old may be required. If the transaction log is backed up daily, the log with the changes will no longer be running on the server.

Because the transaction log continually grows in size, space can become a concern. You can use an event handler on transaction log size to rename the log when it reaches a given size. Then you can use the DELETE_OLD_LOGS option to clean up log files that are no longer needed.

  For more information about controlling transaction log size, see the BACKUP statement.

 Setting the transaction log directory

 Backup utility options

 Managing old transaction logs

 Recovery from database media failure for consolidated databases

 Backup procedures at remote databases

 Upgrading consolidated databases

 Unloading and reloading a consolidated database


Setting the transaction log directory
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

 Setting the transaction log directory

When the Message Agent needs to scan transaction logs other than the current log, it looks through all the transaction log files kept in a designated transaction log directory. A setting on the Message Agent command line tells the Message Agent which directory this is.

Example

For example, the following command line tells the Message Agent to look in the directory e:\archive to find old transaction logs. The command must be entered all on one line.

dbremote -c "eng=server_name;uid=dba;pwd=sql" e:\archive

Log names are not important

The Message Agent opens all the files in the transaction log directory to determine which files are logs, so the actual names of the log files are not important.

This section describes how you can set up a backup procedure to ensure that such a directory is kept in proper shape.


Backup utility options
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

 Backup utility options

The Adaptive Server Anywhere backup utility has several options, accessible through Sybase Central wizard selections or through dbbackup command-line switches, that control its behavior.

This section describes two approaches to using the backup utility in SQL Remote consolidated database backups. Backups must ensure that a set of transaction logs suitable for use by the Message Agent is always available.

 Using the live directory as the transaction log directory

 Using the backup directory as the transaction log directory


Using the live directory as the transaction log directory
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

          Backup utility options

 Using the live directory as the transaction log directory

It is recommended that you use the option to rename and restart the transaction log when backing up the consolidated database and remote database transaction logs. For the dbbackup command-line utility, this is the -r command-line switch.

The figure below illustrates a database named consol.db, with a transaction log named consol.log in the same directory. For the sake of simplicity, we consider the log to be in the same directory as the database, although this would not be generally safe practice in a production environment. The directory is named c:\live.

A backup command line

The following command line backs up the database using the rename and restart option:

dbbackup -r -c "uid=dba;pwd=sql" c:\archive

The connection string options would be different for each database.

Effects of the backup

If you back up the transaction log to a directory c:\archive using the rename and restart option, the Backup utility carries out the following tasks:

1	Backs up the transaction log file, creating a backup file c:\archive\consol.log.

2	Renames the existing transaction log file to 971201nn.log, where nn is the lowest available integer, starting at 00.

3	Starts a new transaction log, as consol.log.

After several backups, the live directory contains a set of sequential transaction logs.

A Message Agent command line

You can run the Message Agent with access to these log files using the following command line:

dbremote -c "dbn=hq;..." c:\live


Using the backup directory as the transaction log directory
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

          Backup utility options

 Using the backup directory as the transaction log directory

An alternative procedure is to use the backup directory as the transaction log directory.

Again, the figure below illustrates a database named consol.db, with a transaction log named consol.log in the same directory. For the sake of simplicity, we consider the log to be in the same directory as the database, although this would not be generally safe practice in a production environment. The directory is named c:\live.

A backup command line

The following command line backs up the database using the rename and restart option, and also uses an option to rename the transaction log backup file:

dbbackup -r -k -c "uid=dba;pwd=sql" c:\archive

The connection string options would be different for each database.

Effects of the backup

If you back up the transaction log to a directory c:\archive using the rename and restart option and the log renaming option, the Backup utility carries out the following tasks:

1	Renames the existing transaction log file to 971201nn.log, where nn is the lowest available integer, starting at 00.

2	Backs up the transaction log file to the backup directory, creating a backup file named 971201nn.log

3	Starts a new transaction log, as consol.log.

After several backups, the live directory and also the archive directory contain a set of sequential transaction logs.

A Message Agent command line

You can run the Message Agent with access to these log files using the following command line:

dbremote -c "dbn=hq;..." c:\archive

Old log names different before 5.5.01
Prior to release 5.5.01 of Adaptive Server Anywhere, the old log files were named consol.l00, consol.l01, and so on. The name change was introduced to allow more old logs to be stored. As the Message Agent scans all the files in the specified directory, regardless of their names, the name change should not affect existing applications.


Managing old transaction logs
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

 Managing old transaction logs

All transaction logs must be guaranteed available until they are no longer needed by the replication system: at that point, they can be discarded.

The replication system no longer needs the logs when all remote databases have received and successfully applied the messages contained in the log files. Remote databases confirm the successful receipt of messages from the consolidated database, and the confirmation sets a value in the consolidated database SQL Remote tables (see The message tracking system). The old transaction logs at the consolidated database are no longer needed by SQL Remote when this receipt confirmation has been received from all remote databases.

Using the Delete_old_logs option

You can use the Delete_old_logs database option at the consolidated database to manage old transaction logs automatically.

The DELETE_OLD_LOGS database option is set by default to OFF. If it is set to ON, then the old transaction logs are deleted automatically by the Message Agent when they are no longer needed. A log is no longer needed when all subscribers have confirmed receiving all changes recorded in that log file.

You can set the DELETE_OLD_LOGS option either for the PUBLIC group or just for the user contained in the Message Agent connection string.

Example

•	The following statement sets the public DELETE_OLD_LOGS:

SET OPTION PUBLIC.DELETE_OLD_LOGS = 'ON'


Recovery from database media failure for consolidated databases
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

 Recovery from database media failure for consolidated databases

This section describes how to recover from a media failure on the database device at the consolidated database.

The procedures to follow are easiest to describe if there is only one transaction log file. While this might not be common for consolidated databases, it is described first, followed by a more common but complicated situation with a set of transaction log files.

 Recovery with a single transaction log

 Recovery with multiple transaction logs


Recovery with a single transaction log
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

          Recovery from database media failure for consolidated databases

 Recovery with a single transaction log

In this case, we assume that there is a single transaction log file, which has existed since the database was created. Also, we assume previous backups of the database file have been made and are available, for example on tape.

♦ To recover the database:

1	Make a copy of the database and log file.

2	Restore the database (.db) file, not the log file, from tape into a temporary directory.

3	Start the database using the existing transaction log and the -a command-line switch, to apply the transactions and bring the database file up to date.

4	Start the database in your normal way. Any new activity will be appended to the current transaction log.

Example

This example illustrates recovery using a mirrored transaction log.

Suppose you have a consolidated database file named consol.db in a directory c:\dbdir, and a transaction log file c:\logdir\consol.log which is mirrored to d:\mirdir\consol.mlg.

♦ To recover from media failure on the C drive:

1	Backup the mirrored transaction log d:\mirdir\consol.mlg.

2	Replace the failed hardware and re-install all affected software.

3	Create a temporary directory to perform the recovery in (for example, c:\recover)

4	Restore the most recent backup of the database file, consol.db, to c:\recover\consol.db.

5	Copy the mirror transaction log, d:\mirdir\consol.mlg, to the recovery directory with a .log extension, giving c:\recover\consol.log.

6	Start the database using the following command line:

dbeng7 -a C:\RECOVER\CONSOL.DB

7	Shutdown the database server.

8	Backup the recovered database and transaction log from c:\recover.

9	Copy the files from c:\recover to the appropriate production directories:

•	Copy c:\recover\consol.db to c:\dbdir\consol.db

•	Copy c:\recover\consol.log to c:\dbdir\consol.lOG, and to d:\mirdir\consol.mlg.

10	Restart your system normally.


Recovery with multiple transaction logs
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

          Recovery from database media failure for consolidated databases

 Recovery with multiple transaction logs

If you have a set of transaction logs, the procedure is different. We assume previous backups of the database file have been made and are available, for example on tape.

♦ To recover the database:

1	Make a copy of the database and log file.

2	Restore the database (.db) file, not the log file, from tape into a temporary directory.

3	 In the temporary directory, start the database, applying the old logs using the -a command-line switch, applying the named transaction logs in the correct order.

4	Start the database using the current transaction log and the -a command-line switch, to apply the transactions and bring the database file up to date.

5	Start the database in your normal way. Any new activity will be appended to the current transaction log.

Example

Suppose you have a consolidated database file named c:\dbdir\cons.db. The transaction log file c:\dbdir\cons.log is mirrored to d:\mirdir\cons.mlg.

Assume that you perform full backups weekly, and you perform incremental backups daily using the following command:

dbbackup -c "uid=dba;pwd=sql" -r -t E:\BACKDIR

This command backs up the transaction log cons.log to the directory e:\backdir. The transaction log file is then renamed to dateNN.log, where date is the current date and NN is the next number in sequence, and a new transaction log is started. The directory e:\backdir is then backed up using a third-party utility.

In this scenario you would be running the Message Agent with the optional directory to point to the renamed transaction log files. The Message Agent command line would be

dbremote -c "uid=dba;pwd=sql" C:\DBDIR

On the third day following the weekly backup the database file gets corrupted because of a bad disk block.

♦ To recover from media failure on the C: drive:

1	Backup the mirrored transaction log d:\mirdir\cons.mlg.

2	Create a temporary directory to perform the recovery in. We will call it c:\recover.

3	Restore the most recent backup of the database file, cons.db to c:\recover\cons.db.

4	Apply the renamed transaction logs in order, as follows

dbeng7 -a C:\DBDIR\date00.LOG C:\RECOVER\CONS.DB

dbeng7 -a C:\DBDIR\date01.LOG C:\RECOVER\CONS.DB

5	Copy the current transaction log, c:\dbdir\cons.log to the recovery directory, giving c:\recover\cons.log.

6	Start the database using the following command:

dbeng7 C:\RECOVER\CONS.DB

7	Shutdown the database server.

8	Backup the recovered database and transaction log from c:\recover.

9	Copy the files from c:\recover to the appropriate production directories.

•	Copy c:\recover\cons.db to c:\dbdir\cons.db.

•	Copy c:\recover\cons.log to c:\dbdir\cons.log, and to d:\mirdir\cons.mlg.

10	Restart your system as normal.


Backup procedures at remote databases
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

 Backup procedures at remote databases

Backup procedures are not as crucial at remote databases as at the consolidated database. You may choose to rely on replication to the consolidated database as a data backup method. In the event of a media failure, the remote database would have to be re-extracted from the consolidated database, and any operations that have not been replicated would be lost. (You could use the log translation utility to attempt to recover lost operations.)

Even if you do choose to rely on replication to protect remote database data, backups still need to be done periodically at remote databases to prevent the transaction log from growing too large. You should use the same option (rename and restart the log) as at the consolidated database, running the Message Agent so that it has access to the renamed log files. If you set the DELETE_OLD_LOGS option to ON at the remote database, the old log files will be deleted automatically by the Message Agent when they are no longer needed.

Automatic transaction log renaming

You can use the -x Message Agent command-line switch to eliminate the need to rename the transaction log on the remote computer when the database server is shut down. The -x option renames transaction log after it has been scanned for outgoing messages.


Upgrading consolidated databases
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

 Upgrading consolidated databases

This section describes issues in upgrading a consolidated database in a SQL Remote environment. The same considerations apply to Adaptive Server Anywhere databases that are primary sites in a Sybase Replication Server installation.

Installing new software does not always make new features available. In many cases, new features require the Upgrade utility to be run on databases. The Upgrade utility adds any information to the system catalog required for new features to be available. When you run the Upgrade utility, it tells you to archive the transaction log. The reason for this is that a new transaction log is created by the Upgrade utility, with a new file format.

When using SQL Remote or Replication Server, the transaction log must be kept for the Message Agent and the Replication Agent, respectively. After running the Upgrade utility, you should shut down the engine, rename the log, and leave it for the Message Agent to delete. The log should also be archived for backup purposes.

  For information on the Upgrade utility, see The Upgrade utility.


Unloading and reloading a consolidated database
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Transaction log and backup management

 Unloading and reloading a consolidated database

If a database is participating in replication, particular care needs to be taken if you wish to unload and reload the databases.

Replication is based on the transaction log. When a database is unloaded and reloaded, the old transaction log is no longer available. For this reason, good backup practices are especially important when participating in replication.

♦ To unload and reload a consolidated database:

1	Shut down the existing database.

2	Perform a full off-line backup by copying the database and transaction log files to a secure location.

3	Run the dbtran utility to display the starting offset and ending offset of the database's current transaction log file. Note the ending offset for later use.

4	Rename the current transaction log file so that it is not modified during the unload process, and place this file in the off-line directory.

5	Start the existing database.

6	Unload the database.

7	Shut down the existing database. This database and any log file created in this and the previous step is no longer needed.

8	Initialize a new database.

9	Reload the data into the new database.

10	Shut down the new database.

11	Erase the current transaction log file for the new database.

12	Use dblog on the new database with the ending offset noted in step 3 as the -z parameter, and also set the relative offset to zero.

dblog -x 0 -z 137829 database-name.db

13	When you run the Message Agent, provide it with the location of the original off-line directory on its command line.


Using passthrough mode
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

 Using passthrough mode

The publisher of the consolidated database can directly intervene at remote sites using a passthrough mode, which enables standard SQL statements to be passed through to a remote site. By default, passthrough mode statements are executed at the local (consolidated) database as well, but an optional keyword prevents the statements from being executed locally.

Caution
Always test your passthrough operations on a test database with a remote database subscribed. Never run untested passthrough scripts against a production database.

Starting and stopping passthrough

Passthrough mode is started and stopped using the PASSTHROUGH statement. Any statement entered between the starting PASSTHROUGH statement and the PASSTHROUGH STOP statement which terminates passthrough mode is checked for syntax errors, executed at the current database, and also passed to the identified subscriber and executed at the subscriber database. We can call the statements between a starting and stopping passthrough statement a passthrough session.

The following statement starts a passthrough session which passes the statements to a list of two named subscribers, without being executed at the local database:

PASSTHROUGH ONLY

FOR userid_1, userid_2;

Directing passthrough statements

The following statement starts a passthrough session that passes the statements to all subscribers to the specified publication:

PASSTHROUGH ONLY

FOR SUBSCRIPTION TO [owner].pubname [ ( string ) ] ;

Passthrough mode is additive. In the following example, statement_1 is sent to user_1, and statement_2 is sent to both user_1 and user_2.

PASSTHROUGH ONLY FOR user_1 ;

statement_1 ;

PASSTHROUGH ONLY FOR user_2 ;

statement_2 ;

The following statement terminates a passthrough session:

PASSTHROUGH STOP ;

PASSTHROUGH STOP terminates passthrough mode for all remote users.

Order of application of passthrough statements

Passthrough statements are replicated in sequence with normal replication messages, in the order in which the statements are recorded in the log.

Passthrough is commonly used to send data definition language statements. In this case, replicated DML statements use the before schema before the passthrough and the after schema following the passthrough.

Notes on using passthrough mode

•	You should always test your passthrough operations on a test database with a remote database subscribed. You should never run untested passthrough scripts against a production database.

•	You should always qualify object names with the owner name. PASSTHROUGH statements are not executed at remote databases from the same user ID. Consequently, object names without the owner name qualifier may not be resolved correctly.

 Uses and limitations of passthrough mode

 Operations not replicated in passthrough mode


Uses and limitations of passthrough mode
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Using passthrough mode

 Uses and limitations of passthrough mode

Passthrough mode is a powerful tool, and should be used with care. Some statements, especially data definition statements, could cause a running SQL Remote setup to come tumbling down. SQL Remote relies on each database in a setup having the same objects: if a table is altered at some sites but not at others, attempts to replicate data changes will fail.

Also, it is important to remember that in the default setting passthrough mode also executes statements at the local database. To send statements to a remote database without executing them locally you must supply the ONLY keyword. The following set of statements drops a table not only at a remote database, but also at the consolidated database.

-- Drop a table at the remote database

-- and at the local database

PASSTHROUGH TO Joe_Remote ;

DROP TABLE CrucialData ;

PASSTHROUGH STOP ;

The syntax to drop a table at the remote database only is as follows:

-- Drop a table at the remote database only

PASSTHROUGH ONLY TO Joe_Remote ;

DROP TABLE CrucialData ;

PASSTHROUGH STOP ;

The following are tasks that can be carried out on a running SQL Remote setup:

•	Add new users.

•	Resynchronize users.

•	Drop users from the setup.

•	Change the address, message type, or frequency for a remote user.

•	Add a column to a table.

Many other schema changes are likely to cause serious problems if executed on a running SQL Remote setup.

Passthrough works on only one level of a hierarchy

In a multi-tier SQL Remote installation, it becomes important that passthrough statements work on the level of databases immediately beneath the current level. In a multi-tier installation, passthrough statements must be entered at each consolidated database, for the level beneath it.


Operations not replicated in passthrough mode
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 19.  Administering SQL Remote for Adaptive Server Anywhere

        Using passthrough mode

 Operations not replicated in passthrough mode

There are special considerations for some statements in passthrough mode.

Calling procedures

When a stored procedure is called in passthrough mode using a CALL or EXEC statement, the CALL statement itself is replicated and none of the statements inside the procedure are replicated. It is assumed that the procedure on the replicate side has the correct effect.

Control of flow statements and cursor operations

Control-flow statements such as IF and LOOP, as well as any cursor operations, are not replicated in passthrough mode. Any statements within the loop or control structure are replicated.

Operations on cursors are not replicated. Inserting rows through a cursor, updating rows in a cursor, or deleting rows through a cursor are not replicated in passthrough mode.

Static embedded SQL SET OPTION statements are not replicated. The following statement is not replicated in passthrough mode:

EXEC SQL SET OPTION . . .

However, the following dynamic SQL statement is replicated:

EXEC SQL EXECUTE IMMEDIATE "SET OPTION . . . "

Batches

Batch statements ( a group of statements surrounded with a BEGIN and END) are not replicated in passthrough mode. You receive an error message if you try to use batch statements in passthrough mode.


CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

About this chapter

This chapter details setup and management issues for SQL Remote administrators using Adaptive Server Enterprise as the server for the consolidated database.

 How the Message Agent for Adaptive Server Enterprise works

 Running the Message Agent

 Error reporting and handling

 Adaptive Server Enterprise transaction log and backup management

 Making schema changes

 Using passthrough mode


How the Message Agent for Adaptive Server Enterprise works
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

 How the Message Agent for Adaptive Server Enterprise works

This section describes how the Message Agent for Adaptive Server Enterprise works. There are some significant differences between how the Message Agent for Adaptive Server Enterprise and the Message Agent for Adaptive Server Anywhere operate, which accommodate the different roles of the two servers.

  For information on features of the Message Agent that are common to Adaptive Server Anywhere and Adaptive Server Enterprise, see Running the Message Agent.

Message Agent is ssremote

The Message Agent for Adaptive Server Enterprise is the following executable:

•	On Windows operating systems, the Message Agent is ssremote.exe

•	On UNIX operating systems, the Message Agent is ssremote.

 Scanning the transaction log

 The stable queue

 Message Agent operation phases


Scanning the transaction log
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        How the Message Agent for Adaptive Server Enterprise works

 Scanning the transaction log

The Message Agent scans the Adaptive Server Enterprise transaction log in order to collect transactions to be sent to remote databases. It stores these transactions in a stable queue.

  For more information about the stable queue, see The stable queue. For more information about how the Message Agent uses the stable queue, see Message Agent operation phases.

The SQL Remote Message Agent uses the same transaction log scanning interface as the Adaptive Server Enterprise Log Transfer manager (LTM). Adaptive Server Enterprise maintains a truncation point, which is an identifier for the oldest page in the transaction log needed by the replication system.

The SQL Remote Message Agent sets the truncation point as soon as transactions are scanned from the transaction log and committed in the stable queue. This allows the dump transaction command to reclaim space in the transaction log as soon as possible. The Message Agent does not wait until confirmation is received from remote databases before setting the truncation point.

Message Agent must be run to reclaim log space
The Message Agent must be run frequently enough to prevent the transaction log from running out of space. The dump transaction command does not reclaim space from pages after the truncation point.

Replication Server and SQL Remote

Using SQL Remote on an Adaptive Server Enterprise database participating in a Replication Server setup may involve other considerations. If your database has a replication agent (LTM) running against it, then you need to use the SQL Remote Open Server as an additional component. Adaptive Server Enterprise databases have replication agents running against them in the following circumstances:

•	The database is participating in a Replication Server setup as a primary database, or

•	The database is participating in a Replication Server setup and is using asynchronous procedure calls.

If the database is participating in a Replication Server setup as a replicate site, and no asynchronous procedure calls are being used, there is no need for the SQL Remote Open Server.

  For more information about the SQL Remote Open Server, see Using SQL Remote with Replication Server.


The stable queue
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        How the Message Agent for Adaptive Server Enterprise works

 The stable queue

The Message Agent for Adaptive Server Enterprise uses a stable queue to hold transactions until they can be deleted. A stable queue is a pair of database tables that hold messages that may still be needed by the replication system.

SQL Remote for Adaptive Server Anywhere does not use a stable queue.

Stable queue not identical to Replication Server stable queue
Sybase Replication Server also uses stable queues as storage areas for replication messages. The Replication Server and SQL Remote stable queues perform similar functions, but are not the same thing.

Stable queue location

The stable queue may be kept in the same database as the tables being replicated, or in a different database. Keeping the stable queue in a separate database complicates the backup and recovery plan, but can improve performance by putting the stable queue workload on separate devices and/or a separate Adaptive Server Enterprise server.

Do not modify the stable queue directly
The stable queue is maintained by and for the Message Agent. You should not modify the stable queue directly.

The stable queue consists of a set of tables that contain information on all transactions scanned from the transaction log,

  For a description of each of the columns of these tables, see Stable Queue tables.


Message Agent operation phases
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        How the Message Agent for Adaptive Server Enterprise works

 Message Agent operation phases

The Message Agent has the following phases of execution:

•	Receiving messages    During this phase, the Message Agent receives incoming messages and applies them to the Adaptive Server Enterprise server.

•	Populating the stable queue    During this phase the Message Agent scans the Adaptive Server Enterprise transaction log into the stable queue.

•	Sending messages    During this phase, the Message Agent builds outgoing messages from the stable queue.

The transactions remain in the stable queue until confirmation has been received from all remote databases. When confirmation is received, the transactions are automatically removed from the stable queue by the Message Agent.

The Message Agent does not scan the transaction log of the database in which the stable queue resides if it is different from the database with SQL Remote system tables.

  For information on running multiple copies of the Message Agent to carry out these tasks, see Running multiple Message Agents.


Running the Message Agent
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

 Running the Message Agent

  This section describes how to run the Message Agent for Adaptive Server Enterprise. For information on features of the Message Agent that are common to Adaptive Server Anywhere and Adaptive Server Enterprise, see Running the Message Agent.

 The Message Agent and replication security

 Running multiple Message Agents


The Message Agent and replication security
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Running the Message Agent

 The Message Agent and replication security

In the tutorials earlier in this book, the Message Agent was run using a user ID with system administrator permissions. The operations in the messages are carried out from the user ID specified in the Message Agent connection string; by using a system administrator user ID, you can be sure that the user has permissions to make all the changes.

In practice, you will not use such a user ID, but the Message Agent needs to run using a user ID with replication role. You can grant replication role with the following statement:

sp_role 'grant', replication_role, user_name

The user for the Message Agent must have insert, update and delete permissions on all replicated tables, in order to apply the changes. Also, the replication error procedure must be created under the Message Agent user ID.

When you setup your Adaptive Server Enterprise database, the scripts ssremote.sql and squeue.sql must be run under the same user name you use for the Message Agent.

  For setup instructions, see Setting Up SQL Remote.

To hide the user password for the Message Agent user ID, you can store the ssremote command-line options in a file, and use ssremote with the @filename parameter. You can use file system security to prevent unauthorized access to the file.


Running multiple Message Agents
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Running the Message Agent

 Running multiple Message Agents

The three phases of Message Agent operation are described in the section Message Agent operation phases. To summarize, these phases are:

•	Receiving messages.

•	Scanning the transaction log.

•	Sending messages.

You may wish to run separate copies of the Message Agent to carry out these different phases. You can specify which phases a given Message Agent is to execute on the Message Agent command line.

Specifying which phases to execute

The command-line options are as follows:

•	Receive    The -r command-line switch instructs the Message Agent to receive messages while it is running. To cause the Message Agent to shut down after receiving available messages, use the -b switch in addition to -r.

•	Scan log    The -i command-line switch instructs the Message Agent to scan the transaction log into the stable queue while it is running.

•	Send    The -s command-line switch instructs the Message Agent to send messages while it is running.

•	Multiple phases    If none of -r, -i, or -s is specified, the Message Agent executes all three phases. Otherwise, only the indicated phases are executed.

There are several circumstances where you may wish to run multiple Message Agents.

•	Ensuring the transaction log does not run out of space    It is important that the transaction log not be allowed to become full. For this reason, you must scan the transaction log frequently enough to ensure that all entries required by SQL Remote are placed in the stable queue. Therefore, you may want to run a Message Agent that scans the transaction log continuously, even if you are only receiving and sending messages in batch mode.

•	Mixing operating systems    If you wish to use a message link supported under Windows 95 or NT, you must use a Message Agent on that platform to send and receive messages. You can do this, while running the log scanning on a UNIX machine, by running two copies of the Message Agent.

How Message Agents are synchronized

The operations of two or more Message Agents are synchronized by a table called sr_marker. This table has a single column called marker, of data type datetime.

When the Message Agent wants to wait for transactions to be scanned into the stable queue, it updates sr_marker and waits for it to work its way through the system. The column in sr_queue_state is also called marker, and contains the most recent marker to be scanned from the transaction log.


Error reporting and handling
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

 Error reporting and handling

This section describes how errors are reported and handled by the Message Agent.

 Default error handling

 Implementing error handling procedures


Default error handling
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Error reporting and handling

 Default error handling

The default action taken by the Message Agent when an error occurs is to record the fact in its log output. The Message Agent sends log output to a window or a log file recording its operation. By default, log output is sent to the window only; the -o command-line option sends output to a log file as well.

The Message Agent may print more information in the output log than in the window. The Message Agent log includes the following:

•	Listing of messages applied.

•	Listing of failed SQL statements.

•	Listing of other errors.

UPDATE conflicts are not errors

UPDATE conflicts are not errors, and so are not reported in the Message Agent output.


Implementing error handling procedures
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Error reporting and handling

 Implementing error handling procedures

SQL Remote allows you to carry out some other process in addition to logging a message if an error occurs. The REPLICATION_ERROR database option allows you to specify a stored procedure to be executed by the Message Agent when an error occurs. By default no procedure is executed .

The procedure must have a single argument of type CHAR or VARCHAR. The procedure is called with any error messages and with the SQL statement that causes the error.

While the option allows you to track and monitor errors in replication, you must still design them out of your setup: this option is not intended to resolve such errors.

For example, the procedure could insert the errors into a table with the current time and remote user ID, and this information can then replicate back to the consolidated database. An application at the consolidated database can create a report or send e-mail to an administrator when errors show up.

  For information on setting the REPLICATION_ERROR option, see SQL Remote options.


Adaptive Server Enterprise transaction log and backup management
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

 Adaptive Server Enterprise transaction log and backup management

You must protect against losing transactions that have been replicated to remote databases. If transactions are lost that have already been replicated to remote databases, the remote databases will be inconsistent with the consolidated database. In this situation, you may have to re-extract all remote databases.

 Protecting against media failure on the transaction log

 Stable queue recovery issues

 Transaction log management


Protecting against media failure on the transaction log
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Adaptive Server Enterprise transaction log and backup management

 Protecting against media failure on the transaction log

Media failure on the transaction log can cause committed transactions to be lost. If the transaction log has been scanned and these transactions have already been sent to subscriber databases, then the subscribing databases contain transactions that are lost from the publishing database, and the databases are in an inconsistent state.

Why the transaction log is needed

The transaction log is needed, even after the entries have been scanned into the stable queue, to guard against media failure on the database file. If the database is lost, it must be recovered to a point that includes every transaction that may have been sent to remote databases.

This recovery is done by restoring a database dump and loading transaction dumps to bring the database up to date. The last transaction dump restored is the dump of the active transaction log at the time of the failure.

Protecting against transaction log loss

There are two ways of protecting against inconsistency arising from media failure on the transaction log:

•	Mirror the transaction log    When a device is mirrored, all writes to the device are copied to a separate physical device.

•	Only replicate backed-up transactions    There is a command-line switch for the Message Agent that prevents it from sending transactions until they are backed up.

Mirroring the transaction log

The only way to protect against media failure on the transaction log is by mirroring the transaction log.

Disk mirroring can provide nonstop recovery in the event of media failure. The disk mirror command causes an Adaptive Server Enterprise database device to be duplicated—that is, all writes to the device are copied to a separate physical device. If one of the devices fails, the other contains an up-to-date copy of all transactions.

  For information on disk mirroring in Adaptive Server Enterprise, see the chapter "Mirroring Database Devices", in the Adaptive Server Enterprise System Administration Guide.

Replicating only backed-up transactions

The Message Agent also provides a command line switch (-u) that only sends transactions that have been backup up. In Adaptive Server Enterprise, this means transactions complete before the latest dump database command or dump transaction command.

Choosing an approach

The goal of the strategy is to reduce the possibility of requiring re-extraction of remote databases to an acceptable level. In large setups, the possibility must be as close to zero as possible, as the cost of re-extraction (in terms of down time) is very high.

•	The Message Agent -u command-line switch can be used instead of transaction log mirroring when recovery of all transactions in a consolidated database is not needed and mirroring is considered too expensive. This may be true in small setups or setups where there are no local users on the consolidated database.

•	The Message Agent -u command-line switch can also be used in addition to mirroring to provide additional protection against total site failure or double media failure.


Stable queue recovery issues
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Adaptive Server Enterprise transaction log and backup management

 Stable queue recovery issues

Keeping the stable queue in a separate database complicates backup and recovery, as consistent versions of the two databases have to be recovered.

Normal recovery automatically restores the two databases to a consistent state, but recovery from media failure takes some care. When restoring database dumps and transaction dumps, it is important to recover the stable queue to a consistent point.

Two procedures in the stable store database are provided to help with recovery from media failure:

•	sp_queue_dump_database    This procedure is called whenever a dump database is scanned from the transaction log.

•	sp_queue_dump_transaction    This procedure is called whenever a dump transaction is scanned from the transaction log.

You can modify these stored procedures to issue dump database and dump transaction commands in the stable store database.


Transaction log management
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Adaptive Server Enterprise transaction log and backup management

 Transaction log management

The Adaptive Server Enterprise log transfer interface allows the Message Agent to scan the Adaptive Server Enterprise transaction log. When this interface is being used, it sets a truncation point in the transaction log. The truncation point prevents Adaptive Server Enterprise from re-using pages in the transaction log before they have been scanned by SSREMOTE. For this reason, DUMP TRANSACTION will not necessarily release transaction log pages that are before the oldest open transaction. DUMP TRANSACTION will not release transaction log pages beyond the "truncation point".

Initializing the truncation point

The SQL Remote setup script (ssremote.sql) initializes the truncation point with the following command

dbcc settrunc( 'ltm', 'valid' ).

The truncation point can be reset with the following command

dbcc settrunc( 'ltm', 'ignore' ).

This command tells Adaptive Server Enterprise to ignore the truncation point, allowing transaction log pages beyond the truncation point to be released for reuse. You should only use this command when you are no longer interested in SQL Remote replication with the database and you want to be able to reclaim space in the transaction device with DUMP TRANSACTION commands. Continuing to run SQL Remote after ignoring the truncation point will fail to replicate any transactions that were in transaction log pages that were not scanned by the Message Agent and were freed by DUMP TRANSACTION.


Making schema changes
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

 Making schema changes

Schema changes to tables being replicated by SQL Remote must be made on a quiet system. A quiet system means the following:

•	No transactions being replicated    There can be no transactions being replicated that modify the tables that are to be altered. All transactions that modify tables being altered must be scanned from the transaction log into the stable queue before the schema is altered. This is performed by running the Message Agent normally, or using the -i -b switches. After the Message Agent completes, you can make the schema change..

•	Message Agent    The Message Agent must be shut down when the schema change is being made.

•	SQL Remote Open Server    If you are using the SQL Remote Open Server, it must be shut down when the schema change is being made.

Schema changes include changes to publications, such as adding articles or modifying articles. However, creating or dropping subscriptions, and adding or removing remote users do not need to be done on a quiet system.

In the Adaptive Server Enterprise transaction log, there is no information recording table structure changes: the SQL Remote log scanning process gets the table structure from the Adaptive Server Enterprise system tables. Consequently, the Message Agent cannot scan an operation from the transaction log that happened against the old table structure.

Information stored in the stable queue before the schema change uses the old table definitions and information stored after the schema change uses the new table definitions.

Passthrough mode can be used at the same time as the schema change to make sure that schema changes at remote databases occur in the correct sequence.


Using passthrough mode
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

 Using passthrough mode

The publisher of the consolidated database can directly intervene at remote sites using a passthrough mode, which enables standard SQL statements to be passed through to a remote site.

Determining recipients of passthrough statements

Passthrough destinations are determined by sp_passthrough_user and sp_passthrough_subscription. Executing either of these procedures determines a set of recipients for any subsequent passthrough statements.

Executing either sp_passthrough_user and sp_passthrough_subscription adds to the current list of recipients. The sp_passthrough_stop procedure resets passthrough (that is, resets the list of recipients to be empty).

In Adaptive Server Enterprise, sp_passthrough never executes statements in the consolidated database. Passthrough SQL statements are applied only to remote databases.

Passthrough statements

To cause passthrough SQL statements to replicate, you call sp_passthrough.

Due to the VARCHAR(255) limitation in Adaptive Server Enterprise, you should build a long SQL statement up in pieces. Calls to sp_passthrough_piece will build up a single SQL statement. Calling sp_passthrough with the last piece will cause the built up statement to replicate.

Notes on using passthrough mode

•	You should always test your passthrough operations on a test database with a remote database subscribed. You should never run untested passthrough scripts against a production database.

•	You should always qualify object names with the owner name. PASSTHROUGH statements are not executed at remote databases from the same user ID. Consequently, object names without the owner name qualifier may not be resolved correctly.

 Schema modifications


Schema modifications
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 20.  Administering SQL Remote for Adaptive Server Enterprise

        Using passthrough mode

 Schema modifications

The Adaptive Server Enterprise log transfer interface does not contain information about the number of columns and data types of the columns in a table. SSREMOTE gets this information directly from the Adaptive Server Enterprise system tables. For this reason, altering a table and then scanning operations that happened before the ALTER TABLE will lead to errors. SSREMOTE must set the "truncation point" beyond all operations on replicated tables before schema changes can be made. Operations on replicated tables need to be prevented between SSREMOTE running and the schema changes being made.


CHAPTER 21.  Using SQL Remote with Replication Server
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 21.  Using SQL Remote with Replication Server

About this chapter

This chapter describes the additional components needed to use SQL Remote on an Adaptive Server Enterprise database that also participates in a Replication Server installation.

 When you need to use the SQL Remote Open Server

 Architecture for Replication Server/SQL Remote installations

 Setting up SQL Remote Open Server

 Configuring Replication Server

 Other issues


When you need to use the SQL Remote Open Server
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

 When you need to use the SQL Remote Open Server

The Message Agent for Adaptive Server Enterprise scans the Adaptive Server Enterprise transaction log to populate the stable queue, as described in the section The stable queue). SQL Remote messages are built from the transactions in the stable queue.

The Message Agent uses the same interface to scan the transaction log as the Replication Agent for Adaptive Server Enterprise. This means the Message Agent cannot scan the transaction log of an Enterprise database that is a primary site in a Replication Server setup (or a replicate site that allows asynchronous updates to primary data).

If there is a Replication Agent running against your Adaptive Server Enterprise database, you must use the SQL Remote Open Server as an additional component. In this case, SQL Remote is set up so that Replication Server populates the stable queue. The SQL Remote Message Agent does not scan the transaction log. Instead, the SQL Remote Open Server receives transactions from Replication Server. The transactions are parsed by the SQL Remote Open Server and stored in the SQL Remote stable queue.

  This chapter assumes knowledge of Replication Server. For information, see your Replication Server documentation.

Open Server runtime components required
The Open Server runtime components are not included with SQL Remote. You must obtain them separately from Sybase in order to use the SQL Remote Open Server.


Architecture for Replication Server/SQL Remote installations
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

 Architecture for Replication Server/SQL Remote installations

The arrangement for using a database as a Replication Server primary site and as a SQL Remote database is illustrated in the following diagram. The diagram illustrates a case where the stable queue is held in a different database from the data being replicated. The stable queue may alternatively be held in the same database as the data being replicated. All connections are client/server connections, and so the components may be running on the same or different machines.

 How the pieces fit together


How the pieces fit together
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

        Architecture for Replication Server/SQL Remote installations

 How the pieces fit together

The SQL Remote Open Server acts as a replicate database in the Replication Server setup, and so replication definitions and subscriptions are required in the Adaptive Server Enterprise database on all tables participating in SQL Remote replication and on several of the SQL Remote system tables.

Contents of the stable queue

All operations are replicated to the SQL Remote Open Server, which stores them in the stable queue. The stable queue does not have copies of the tables being replicated. It parses the inserts, updates, and deletes to build transactions. All transactions are stored in an image column of a single table. These transactions are used by the Message Agent to build SQL Remote messages.

Incoming messages

The Message Agent always applies incoming SQL Remote messages directly to Adaptive Server Enterprise. It does not send operations to Replication Server. Incoming messages are applied directly to the consolidated database regardless of how the stable queue is populated. Conflict resolution is also performed in the same way.

Replication Server and SQL Remote

SQL Remote allows two-way replication between the consolidated database and remote databases. Replication Server is performing one-way replication from the consolidated database to the SQL Remote Open Server. From Replication Server's perspective, transactions that originate in remote SQL Remote databases appear as transactions originating in the consolidated SQL Remote database.

SQL Remote system tables

The SQL Remote Open Server requires information from the SQL Remote system tables concerning publications and subscriptions. The Open Server uses a connection to the Adaptive Server Enterprise database holding that information to retrieve it when it starts.

If the SQL Remote system tables are updated while the Open Server is running, the SQL Remote Open Server needs to receive this information at the correct time. For this reason, some of the SQL Remote system tables need to be marked for replication. This is described in Setting up SQL Remote Open Server.

The SQL Remote Open Server executable

The SQL Remote Open Server is the following executable:

•	On Windows operating systems, the SQL Remote Open Server is ssqueue.exe.

•	On UNIX operating systems, the SQL Remote Open Server is ssqueue.


Setting up SQL Remote Open Server
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

 Setting up SQL Remote Open Server

This section describes how to set up a SQL Remote installation using the SQL Remote Open Server. The procedure depends on whether the SQL Remote stable queue is being kept in a separate Adaptive Server Enterprise database from the tables being replicated or in the same Adaptive Server Enterprise database.

  For more information about stable queue location, see The stable queue.

Initial copies of the data

The setup procedure assumes you are using the extraction utility to produce an initial copy of the data in each remote database. You must be sure not to use the Replication Server materialization feature for this purpose.

The procedure for setting up SQL Remote Open Server has two stages:

•	Prepare a SQL Remote setup    This stage depends on whether you have an existing SQL Remote installation or not.

•	Add the SQL Remote Open Server to the setup    This stage is the same regardless of previous installations.

♦ To prepare your SQL Remote setup, if you have an existing SQL Remote installation:

1	On a quiet primary database, use the Message Agent to scan any remaining transactions into the stable queue.

A quiet database is one where neither the Message Agent not the SQL Remote Open Server is running, and where no transactions are being replicated.

2	Follow the steps in the section Upgrading SQL Remote for Adaptive Server Enterprise to upgrade your SQL Remote software at the consolidated site.

3	Invalidate the Message Agent truncation point at the consolidated database using the following command:

dbcc settrunc('ltm', 'ignore')

4	At the stable queue database, execute the stored procedure sp_queue_log_transfer_reset.

♦ To prepare your SQL Remote setup, with no existing installation:

1	Set up SQL Remote as described in Setting Up SQL Remote.

2	Set up your SQL Remote publications and subscriptions at this point. For information on this procedure, see SQL Remote Design for Adaptive Server Enterprise.

3	Extract the remote databases. For information on this procedure, see Using the extraction utility.

You are now ready to set up the SQL Remote Open Server.

♦ To set up the SQL Remote Open Server:

1	If the SQL Remote stable queue is in a separate database:

•	Set up the stable queue database as a replicate database in a Replication Server setup. This will create the tables and procedures needed by Replication Server, such as rs_lastcommit.

•	Drop the Replication Server connection to the stable queue database.

2	Add an entry to your interfaces file for the SQL Remote Open Server. The default name used on the SQL Remote Open Server command line is SSQueue.

3	Start the SQL Remote Open Server.

4	Create a Replication Server connection to the SQL Remote Open Server. The user ID and password for this connection must match the user ID and password specified on the SQL Remote Open Server command line for the stable queue connection (that is, the -cq switch, or -c if -cq is not specified).

Configure Replication Server now
You should configure Replication Server for this connection at this point. For a description, see Configuring Replication Server.

5	Define, activate, and validate Replication Server replication definitions and subscriptions for the SQL Remote tables sr_marker, sr_remoteuser, sr_subscription, and sr_passthrough. The script ssremote.rs is a sample script to perform this task. You will need to edit the server and database names in the script to match your names.

If the SQL Remote system tables have any data in them, create the replication definitions so that no materialization happens.

  For information on creating replication definitions with no materialization, see the Replication Server Administration Guide. The section in Chapter 7, Managing Subscriptions entitled Bulk Materialization describes how to set up Replication Server for the case where data exists at a remote database.

6	Define, activate, and validate replication definitions and subscriptions for the tables in your database that need to be replicated by SQL Remote. These must be created without materialization.


Configuring Replication Server
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

 Configuring Replication Server

This section describes how to configure Replication Server for use with the SQL Remote Open Server

The Replication Server connection to the SQL Remote Open Server must have several configuration parameters set.

 Set the dsi_xact_group_size parameter

 Set the dsi_num_threads parameter

 Create replication definitions for SQL Remote data

 Suspend and restart the connection


Set the dsi_xact_group_size parameter
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

        Configuring Replication Server

 Set the dsi_xact_group_size parameter

By default, Replication Server groups multiple transactions into larger transactions. The dsi_xact_group_size parameter controls the maximum size of a grouped transaction.

The dsi_xact_group_size parameter must be set to -1 to disable transaction grouping. Transactions that originate from different remote databases in a SQL Remote setup must not be grouped together.

How to set the parameter

You can set the parameter using the following statement:

CONFIGURE CONNECTION TO  "ssqueue_server"

SET dsi_xact_group_size TO '-1'


Set the dsi_num_threads parameter
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

        Configuring Replication Server

 Set the dsi_num_threads parameter

The SQL Remote Open Server does not support multiple DSI threads. Replication Server should not be configured to use multiple DSI threads on SQL Remote connections.


Create replication definitions for SQL Remote data
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

        Configuring Replication Server

 Create replication definitions for SQL Remote data

Replication definitions for tables being replicated by SQL Remote must have certain characteristics. This section describes those characteristics.

In some circumstances SQL Remote replicates an UPDATE operation as an INSERT or a DELETE (see Replication of updates). This is referred to as subscription migration in the Replication Server documentation. In order to replicate an UPDATE as an INSERT, SQL Remote requires the full pre-image of the row. This means that Replication Server must specify the values of every column in the WHERE clause of any UPDATE to a table that might need to be replicated as an INSERT.

The simplest way to achieve this is to list all columns in the PRIMARY KEY of the replication definition. This forces Replication Server to include every column in the WHERE clause of every update. REPLICATE MINIMAL COLUMNS can be used on these replication definitions to prevent every column from being listed in the SET clause of the update.

Text and image columns

Replication Server does not accept TEXT or IMAGE columns in the primary key of a replication definition. You should include all the columns except for the TEXT and IMAGE columns in the PRIMARY KEY list of your replication definition, and specify all the TEXT and IMAGE columns in the ALWAYS_REPLICATE clause. You should use REPLICATE ALL COLUMNS, instead of REPLICATE MINIMAL COLUMNS in your replication definition. This forces Replication Server to send the pre-image of the TEXT and IMAGE columns to the SQL Remote Open Server whenever an update occurs.

Using the  dsi_sql_data_style data style

Replication Server 11.5 has a new dsi_sql_data_style for SQL Remote. This data style automatically includes all columns in the WHERE clause of every UPDATE. It is not necessary to list all columns in the PRIMARY KEY of the replication definition. A replication definition using REPLICATE MINIMAL COLUMNS prevents Replication Server from keeping the full pre-image of rows being updated, so the SQL Remote dsi_sql_data_style will not work with REPLICATE MINIMAL COLUMNS.


Suspend and restart the connection
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

        Configuring Replication Server

 Suspend and restart the connection

After configuring the Replication Server connection to the SQL Remote Open Server, you should suspend and resume the connection so that the parameter settings can take effect. The following commands accomplish this task:

suspend connection to ssqueue_server

go

resume connection to ssqueue_server

go


Other issues
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 21.  Using SQL Remote with Replication Server

 Other issues

This section lists other issues regarding using SQL Remote with Replication Server.

Running the Message Agent   The Message Agent should be run with command line switches to receive and send (-r and -s). This will prevent the Message Agent from attempting to scan the transaction log. If the Message Agent attempts to scan the transaction log while the Replication Agent is running, it will get an error attempting to reserve the "log transfer context".

Procedure calls in SQL Remote Open Server   The SQL Remote Open Server passes all procedure calls it receives from Replication Server through to the stable queue database. For example, rs_get_lastcommit and rs_update_lastcommit are executed in the stable queue database.

Coordinated dumps   Replication Server provides a mechanism to coordinate database dumps and transaction log dumps between the main database and the stable queue database. The rs_dumpdb and rs_dumptran function strings can be used to perform coordinated dumps of the stable queue database. Please see the Replication Server documentation for more information.

Schema changes   If you make any schema changes to a SQL Remote installation, you must do so on a quiet system. This includes shutting down the SQL Remote  Open Server.


CHAPTER 22.  Utilities and Options Reference
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 22.  Utilities and Options Reference

About this chapter

This chapter provides reference material for the SQL Remote command line utilities and SQL Remote database options.

 The Message Agent

 The Database Extraction utility

 The SQL Remote Open Server

 SQL Remote options


The Message Agent
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 22.  Utilities and Options Reference

 The Message Agent

Purpose

To send and apply SQL Remote messages, and to maintain the message tracking system to ensure message delivery.

Syntax

{ dbremote | ssremote } [ switches ] [ directory ]

Command-line switches

Switch	Description
@filename	Read in switches from configuration file
@envvar	Read in switches from environment variable
-a	Do not apply received transactions
-b	Run in batch mode
-c "keyword=value; ..."	Supply database connection parameters
-cq "keyword=value; ..."	Supply database connection parameters for the stable queue (Adaptive Server Enterprise only)
-dl	Display log messages on screen
-e locale-string	Locale setting (Adaptive Server Enterprise only)
-fq	Full scan of the stable queue when sending messages (Adaptive Server Enterprise only)
-g n	Group transactions consisting of less than n operations.
-i	Scan transactions from the transaction log into the stable queue (Adaptive Server Enterprise only).
-k	Close window on completion
-l length	Maximum message length
-m size	Maximum amount of memory used for building messages.
-o file	Output messages to file
-os file	Maximum file size for logging output messages
-ot file	Truncate file and log output messages
-p	Do not purge messages
-q	Run with minimized window
-r	Receive messages
-rd minutes	Polling frequency for incoming messages
-rp number	Number of receive polls before message is assumed lost
-ru time	Waiting period to re-scan log on receipt of a resend.
-s	Send messages
-sd time	Send polling period
-t	Replicate all triggers (Adaptive Server Anywhere only)
-u	Process only backed up transactions
-ud	On UNIX platforms, run as a daemon.
-v	Verbose operation
-w n	Number of worker threads to apply incoming messages (Windows NT and Solaris only)
-x	Rename and restart the transaction log (Adaptive Server Anywhere only).
directory	The directory in which old transaction logs are held (Adaptive Server Anywhere only)
Description

The Message Agent sends and applies messages for SQL Remote replication, and maintains the message tracking system to ensure message delivery.

The name of the Message Agent executable is as follows:

•	dbremote    The Message Agent for Adaptive Server Anywhere.

•	ssremote    The Message Agent for Adaptive Server Enterprise.

You can also run the Message Agent  from your own application by calling into the DBTools library. For more information, see the file dbrmt.h in the h subdirectory of your SQL Remote installation directory.

For Adaptive Server Anywhere, the user ID in the Message Agent command line must have either REMOTE DBA or DBA authority. For Adaptive Server Enterprise, the user ID must have replication role.

The optional directory parameter specifies a directory in which old transaction logs are held, so that the Message Agent has access to events from before the current log was started.

The Message Agent uses a number of connections to the database. For a listing, see Connections used by the Message Agent.

 For information on REMOTE DBA authority, see The Message Agent and replication security.

Command-line switch details

@filename    Read in command-line switches from the supplied file.

The file may contain line breaks, and may contain any set of command line switches. For example, the following command file holds a set of command line switches for a Message Agent that starts with a cache size of 4 Mb, sends messages only, and connects to a database named field on a server named myserver:

-m 4096

-s

-c "eng=myserver;dbn=field;uid=sa;pwd=sysadmin"

If this configuration file is saved as c:\config.txt, it can be used in an command line as follows:

ssremote @c:\config.txt

or

dbremote @c:\config.txt

@environment-variable    Read in command-line switches from the supplied environment variable.

The environment variable may contain any set of command line switches. For example, the first of the following pair of statements sets an environment variable holding a set of command line switches for a database server that starts with a cache size of 4 Mb, receives messages only, and connects to a database named field on a server named myserver. The set statement should be entered all on one line:

set envvar=-m 4096 -r

-c "eng=myserver;dbn=field;uid=sa;pwd=sysadmin"

ssremote @envvar

-a    Process the received messages (those in the inbox) without applying them to the database. Used together with -v (for verbose output) and -p (so the messages are not purged), this flag can help detect problems with incoming messages. Used without -p, this flag purges the inbox without applying the messages, which may be useful if a subscription is being restarted.

-b    Run in batch mode. In this mode, the Message Agent processes incoming messages, scans the transaction log once and processes outgoing messages, and then stops.

-c "parameter=value; ..."     Specify connection parameters. For Adaptive Server Anywhere, if this option is not specified, the environment variable SQLCONNECT is used.

For example, the following statement runs dbremote on a database file named c:\asa6\asademo.db, connecting with user ID DBA and password SQL:

dbremote -c "uid=DBA;pwd=SQL;dbf=c:\asa6\asademo.db"

The Message Agent must be run by a user with REMOTE DBA authority or DBA authority.

  For information on REMOTE DBA authority, see The Message Agent and replication security.

The Message Agent for Adaptive Server Anywhere supports the full range of Adaptive Server Anywhere connection parameters. The Message Agent for Adaptive Server Enterprise supports the following connection parameters:

Parameter	Description
UID	Login ID
PWD	Password
DBN	(optional) Database name. If this parameter is not supplied, the connection defaults to the default database for the login ID.
ENG	Adaptive Server Enterprise name.
-cq "parameter=value; ..."    Specify connection parameters for the stable queue. This option applies to Adaptive Server Enterprise only. If not supplied, the values default to the -c values.

-dl    Display messages in the Message Agent window or on the command line and also in the log file if specified.

-e locale-string    This option applies to Adaptive Server Enterprise only. Specify Adaptive Server Enterprise locale information. The locale string has the following format:

"language_name,charset_name[,sort_order]"

By default, the Message Agent uses the default locale, which is defined in the file sybase\locales\locales.dat.

If language_name and charset_name are not supplied, the Message Agent obtains them from Adaptive Server Enterprise. If sort_order is not supplied, the Message Agent uses a binary sort order (sort by byte value).

-fq    This option is for use only with Adaptive Server Enterprise. It permits a a full scan of the stable queue when sending messages, starting from the oldest confirm_sent value in the sr_remoteuser table.

This feature is intended for occasional use to clean out a large stable queue. If, for example, a single user has not confirmed receipt of a message from a long time ago, the stable queue may be very large. However, by running -fq you can delete entries from more up-to-date users that have been confirmed, even though they are more recent than the cutoff value at which entries are deleted by default.

-g   n  Instructs the Message Agent to group transactions containing less than n operations together with transactions that follow. The default is twenty operations. Increasing the value of n can  speed up processing of incoming messages, by doing less commits. However, it can also cause deadlock and blocking by increasing the size of transactions.

-i    Scan transactions from the transaction log into the stable queue. This option is available for Adaptive Server Enterprise only. It is used when you wish to run a separate copy of the Message Agent for scanning the transaction log and for sending and receiving messages.

If none of -r, -i, or -s is specified, the Message Agent executes all three phases. Otherwise, only the indicated phases are executed.

  For more information, see Running multiple Message Agents.

-k    Close window on completion when used together with the -o parameter.

-l length    Specifies the maximum length of each message to be sent, in bytes. Longer transactions are split into more than one message. The default is 50000 bytes and the minim length is 10000.

Caution
The maximum message length must be the same at all sites in an installation.

For platforms with restricted memory allocation, the value must be less than the maximum memory allocation of the operating system. For example, Windows 3.x allows a maximum memory allocation of 64K, and the maximum message length must be less than this.

-m size    Specifies a maximum amount of memory to be used by the Message Agent for building messages and caching incoming messages. The allowed size can be specified as n (in bytes), nK, or nM. The default is 2048K (2M).

When all remote databases are receiving unique subsets of the operations being replicated, a separate message for each remote database is built up concurrently. Only one message is built for a group of remote users that are receiving the same operations. When the memory being used exceeds the -m value, messages are sent before reaching their maximum size (as specified by the -l switch).

When messages arrive, they are stored in memory by the Message Agent until they are applied. This caching of messages prevents rereading of that are out of order messages from the message system , which may lower performance on large installations. When the memory usage specified using the -m switch is exceeded, messages are flushed in a least-recently used fashion.

-o    Append output to a log file. Default is to send output to the screen.

-os    Specifies the maximum file size for logging output messages. The allowed size can be specified as n (bytes), nK (Kb), or nM (Mb). By default there is no limit, and the minimum limit is 10000 bytes.

Before SQL Remote logs output messages to a file, it checks the current file size. If the log message will make the filesize exceed the specified size, SQL Remote renames the output file to yymmddnn.dbr (for dbremote) and yymmddnn.ssr (for ssremote) where nn is an integer from 00 to 99 and yymmdd represents the current year, month, and date.

If the Message Agent us running in continuous mode for a long time, this option allows you to manually delete old log files and free up disk space.

-ot    Truncate the log file and then append output messages to it. Default is to send output to the screen.

-p    Process the messages without purging them.

-q    For Windowing operating systems only, starts the Message Agent with a minimized window.

-r    Receive messages. If none of -r, -i, or -s is specified, the Message Agent executes all three phases. Otherwise, only the indicated phases are executed.

The Message Agent runs in continuous mode if called with -r. To have the Message Agent shut down after receiving messages, use the -b switch in addition to -r.

-rd time    By default, the Message Agent polls for incoming messages every minute. This option (rd stands for receive delay) allows the polling frequency to be configured, which is useful when polling is expensive. The Message Agent checks for incoming messages once after each send cycle, regardless of the polling frequency, so if a value greater then the SEND EVERY frequency is supplied, the Message Agent checks for incoming messages once after each send cycle.

You can use a suffix of s after the number to indicate seconds, which may be useful if you want frequent polling. For example:

dbremote -rd 30s

polls every thirty seconds.

  For more information on polling, see Polling for messages and requesting resends.

-rp    When running in continuous mode, the Message Agent polls at certain intervals for messages. After polling a set number of times (by default, one), if a message is missing, the Message Agent assumes it has got lost and requests that it be resent. On slow message systems, this can result in many unnecessary resend requests. You can set the number of polls before a resend request is issued using this option, to cut down on the number of resend requests.

  For more information on configuring this option, see Polling for messages and requesting resends.

-ru    Control the resend urgency. This is the time between detection of a resend request and when the Message Agent starts fulfilling the request. Use this switch to help the Message Agent collect resend requests from multiple users before rescanning the log. The time unit can be any of {s = seconds; m = minutes; h = hours; d = days}

-s    Send messages. If none of -r, -i, or -s is specified, the Message Agent executes all three phases. Otherwise, only the indicated phases are executed.

-sd time    Control the send delay which is the time to wait between polls for more transaction log data to send.

-t    All trigger actions are replicated. If you do use this switch, you must ensure that the trigger actions are not carried out twice at remote databases, once by the trigger being fired at the remote site, and once by the explicit application of the replicated actions from the consolidated database.

To ensure that trigger actions are not carried out twice, you can wrap an IF CURRENT REMOTE USER IS NULL ... END IF statement around the body of the triggers. This option is available for Adaptive Server Anywhere only.

-u    Process only transactions that have been backed up. This switch prevents the Message Agent from processing transactions since the latest backup. Using this switch, outgoing transactions and confirmation of incoming transactions are not sent until they have been backed up.

In Adaptive Server Anywhere, this means only transactions from renamed logs are processed. In Adaptive Server Enterprise, this means that only transactions committed before the latest dump database or dump transaction statement are processed.

-ud    On UNIX platforms, you can run the Message Agent as a daemon by supplying the -ud command-line option.

If you run the Message Agent as a daemon, you must also supply the -o or -ot command-line option, to log output information.

If you run the Message Agent  as a daemon and are using FTP or SMTP message links, you must store the message link parameters in the database, because the Message Agent does not prompt the user for these options when running as a daemon.

  For information on message link parameters, see Setting message type control parameters.

-v    Verbose output. This switch displays the SQL statements contained in the messages to the screen and, if the -o or -ot switch is used, to a log file.

-w n    The number of worker threads used to apply incoming messages. The default is zero, which means all messages are applied by the main (and only) thread. A value of 1 (one) would have one thread receiving messages from the message system and one thread applying messages to the database.

The -w switch makes it possible to increase the throughput of incoming messages with hardware upgrades. Putting the consolidated database on a device that can perform many concurrent operations (a RAID array with a striped logical drive) will improve throughput of incoming messages. Multiple processors in the computer running the Message Agent could also improve throughput of incoming messages.

The -w switch will not improve performance significantly on hardware that cannot perform many concurrent operations.

Incoming messages from a single remote database will never be applied on multiple threads. Messages from a single remote database are always applied serially in the correct order.

This option is not available on Windows 3.x.

-x    Rename and restart the transaction log after it has been scanned for outgoing messages. In some circumstances, replicating data to a consolidated database can take the place of backing up remote databases, or renaming the transaction log when the database server is shut down. This option is available for Adaptive Server Anywhere only.

Message system control parameters

SQL Remote uses several registry settings (in Windows 95 and NT) or initialization file settings (Windows 3.x and OS/2) to control aspects of message link behavior.

The message link control parameters are stored in the following places:

•	Windows 95 and Windows NT    In the registry, at the following location:

\\HKEY_CURRENT_USER

\Software

\Sybase

\SQL Remote

•	Windows 3.x and OS/2    In the file SQLANY.INI, in your SQL Remote installation directory.

•	NetWare    You should create a file named dbremote.ini in the sys:\system directory to hold the FILE system directory setting.

  For a listing of registry settings, see the section for each message system under Using message types.


The Database Extraction utility
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 22.  Utilities and Options Reference

 The Database Extraction utility

You can access the remote database extraction utility in the following ways:

•	From Sybase Central, for interactive use under Windows 95 or NT.

•	From the system command line, using the ssxtract or dbxtract command-line utilities. This is useful for incorporating into batch or command files.

ssxtract is the extraction utility for Adaptive Server Enterprise, dbxtract is the extraction utility for Adaptive Server Anywhere.

By default, the extraction utility runs at isolation level zero. If you are extracting a database from an active server, you should run it at isolation level 3 (see Extraction utility options) to ensure that data in the extracted database is consistent with data on the server. Running at isolation level 3 may hamper others' turnaround time on the server because of the large number of locks required. It is recommended that you run the extraction utility when the server is not busy, or run it against a copy of the database (see Designing an efficient extraction procedure).

Objects owned by dbo

The dbo user ID owns a set of Adaptive Server Enterprise-compatible system objects in an Adaptive Server Anywhere database.

For Adaptive Server Anywhere, the extraction utility does not unload the objects created for the dbo user ID during database creation. Changes made to these objects, such as redefining a system procedure, are lost when the data is unloaded. Any objects created by the dbo user ID since the initialization of the database are unloaded by the Extraction utility, and so these objects are preserved.

 Extracting a remote database in Sybase Central

 The extraction command-line utility

 Extraction utility options


Extracting a remote database in Sybase Central
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 22.  Utilities and Options Reference

        The Database Extraction utility

 Extracting a remote database in Sybase Central

Running the extraction utility from Sybase Central carries out the following tasks related to creating and synchronizing SQL Remote subscriptions:

•	Creates a command file to build a remote database containing a copy of the data in a specified publication.

•	Creates the necessary SQL Remote objects, such as message types, publisher and remote user IDs, publication and subscription, for the remote database to receive messages from and send messages to the consolidated database.

•	Starts the subscription at both the consolidated and remote databases.

♦ To extract a remote database from a running database

1	Connect to the database.

2	Right-click the database and choose Extract Database from the popup menu.

3	Follow the instructions in the wizard.

♦ To extract a remote database from a database file or a running database

1	Open the Utilities folder.

2	In the right pane, double-click Extract Database.

3	Follow the instructions in the wizard.


The extraction command-line utility
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 22.  Utilities and Options Reference

        The Database Extraction utility

 The extraction command-line utility

Purpose

To extract a remote Adaptive Server Anywhere database from a consolidated Adaptive Server Enterprise or Adaptive Server Anywhere database.

Syntax

{ ssxtract | dbxtract } [ switches ]  [ directory ] subscriber

Switch	Description
-an database	Creates a database file with the same settings as the database being unloaded and automatically reloads it.
-ac "keyword=value; ..."	Connect to the database specified in the connect string to do the reload.
-b	Do not start subscriptions
-c "keyword=value; ..."	Supply database connection parameters
-d	Unload data only
-e language,charset	Specify the locale to be used
-f	Extract fully qualified publications
-ii	Internal unload, internal reload
-ix	Internal unload, external reload
-j count	Iteration count for view creation statements
-l level	Perform all extraction operations at specified isolation level
-k	Close window on completion
-n	Extract schema definition only
-o file	Output messages to file
-p character	Escape character
-q	Operate quietly: do not print messages or show windows
-r file	Specify name of generated reload Interactive SQL command file (default "reload.sql")
-u	Unordered data
-v	Verbose messages
-x	Use external table loads
-xf	Exclude foreign keys
-xi	External unload, internal reload
-xp	Exclude stored procedures
-xt	Exclude triggers
-xv	Exclude views
-xx	External unload, external load
-y	Overwrite command file without confirmation
directory	The directory to which the files are written. This is not needed if you use -an or -ac
subscriber	The subscriber for whom the database is to be extracted.
Description

ssxtract is the extraction utility for Adaptive Server Enterprise. It is run against a Adaptive Server Enterprise and creates a command file for a remote Adaptive Server Anywhere database.

dbxtract is the extraction utility for Adaptive Server Anywhere. It is run against an Adaptive Server Anywhere database and creates a command file for a remote Adaptive Server Anywhere database.

There is no extraction utility to create remote Adaptive Server Enterprise databases.

The command line extraction utility creates a command file and a set of associated data files. The command file can be run against a newly-initialized Adaptive Server Anywhere database to create the database objects and load the data for the remote database.

By default, the command file is named reload.sql.

If the remote user is a group, then all the user IDs that are members of that group are extracted. This allows multiple users on a remote database with different user IDs, without requiring a custom extraction process.

SSXtract notes

Not all Adaptive Server Enterprise objects have corresponding objects in Adaptive Server Anywhere. The ssxtract utility has the following limitations:

•	Single database    All extracted objects must be in a single Adaptive Server Enterprise database.

•	Passwords    The password for the extracted user IDs are the same as the user ID itself.

•	Permissions    The extracted user ID is granted REMOTE DBA authority.

•	Named constraints    These are extracted as Adaptive Server Anywhere CHECK constraints.

•	System tables    The sp_populate_sql_anywhere SQL Remote procedure builds a set of Adaptive Server Anywhere system tables in TEMPDB from the Adaptive Server Enterprise system tables. The extracted schema comes from these temporary system tables.

  For more information about the command-line switches, see Extraction utility options.


Extraction utility options
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 22.  Utilities and Options Reference

        The Database Extraction utility

 Extraction utility options

Create a database for reloading (-an)    You can combine the operations of unloading a database, creating a new database, and loading the data using this option.

For example, the following command (which should be entered all on one line) creates a new database file named asacopy.db and copies the schema and data for the field_user subscriber of asademo.db into it:

dbxtract -c "uid=dba;pwd=sql;dbf=asademo.db" -an asacopy.db field_user

If you use this option, no copy of the data is created on disk, so you do not specify an unload directory on the command line. This provides greater security for your data, but at some cost for performance.

Reload the data to an existing database (-ac)    You can combine the operation of unloading a database and reloading the results into an existing database using this option.

For example, the following command (which should be entered all on one line) loads a copy of the data for the field_user subscriber into an existing database file named newdemo.db:

dbxtract -c "uid=dba;pwd=sql;dbf=asademo.db" -ac "uid=dba;pwd=sql;dbf=newdemo.db" field_user

If you use this option, no copy of the data is created on disk, so you do not specify an unload directory on the command line. This provides greater security for your data, but at some cost for performance.

Do not start subscriptions automatically (-b)   If this option is selected, subscriptions at the consolidated database (for the remote database) and at the remote database (for the consolidated database) must be started explicitly using the START SUBSCRIPTION statement for replication to begin.

Connection parameters (-c)   A set of connection parameters, in a string.

•	dbxtract connection parameters     The user ID should have DBA authority to ensure that the user has permissions on all the tables in the database.

For example, the following statement (which should be typed on one line) extracts a database for remote user ID joe_remote from the asademo database running on the sample_server server, connecting as user ID DBA with password SQL. The data is unloaded into the c:\unload directory.

ssxtract -c "eng=sample_server;dbn=sademo;

uid=dba;pwd=sql" c:\extract joe_remote

If connection parameters are not specified, connection parameters from the SQLCONNECT environment variable are used, if set.

•	ssxtract connection parameters    The following connection parameters are supported:

Parameter	Description
UID	Login ID
PWD	Password
DBN	(optional) Database name. If this parameter is not supplied, the connection defaults to the default database for the login ID.
ENG	Adaptive Server Enterprise name.
ssxtract cannot extract passwords. It sets passwords to be the same as the user ID.

Unload the data only (-d)   If this option is selected, the schema definition is not unloaded, and publications and subscriptions are not created at the remote database. This option is for use when a remote database already exists with the proper schema, and needs only to be filled with data.

Use specified locale (-e)    This option applies to Adaptive Server Enterprise only.

Specify Adaptive Server Enterprise locale information. The locale string has the following format:

"language_name,charset_name[,sort_order]"

By default, the Message Agent uses the default locale, which is defined in the file sybase\locales\locales.dat.

If language_name and charset_name are not supplied, the Message Agent obtains them from Adaptive Server Enterprise. If sort_order is not supplied, the Message Agent uses a binary sort order (sort by byte value).

Extract fully qualified publications (-f)    In most cases, you do not need to extract fully qualified publication definitions for the remote database, since it typically replicates all rows back to the consolidated database anyway.

However, you may want fully qualified publications for multi-tier setups or for setups where the remote database has rows that are not in the consolidated database.

Internal unload, internal load (-ii)     Using this option forces the reload script to use the internal UNLOAD and LOAD TABLE statements rather than the Interactive SQL OUTPUT and INPUT statements to unload and load data, respectively.

This combination of operations is the default behavior.

External operations takes the path of the data files relative to the current working directory of dbxtract, while internal statements take the path relative to the server.

Internal unload, external load (-ix)    Using this option forces the reload script to use the internal UNLOAD statement to unload data, and the Interactive SQL INPUT statement to load the data into the new database.

External operations takes the path of the data files relative to the current working directory of dbxtract, while internal statements take the path relative to the server.

Iteration count for views (-j)    If there are nested views in the consolidated database, this option specifies the maximum number of iterations to use when extracting the views.

Perform extraction at a specified isolation level (-l)     The default setting is an isolation level of zero. If you are extracting a database from an active server, you should run it at isolation level 3 (see Extraction utility options) to ensure that data in the extracted database is consistent with data on the server. Increasing the isolation level may result in large numbers of locks being used by the extraction utility, and may restrict database use by other users.

Unload the schema definition only (-n)    With this definition, none of the data is unloaded. The reload file contains SQL statements to build the database structure only. You can use the SYNCHRONIZE SUBSCRIPTION statement to load the data over the messaging system. Publications, subscriptions, PUBLISH and SUBSCRIBE permissions are part of the schema.

Output messages to file (-o)    Outputs the messages from the extraction process to a file for later review.

Escape character (-p)    The default escape character (\) can be replaced by another character using this option.

Operate quietly (-q)    Display no messages except errors. This option is not available from other environments. This is available only from the command-line utility.

Reload filename (-r)    The default name for the reload command file is reload.sql in the current directory You can specify a different file name with this option.

Output the data unordered (-u)    By default the data in each table is ordered by primary key. Unloads are quicker with the -u switch, but loading the data into the remote database is slower.

Verbose mode (-v)    The name of the table being unloaded and the number of rows unloaded are displayed. The SELECT statement used is also displayed.

Exclude foreign key definitions (-xf)    You can use this if the remote database contains a subset of the consolidated database schema, and some foreign key references are not present in the remote database.

External unload, internal load (-xi)    The default behavior for unloading the database is to use the UNLOAD statement, which is executed by the database server. If you choose an external unload, dbxtract uses the OUTPUT statement instead. The OUTPUT statement is executed at the client.

External operations takes the path of the data files relative to the current working directory of dbxtract, while internal statements take the path relative to the server.

Exclude stored procedure (-xp)    Do not extract stored procedures from the database.

Exclude triggers (-xt)    Do not extract triggers from the database.

Exclude views (-xv)    Do not extract views from the database.

External unload, external load (-xx)    Use the OUTPUT statement to unload the data, and the INPUT statement to load the data into the new database.

The default unload behavior is to use the UNLOAD statement, and the default loading behavior is to use the LOAD TABLE statement. The internal UNLOAD and LOAD TABLE statements are faster than OUTPUT and INPUT.

External operations takes the path of the data files relative to the current working directory of dbxtract, while internal statements take the path relative to the server.

Operate without confirming actions (-y)    Without this option, you are prompted to confirm the replacement of an existing command file.


The SQL Remote Open Server
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 22.  Utilities and Options Reference

 The SQL Remote Open Server

Purpose

To take replication data from Replication Server and apply it to the SQL Remote stable queue. This utility is needed only for databases participating in both Replication Server (and using a Replication Agent) and SQL Remote replication.

Syntax

ssqueue  [ switches ] [ open-server-name ]

Command-line switches

Switch	Description
open-server-name	An open server name, which must be declared in the interfaces file.
-c "keyword=value; ..."	Supply database connection parameters
-cq "keyword=value; ..."	Supply database connection parameters for the stable queue
-dl	Display messages in window
-k	Close window on completion
-o file	Output messages to file
-os file	Maximum file size for logging output messages
-ot file	Truncate file and log output messages
-q	Run with minimized window
-ud	Run as a daemon [UNIX]
-v	Verbose operation
Description

The SQL Remote Open Server is used to enable an Adaptive Server Enterprise database to take part in both SQL Remote replication while acting as a primary site in a Replication Server installation (or a replicate site using asynchronous procedure calls).

The name of the executable is as follows:

•	ssqueue.exe    Windows NT platforms.

•	ssqueue    UNIX platforms.

Command-line switch details

open-server-name    Replication Server must connect to the SQL Remote Open Server, which therefore must have an open server name. This open server name is set on the command line, and must correspond to a master and query entry in the interfaces file on the machine running the SQL Remote Open Server, and to a query entry on the interfaces file of the machine running Replication Server.

The interfaces file is named sql.ini on Windows operating systems, and interfaces on UNIX.

The default value for the open server name is SSQueue.

-c    Specify connection parameters to the database holding the data being replicated. This connection is required for the SQL Remote Open Server to gain access to the SQL Remote system tables.

The connection parameters must come from the following list:

Parameter	Description
UID	Login ID
PWD	Password
DBN	(optional) Database name. If this parameter is not supplied, the connection defaults to the default database for the login ID.
ENG	Server name.
-cq    Specify connection parameters for the stable queue. If not supplied, the values default to the -c values.

-dl    Display messages in the window or on the command line and also in the log file.

-k    Close window on completion.

-o    Append output to a log file. Default is to send output to the screen.

-os    Specifies the maximum file size for logging output messages. The allowed size can be specified as n (bytes), nK (kb), or nM (Mb). By default there is no limit, and the minimum limit is 10000 bytes.

Before SQL Remote logs output messages to a file, it checks the current file size. If the log message will make the filesize exceed the specified size, SQL Remote renames the output file to yymmddnn.dbr (for dbremote) and yymmddnn.ssr (for ssremote) where nn is an integer from 00 to 99 and yymmdd represents the current year, month, and date.

If the Message Agent us running in continuous mode for a long time, this option allows you to manually delete old log files and free up disk space.

-ot    Truncate the log file and then append output messages to it. Default is to send output to the screen.

-q    For Windowing operating systems only, starts the Message Agent with a minimized window.

-ud    On UNIX platforms, you can run the SQL Remote Open Server as a daemon by supplying the -ud command-line option.

If you run as a daemon, you must also supply the -o or -ot command-line option, to log output information.

-v    Verbose output. This switch displays the SQL statements contained in the messages to the screen and, if the -o switch is used, to a log file.


SQL Remote options
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 22.  Utilities and Options Reference

 SQL Remote options

Function

Replication options are database options included to provide control over replication behavior.

Anywhere Syntax

SET [ TEMPORARY ] OPTION

   ... [ userid. | PUBLIC. ]option_name = [ option_value ]

Enterprise syntax:

exec sp_remote_option option-name, option-value

Parameters

Argument	Description
option_name	The name of the option being changed.
option-value	A string containing the setting for the option.
Description

The following options are available.

OPTION	VALUES	DEFAULT
Blob_threshold	integer, in kb	256
Compression	-1 to 9	6
Delete_old_logs	ON, OFF	OFF
External_remote_options	ON, OFF	OFF
Qualify_owners	ON, OFF	OFF
Quote_all_identifiers	ON, OFF	OFF
Replication_error	procedure-name	NULL
Save_remote_passwords	ON, OFF	ON
SR_Date_Format	date-string	yyyy/mm/dd
SR_Time_Format	time-string	hh:nn:ss.Ssssss
SR_Timestamp_Format	timestamp-string	yyyy/mm/dd hh:nn:ss.Ssssss
Subscribe_by_remote	ON,OFF	ON
Verify_threshold	integer	256
Verify_all_columns	ON,OFF	OFF
These options are used by the Message Agent, and should be set for the user ID specified on the Message Agent command line. They can also be set for general public use.

The options are as follows:

Blob_threshold option    Any value longer than the Blob_threshold option is replicated as a blob. That is, it is broken into pieces and replicated in chunks, before being reconstituted by using a SQL variable and concatenating the pieces at the recipient site.

If you are replicating blobs in an installation with Adaptive Server Enterprise, you must ensure that Blob_threshold is set to a value larger the largest blob being replicated.

  For information on blob replication and Adaptive Server Enterprise, see Replication of blobs.

Compression option    Set the level of compression for messages. Values can be from -1 to 9, and have the following meanings:

•	-1    Send messages in Version 5 format. Message Agents (both dbremote and ssremote) from previous versions of SQL Remote cannot read messages sent in Version 6 or Version 7 format. You should ensure that COMPRESSION is set to -1 until all Message Agents in your system are upgraded to Version 7.

•	0    No compression.

•	1 to 9    Increasing degrees of compression. Creating messages with high compression can take longer than creating messages with low compression.

Delete_old_logs option    This option is used by SQL Remote and by the Adaptive Server Anywhere Replication Agent. The default setting is OFF. When set to ON, the Message Agent (DBREMOTE) deletes each old transaction log when all the changes it contains have been sent and confirmed as received.

External_remote_options    This option is used by SQL Remote to indicate whether the message link parameters should be stored in the database (OFF) or externally (ON). By default, the setting is OFF.

Qualify_owners option    Controls whether SQL statements being replicated by SQL Remote should use qualified object names. The default in Adaptive Server Anywhere is ON and the default in Adaptive Server Enterprise is OFF.

Qualifying owners in Adaptive Server Enterprise setups is rarely needed because it is common for objects to be owned by dbo. When qualification is not needed in Adaptive Server Anywhere setups, messages will be slightly smaller with the option off.

Quote_all_identifiers option    Controls whether SQL statements being replicated by SQL Remote should use quoted identifiers. The default is OFF.

When this option is off, the dbremote quotes identifiers that require quotes by Adaptive Server Anywhere (as it has always done) and ssremote does not quote any identifiers. When the option is on, all identifiers are quoted.

Replication_error option     Specifies a stored procedure called by the Message Agent when a SQL error occurs. By default no procedure is called.

The replication error procedure must have a single argument of type CHAR, VARCHAR, or LONG VARCHAR. The procedure may be called once with the SQL error message and once with the SQL statement that causes the error.

While the option allows you to track and monitor SQL errors in replication, you must still design them out of your setup: this option is not intended to resolve such errors.

You can use a table with DEFAULT CURRENT REMOTE USER to record the remote site that caused the error.

Save_remote_passwords option    When a password is entered into the message link dialog box on first connection, the parameter values are saved. By default, Save_remote_passwords is ON and the password is saved. If you are storing the message link parameters externally, rather than in the database, you may wish not to save the passwords. You can prevent the passwords from being saved by setting this option to NO.

SR_Date_Format option    The Message Agent uses this option when replicating columns that store a date. The option is a string build from the following symbols:

Symbol	Description
yy	Two digit year
yyyy	Four-digit year
mm	Two-digit month
mmm	Character format for month
dd	Two-digit day
Each symbol is substituted with the date being replicated.

If you set the mm format symbol in upper case, the corresponding characters are also upper case.

For the digit formats, the case of the option setting controls padding. If the symbols are the same case (such as DD), the number is padded with zeroes. If the symbols are mixed case (such as Mm), the number is not zero padded.

SR_Time_Format option    The Message Agent uses this option when replicating columns that store a time. The option is a string build from the following symbols:

Symbol	Description
hh	Two digit hours (24-hour clock)
nn	Two-digit minutes
mm	Two digit minutes if following a colon (as in hh:mm)
ss[.s...]	Two-digit seconds plus optional fractions of a second.
Using mixed case in the formatting string suppresses leading zeroes.

SR_Timestamp_Format    The Message Agent  replicates datetime information using this option. For Adaptive Server Anywhere this is the timestamp, datetime, and smalldatetime data types. For Adaptive Server Enterprise, this is the datetime and smalldatetime data types.

The format strings are taken from the SR_Date_Format and SR_Time_Format settings.

The default setting is the SR_Date_Format setting,followed by the SR_Time_Format setting.

Subscribe_by_remote option     When set to ON, operations from remote databases on rows with a subscribe by value that is NULL or an empty string assume the remote user is subscribed to the row. When set to OFF, the remote user is assumed not to be subscribed to the row.

The only limitation of this option is that it will lead to errors if a remote user really does want to INSERT (or UPDATE) a row with a NULL or empty subscription expression (for information held only at the consolidated database). This is reasonably obscure and can be worked around by assigning a subscription value in your installation that belongs to no remote user.

  For more information about this option, see Using the Subscribe_by_remote option with many-to-many relationships, and Using the Subscribe_by_remote option with many-to-many relationships.

Verify_threshold option    If the data type of a column is longer than the threshold, old values for the column are not verified when an UPDATE is replicated. The default setting is 1000.

This option keeps the size of SQL Remote messages down, but has the disadvantage that conflicting updates of long values are not detected.

Verify_all_columns option    The default setting is OFF. When set to ON, messages containing updates published by the local database are sent with all column values included, and a conflict in any column triggers a RESOLVE UPDATE trigger at the subscriber database.

The extraction utility for Adaptive Server Enterprise sets the public option in remote Adaptive Server Anywhere databases to match the setting in the Adaptive Server Enterprise database.

Examples

•	The following statement sets the Verify_all_columns option to OFF in Adaptive Server Anywhere, for all users:

SET OPTION PUBLIC.Verify_all_columns = 'OFF'

•	The following statements set the Verify_all_columns option to OFF in Adaptive Server Enterprise:

exec sp_remote_option Verify_all_columns, 'OFF'

go

In Adaptive Server Enterprise, replication options are used only by SQL Remote.


CHAPTER 23.  System Objects for Adaptive Server Anywhere
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 23.  System Objects for Adaptive Server Anywhere

About this chapter

SQL Remote-specific system information is held in a the Adaptive Server Anywhere catalog. A more comprehensible version of this information is held in a set of system views.

 SQL Remote system tables

 SQL Remote system views


SQL Remote system tables
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

 SQL Remote system tables

This section describes the system tables used by SQL Remote to define and manage SQL Remote information. In the following diagram, arrows indicate foreign key relations between tables: the arrow leads from the foreign table to the primary table.

These tables are described in more detail in the following sections.

 SYSARTICLE table

 SYSARTICLECOL table

 SYSPUBLICATION table

 SYSREMOTEOPTION table

 SYSREMOTEOPTIONTYPE table

 SYSREMOTETYPE table

 SYSREMOTEUSER table

 SYSSUBSCRIPTION table


SYSARTICLE table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSARTICLE table

Function

Each row describes an article in a SQL Remote publication.

Columns

Column	Data type	Description
publication_id	UNSIGNED INT	The publication of which this article is a part.
table_id	UNSIGNED INT	Each article consists of columns and rows from a single table. This column contains the table ID for this table.
where_expr	LONG VARCHAR	For articles that contain a subset of rows defined by a WHERE clause, this column contains the search condition.
subscribe_by_expr	LONG VARCHAR	For articles that contain a subset of rows defined by a SUBSCRIBE BY expression, this column contains the expression.
query	CHAR(1)	The SUBSCRIBE BY expression could be a subquery that returns multiple values. This column contains Y or N to indicate if the expression is a subquery (Y) or not (N). This column is used by the Extraction utility


SYSARTICLECOL table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSARTICLECOL table

Function

Each row identifies a column in an article, identifying the column, the table it is in, and the publication it is part of.

Columns

Column	Data type	Description
publication_id	UNSIGNED INT	A unique identifier for the publication of which the column is a part.
table_id	UNSIGNED INT	The table to which the column belongs.
column_id	UNSIGNED INT	The column identifier, from the SYSCOLUMN system table.


SYSPUBLICATION table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSPUBLICATION table

Function

Each row describes a SQL Remote publication.

Columns

Column	Data type	Description
publication_id	UNSIGNED INT	A unique identifier for the publication
creator	UNSIGNED INT	The user ID that owns the publication
publication_name	VARCHAR(128)	The name of the publication
remarks	LONG VARCHAR	Comments


SYSREMOTEOPTION table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSREMOTEOPTION table

Function

Each row describes the values of a SQL Remote message link parameter.

Columns

Column	Data type	Description
option_id	UNSIGNED INT	An identification number for the message link parameter.
user_id	UNSIGNED INT	The user ID for which the parameter is set.
"setting00"	VARCHAR(255)	The value of the message link parameter.


SYSREMOTEOPTIONTYPE table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSREMOTEOPTIONTYPE table

Function

Each row describes one of the SQL Remote message link parameters.

Columns

Column	Data type	Description
option_id	UNSIGNED INT	An identification number for the message link parameter.
type_id	SMALLINT	An identification number for the message type that uses this parameter
"option"	VARCHAR(128)	The name of the message link parameter.


SYSREMOTETYPE table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSREMOTETYPE table

Function

Each row describes one of the SQL Remote message types, including the publisher address.

Columns

Column	Data type	Description
type_id	SMALLINT	An identification number for the message type.
type_name	VARCHAR(128)	The message type. There is a separate row for each of the following: • FILE • MAPI • VIM • SMTP
publisher_address	VARCHAR(128)	The publisher's address for the message type type_name. SQL Remote receives messages from this address.
remarks	LONG VARCHAR	Comments


SYSREMOTEUSER table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSREMOTEUSER table

Function

Each row describes a user ID with REMOTE permissions (a subscriber), together with the status of SQL Remote messages sent to and from that user.

Columns

Column	Data type	Description
user_id	UNSIGNED INT	The user ID of the user with REMOTE permissions.
consolidate	CHAR(1)	The column contains either an N to indicate a user granted REMOTE permissions, or a Y to indicate a user granted CONSOLIDATE permissions.
type_id	SMALLINT	The ID of the message system used to send messages to this user.
address	LONG VARCHAR	The address to which SQL Remote messages are to be sent. The address must be appropriate for the address_type.
frequency	CHAR(1)	How frequently SQL Remote messages are to be sent. P for Periodically, and A stands for Occasionally.
send_time	TIME	The next time messages are to be sent to this user.
log_send	NUMERIC(20, 0)	If log_send is greater than log_sent, the Message Agent resends messages immediately to the subscriber the next time it is run.
time_sent	TIMESTAMP	The time the most recent message was sent to this subscriber.
log_sent	NUMERIC(20, 0)	The local log offset for the most recently sent operation to this subscriber.
confirm_sent	NUMERIC(20, 0)	The log offset for the most recently confirmed operation from this subscriber.
send_count	INT	The number of SQL Remote messages have been sent to this subscriber.
resend_count	INT	Counter to ensure messages are applied only once at the subscriber database.
time_received	DATETIME	The time the most recent message was received from this subscriber.
log_received	NUMERIC(20, 0)	The log offset in the subscriber's database for the operation most recently received at the current database.
confirm_received	NUMERIC(20, 0)	The log offset in the subscriber's database for the most recent operation for which a confirmation message has been sent.
receive_count	INT	How number of messages received from this subscriber.
rereceive_count	INT	Counter to ensure messages are applied only once at the current database.


SYSSUBSCRIPTION table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system tables

 SYSSUBSCRIPTION table

Function

Each row describes a subscription from one user ID (which must have REMOTE permissions) to one publication.

Columns

Column	Data type	Description
publication_id	UNSIGNED INT	The identifier for the publication to which the user ID is subscribed.
user_id	UNSIGNED INT	The user ID that is subscribed to the publication.
subscribe_by	VARCHAR(128)	For publications with a SUBSCRIBE BY expression, this column holds the matching value for this subscription.
created	NUMERIC(20, 0)	The offset in the transaction log at which the subscription was created.
started	NUMERIC(20, 0)	The offset in the transaction log at which the subscription was started.


SQL Remote system views
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

 SQL Remote system views

This section describes the database views used by SQL Remote to present and summarize SQL Remote information.

 SYSARTICLES view

 SYSARTICLECOLS view

 SYSPUBLICATIONS view

 SYSREMOTEOPTIONS view

 SYSREMOTEUSERS view

 SYSSUBSCRIPTIONS view


SYSARTICLES view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system views

 SYSARTICLES view

Function

Each row lists describes an article.

Columns

Column	Description
publication_name	The publication of which this article is a part.
table_name	Each article consists of columns and rows from a single table. This column contains the name of this table.
where_expr	For articles that contain a subset of rows defined by a WHERE clause, this column contains the search condition.
subscribe_by_expr	For articles that contain a subset of rows defined by a SUBSCRIBE BY expression, this column contains the expression.


SYSARTICLECOLS view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system views

 SYSARTICLECOLS view

Function

Each row describes a column that appears in an article.

Columns

Column	Description
publication_name	The name of the publication of which the column is a part.
table_name	The name of the table to which the column belongs.
column_name	The column name.


SYSPUBLICATIONS view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system views

 SYSPUBLICATIONS view

Function

Lists the names of all publications.

Columns

Column	Description
publication_name	The name of the publication
createor	The owner of the publication
remarks	Comments


SYSREMOTEOPTIONS view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system views

 SYSREMOTEOPTIONS view

Function

Lists the SQL Remote message link parameters and their values, as stored in the SYSREMOTEOPTION and SYSREMOTEOPTIONTYPE system tables, in more readable form.

Columns

Column	Description
type_name	The message link type.
"option"	The option name.
setting	The option value.


SYSREMOTEUSERS view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system views

 SYSREMOTEUSERS view

Function

Lists information about remote users and their status.

Columns

Column	Description
user_name	The user ID of the user with REMOTE permissions.
consolidate	The column contains either an N to indicate a user with REMOTE permissions, or a Y to indicate a user with CONSOLIDATE permissions.
type_name	The name of the message type used to send messages to this user.
address	The address to which SQL Remote messages are to be sent. The address must be appropriate for the address_type.
frequency	How frequently SQL Remote messages are to be sent.
send_time	The next time messages are to be sent to this user.
next_send	The next time messages are to be sent to this user, in a more comprehensible format.
log_send	Messages are sent only to subscribers for whom log_send is greater than log_sent.
time_sent	The time the most recent message was sent to this subscriber.
log_sent	The transaction log offset for the most recently sent operation.
confirm_sent	The transaction log offset for the most recently confirmed operation from this subscriber.
send_count	How many SQL Remote messages have been sent.
resend_count	Counter to ensure messages are applied only once at the subscriber database.
time_received	The time the most recent message was received from this subscriber.
log_received	The log offset in the subscriber's database for the operation most recently received at the current database.
confirm_received	The log offset in the subscriber's database for the most recent operation for which a confirmation message has been sent.
receive_count	How many messages have been received.
rereceive_count	Counter to ensure messages are applied only once at the current database.


SYSSUBSCRIPTIONS view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 23.  System Objects for Adaptive Server Anywhere

        SQL Remote system views

 SYSSUBSCRIPTIONS view

Function

Each row lists information about a subscription.

Columns

Column	Description
publication_name	The name of the publication to which the user ID is subscribed.
user_name	The user ID that is subscribed to the publication.
subscribe_by	For publications with a SUBSCRIBE BY expression, this column holds the matching value for this subscription.
created	The offset in the transaction log at which the subscription was created.
started	The offset in the transaction log at which the subscription was started.


CHAPTER 24.  System Objects for Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 24.  System Objects for Adaptive Server Enterprise

About this chapter

SQL Remote-specific system information is held in a set of tables called the SQL Remote system tables. A more comprehensible version of this information is held in a set of views, called the SQL Remote system views.

 SQL Remote system tables

 SQL Remote system views

 Stable Queue tables


SQL Remote system tables
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

 SQL Remote system tables

This section describes the database tables used by SQL Remote to define and manage SQL Remote information.

Caution
These tables are for use only by SQL Remote. Do not alter these tables or their contents directly.

 #remote table

 sr_article table

 sr_articlecol table

 sr_marker table

 sr_object table

 sr_option table

 sr_passthrough table

 sr_publication table

 sr_publisher table

 sr_remoteoption table

 sr_remoteoptiontype table

 sr_remotetable table

 sr_remotetype table

 sr_remoteuser table

 sr_subscription table


#remote table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 #remote table

Function

This temporary table is created by the Message Agent to hold the name of the current remote user and of the current publisher. This table exists only in Adaptive Server Enterprise.

Columns

Column	Data type	Description
current_remote_user	VARCHAR(128)	Current remote user (from the Message Agent command line).
current_publisher	VARCHAR(128)	Current publisher
Description

This is not a system table. When the Message Agent for Adaptive Server Enterprise connects to the server, it holds the value of the current remote user ID and the value of the current publisher in the #remote table. This temporary table is held in TEMPDB.

The values from #remote can be used in conflict resolution procedures.

The CREATE TABLE statement for this table is:

CREATE TABLE #remote (

current_remote_user varchar(128),

current_publisher varhcar(128)

)

The table has a single row.


sr_article table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_article table

Function

Each row describes an article in a SQL Remote publication.

Columns

Column	Data type	Description
publication_id	INT	The publication of which this article is a part.
table_id	INT	Each article consists of columns and rows from a single table. This column contains the table ID for this table.
where_expr	VARCHAR(128)	For articles that contain a subset of rows defined by a WHERE clause, this column contains the search condition.
subscribe_by_expr	VARCHAR(128)	For articles that contain a subset of rows defined by a SUBSCRIBE BY expression, this column contains the expression.
subscribe_by_view	VARCHAR(128)	For articles that contain a subset of the rows defined by a view. This column contains the name of the view.


sr_articlecol table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_articlecol table

Function

Each row identifies a column in an article, identifying the column, the table it is in, and the publication it is part of.

Columns

Column	Data type	Description
publication_id	INT	A unique identifier for the publication of which the column is a part.
table_id	INT	The table to which the column belongs.
column_id	INT	The column identifier, from the SYSCOLUMN system table.


sr_marker table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_marker table

Function

To ensure that messages received by the Message Agent are sent to remote databases in the same session.

Columns

Column	Data type	Description
marker	DATETIME	A time value indicating when the latest messages were applied.
Description

When a consolidated database uses two Message Agents, one to populate the stable queue (-i) and one to receive and send messages (-r -s), the single row of the sr_marker table is used to ensure that messages received and applied to the database are sent before the Message Agent closes down.


sr_object table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_object table

Function

Holds a list of SQL Remote objects. The extraction utility needs to know not to extract the SQL Remote system objects. The sp_populate_sql_anywhere procedure that creates a set of Adaptive Server Anywhere system tables in TEMPDB gets a list of SQL Remote objects from the sr_object table.

Columns

Column	Data type	Description
name	VARCHAR(128)	The name of the object.
type	CHAR(1)	One of the following: • U    User-defined table • V    View • P    Procedure


sr_option table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_option table

Function

Each row describes a replication option used by SQL Remote.

Columns

Column	Data type	Description
option	VARCHAR(128)	The name of the option.
value	VARCHAR(128)	The setting for the option.
Description

  For information about available options, see SQL Remote options.


sr_passthrough table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_passthrough table

Function

Each row describes a passthrough operation being sent to a user or to subscribers to a publication.

Columns

Column	Data type	Description
operation	VARCHAR(20)	A passthrough operation, or piece of a passthrough operation, entered using sp_passthrough or sp_passthrough_piece.
value	VARCHAR(255)	A subscription column value indicating which users are to receive the operation.
id	INT	A user who is to receive the operation.


sr_publication table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_publication table

Function

Each row describes a SQL Remote publication.

Columns

Column	Data type	Description
publication_id	INT	An identifier for the publication
publication_name	VARCHAR(128)	The name of the publication.


sr_publisher table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_publisher table

Function

The row holds the user ID of the  publisher.

Columns

Column	Data type	Description
user_id	INT	The user ID of the publisher.


sr_remoteoption table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_remoteoption table

Function

Each row describes the values of a SQL Remote message link parameter.

Columns

Column	Data type	Description
option_id	INTEGER	An identification number for the message link parameter.
user_id	INTEGER	The user ID for which the parameter is set.
"setting00"	VARCHAR(255)	The value of the message link parameter.


sr_remoteoptiontype table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_remoteoptiontype table

Function

Each row describes one of the SQL Remote message link parameters.

Columns

Column	Data type	Description
option_id	INTEGER	An identification number for the message link parameter.
type_id	INTEGER	An identification number for the message type that uses this parameter
"option"	VARCHAR(128)	The name of the message link parameter.


sr_remotetable table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_remotetable table

Function

Each row describes a table that is marked for replication using SQL Remote.

Columns

Column	Data type	Description
table_id	INT	The id of the table.
resolve_name	VARCHAR(128)	The name of the stored procedure to be executed in the case of conflicts.
old_row_name	VARCHAR(128)	The table that holds the old row name.
remote_row_name	VARCHAR(128)	The table that holds the remote row name.


sr_remotetype table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_remotetype table

Function

Each row describes one of the SQL Remote message types, including the publisher address.

Columns

Column	Data type	Description
type_id	INT	An identification number for the message type.
type_name	VARCHAR(128)	The message type. There is a separate row for each of the following: • FILE • MAPI • VIM • SMTP
publisher_address	VARCHAR(128)	The publisher's address for the message type type_name.


sr_remoteuser table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_remoteuser table

Function

Each row describes a user ID with REMOTE permissions (a subscriber), together with the status of SQL Remote messages sent to and from that user.

Columns

Column	Data type	Description
user_id	INT	The user ID of the user with REMOTE permissions.
consolidate	CHAR(1)	The column contains either an N to indicate a user granted REMOTE permissions, or a Y to indicate a user granted CONSOLIDATE permissions.
type_id	INT	The ID of the message system used to send messages to this user.
address	VARCHAR(128)	The address to which SQL Remote messages are to be sent. The address must be appropriate for the address_type.
frequency	CHAR(1)	How frequently SQL Remote messages are to be sent.
send_time	DATETIME	The next time messages are to be sent to this user.
log_send	NUMERIC(20, 0)	Messages are sent only to subscribers for whom log_send is greater than log_sent.
time_sent	DATETIME	The time the most recent message was sent to this subscriber.
log_sent	NUMERIC(20, 0)	The log offset for the most recently sent operation.
confirm_sent	NUMERIC(20, 0)	The log offset for the most recently confirmed operation from this subscriber.
send_count	INT	How many SQL Remote messages have been sent.
resend_count	INT	Counter to ensure messages are applied only once at the subscriber database.
time_received	DATETIME	The time the most recent message was received from this subscriber.
log_received	NUMERIC(20, 0)	The log offset in the subscriber's database for the operation most recently received at the current database.
confirm_received	NUMERIC(20, 0)	The log offset in the subscriber's database for the most recent operation for which a confirmation message has been sent.
receive_count	INT	How many messages have been received from this subscriber.
rereceive_count	INT	Counter to ensure messages are applied only once at the current database.
filler1	CHAR(255)	Reserved
filler2	CHAR(255)	Reserved
filler3	CHAR(255)	Reserved
filler4	CHAR(255)	Reserved


sr_subscription table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system tables

 sr_subscription table

Function

Each row describes a subscription from one user ID (which must have REMOTE permissions) to one publication.

Columns

Column	Data type	Description
publication_id	INT	The identifier for the publication to which the user ID is subscribed.
user_id	INT	The user ID that is subscribed to the publication.
subscribe_by	VARCHAR(128)	For publications with a SUBSCRIBE BY expression, this column holds the matching value for this subscription.
created	NUMERIC(20, 0)	The offset in the transaction log at which the subscription was created.
started	NUMERIC(20, 0)	The offset in the transaction log at which the subscription was started.
operation	VARCHAR(20)


SQL Remote system views
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

 SQL Remote system views

This section describes the database views used by SQL Remote to present and summarize SQL Remote information.

 sr_articles view

 sr_articlecols view

 sr_publications view

 sr_remoteoptions view

 sr_remotetables view

 sr_remotetypes view

 sr_remoteusers view

 sr_subscriptions view


sr_articles view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_articles view

Function

Each row lists describes an article.

Columns

Column	Description
publication_name	The publication of which this article is a part.
table_name	Each article consists of columns and rows from a single table. This column contains the name of this table.
where_expr	For articles that contain a subset of rows defined by a WHERE clause, this column contains the search condition.
subscribe_by_expr	For articles that contain a subset of rows defined by a SUBSCRIBE BY expression, this column contains the expression.
subscribe_by_view	For articles that contain a subset of rows defined by a view, this column contains the name of the view.


sr_articlecols view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_articlecols view

Function

Each row describes a column that appears in an article.

Columns

Column	Description
publication_name	The name of the publication of which the column is a part.
table_name	The name of the table to which the column belongs.
column_name	The column name.


sr_publications view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_publications view

Function

Lists the names of all publications.

Columns

Column	Description
publication_name	The name of the publication


sr_remoteoptions view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_remoteoptions view

Function

Lists the SQL Remote message link parameters and their values, as stored in the remoteoption and remoteoptiontype system tables, in more readable form.

Columns

Column	Description
type_name	The message link type.
"option"	The option name.
setting	The option value.


sr_remotetables view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_remotetables view

Function

Lists the tables marked for SQL Remote replication, as stored in the remotetable system table, in more readable form.

This table exists only in Adaptive Server Enterprise.

Columns

Column	Description
table_name	The name of the table.
resolve_name	The name of the stored procedure to be executed in the case of conflicts.
old_row_name	The table that holds the old row name.
remote_row_name	The table that holds the remote row name.


sr_remotetypes view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_remotetypes view

Function

Lists the message types, as stored in the remotetype system table.

Columns

Column	Description
type_id	An identification number for the message type.
type_name	The message type. There is a separate row for each of the following: • FILE • MAPI • VIM • SMTP
publisher_address	The publisher's address for the message type type_name.


sr_remoteusers view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_remoteusers view

Function

Lists information about remote users and their status.

Columns

Column	Description
user_name	The user ID of the user with REMOTE permissions.
consolidate	The column contains either an N to indicate a user granted REMOTE permissions, or a Y to indicate a user granted CONSOLIDATE permissions.
type_name	The name of the message system used to send messages to this user.
address	The address to which SQL Remote messages are to be sent. The address must be appropriate for the address_type.
frequency	How frequently SQL Remote messages are to be sent.
send_time	The next time messages are to be sent to this user.
next_send	The next time messages are to be sent to this user, in a more comprehensible format.
log_send	Messages are sent only to subscribers for whom log_send is greater than log_sent.
time_sent	The time the most recent message was sent to this subscriber.
log_sent	The log offset for the most recently sent operation.
confirm_sent	The log offset for the most recently confirmed operation from this subscriber.
send_count	How many SQL Remote messages have been sent.
resend_count	Counter to ensure messages are applied only once at the subscriber database.
time_received	The time the most recent message was received from this subscriber.
log_received	The log offset in the subscriber's database for the operation most recently received at the current database.
confirm_received	The log offset in the subscriber's database for the most recent operation for which a confirmation message has been sent.
receive_count	How many messages have been received.
rereceive_count	Counter to ensure messages are applied only once at the current database.


sr_subscriptions view
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        SQL Remote system views

 sr_subscriptions view

Function

Each row lists information about a subscription.

Columns

Column	Description
publication_name	The name of the publication to which the user ID is subscribed.
user_name	The user ID that is subscribed to the publication.
subscribe_by	For publications with a SUBSCRIBE BY expression, this column holds the matching value for this subscription.
created	The offset in the transaction log at which the subscription was created.
started	The offset in the transaction log at which the subscription was started.


Stable Queue tables
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

 Stable Queue tables

This section describes the database tables used by SQL Remote to define and manage the stable queue information. The stable queue may be kept in the same database as the SQL Remote database, or in a separate database.

The stable queue is used only by SQL Remote for Adaptive Server Enterprise.

 sr_queue_state table

 sr_transaction table

 sr_confirmed_transaction table

 sr_queue_coordinate table


sr_queue_state table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        Stable Queue tables

 sr_queue_state table

Function

A single row table that stores persistent global information about the state of the stable queue.

Columns

Column	Data type	Description
version	INT	The stable queue version number
page_id	INT	Transaction log page_id of the last entry scanned.
row_id	INT	Transaction log row_id of the last entry scanned.
confirm_offset	NUMERIC(20,0)	The minimum value of the confirmation offsets received from all remote users. This value is used by the Message Agent to decide which transactions can be deleted from the stable queue.
commit_offset	NUMERIC(20,0)	The transaction log offset of the most recent transaction completed before the oldest incomplete transaction.
backup_offset	NUMERIC(20,0)	The transaction log offset of the last dump database or dump transaction command. This information is used when the Message Agent is run with the -u command-line switch (replicate only backed up transactions).
marker	DATETIME	The most recent incoming message that has been scanned into the stable queue. When a message is applied to the Adaptive Server Enterprise server, it sets the time_received column in sr_remoteuser. When the transaction log is scanned and the transactions from that message are scanned into the stable queue, it sets the time_received column of sr_queue_state. The purpose of the column is co-ordination between one Message Agent that is scanning the transaction log continuously and another Message Agent that is receiving messages and sending messages in batch mode. When in batch mode, the Message Agent receives messages, waits for those messages to be scanned into the stable queue, and then sends messages. The waiting is done through the database by looking at the time_received column of sr_queue_state.
confirmed_id	NUMERIC(20,0)	The sending thread deletes rows with confirmed_id less than this value from sr_confirmed_transaction.


sr_transaction table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        Stable Queue tables

 sr_transaction table

Function

This table has one row for each transaction in the stable queue.

Columns

Column	Description
offset	The transaction log offset of the commit operation for the transaction. This value uniquely identifies each transaction
user_id	The remote user where the transaction originated. This column holds NULL if the transaction did not originate from a remote user. The user_id column is used to ensure that actions are not replicated back to the remote site that entered them.
data	The transaction itself, in an internal representation.


sr_confirmed_transaction table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        Stable Queue tables

 sr_confirmed_transaction table

Function

Each row marks the corresponding row in sr_transaction.

Columns

Column	Data type	Description
confirmed_id	NUMERIC (20,0)	A unique ID
offset	NUMERIC (20,0)	A copy of an offset used to mark rows in sr_transaction for deletion.


sr_queue_coordinate table
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 24.  System Objects for Adaptive Server Enterprise

        Stable Queue tables

 sr_queue_coordinate table

Function

A single row, that coordinates the SQL Remote log scanning thread and the sending thread to access the stable queue and related tables.

Columns

Column	Data type	Description
status	CHAR(1)	N if the stable queue has not yet been used by SQL Remote. L and S if the SQL Remote log scanning thread and sending thread have accessed the queue.


CHAPTER 25.  Command Reference for Adaptive Server Anywhere
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 25.  Command Reference for Adaptive Server Anywhere

About this chapter

This chapter describes the SQL statements used for executing SQL Remote commands, and the system tables, used for storing information about the SQL Remote installation and its state.

 ALTER PUBLICATION statement

 ALTER REMOTE MESSAGE TYPE statement

 CREATE PUBLICATION statement

 CREATE REMOTE MESSAGE TYPE statement

 CREATE SUBSCRIPTION statement

 CREATE TRIGGER statement

 DROP PUBLICATION statement

 DROP REMOTE MESSAGE TYPE statement

 DROP SUBSCRIPTION statement

 GRANT CONSOLIDATE statement

 GRANT PUBLISH statement

 GRANT REMOTE statement

 GRANT REMOTE DBA statement

 PASSTHROUGH statement

 REMOTE RESET statement

 REVOKE CONSOLIDATE statement

 REVOKE PUBLISH statement

 REVOKE REMOTE statement

 REVOKE REMOTE DBA statement

 SET REMOTE OPTION statement

 START SUBSCRIPTION statement

 STOP SUBSCRIPTION statement

 SYNCHRONIZE SUBSCRIPTION statement

 UPDATE statement


ALTER PUBLICATION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 ALTER PUBLICATION statement

Function

Use this statement to alter the definition of a SQL Remote publication.

Syntax

ALTER PUBLICATION [ owner.]publication-name
  ADD TABLE article-description
...	| MODIFY TABLE article-description
| { DELETE | DROP } TABLE [ owner.]table-name
| RENAME publication-name

Parameters

article-description:
table-name [ ( column-name, ... ) ]
... 	[ WHERE search-condition ]
... 	[ SUBSCRIBE BY expression ]

Usage

Anywhere. This statement is applicable only to SQL Remote.

Permissions

Must have DBA authority, or be owner of the publication. Requires exclusive access to all tables referred to in the statement.

Side effects

Automatic commit.

See also

CREATE PUBLICATION statement

DROP PUBLICATION statement

sp_add_article procedure

sp_add_article_col procedure

Description

The ALTER PUBLICATION statement alters a SQL Remote publication in the database. The contribution to a publication from one table is called an article. Changes can be made to a publication by adding, modifying, or deleting articles, or by renaming the publication. If an article is modified, the entire specification of the modified article must be entered.

Example

The following statement adds the customer table to the pub_contact publication.

ALTER PUBLICATION pub_contact (

ADD TABLE customer

)


ALTER REMOTE MESSAGE TYPE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 ALTER REMOTE MESSAGE TYPE statement

Function

Use this statement to change the publisher's message system, or the publisher's address for a given message system, for a message type that has been created.

Syntax

ALTER REMOTE MESSAGE TYPE message-system
..	ADDRESS address-string

Parameters

Parameter	Description
message-system	One of the message systems supported by SQL Remote. It must be one of the following values: • FILE • FTP • MAPI • SMTP • VIM
address-string	A string containing a valid address for the specified message system.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

CREATE REMOTE MESSAGE TYPE statement

sp_remote_type procedure

Description

The statement changes the publisher's address for a given message type.

The Message Agent sends outgoing messages from a database by one of the supported message links. The extraction utility uses this address when executing the GRANT CONSOLIDATE statement in the remote database.

The address is the publisher's address under the specified message system. If it is an e-mail system, the address string must be a valid e-mail address. If it is a file-sharing system, the address string is a subdirectory of the directory specified by the SQLREMOTE environment variable, or of the current directory if that is not set. You can override this setting on the GRANT CONSOLIDATE statement at the remote database.

Example

The following statement changes the publisher's address for the FILE message link to new_addr.

CREATE REMOTE MESSAGE TYPE file

ADDRESS 'new_addr'


CREATE PUBLICATION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 CREATE PUBLICATION statement

Function

Use this statement to create a publication for replication with SQL Remote.

Syntax

CREATE PUBLICATION [  owner.]publication-name
... ( TABLE article-description, ... )

Parameters

article-description:
table-name [ ( column-name, ... ) ]
... [ WHERE search-condition ]
... [ SUBSCRIBE BY expression ]

Permissions

Must have DBA authority. Requires exclusive access to all tables referred to in the statement.

Side effects

Automatic commit.

See also

ALTER PUBLICATION statement

DROP PUBLICATION statement

sp_create_publication procedure

Description

The CREATE PUBLICATION statement creates a publication in the database. A publication can be created for another user by specifying an owner name.

In SQL Remote, publishing is a two-way operation, as data can be entered at both consolidated and remote databases. In a SQL Remote installation, any consolidated database and all remote databases must have the same publication defined. Running the extraction utility from a consolidated database automatically executes the correct CREATE PUBLICATION statement in the remote database.

Article   Publications are built from articles. Each article is a table or part of a table. An article may be a vertical partition of a table (a subset of the table's columns), a horizontal partition (a subset of the table's rows) or a vertical and horizontal partition.

SUBSCRIBE BY clause   One way of defining a subset of rows of a table to be included in an article is to use a SUBSCRIBE BY clause. This clause allows many different subscribers to receive different rows from a table in a single publication definition.

WHERE clause   The WHERE clause is a way of defining the subset of rows of a table to be included in an article. It is useful if the same subset is to be received by all subscribers to the publication.

You can combine WHERE and SUBSCRIBE BY clauses in an article definition.

Example

The following statement creates a simple publication:

CREATE PUBLICATION pub_contact (

TABLE contact

)


CREATE REMOTE MESSAGE TYPE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 CREATE REMOTE MESSAGE TYPE statement

Function

Use this statement to identify a message-link and return address for outgoing messages from a database.

Syntax

CREATE REMOTE MESSAGE TYPE message-system
...ADDRESS address-string

Parameters

Parameter	Description
message-system	One of the message systems supported by SQL Remote. It must be one of the following values: • FILE • FTP • MAPI • SMTP • VIM
address-string	A string containing a valid address for the specified message system.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

GRANT PUBLISH statement

GRANT REMOTE statement

GRANT CONSOLIDATE statement

sp_remote_type procedure

Using message types

Description

The Message Agent sends outgoing messages from a database using one of the supported message links. Return messages for users employing the specified link are sent to the specified address as long as the remote database is created by the extraction utility. The Message Agent starts links only if it has remote users for those links.

The address is the publisher's address under the specified message system. If it is an e-mail system, the address string must be a valid e-mail address. If it is a file-sharing system, the address string is a subdirectory of the directory set in the SQLREMOTE environment variable, or of the current directory if that is not set. You can override this setting on the GRANT CONSOLIDATE statement at the remote database.

The initialization utility creates message types automatically, without an address. Unlike other CREATE statements, the CREATE REMOTE MESSAGE TYPE statement does not give an error if the type exists; instead it alters the type.

Example

When remote databases are extracted using the extraction utility, the following statement sets all recipients of file message-system messages to send messages back to the company subdirectory.

The statement also instructs dbremote to look in the company subdirectory for incoming messages.

CREATE REMOTE MESSAGE TYPE file

ADDRESS 'company'


CREATE SUBSCRIPTION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 CREATE SUBSCRIPTION statement

Function

Use this statement to create a subscription for a user to a publication.

Syntax

CREATE SUBSCRIPTION
... TO publication-name [ ( subscription-value ) ]
 ... FOR subscriber-id

Parameters

Parameter	Description
publication-name	The name of the publication to which the user is being subscribed. This may include the owner of the publication.
subscription-value	A string that is compared to the subscription expression of the publication. The subscriber receives all rows for which the subscription expression matches the subscription value.
subscriber-id	The user ID of the subscriber to the publication. This user must have been granted REMOTE permissions.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

DROP SUBSCRIPTION statement

GRANT REMOTE statement

SYNCHRONIZE SUBSCRIPTION statement

START SUBSCRIPTION statement

sp_subscription procedure

Description

In a SQL Remote installation, data is organized into publications for replication. In order to receive SQL Remote messages, a subscription must be created for a user ID with REMOTE permissions.

If a string is supplied in the subscription, it is matched against each SUBSCRIBE BY expression in the publication. The subscriber receives all rows for which the value of the expression is equal to the supplied string.

In SQL Remote, publications and subscriptions are two-way relationships. If you create a subscription for a remote user to a publication on a consolidated database, you should also create a subscription for the consolidated database on the remote database. The extraction utility carries this out automatically.

Example

•	The following statement creates a subscription for the user p_chin to the publication pub_sales. The subscriber receives all rows for which the subscription expression has a value of Eastern.

CREATE SUBSCRIPTION

TO pub_sales ( 'Eastern' )

FOR p_chin


CREATE TRIGGER statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 CREATE TRIGGER statement

Function

Use this statement to create a new trigger in the database. One form of trigger is designed specifically for use by SQL Remote.

Syntax

CREATE TRIGGER  trigger-name  trigger-time  trigger-event
[, trigger-event,..]
... [ ORDER integer ] ON table-name
... [ REFERENCING [ OLD AS old-name ]
[ NEW AS new-name ] ]
[ REMOTE AS remote-name ] ]
... [ FOR EACH { ROW | STATEMENT } ]
... [ WHEN ( search-condition ) ]
... [ IF UPDATE ( column-name ) THEN
... [ { AND | OR } UPDATE ( column-name ) ] ... ]
... compound-statement
... [ ELSEIF UPDATE ( column-name ) THEN
... [ { AND | OR } UPDATE ( column-name ) ] ...
... compound-statement
... END IF ] ]

Parameters

trigger-time:
BEFORE  |  AFTER  |  RESOLVE

trigger-event:
DELETE  |  INSERT  |  UPDATE  |  UPDATE OF column-list

Usage

Anywhere.

Permissions

Must have RESOURCE authority and have ALTER permissions on the table, or must have DBA authority. CREATE TRIGGER puts a table lock on the table and thus requires exclusive use of the table.

Side effects

Automatic commit.

See also

UPDATE statement

Description

The CREATE TRIGGER statement creates a trigger associated with a table in the database and stores the trigger in the database.

Triggers can be triggered by one or more of the following events:

•	INSERT    Invoked whenever a new row is inserted into the table associated with the trigger.

•	DELETE    Invoked whenever a row of the associated table is deleted.

•	UPDATE    Invoked whenever a row of the associated table is updated.

•	UPDATE OF column-list    Invoked whenever a row of the associated table is updated and a column in the column-list has been modified.

BEFORE UPDATE triggers fire any time an update occurs on a row, regardless of whether or not the new value differs from the old value. AFTER UPDATE triggers will fire only if the new value is different from the old value.

Row and statement-level triggers

The trigger is declared as either a row-level trigger, in which case it executes before or after each row is modified, or as a statement-level trigger, in which case it executes after the entire triggering statement is completed.

Row-level triggers can be defined to execute BEFORE or AFTER the insert, update, or delete. Statement-level triggers execute AFTER the statement. The RESOLVE trigger time is for use with SQL Remote; it fires before row-level UPDATE or UPDATE OF column-lists only.

To declare a trigger as a row-level trigger, use the FOR EACH ROW clause. To declare a trigger as a statement-level trigger, you can either use a FOR EACH STATEMENT clause or omit the FOR EACH clause. For clarity, it is recommended that you enter the FOR EACH STATEMENT clause if declaring a statement-level trigger.

Order of firing

Triggers of the same type (insert, update, or delete) that fire at the same time (before, after, or resolve) can use the ORDER clause to determine the order that the triggers are fired.

Referencing deleted and inserted values

The REFERENCING OLD and REFERENCING NEW clauses allow you to refer to the deleted and inserted rows. For the purposes of this clause, an UPDATE is treated as a delete followed by an insert.

The REFERENCING REMOTE clause is for use with SQL Remote. It allows you to refer to the values in the VERIFY clause of an UPDATE statement. It should be used only with RESOLVE UPDATE or RESOLVE UPDATE OF column-list triggers.

The meaning of REFERENCING OLD and REFERENCING NEW differs, depending on whether the trigger is a row-level or a statement-level trigger. For row-level triggers, the REFERENCING OLD clause allows you to refer to the values in a row prior to an update or delete, and the REFERENCING NEW clause allows you to refer to the inserted or updated values. The OLD and NEW rows can be referenced in BEFORE and AFTER triggers. The REFERENCING NEW clause allows you to modify the new row in a BEFORE trigger before the insert or update operation takes place.

For statement-level triggers, the REFERENCING OLD and REFERENCING NEW clauses refer to declared temporary tables holding the old and new values of the rows. The default names for these tables are deleted and inserted.

The WHEN clause causes the trigger to fire only for rows where the search-condition evaluates to true.

Updating values with the same value

BEFORE UPDATE triggers fire any time an UPDATE occurs on a row, whether or not the new value differs from the old value. AFTER UPDATE triggers fire only if the new value is different from the old value.

Example

•	When a new department head is appointed, update the manager_id column for employees in that department.

CREATE TRIGGER

tr_manager BEFORE UPDATE OF dept_head_id ON department

REFERENCING OLD AS old_dept

NEW AS new_dept

FOR EACH ROW

BEGIN

UPDATE employee

SET employee.manager_id=new_dept.dept_head_id

WHERE employee.dept_id=old_dept.dept_id

END


DROP PUBLICATION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 DROP PUBLICATION statement

Function

Use this statement to drop a SQL Remote publication.

Syntax

DROP PUBLICATION [ owner.]publication-name

Usage

Anywhere. This statement is applicable only to SQL Remote.

Permissions

Must have DBA authority.

Side effects

Automatic commit. All subscriptions to the publication are dropped.

See also

CREATE PUBLICATION statement

sp_drop_publication procedure

Description

The DROP PUBLICATION statement drops an existing publication from the database.

Publication definitions are held at both consolidated and remote databases in a SQL Remote installation.

Example

DROP PUBLICATION pub_contact


DROP REMOTE MESSAGE TYPE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 DROP REMOTE MESSAGE TYPE statement

Function

Use this statement to delete a message type definition from a database.

Syntax

DROP REMOTE MESSAGE TYPE message-system

Parameters

Parameter	Description
message-system	One of the message systems supported by SQL Remote. It must be one of the following values: • FILE • FTP • MAPI • SMTP • VIM
Permissions

Must have DBA authority. To be able to drop the type, there must be no user granted REMOTE or CONSOLIDATE permissions with this type.

Side effects

Automatic commit.

See also

CREATE REMOTE MESSAGE TYPE statement

ALTER REMOTE MESSAGE TYPE statement

sp_drop_remote_type procedure

Using message types.

Description

The statement removes a message type from a database.

Example

The following statement drops the FILE message type from a database.

DROP REMOTE MESSAGE TYPE file


DROP SUBSCRIPTION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 DROP SUBSCRIPTION statement

Function

Use this statement to drop a subscription for a user from a publication.

Syntax

DROP SUBSCRIPTION TO publication-name [ ( subscription-value ) ]
... FOR subscriber-id, ...

Parameters

Parameter	Description
publication-name	The name of the publication to which the user is being subscribed. This may include the owner of the publication.
subscription-value	A string that is compared to the subscription expression of the publication. This value is required because a user may have more than one subscription to a publication.
subscriber-id	The user ID of the subscriber to the publication.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

CREATE SUBSCRIPTION statement

DROP SUBSCRIPTION statement

Description

Drops a SQL Remote subscription for a user ID to a publication in the current database. The user ID will no longer receive updates when data in the publication is changed.

In SQL Remote, publications and subscriptions are two-way relationships. If you drop a subscription for a remote user to a publication on a consolidated database, you should also drop the subscription for the consolidated database on the remote database to prevent updates on the remote database being sent to the consolidated database.

Example

The following statement drops a subscription for the user ID SamS to the publication pub_contact.

DROP SUBSCRIPTION TO pub_contact

FOR SamS


GRANT CONSOLIDATE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 GRANT CONSOLIDATE statement

Function

Use this statement to identify the database immediately above the current database in a SQL Remote hierarchy, who will receive messages from the current database.

Syntax

GRANT CONSOLIDATE
... TO userid, ...
 ... TYPE message-system, ...
 ... ADDRESS address-string, ...
 ... [ SEND { EVERY | AT }'hh:mm' ]

Parameters

Parameter	Description
userid	The user ID for the user to be granted the permission
message-system	One of the message systems supported by SQL Remote. It must be one of the following values: • FILE • FTP • MAPI • SMTP • VIM
address-string	A string containing a valid address for the specified message system.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

GRANT REMOTE statement

REVOKE CONSOLIDATE statement

GRANT PUBLISH statement

sp_grant_consolidate procedure

Description

In a SQL Remote installation, the database immediately above the current database in a SQL Remote hierarchy must be granted CONSOLIDATE permissions. GRANT CONSOLIDATE is issued at a remote database to identify its consolidated database. Each database can have only one user ID with CONSOLIDATE permissions: you cannot have a database that is a remote database for more than one consolidated database.

The consolidated user is identified by a message system, identifying the method by which messages are sent to and received from the consolidated user. The address-name must be a valid address for the message-system, enclosed in single quotes.

For the FILE message type, the address is a subdirectory of the directory pointed to by the SQLREMOTE environment variable.

The GRANT CONSOLIDATE statement is required for the consolidated database to receive messages, but does not by itself subscribe the consolidated database to any data. To subscribe to data, a subscription must be created for the consolidated user ID to one of the publications in the current database. Running the database extraction utility at a consolidated database creates a remote database with the proper GRANT CONSOLIDATE statement aready issued.

The optional SEND EVERY and SEND AT clauses specify a frequency at which messages are sent. The string contains a time that is a length of time between messages (for SEND EVERY) or a time of day at which messages are sent (for SEND AT). With SEND AT, messages are sent once per day.

If a user has been granted remote permissions without a SEND EVERY or SEND AT clause, the Message Agent processes messages, and then stops. In order to run the Message Agent continuously, you must ensure that every user with REMOTE permission has either a SEND AT or SEND EVERY frequency specified.

It is anticipated that at many remote databases, the Message Agent will be run periodically, and that the consolidated database will have no SEND clause specified.

Example

GRANT CONSOLIDATE TO con_db

TYPE mapi

ADDRESS 'Consolidated Database'


GRANT PUBLISH statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 GRANT PUBLISH statement

Function

Use this statement to identify the publisher of the current database.

Syntax

GRANT PUBLISH TO userid

Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

GRANT REMOTE statement

GRANT CONSOLIDATE statement

REVOKE PUBLISH statement

CREATE PUBLICATION statement

CREATE SUBSCRIPTION statement

sp_publisher procedure

Description

Each database in a SQL Remote installation is identified in outgoing messages by a user ID, called the publisher. The GRANT PUBLISH statement identifies the publisher user ID associated with these outgoing messages.

Only one user ID can have PUBLISH authority. The user ID with PUBLISH authority is identified by the special constant CURRENT PUBLISHER. The following query identifies the current publisher:

SELECT CURRENT PUBLISHER

If there is no publisher, the special constant is NULL.

The current publisher special constant can be used as a default setting for columns. It is often useful to have a CURRENT PUBLISHER column as part of the primary key for replicating tables, as this helps prevent primary key conflicts due to updates at more than one site.

In order to change the publisher, you must first drop the current publisher using the REVOKE PUBLISH statement, and then create a new publisher using the GRANT PUBLISH statement.

Example

GRANT PUBLISH TO publisher_ID


GRANT REMOTE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 GRANT REMOTE statement

Function

Use this statement to identify a database immediately below the current database in a SQL Remote hierarchy, who will receive messages from the current database. These are called remote users.

Syntax

GRANT REMOTE TO userid, ...
...	TYPE message-system, ...
...	ADDRESS address-string, ...
...	[ SEND { EVERY | AT } send-time ]

Parameters

Parameter	Description
userid	The user ID for the user to be granted the permission
message-system	One of the message systems supported by SQL Remote. It must be one of the following values: • FILE • FTP • MAPI • SMTP • VIM
address-string	A string containing a valid address for the specified message system.
send-time	A string containing a time specification in the form hh:mm.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

GRANT CONSOLIDATE statement

REVOKE REMOTE statement

GRANT PUBLISH statement

sp_grant_remote procedure

Granting and revoking REMOTE and CONSOLIDATE permissions,

Description

In a SQL Remote installation, each database receiving messages from the current database must be granted REMOTE permissions.

The single exception is the database immediately above the current database in a SQL Remote hierarchy, which must be granted CONSOLIDATE permissions.

The remote user is identified by a message system, identifying the method by which messages are sent to and received from the consolidated user. The address-name must be a valid address for the message-system, enclosed in single quotes.

For the FILE message type, the address is a subdirectory of the directory pointed to by the SQLREMOTE environment variable.

The GRANT REMOTE statement is required for the remote database to receive messages, but does not by itself subscribe the remote user to any data. To subscribe to data, a subscription must be created for the user ID to one of the publications in the current database, using the database extraction utility or the CREATE SUBSCRIPTION statement.

The optional SEND EVERY and SEND AT clauses specify a frequency at which messages are sent. The string contains a time that is a length of time between messages (for SEND EVERY) or a time of day at which messages are sent (for SEND AT). With SEND AT, messages are sent once per day.

If a user has been granted remote permissions without a SEND EVERY or SEND AT clause, the Message Agent processes messages, and then stops. In order to run the Message Agent continuously, you must ensure that every user with REMOTE permission has either a SEND AT or SEND EVERY frequency specified.

It is anticipated that at many consolidated databases, the Message Agent will be run continuously, so that all remote databases would have a SEND clause specified. A typical setup may involve sending messages to laptop users daily (SEND AT) and to remote servers every hour or two (SEND EVERY). You should use as few different times as possible, for efficiency.

Example

•	The following statement grants remote permissions to user SamS, using a MAPI e-mail system, sending messages to the address Singer, Samuel once every two hours:

GRANT REMOTE TO SamS

TYPE mapi

ADDRESS 'Singer, Samuel'

SEND EVERY '02:00'


GRANT REMOTE DBA statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 GRANT REMOTE DBA statement

Function

Use this statement to provide DBA privileges to a user ID, but only when connected from the Message Agent.

Syntax 1

GRANT REMOTE DBA
TO userid, ...
IDENTIFIED BY password

Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

The Message Agent and replication security

REVOKE REMOTE DBA statement

Description

REMOTE DBA authority enables the Message Agent to have full access to the database in order to make any changes contained in the messages, while avoiding security problems associated with distributing DBA user IDs passwords.

REMOTE DBA has the following properties.

•	No distinct permissions when not connected from the Message Agent. A user ID granted REMOTE DBA authority has no extra privileges on any connection apart from the Message Agent. Even if the user ID and password for a REMOTE DBA user is widely distributed, there is no security problem. As long as the user ID has no permissions beyond CONNECT granted on the database, no one can use this user ID to access data in the database.

•	Full DBA permissions when connected from the Message Agent.


PASSTHROUGH statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 PASSTHROUGH statement

Function

Use this statement to start or stop passthrough mode for SQL Remote administration. Forms 1 and 2 start passthrough mode, while form 3 stops passthrough mode.

Syntax 1

PASSTHROUGH [ ONLY ] FOR userid, ...

Syntax 2

PASSTHROUGH [ ONLY ] FOR SUBSCRIPTION
... TO [ ( owner ) ].publication-name [ ( constant ) ]

Syntax 3

PASSTHROUGH STOP

Permissions

Must have DBA authority.

Side effects

None.

See also

sp_passthrough procedure

Description

In passthrough mode, any SQL statements are executed by the database server, and are also placed into the transaction log to be sent in messages to subscribers. If the ONLY keyword is used to start passthrough mode, the statements are not executed at the server; they are sent to recipients only. The recipients of the passthrough SQL statements are either a list of user IDs (form 1) or all subscribers to a given publication. Passthrough mode may be used to apply changes to a remote database from the consolidated database or send statements from a remote database to the consolidated database.

Syntax 2 sends statements to remote databases whose subscriptions are started, and does not send statements to remote databases whose subscriptions are created and not started.

Example

PASSTHROUGH FOR rem_db ;

...

( SQL statements to be executed at the remote database )

...

PASSTHROUGH STOP ;


REMOTE RESET statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 REMOTE RESET statement

Function

Use this statement in custom database-extraction procedures to start all subscriptions for a remote user in a single transaction.

Syntax

REMOTE RESET userid

Permissions

Must have DBA authority.

Side effects

No automatic commit is done by this statement.

See also

START SUBSCRIPTION statement

Description

This command starts all subscriptions for a remote user in a single transaction. It sets the log_sent and confirm_sent values in SYSREMOTEUSER table to the current position in the transaction log. It also sets the created and started values in SYSSUBSCRIPTION to the current position in the transaction log for all subscriptions for this remote user. The statement does not do a commit. You must do an explicit commit after this call.

In order to write an extraction process that is safe on a live database, the data must be extracted at isolation level 3 in the same transaction as the subscriptions are started.

This statement is an alternative to start subscription. START SUBSCRIPTION has an implicit commit as a side effect, so that if a remote user has several subscriptions, it is impossible to start them all in one transaction using START SUBSCRIPTION.

Example

•	The following statement resets the subscriptions for remote user SamS:

REMOTE RESET SamS


REVOKE CONSOLIDATE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 REVOKE CONSOLIDATE statement

Function

Use this statement to stop a consolidated database from receiving SQL Remote messages from this database.

Syntax

REVOKE CONSOLIDATE FROM userid, ...

Permissions

Must have DBA authority.

Side effects

Automatic commit. Drops all subscriptions for the user.

See also

GRANT CONSOLIDATE statement

sp_revoke_consolidate procedure

Description

CONSOLIDATE permissions must be granted at a remote database for the user ID representing the consolidated database. The REVOKE CONSOLIDATE statement removes the consolidated database user ID from the list of users receiving messages from the current database.

Example

•	The following statement revokes consolidated status from the user ID condb:

REVOKE CONSOLIDATE FROM condb


REVOKE PUBLISH statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 REVOKE PUBLISH statement

Function

Use this statement to terminate the identification of the named user ID as the CURRENT publisher.

Syntax

REVOKE PUBLISH FROM userid

Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

GRANT PUBLISH statement

REVOKE REMOTE statement

CREATE PUBLICATION statement

CREATE SUBSCRIPTION statement

sp_publisher procedure

Description

Each database in a SQL Remote installation is identified in outgoing messages by a publisher user ID. The current publisher user ID can be found using the CURRENT PUBLISHER special constant. The following query identifies the current publisher:

SELECT CURRENT PUBLISHER

The REVOKE PUBLISH statement ends the identification of the named user ID as the publisher.

You should not REVOKE PUBLISH from a database while the database has active SQL Remote publications or subscriptions.

Issuing a REVOKE PUBLISH statement at a database has several consequences for a SQL Remote installation:

•	You will not be able to insert data into any tables with a CURRENT PUBLISHER column as part of the primary key. Any outgoing messages will not be identified with a publisher user ID, and so will not be accepted by recipient databases.

If you change the publisher user ID at any consolidated or remote database in a SQL Remote installation, you must ensure that the new publisher user ID is granted REMOTE permissions on all databases receiving messages from the database. This will generally require all subscriptions to be dropped and recreated.

Example

REVOKE PUBLISH FROM publisher_ID


REVOKE REMOTE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 REVOKE REMOTE statement

Function

Use this statement to stop a user from being able to receive SQL Remote messages from this database.

Syntax

REVOKE REMOTE FROM userid, ...

Permissions

Must have DBA authority.

Side effects

Automatic commit. Drops all subscriptions for the user.

See also

sp_revoke_remote procedure

Description

REMOTE permissions are required for a user ID to receive messages in a SQL Remote replication installation. The REVOKE REMOTE statement removes a user ID from the list of users receiving messages from the current database.

Example

REVOKE REMOTE FROM SamS


REVOKE REMOTE DBA statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 REVOKE REMOTE DBA statement

Function

Use this statement to provide DBA privileges to a user ID, but only when connected from the Message Agent.

Syntax 1

REVOKE REMOTE DBA
FROM userid, ...

Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

The Message Agent and replication security

GRANT REMOTE DBA statement

Description

REMOTE DBA authority enables the Message Agent to have full access to the database in order to make any changes contained in the messages, while avoiding security problems associated with distributing DBA user IDs passwords.

This statement revokes REMOTE DBA authority from a user ID.


SET REMOTE OPTION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 SET REMOTE OPTION statement

Function

Use this statement to set a message control parameter for a SQL Remote message link.

Syntax

SET REMOTE link-name OPTION
... [ userid.| PUBLIC.]link-option-name  = link-option-value

Parameters

link-name:
file | ftp | mapi | smtp | vim

link-option-name:
file-option | ftp-option | mapi-option | smtp-option | vim-option

file-option:
debug | directory

ftp-option:
active_mode | debug | host | password | port | root_directory | user

mapi-option:
debug | force_download | ipm_receive | ipm_send | profile

smtp-option:
debug | local_host |  pop3_host  | pop3_password | pop3_userid | smtp_host | top_supported

vim-option:
debug | password | path | receive_all | send_vim_mail | userid

link-option-value:
string

Permissions

Must have DBA authority. The publisher can set their own options.

Side effects

Automatic commit.

See also

sp_link_option procedure

Description

The Message Agent saves message link parameters when the user enters them in the message link dialog box when the message link is first used. In this case, it is not necessary to use this statement explicitly. This statement is most useful when preparing a consolidated database for extracting many databases.

The option names are case sensitive. The case sensitivity of option values depends on the option: boolean values are case insensitive, while the case sensitivity of passwords, directory names, and other strings depend on the cases sensitivity of the file system (for directory names), or the database (for user IDs and passwords).

userid    If no userid is specified, then the current publisher is assumed.

Option values    The option values are message-link dependent. For more information, see the following locations:

•	The file message system.

•	The ftp message system.

•	The MAPI message system.

•	The SMTP message system.

•	The VIM message system.

Examples

The following statement sets the FTP host to ftp.mycompany.com for the ftp link for user myuser:

SET REMOTE FTP OPTION myuser.host = 'ftp.mycompany.com'


START SUBSCRIPTION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 START SUBSCRIPTION statement

Function

Use this statement to start a subscription for a user to a publication.

Syntax

START SUBSCRIPTION
... TO publication-name [ ( subscription-value) ]
... FOR subscriber-id, ...

Parameters

Parameter	Description
publication-name	The name of the publication to which the user is being subscribed. This may include the owner of the publication.
subscription-value	A string that is compared to the subscription expression of the publication. The value is required here because each subscriber may have more than one subscription to a publication.
subscriber-id	The user ID of the subscriber to the publication. This user must have a subscription to the publication.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

CREATE SUBSCRIPTION statement

REMOTE RESET statement

SYNCHRONIZE SUBSCRIPTION statement

sp_subscription procedure

Description

A SQL Remote subscription is said to be started when publication updates are being sent from the consolidated database to the remote database.

The START SUBSCRIPTION statement is one of a set of statements that manage subscriptions. The CREATE SUBSCRIPTION statement defines the data that the subscriber is to receive. The SYNCHRONIZE SUBSCRIPTION statement ensures that the consolidated and remote databases are consistent with each other. The START SUBSCRIPTION statement is required to start messages being sent to the subscriber.

Data at each end of the subscription must be consistent before a subscription is started. It is recommended that you use the database extraction utility to manage the creation, synchronization, and starting of subscriptions. If you use the database extraction utility, you do not need to execute an explicit START SUBSCRIPTION statement. Also, the Message Agent starts subscriptions once they are synchronized.

Example

The following statement starts the subscription of user SamS to the pub_contact publication.

START SUBSCRIPTION TO pub_contact

FOR SamS


STOP SUBSCRIPTION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 STOP SUBSCRIPTION statement

Function

Use this statement to stop a subscription for a user to a publication.

Syntax

STOP SUBSCRIPTION
... TO publication-name [ ( subscription-value) ]
... FOR subscriber-id, ...

Parameters

Parameter	Description
publication-name	The name of the publication to which the user is being subscribed. This may include the owner of the publication.
subscription-value	A string that is compared to the subscription expression of the publication. The value is required here because each subscriber may have more than one subscription to a publication.
subscriber-id	The user ID of the subscriber to the publication. This user must have a subscription to the publication.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

CREATE SUBSCRIPTION statement

SYNCHRONIZE SUBSCRIPTION statement

Description

A SQL Remote subscription is said to be started when publication updates are being sent from the consolidated database to the remote database.

The STOP SUBSCRIPTION statement prevents any further messages being sent to the subscriber. The START SUBSCRIPTION statement is required to restart messages being sent to the subscriber. However, you should ensure that the subscription is properly synchronized before restarting: that no messages have been missed.

Example

The following statement starts the subscription of user SamS to the pub_contact publication.

STOP SUBSCRIPTION TO pub_contact

FOR SamS


SYNCHRONIZE SUBSCRIPTION statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 SYNCHRONIZE SUBSCRIPTION statement

Function

Use this statement to synchronize a subscription for a user to a publication.

Syntax

SYNCHRONIZE SUBSCRIPTION
... TO publication-name [ ( subscription-value) ]
... FOR remote-user, ...

Parameters

Parameter	Description
publication-name	The name of the publication to which the user is being subscribed. This may include the owner of the publication.
subscription-value	A string that is compared to the subscription expression of the publication. The value is required here because each subscriber may have more than one subscription to a publication.
remote-user	The user ID of the subscriber to the publication. This user must have a subscription to the publication.
Permissions

Must have DBA authority.

Side effects

Automatic commit.

See also

CREATE SUBSCRIPTION statement

START SUBSCRIPTION statement

Description

A SQL Remote subscription is said to be synchronized when the data in the remote database is consistent with that in the consolidated database, so that publication updates sent from the consolidated database to the remote database will not result in conflicts and errors.

To synchronize a subscription, a copy of the data in the publication at the consolidated database is sent to the remote database. The SYNCHRONIZE SUBSCRIPTION statement does this through the message system. It is recommended that where possible you use the database extraction utility instead to synchronize subscriptions without using a message system.

Example

The following statement synchronizes the subscription of user SamS to the pub_contact publication.

SYNCHRONIZE SUBSCRIPTION TO pub_contact

FOR SamS


UPDATE statement
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 25.  Command Reference for Adaptive Server Anywhere

 UPDATE statement

Function

Use this statement to modify data in the database.

Syntax 1

UPDATE table-list
... 	SET column-name = expression, ...
... 	[ FROM table-list ]
... 	[ WHERE search-condition ]
... 	[ ORDER BY expression [ ASC | DESC ] , ... ]

Syntax 2

UPDATE table-list
... 	SET column-name = expression, ...
... 	[  VERIFY ( column-name, ... ) VALUES ( expression, ... ) ]
... 	[  WHERE search-condition ]
... 	[  ORDER BY expression [ ASC | DESC ] , ... ]

Syntax 3

UPDATE table
...PUBLICATION publication
...{ SUBSCRIBE BY expression  |
      OLD SUBSCRIBE BY expression
      NEW SUBSCRIBE BY expression
   }
...WHERE search-condition

expression: value | subquery

Usage

Syntax 1 can be used anywhere.

Syntax 2 and Syntax 3 are applicable only to SQL Remote.

Syntax 3 with no OLD and NEW SUBSCRIBE BY expressions must be used in a BEFORE trigger.

Syntax 3 with OLD and NEW SUBSCRIBE BY expressions can be used anywhere.

Permissions

Must have UPDATE permission for the columns being modified.

Side effects

None.

See also

CREATE TRIGGER statement

Description

The UPDATE statement is used to modify rows of one or more tables. Each named column is set to the value of the expression on the right hand side of the equal sign. There are no restrictions on the expression. Even column-name can be used in the expression—the old value will be used.

If no WHERE clause is specified, every row will be updated. If a WHERE clause is specified, then only those rows which satisfy the search condition will be updated.

Normally, the order that rows are updated doesn't matter. However, in conjunction with the NUMBER(*) function, an ordering can be useful to get increasing numbers added to the rows in some specified order. Also, if you wish to do something like add 1 to the primary key values of a table, it is necessary to do this in descending order by primary key, so that you do not get duplicate primary keys during the operation.

Views can be updated provided the SELECT statement defining the view does not contain a GROUP BY clause, an aggregate function, or involve a UNION operation.

Character strings inserted into tables are always stored in the case they are entered, regardless of whether the database is case sensitive or not. Thus a character data type column updated with a string Value is always held in the database with an upper-case V and the remainder of the letters lower case. SELECT statements return the string as Value. If the database is not case-sensitive, however, all comparisons make Value the same as value, VALUE, and so on. Further, if a single-column primary key already contains an entry Value, an INSERT of value is rejected, as it would make the primary key not unique.

Updates based on joins

The optional FROM clause allows tables to be updated based on joins. If the FROM clause is present, the WHERE clause qualifies the rows of the FROM clause. Data is updated only in the table list immediately following the UPDATE keyword.

If a FROM clause is used, it is important to qualify the table name that is being updated the same way in both parts of the statement. If a correlation name is used in one place, the same correlation name must be used in the other. Otherwise, an error is generated.

SQL Remote updates

Syntax 2 is intended for use with SQL Remote only, in single-row updates executed by the Message Agent. The VERIFY clause contains a set of values that are expected to be present in the row being updated. If the values do not match, any RESOLVE UPDATE triggers are fired before the UPDATE proceeds. The UPDATE does not fail if the VERIFY clause fails to match.

Syntax 3 is intended for use with SQL Remote only. If no OLD and NEW expressions are used, it must be used inside a BEFORE trigger so that it has access to the relevant values. The purpose is to provide a full list of subscribe by values any time the list changes. It is placed in SQL Remote triggers so that the database server can compute the current list of SUBSCRIBE BY values. Both lists are placed in the transaction log.

The Message Agent uses the two lists to make sure that the row moves to any remote database that did not have the row and now needs it. The Message Agent also removes the row from any remote database that has the row and no longer needs it. A remote database that has the row and still needs it is not be affected by the UPDATE statement.

Performance tip

Syntax 3 of the UPDATE statement allows the old SUBSCRIBE BY list and the new SUBSCRIBE BY list to be explicitly specified, which can make SQL Remote triggers more efficient. In the absence of these lists, the database server computes the old SUBSCRIBE BY list from the publication definition. Since the new SUBSCRIBE BY list is commonly only slightly different from the old SUBSCRIBE BY list, the work to compute the old list may be done twice. By specifying both the old and new lists, this extra work can be avoided.

The OLD and NEW SUBSCRIBE BY syntax is especially useful when many tables are being updated in the same trigger with the same subscribe by expressions. This can dramatically increase performance.

The SUBSCRIBE BY expression is either a value or a subquery.

Using UPDATE to maintain subscriptions

Syntax 3 of the UPDATE statement is used to implement a specific SQL Remote feature, and is to be used inside a BEFORE trigger.

For publications created using a subquery in a subscription expression, you must write a trigger containing syntax 3 of the UPDATE statement in order to ensure that the rows are kept in their proper subscriptions.

  For a full description of this feature, see Territory realignment in the Contact example.

Syntax 3 of the UPDATE statement makes an entry in the transaction log, but does not change the database table.

Examples

•	Transfer employee Philip Chin (employee 129) from the sales department to the marketing department.

UPDATE employee

SET dept_id = 400

WHERE emp_id = 129 ;


CHAPTER 26.  Command Reference for Adaptive Server Enterprise
  Replication and Synchronization Guide

    PART 3. SQL Remote

 CHAPTER 26.  Command Reference for Adaptive Server Enterprise

About this chapter

This chapter describes the SQL Remote stored procedures, used for executing SQL Remote commands.

 sp_add_article procedure

 sp_add_article_col procedure

 sp_add_remote_table procedure

 sp_create_publication procedure

 sp_drop_publication procedure

 sp_drop_remote_type procedure

 sp_drop_sql_remote procedure

 sp_grant_consolidate procedure

 sp_grant_remote procedure

 sp_link_option procedure

 sp_modify_article procedure

 sp_modify_remote_table procedure

 sp_passthrough procedure

 sp_passthrough_piece procedure

 sp_passthrough_stop procedure

 sp_passthrough_subscription procedure

 sp_passthrough_user procedure

 sp_populate_sql_anywhere procedure

 sp_publisher procedure

 sp_queue_clean procedure

 sp_queue_confirmed_delete_old procedure

 sp_queue_confirmed_transaction procedure

 sp_queue_delete_old procedure

 sp_queue_drop procedure

 sp_queue_dump_database procedure

 sp_queue_dump_transaction procedure

 sp_queue_get_state procedure

 sp_queue_log_transfer_reset procedure

 sp_queue_read procedure

 sp_queue_reset procedure

 sp_queue_set_confirm procedure

 sp_queue_set_progress procedure

 sp_queue_transaction procedure

 sp_remote procedure

 sp_remote_option procedure

 sp_remote_type procedure

 sp_remove_article procedure

 sp_remove_article_col procedure

 sp_remove_remote_table procedure

 sp_revoke_consolidate procedure

 sp_revoke_remote procedure

 sp_subscription procedure

 sp_subscription_reset procedure


sp_add_article procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_add_article procedure

Purpose

To add an article to a publication.

Syntax

sp_add_article publication_name, table_name, where_expr, subscribe_by_expr, subscribe_by_view

Argument	Description
publication_name	The name of the publication to which the article is to be added.
table_name	The table containing the article.
where_expr	This optional argument must be a column name or NULL. The publication includes only rows for which the supplied column value is not NULL. The default value is NULL, in which case no rows are excluded from the publication.
subscribe_by_expr	The new subscription expression defining which rows are to be included in the publication for each subscription. The expression must be the name of a column in table_name. The default value is NULL.
subscribe_by_view	A view defining the columns and rows to be included in the publication.   For more information, see Tuning extraction performance and Tuning extraction performance for shared rows.
See also

sp_add_remote_table procedure

sp_create_publication procedure

sp_remove_article procedure

CREATE PUBLICATION statement

Description

Running sp_add_article adds an article to a publication. The table must be marked for replication using sp_add_remote_table before it can be added to a publication; failure to do so leads to an error.

Calling sp_add_article adds all the columns of the table to a publication. If you wish to include only some of the columns of the table in a publication you must first run sp_add_article and then call sp_add_article_col.

As with other data definition changes, in a production environment this procedure should only be run on a quiet SQL Remote installation.

  For more information on the requirements for a quiet system, see Making schema changes.

Example

•	The following statement adds the SalesRep table to a publication named SalesRepData:

sp_add_article 'SalesRepData', 'SalesRep'

go


sp_add_article_col procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_add_article_col procedure

Purpose

To add a column to an article in a publication.

Syntax

sp_add_article_col publication_name, table_name, column_name

Argument	Description
publication_name	The name of the publication to which the article is to be added.
table_name	The table containing the article.
column_name	The column to be added to the article in a publication
See also

sp_add_article procedure

sp_remove_article procedure

ALTER PUBLICATION statement

Description

Running sp_add_article_col adds a column to an article in a publication. The table must first be added to the publication using the sp_add_article procedure.

To add all the columns of a table to a publication you do not need to use sp_add_article_col; just call sp_add_article.

To add only some of the columns of a table to a publication you first call sp_add_article, and then call sp_add_article_col for each of the columns you wish to include in the publication.

As with other data definition changes, in a production environment this procedure should only be run on a quiet SQL Remote installation.

  For more information on the requirements for a quiet system, see Making schema changes.

Example

•	The following statements add the emp_id and emp_lname columns of the employee table to a publication named Personnel:

sp_add_article 'Personnel', employee'

sp_add_article_col 'Personnel', 'employee', 'emp_id'

sp_add_article_col 'Personnel', 'employee', 'emp_lname'

go


sp_add_remote_table procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_add_remote_table procedure

Purpose

To mark a table for SQL Remote replication.

Syntax

sp_add_remote_table table_name,

[ resolve_procedure, ]

[ old_row_name, ]

[ remote_row_name ]

Argument	Description
table_name	The table to be marked for SQL Remote replication.
resolve_procedure	The name of a stored procedure that carries out actions when a conflict occurs.
old_row_name	The name of a  table holding the values in the table when a conflict occurs.
remote_row_name	The name of a table holding the values at the remote database when a conflict-causing UPDATE statement was applied.
Authorization

You must be a system administrator to execute this procedure.

See also

sp_modify_remote_table procedure

sp_remove_remote_table procedure

Managing conflicts.

Description

Each table in a database must be marked for replication by using sp_add_remote_table before it can be included in any SQL Remote  publications. After executing sp_add_remote_table, you can add the table to a publication using the sp_add_article procedure and the sp_add_article_col procedure.

The sp_add_remote_table procedure calls sp_setreplicate, which flags the table for replication. This tells Adaptive Server Enterprise to put extended information into the transaction log. This information includes the entire before and after images of the row.

The first argument is the name of the table to be marked for replication.

The remaining three arguments are optional. They are object names required only for custom conflict resolution. If you are implementing custom conflict resolution, you must supply the names of two tables, and a stored procedure. The sp_add_remote_table procedure does not check for the existence of the conflict resolution arguments: you can create them either before or after marking the table for replication.

The two tables must have the same columns and data types as table table_name.

Examples

•	The following statement marks the Customer table for replication, using default conflict resolution:

exec sp_add_remote_table Customer

•	The following statement marks the Customer table for replication, using a stored procedure named Customer_Conflict to resolve conflicts. The old and remote rows are stored in tables named old_Customer and remote_Customer, respectively:

exec sp_add_remote_table Customer, Customer_Conflict, old_Customer, remote_Customer


sp_create_publication procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_create_publication procedure

Purpose

To create a publication.

Syntax

sp_create_publication publication_name

Argument	Description
publication_name	The name of the publication
See also

sp_drop_publication procedure

CREATE PUBLICATION statement

Description

Running sp_create_publication creates a publication, but one with no content. Once the publication is created, you must add articles to it using the sp_add_remote_table procedure and the sp_add_article procedure.

Example

•	The following statement creates a publication named SalesRepData:

sp_create_publication 'SalesRepData'

go


sp_drop_publication procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_drop_publication procedure

Purpose

To drop a publication from the database.

Syntax

sp_drop_publication publication_name

Argument	Description
publication_name	The name of the publication to be dropped
See also

sp_create_publication procedure

DROP PUBLICATION statement

Description

Running sp_drop_publication drops a publication from the database. All articles that make up the publication, and subscriptions to the publication, are also dropped.

Example

•	The following statement drops the publication named SalesRep:

sp_drop_publication 'SalesRep'

go


sp_drop_remote_type procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_drop_remote_type procedure

Purpose

To drop a message type from the database.

Syntax

sp_drop_remote_type type_name

Argument	Description
type_name	The message type to drop. This must be a string containing one of the following: • file • ftp • smtp • mapi • vim
See also

sp_remote_type procedure

DROP REMOTE MESSAGE TYPE statement

Description

Drops the named  message type from the database.

Example

•	The following statement drops the MAPI message type from the database:

sp_drop_remote_type mapi

go


sp_drop_sql_remote procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_drop_sql_remote procedure

Purpose

To drop the SQL Remote system objects from a database.

Syntax

sp_drop_sql_remote

See also

sp_queue_drop procedure

Description

Drops the SQL Remote system objects from the database, so that it can no longer function in a SQL Remote installation.

The sole SQL Remote object not removed is the sp_drop_sql_remote procedure itself (a procedure cannot drop itself from a database). To complete removal of SQL Remote requires that sp_drop_sql_remote be dropped explicitly after it is called.

The sp_drop_sql_remote procedure does not remove stable queue objects from the database. To remove the stable queue, use the sp_queue_drop procedure.

Example

•	The following statements remove SQL Remote system objects from a database:

sp_drop_sql_remote_type

go

drop procedure sp_drop_sql_remote

go


sp_grant_consolidate procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_grant_consolidate procedure

Purpose

To identify a database immediately above the current database in a SQL Remote hierarchy, who will receive messages from the current database. This procedure applies only to Adaptive Server Enterprise databases acting as remote databases.

Syntax

sp_grant_consolidate user_name, type_name, address

[, frequency ] [, send_time ]

Argument	Description
user_name	The user ID who will be able to receive SQL Remote messages.
type_name	The message type to be used. This must be one of the following: • file • ftp • smtp • mapi • vim
address	A string holding the address, according to the specified message type, to which the replication messages should be sent for this user.
frequency	A string containing one of the following: • SEND EVERY   Indicates that messages are sent at a frequency specified by send_time. • SEND AT   Indicates that messages are sent at a time of day specified by send_time.
send_time	A string containing a time specification with the following meaning: • If frequency is SEND EVERY, specifies a length of time between messages. • If frequency is SEND AT, specifies a time of day at which messages will be sent. If no frequency is specified, the Message Agent sends messages, and then stops.
See also

sp_grant_remote procedure

sp_revoke_consolidate procedure

GRANT CONSOLIDATE statement

Description

If the Adaptive Server Enterprise server is acting as a remote database in a SQL Remote installation, the single database above the current database must be granted consolidated permissions using the sp_grant_consolidate procedure.

The consolidated  user is identified by a message system, identifying the method by which messages are sent to and received from the consolidated user. The address-name must be a valid address for the message-system, enclosed in single quotes.

The sp_grant_consolidate procedure is required for the remote database to receive messages, but does not by itself subscribe the remote user to any data. To subscribe to data, a subscription must be created for the user ID to one of the publications in the current database.

The optional frequency argument specifies a frequency at which messages are sent. The send_time argument contains a time that is a length of time between messages (for SEND EVERY) or a time of day at which messages are sent (for SEND AT). With SEND AT, messages are sent once per day.

If no frequency argument is supplied, the Message Agent processes messages, and then stops. In order to run the Message Agent continuously, you must ensure that every user with remote or consolidated permission has a frequency specified.

Example

•	The following statement grants consolidated permissions to user hq_user, using a file sharing system, sending messages to the address hq_dir: No frequency arguments are specified, and the Message Agent will run in batch mode.

sp_grant_consolidate

@user_name=hq_user,

@address=hq_dir,

@type_name=file

go


sp_grant_remote procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_grant_remote procedure

Purpose

To identify a database immediately below the current database in a SQL Remote hierarchy, who will receive messages from the current database. These are called remote users.

Syntax

sp_grant_remote user_name, type_name, address

[, frequency ] [, send_time ]

Argument	Description
user_name	The user ID who will be able to receive SQL Remote messages.
type_name	The message type to be used. This must be one of the following: • file • ftp • smtp • mapi • vim
address	A string holding the address, according to the specified message type, to which the replication messages should be sent for this user.
frequency	A string containing one of the following: • SEND EVERY   Indicates that messages are sent at a frequency specified by send_time. • SEND AT   Indicates that messages are sent at a time of day specified by send_time.
send_time	An optional string containing a time specification with the following meaning: • If frequency is SEND EVERY, specifies a length of time between messages. • If frequency is SEND AT, specifies a time of day at which messages will be sent. If no frequency is specified, the Message Agent sends messages, and then stops.
See also

sp_revoke_remote procedure

GRANT REMOTE statement

Description

In a SQL Remote installation, each database receiving messages from the current database must be granted REMOTE permissions using the sp_grant_remote procedure.

The remote user is identified by a message system, identifying the method by which messages are sent to and received from the consolidated user. The address-name must be a valid address for the message-system, enclosed in single quotes.

The sp_grant_remote procedure is required for the remote database to receive messages, but does not by itself subscribe the remote user to any data. To subscribe to data, a subscription must be created for the user ID to one of the publications in the current database.

The optional frequency argument specifies a frequency at which messages are sent. The send_time argument contains a time that is a length of time between messages (for SEND EVERY) or a time of day at which messages are sent (for SEND AT). With SEND AT, messages are sent once per day.

If no frequency argument is supplied, the Message Agent processes messages, and then stops. In order to run the Message Agent continuously, you must ensure that every user with REMOTE permission has a frequency specified.

It is anticipated that at many consolidated databases, the Message Agent will be run continuously, so that all remote databases would have a frequency argument specified. A typical setup may involve sending messages to laptop users daily (SEND AT) and to remote servers every hour or two (SEND EVERY). You should use as few different times as possible, for efficiency.

Example

•	The following statement grants remote permissions to user SamS, using a MAPI e-mail system, sending messages to the address Singer, Samuel once every two hours:

exec sp_grant_remote 'SamS',

'mapi',

'Singer, Samual',

'SEND EVERY',

'02:00'

go


sp_link_option procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_link_option procedure

Purpose

To set a message control parameter for a SQL Remote message link.

Syntax

sp_link_option link-name, userid, option-name, option-value

Parameters

link-name:
file | ftp | mapi | smtp | vim

link-option-name:
file-option | ftp-option | mapi-option | smtp-option | vim-option

file-option:
debug | directory

ftp-option:
active_mode | debug | host | password | port | root_directory | user

mapi-option:
debug | force_download | ipm_receive | ipm_send | profile

smtp-option:
debug | local_host |  pop3_host  | pop3_password | pop3_userid | smtp_host | top_supported

vim-option:
debug | password | path | receive_all | send_vim_mail | userid

link-option-value:
string

Permissions

Must have DBA authority. The publisher can set their own options.

Side effects

Automatic commit.

See also

SET REMOTE OPTION statement

Description

The Message Agent saves message link parameters when the user enters them in the message link dialog box when the message link is first used. In this case, it is not necessary to use this procedure explicitly. This procedure is most useful when preparing a consolidated database for extracting many databases.

The option names are case sensitive. The case sensitivity of option values depends on the option: boolean values are case insensitive, while the case sensitivity of passwords, directory names, and other strings depend on the cases sensitivity of the file system (for directory names), or the database (for user IDs and passwords).

userid    If no userid is specified, then the current publisher is assumed.

Option values    The option values are message-link dependent. For more information, see the following locations:

•	The file message system.

•	The ftp message system.

•	The MAPI message system.

•	The SMTP message system.

•	The VIM message system.

Example

The following statement sets the FTP host to ftp.mycompany.com for the ftp link for user myuser:

exec sp_link_option ftp, myuser,

host, 'ftp.mycompany.com'


sp_modify_article procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_modify_article procedure

Purpose

To change the description of an article in a procedure.

Syntax

sp_modify_article
publication_name,
table_name,
[ where_expr, ]
[ subscribe_by_expr ]
[ subscribe_by_view ]

Argument	Description
publication_name	The name of the publication for which the article is to be modified.
table_name	The table containing the article.
where_expr	This optional argument must be a column name or NULL. The publication includes only rows for which the supplied column name is not NULL. The default value is NULL, in which case no rows are excluded from the publication..
subscribe_by_expr	The new subscription expression defining which rows are to be included in the publication for each subscription. The default value is NULL.
subscribe_by_view	A view defining the rows and columns to be included in the publication. The default is NULL.   For more information, see Tuning extraction performance and Tuning extraction performance for shared rows.
See also

sp_add_article procedure

sp_remove_article procedure

ALTER PUBLICATION statement

Description

To change the description of an article in a publication. The WHERE expression, the subscription expression, and the subscription view can each be changed.

As with other data definition changes, in a production environment this procedure should only be run on a quiet SQL Remote installation.

  For more information on the requirements for a quiet system, see Making schema changes.

Examples

The following statement changes an article in the SalesRepData publication that takes information from the Customer table, so that it has no subscription expression:

sp_modify_article SalesRepData, Customer

go

The following statement changes an article in the SalesRepData publication that takes information from the Customer table, so that it has a  subscription expression that is the rep_key column:

sp_modify_article SalesRepData, 	Customer,

NULL, rep_key

go


sp_modify_remote_table procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_modify_remote_table procedure

Purpose

To change the resolution objects for a table marked for SQL Remote replication.

Syntax

sp_modify_remote_table table_name,

[ resolve_name, ]

[ old_row_name, ]

[ remote_row_name ]

Argument	Description
table_name	A table marked for SQL Remote replication.
resolve_procedure	The name of the new stored procedure for carrying out actions when a conflict occurs.
old_row_name	The name of the new table for holding the values in the table when a conflict occurs.
remote_row_name	The name of the new table for holding the values at the remote database when a conflict-causing UPDATE statement was applied.
See also

sp_add_remote_table procedure

sp_remove_remote_table procedure

Managing conflicts.

Description

Each table in a database must be marked for replication by using sp_add_remote_table before it can be included in any SQL Remote  publications.

The sp_modify_remote_table allows you to change the way in which conflict resolution is carried out for update conflicts occurring on this table.

The arguments are, in addition to the table name, the object names required  for custom conflict resolution. If you are implementing custom conflict resolution, you must supply the names of two tables, and a stored procedure. The sp_modify_remote_table procedure does not check for the existence of the conflict resolution arguments: you can create them either before or after marking the table for replication.

The two tables must have the same columns and data types as table table_name.

Example

The following statement instructs SQL Remote to use the resolve_Cust procedure, the old_Cust table, and the remote_Cust table to resolve update conflicts on the Customer table:

sp_add_remote_table Customer, resolve_Cust,

old_Cust, remote_Cust

go


sp_passthrough procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_passthrough procedure

Purpose

To send a SQL statement in passthrough mode.

Syntax

sp_passthrough statement

Argument	Description
statement	A string containing a statement to be executed in passthrough mode.
See also

sp_passthrough_piece procedure

sp_passthrough_stop procedure

sp_passthrough_subscription procedure

sp_passthrough_user procedure

PASSTHROUGH statement

Description

To send passthrough operations. The recipients of the passthrough statement are determined by previous calls to sp_passthrough_user and sp_passthrough_subscription.

The string must be less than 255 characters long. For SQL statements longer than 255 characters, you should execute a sequence of calls to the sp_passthrough_piece procedures, and execute sp_passthrough for the final piece of the statement and to cause the replication to occur.

Caution
You should always test your passthrough operations on a test database with a remote database subscribed. You should never run untested passthrough scripts against a production database.

Example

•	The following statement sends a create table statement to the current recipients of passthrough statements.

exec sp_passthrough

'CREATE TABLE simple (

id integer NOT NULL,

name char(50) )'

go


sp_passthrough_piece procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_passthrough_piece procedure

Purpose

To build a long SQL statement for passthrough.

Syntax

sp_passthrough_piece string

Argument	Description
string	A piece of a statement to be executed in passthrough mode.
See also

sp_passthrough procedure

sp_passthrough_stop procedure

sp_passthrough_subscription procedure

sp_passthrough_user procedure

PASSTHROUGH statement

Description

The sp_passthrough procedure is used to send statements directly to a set of remote users. Statements that are longer than 255 characters have to be built up piece by piece.

To build and send a long SQL statement, call sp_passthrough_piece for all but the final piece of the statement, and then call sp_passthrough for the final piece. This completes and replicates the statement.

All pieces of a passthrough statement must be built within a single transation.

Example

•	The following statements send a long passthrough statement to the current list of passthrough recipients:

begin transaction

go

exec sp_passthrough_piece 'CREATE TABLE

DBA.employee

(

emp_id  integer NOT NULL,

manager_id  integer NULL,

emp_fname  char(20) NOT NULL,

emp_lname  char(20) NOT NULL,'

go

exec sp_passthrough_piece '

dept_id  integer NOT NULL,

street  char(40) NOT NULL,

city  char(20) NOT NULL,

state  char(4) NOT NULL,

zip_code  char(9) NOT NULL,

phone  char(10) NULL,'

go

exec sp_passthrough_piece 'status  char(1) NULL,

ss_number  char(11) NOT NULL,

salary  numeric(20,3) NOT NULL,

start_date  date NOT NULL,

termination_date  date NULL,

birth_date  date NULL,'

go

exec sp_passthrough '

bene_health_ins  char(1) NULL,

bene_life_ins  char(1) NULL,

bene_day_care  char(1) NULL,

sex  char(1) NULL,

PRIMARY KEY (emp_id),

)'

go

commit

go


sp_passthrough_stop procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_passthrough_stop procedure

Purpose

Resents passthrough mode

Syntax

sp_passthrough_stop

See also

sp_passthrough procedure

sp_passthrough_subscription procedure

sp_passthrough_user procedure

PASSTHROUGH statement

Description

The sp_passthrough_stop procedure resents the list of recipients of passthrough statements to be empty, and clears any statements that are currently being built.

Example

•	The following statement resets the passthrough recipient list to be empty.

exec sp_passthrough_stop

go


sp_passthrough_subscription procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_passthrough_subscription procedure

Purpose

Adds subscribers to a given publication to the recipient list for passthrough statements.

Syntax

sp_passthrough_subscription publication_name, subscribe_by

Argument	Description
publication_name	The name of the publication
subscribe_by	The subscription value for recipients to receive passthrough statements.
See also

sp_passthrough procedure

sp_passthrough_piece procedure

sp_passthrough_stop procedure

sp_passthrough_user procedure

PASSTHROUGH statement

Description

This is one of two ways that you can add to the list of recipients for passthrough statements, the other being to use the sp_passthrough_user procedure.

The users that are added to the recipient list by a call to the sp_passthrough_subscription procedure are all those users subscribing to the publication publication_name with a subscription value of subscribe_by.

The default setting for subscribe_by is NULL. In this case, all subscribers to the publication receive the passthrough statements.

Example

•	The following statement adds to the list of passthrough recipients the subscriber or subscribers to the SalesRepData publication who use subscription values of 'rep1'.

Sp_passthrough_subscription SalesRepData, rep1


sp_passthrough_user procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_passthrough_user procedure

Purpose

Adds a named user to the list of recipients for passthrough statements.

Syntax

sp_passthrough_user user_name

Argument	Description
user_name	The user to be added to the list of recipients.
See also

sp_passthrough procedure

sp_passthrough_piece procedure

sp_passthrough_stop procedure

sp_passthrough_subscription procedure

PASSTHROUGH statement

Description

This is one of two ways that you can add to the list of recipients for passthrough statements, the other being to use the sp_passthrough_subscription procedure.

The sp_passthrough_user procedure adds the named user to the list of recipients for passthrough statements. The list remains in force until reset using the sp_passthrough_stop procedure.

Example

•	The following statement adds the user field_user to the list of recipients for passthrough statements:

sp_passthrough_user 'field_user'

go


sp_populate_sql_anywhere procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_populate_sql_anywhere procedure

Purpose

To create a copy of the Adaptive Server Anywhere system tables in the TEMPDB. This procedure is used by the extraction utility ssxtract.

Syntax

sp_populate_sql_anywhere

Description

To create a set of Adaptive Server Anywhere system tables for a remote Adaptive Server Anywhere database, in TEMPDB. The information is used by the extraction utility to construct an Adaptive Server Anywhere database schema from the set of publications in the Adaptive Server Enterprise consolidated database.

This procedure is used by the ssxtract extraction utility. It should not be called directly.


sp_publisher procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_publisher procedure

Purpose

To set the publisher of the current database, or to remove the publisher.

Syntax

sp_publisher [ user_name ]

Argument	Description
user_name	The user ID to be identifies as the publisher for the database.
See also

Managing SQL Remote permissions.

GRANT PUBLISH statement

Description

Each database in a SQL Remote installation is identified in outgoing messages by a user ID, called the publisher. The sp_publisher procedure sets the publisher user ID associated with these outgoing messages.

Each database can have at most one publisher; if a publisher already exists, sp_publisher changes the name of the publisher.

If no user_name argument is provided, the current publisher is removed, so that the database has no publisher. Only the permission to be the publisher is removed; the user ID is not removed from the database.

Examples

•	The following statement identifies the user ID joe as the publisher of the current database:

sp_publisher joe

go

•	The following statement sets the current database to have no publisher:

sp_publisher

go


sp_queue_clean procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_clean procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_clean

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It removes from the stable queue any transactions that completed after the start of the oldest incomplete transaction the last time the log was scanned.


sp_queue_confirmed_delete_old procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_confirmed_delete_old procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_confirmed_delete_old

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It removes from the stable queue any transactions whose offsets are shown in sr_confirmed_transaction.


sp_queue_confirmed_transaction procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_confirmed_transaction procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_confirmed_transaction offset

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It adds the supplied offset to sr_confirmed_transaction. SQL Remote removes from the stable queue any transactions whose offsets match this offset.


sp_queue_delete_old procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_delete_old procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_delete_old

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It deletes from the stable queue any transactions that have been confirmed by all remote databases.


sp_queue_drop procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_drop procedure

Purpose

To drop the stable queue objects from a database..

Syntax

sp_queue_drop

See also

sp_drop_sql_remote procedure

Description

Drops the stable queue system objects from the database, so that the database no longer supports a SQL Remote stable queue.

The sole stable queue object not removed is the sp_queue_drop procedure itself (a procedure cannot drop itself from a database). To complete removal of the stable queue requires that sp_queue_drop be dropped explicitly after it is called.

The sp_queue_drop procedure does not remove SQL Remote system objects from the database. To remove the SQL Remote system objects, use the sp_drop_sql_remote procedure.

Examples

•	The following statements remove the stable queue objects from the database:

sp_queue_drop

go

drop procedure sp_queue_drop

go


sp_queue_dump_database procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_dump_database procedure

Purpose

To facilitate recovery from media failure when the stable queue is in a separate database from the SQL Remote objects.

Syntax

sp_queue_dump_database

See also

sp_queue_dump_transaction procedure

Stable queue recovery issues

Description

Keeping the stable queue in a separate database complicates backup and recovery, as consistent versions of the two databases have to be recovered.

Normal recovery automatically restores the two databases to a consistent state, but recovery from media failure takes some care. When restoring database dumps, it is important to recover the stable queue to a consistent point. The sp_queue_dump_database procedure is provided to help with recovery from media failure. It is called whenever a dump database is scanned.

As provided, the procedure does not carry out any operations. You can modify this stored procedure to issue a dump database command in the stable store database.


sp_queue_dump_transaction procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_dump_transaction procedure

Purpose

To facilitate recovery from media failure, when the stable queue is in a separate database from the SQL Remote objects.

Syntax

sp_queue_dump_transaction

See also

sp_queue_dump_database procedure

Stable queue recovery issues

Description

Keeping the stable queue in a separate database complicates backup and recovery, as consistent versions of the two databases have to be recovered.

Normal recovery automatically restores the two databases to a consistent state, but recovery from media failure takes some care. When restoring database dumps, it is important to recover the stable queue to a consistent point. The sp_queue_dump_transaction procedure is provided to help with recovery from media failure. It is called whenever a dump transaction is scanned.

As provided, the procedure does not carry out any operations. You can modify this stored procedure to issue a dump transaction command in the stable store database.


sp_queue_get_state procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_get_state procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_get_state

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It returns a description of the current state of the stable queue.


sp_queue_log_transfer_reset procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_log_transfer_reset procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_log_transfer_reset

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It resets the page and row IDs to zero in the sr_queue_state table.


sp_queue_read procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_read procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_read start_offset, stop_offset

Description

This procedure reads transactions from the stable queue. It is exclusively for use by the Message Agent.


sp_queue_reset procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_reset procedure

Purpose

To reset the server to a point where the stable queue is empty.

Syntax

sp_queue_reset

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly in a production environment. It deletes all rows from the stable queue sr_transaction table, and resets the sr_queue_state table, ready for a new SQL Remote setup.

In a development phase, this procedure can be useful to reset the server.


sp_queue_set_confirm procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_set_confirm procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_set_confirm confirm_offset

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It sets the minimum confirmation offset from all remote users in the sr_queue_state table.


sp_queue_set_progress procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_set_progress procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_set_progress page_id, row_id, commit_offset, backup_offset, marker

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It sets the transaction log scanning progress value in the sr_queue_state table.


sp_queue_transaction procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_queue_transaction procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly.

Syntax

sp_queue_transaction offset, user_id

Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly. It adds a new transaction to the stable queue.


sp_remote procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_remote procedure

Purpose

This procedure is used by the SQL Remote Message Agent, and should not be called directly, with a single exception described below. It manages rows in the sr_remoteuser table.

Syntax

sp_remote operation, user_name [ , offset ] [ , confirm ]

Argument	Description
operation	The name of an action. The only value that should be used by a user is reset; all others are for use by the Message Agent.
user_name	The name of the remote user being reset
offset	Not used
confirm	Not used
Description

This procedure is used by the SQL Remote Message Agent, and should not be called directly with the single exception of the reset call. It maintains the message tracking information in the sr_remoteuser table.

The following special case can be used directly, when creating a custom database extraction process:

sp_remote reset, remote_user

where remote_user is the remote user name.

This command starts all subscriptions for a remote user in a single transaction. It sets the log_sent and confirm_sent values in sr_remoteuser table to the current position in the transaction log. It also sets the created and started values in sr_subscription to the current position in the transaction log for all subscriptions for this remote user. The procedure does not do a commit. You must do an explicit commit after this call.

In order to write an extraction process that is safe on a live database, the data must be extracted at isolation level 3 in the same transaction as the subscriptions are started.


sp_remote_option procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_remote_option procedure

Purpose

To set a SQL Remote option.

Syntax

sp_remote_option option_name, option_value

Argument	Description
option_name	The name of one of the SQL Remote options
option_value	The value to which the option is set.
See also

SQL Remote options.

Description

The SQL Remote options provide control over replication behavior. The following options are available in Adaptive Server Enterprise:

OPTION	VALUES	DEFAULT
Blob_threshold	Integer, in K	256
Compression	-1 to 9	6
Delete_old_logs	ON, OFF	OFF
Qualify_owners	ON, OFF	OFF
Quote_all_identifiers	ON, OFF	OFF
Replication_error	procedure-name	NULL
SR_Date_Format	time-string	hh:nn:ss.Ssssss
SR_Time_Format	date-string	yyyy/mm/dd
SR_Timestamp_Format	timestamp-string	yyyy/mm/dd hh:nn:ss.Ssssss
Subscribe_by_remote	ON,OFF	ON
Verify_threshold	integer	256
Verify_all_columns	ON,OFF	OFF
  For a complete description of these options, see SQL Remote options.

Example

•	The following statement sets the Verify_all_columns option to OFF, so that old values of update statements applied by the Message Agent are not checked automatically for all columns.

sp_remote_option Verify_all_columns, OFF

go


sp_remote_type procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_remote_type procedure

Purpose

To create or modify a SQL Remote message type.

Syntax

sp_remote_type type_name publisher_address

Argument	Description
type_name	The message type to create or alter. This must be one of the following: • file • ftp • smtp • mapi • vim
publisher_address	The address of the publisher under the specified message type.
See also

sp_drop_remote_type procedure

ALTER REMOTE MESSAGE TYPE statement

Description

The Message Agent sends outgoing messages from a database using one of the supported message links. Return messages for users employing the specified link are sent to the specified address as long as the remote database is created by the Extraction Utility. The Message Agent starts links only if it has remote users for those links.

The address is the publisher's address under the specified message system. If it is an e-mail system, the address string must be a valid e-mail address. If it is a file-sharing system, the address string is a subdirectory of the directory set in the SQLREMOTE environment variable or registry entry, or of the current directory if that is not set.

Example

The following example creates a FILE message type for a database, and gives the publisher's address as a subdirectory of the SQLREMOTE location named publisher:

sp_remote_type file, publisher

go


sp_remove_article procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_remove_article procedure

Purpose

To remove an article from a publication

Syntax

sp_remove_article publication_name, table_name

Argument	Description
publication_name	The name of the publication from which the article is to be deleted.
table_name	The table containing the article.
See also

sp_add_article procedure

ALTER PUBLICATION statement

Description

Running sp_add_article removes an article from a publication. Any article including parts of the named table is removed from the publication.

Example

•	The following statement removes any articles that use part of the  SalesRep table from a publication named SalesRepData:

sp_remove_article SalesRepData, SalesRep

go


sp_remove_article_col procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_remove_article_col procedure

Purpose

To remove a column from an article in a publication.

Syntax

sp_remove_article_col publication_name, article_name, column_name

Argument	Description
publication_name	The name of the publication to which the article belongs.
article_name	The article from which the column is to be removed.
column_name	The column to be removed from the article.
See also

sp_add_article_col procedure

sp_remove_article procedure

ALTER PUBLICATION statement

Description

You can remove a column from a publication using sp_remove_article_col.

To remove a column using sp_remove_article_col, the column must have been explicitly added to a publication using the sp_add_article_col procedure. Although the sp_add_article procedure, without use of sp_add_article_col, adds all the columns of a table to a publication, you cannot remove a single column from such a publication using sp_remove_article_col.

Example

•	The following statement removes the column emp_lname of the employee table from a publication named Personnel:

sp_remove_article_col 'Personnel', 'employee', 'emp_lname'

go


sp_remove_remote_table procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_remove_remote_table procedure

Purpose

To mark a table as unavailable for SQL Remote replication.

Syntax

sp_remove_remote_table table_name

Argument	Description
table_name	The table to be marked as not available for SQL Remote replication.
See also

sp_add_remote_table procedure

sp_modify_remote_table procedure

Description

Marks a table as unavailable for replication. Once this procedure has been called, the data in the table cannot be shared with other databases using SQL Remote.

Example

•	The following statement marks the employee table as unavailable for replication:

sp_remove_remote_table employee

go


sp_revoke_consolidate procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_revoke_consolidate procedure

Purpose

To stop a user from being able to receive SQL Remote messages from this database.

Syntax

sp_revoke_consolidate user_name

Argument	Description
user_name	The user ID who will no longer be able to act as a consolidated database.
See also

sp_grant_consolidate procedure

Description

The sp_revoke_consolidate procedure  removes the consolidated database user ID from the list of users receiving messages from the current database.

Example

•	The following statement revokes consolidated permissions from user hq_user:

sp_revoke_consolidate hq_user

go


sp_revoke_remote procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_revoke_remote procedure

Purpose

To stop a user from being able to receive SQL Remote messages from this database.

Syntax

sp_revoke_remote user_name

Argument	Description
user_name	The user ID who will no longer be able to receive SQL Remote messages.
See also

sp_grant_remote procedure

Description

The sp_revoke_remote procedure removes a user ID from the list of users receiving messages from the current database.

Example

•	The following statement revokes remote permissions from user Field User:

sp_revoke_remote 'Field user'

go


sp_subscription procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_subscription procedure

Purpose

To manage subscriptions.

Syntax

sp_subscription operation,

publication_name,

user_name,

[ subscribe_by ]

Argument	Description
operation	The operation to be performed. This must be one of the following: • create   To create a subscription to a given publication for a user. • drop   To drop a subscription to a given publication for a user. • start   To start a subscription to the named publication. • stop   To stop a subscription to the named publication. • synchronize   To synchronize a subscription to the named publication.
publication_name	The name of the publication to which the subscription refers.
user_name	The user ID who is being subscribed to the publication.
subscribe_by	The subscription value.
See also

Creating subscriptions.

Description

The sp_subscription procedure is used to manage subscriptions. The first argument to the procedure (operation) specified whether the procedure is being created, dropped, started, stopped, or synchronized.

In general, starting and synchronizing subscriptions is done using the extraction utility. Sybase Central does not display subscriptions as started until the Message Agent first runs against the database.

Example

The following statement creates a subscription for user SalesRep1 to the SalesRepData publication, which has no subscription expression.

sp_subscription create,

SalesRepData,

SalesRep1

go


sp_subscription_reset procedure
  Replication and Synchronization Guide

    PART 3. SQL Remote

      CHAPTER 26.  Command Reference for Adaptive Server Enterprise

 sp_subscription_reset procedure

Purpose

To reset all SQL Remote information for all remote users.

Syntax

sp_subscription_reset

Description

This procedure resets all the entries in the sr_remote_user and sr_subscrioption tables to zero or NULL.


PART 4. Appendixes
  Replication and Synchronization Guide

 PART 4. Appendixes

This material is supplementary material, not required for everyday use of the product.

 APPENDIX A.  Enterprise and Anywhere: Differences

 APPENDIX B.  Supported Platforms and Message Links


APPENDIX A.  Enterprise and Anywhere: Differences
  Replication and Synchronization Guide

    PART 4. Appendixes

 APPENDIX A.  Enterprise and Anywhere: Differences

About this Appendix

This appendix summarizes the differences between SQL Remote for Adaptive Server Enterprise and for Adaptive Server Anywhere.

This appendix describes the main differences between these versions of the technology.

 Types of difference

 Differences in functionality

 Differences in approach

 Limitations for Enterprise to Enterprise replication


Types of difference
  Replication and Synchronization Guide

    PART 4. Appendixes

      APPENDIX A.  Enterprise and Anywhere: Differences

 Types of difference

The differences between the versions of the software are of the following kinds:

•	Functionality    Tasks that can be carried out by one of the two versions, but not by the other.

•	Approach    Although a similar result can be obtained, a different approach is required in each version. This includes tasks that are carried out in ways that are superficially different, but which have the same result.

•	Server differences    Tasks associated with SQL Remote, such as backup management, are different for the two servers. These differences are not described here.

This appendix addresses only replication using Adaptive Server Anywhere as remote databases. There are additional limitations if using Adaptive Server Enterprise as remote servers.


Differences in functionality
  Replication and Synchronization Guide

    PART 4. Appendixes

      APPENDIX A.  Enterprise and Anywhere: Differences

 Differences in functionality

The major differences in functionality between SQL Remote for Adaptive Server Enterprise (SRE) and SQL Remote for Adaptive Server Anywhere (SRA) are as follows:

•	Schema changes    For SRE, schema changes must be made on a quiet system. A quiet system means the following:

•	No transactions being replicated    There can be no transactions being replicated that modify the tables that are to be altered. All transactions that modified tables being altered must be scanned from the transaction log into the stable queue before the schema is altered. This is performed by running the Message Agent normally, or using the -i -b switches. After the Message Agent completes, you can make the schema change.

•	Message Agent shut down    The Message Agent must be shut down when the schema change is being made.

•	SQL Remote Open Server    If you are using the SQL Remote Open Server, it must be shut down when the schema change is being made.

•	Trigger action replication    In SRE, trigger actions are replicated. In SRA you have the choice of replicating trigger actions, but by default they are not replicated. The replication of trigger actions requires SRE users to ensure that triggers are not fired at remote databases.

•	Platform availability    SRA is available on a wider variety of platforms that SRE, reflecting the platform availability of the two servers.

•	Publication definitions    Publications in SRA can be more selective than those in SRE. For example, in SRA you can use a WHERE clause with any value. In SRE, you can only use IS NULL and IS NOT NULL conditions in the WHERE clause.


Differences in approach
  Replication and Synchronization Guide

    PART 4. Appendixes

      APPENDIX A.  Enterprise and Anywhere: Differences

 Differences in approach

There are some features of SQL Remote that must be approached in a different manner in SRE and SRA.

•	Partitioning tables that do not contain the subscription expression    In SRA, publications can contain subqueries, and these allow tables that do not contain a partition expression to nevertheless be distributed properly among subscribers. In SRE, an additional column must be added to such tables, containing a list of subscribers, and triggers must be written to maintain the column. This column can have a maximum size of 255.

  For descriptions, see Partitioning tables that do not contain the subscription expression, and Partitioning tables that do not contain the subscription column.

•	Conflict resolution    In SRA, conflict resolution is carried out using a special trigger syntax. In SRE, stored procedures must be written to carry out this task.

  For descriptions, see Managing conflicts, and Managing conflicts.

•	Storing messages before sending    In SRE, a separate table named the stable queue is used to hold changes before replication. In SRA, there is no stable queue; instead, the messages are retrieved from current and old transaction log files.

•	Commands    Whereas SQL Remote tasks such as creating publications are carried out using SQL statements in SRA, they are carried out using system stored procedures in SRE.

The Sybase Central administration tool hides many of these stylistic differences by providing a common look and feel to the administration of each version of SQL Remote.

 Adaptive Server Enterprise procedures and Adaptive Server Anywhere statements


Adaptive Server Enterprise procedures and Adaptive Server Anywhere statements
  Replication and Synchronization Guide

    PART 4. Appendixes

      APPENDIX A.  Enterprise and Anywhere: Differences

        Differences in approach

 Adaptive Server Enterprise procedures and Adaptive Server Anywhere statements

In SQL Remote for Adaptive Server Anywhere, SQL statements are used to carry out the tasks that these stored procedures carry out in Adaptive Server Enterprise. The following table lists the SQL Remote procedures, and how they correspond to SQL statements in Adaptive Server Anywhere:

Adaptive Server Enterprise procedure	Corresponding Adaptive Server Anywhere statement
sp_remote_type	CREATE REMOTE MESSAGE TYPE
sp_remote_type	ALTER REMOTE MESSAGE TYPE
sp_drop_remote_type	DROP REMOTE MESSAGE TYPE
sp_grant_remote	GRANT REMOTE
sp_revoke_remote	REVOKE REMOTE
sp_publisher	GRANT PUBLISH
sp_publisher	REVOKE PUBLISH
sp_create_publication sp_add_article sp_add_article_col	CREATE PUBLICATION
sp_add_article sp_remove_article sp_add_article_col sp_remove_article_col	ALTER PUBLICATION
sp_drop_publication	DROP PUBLICATION
sp_subscription 'create'	CREATE SUBSCRIPTION
sp_subscription 'drop'	DROP SUBSCRIPTION
sp_subscription 'start'	START SUBSCRIPTION
sp_subscription 'stop'	STOP SUBSCRIPTION
sp_subscription 'synchronize'	SYNCHRONIZE SUBSCRIPTION
sp_passthrough_user	PASSTHROUGH FOR USERID
sp_passthrough_subscription	PASSTHROUGH FOR SUBSCRIPTION
sp_passthrough_stop	PASSTHROUGH STOP


Limitations for Enterprise to Enterprise replication
  Replication and Synchronization Guide

    PART 4. Appendixes

      APPENDIX A.  Enterprise and Anywhere: Differences

 Limitations for Enterprise to Enterprise replication

If you wish to use SQL Remote for replication between Adaptive Server Enterprise databases, rather than with Adaptive Server Anywhere remote databases, you should be aware of the following limitations:

•	Database extraction    The extraction utility creates RELOAD.SQL scripts and data files for building Adaptive Server Anywhere remote databases. Setting up remote ASE databases requires an extraction process created by the customer.

  For more information about how to create an extraction process, see sp_remote procedure.

•	Referential integrity errors    Referential integrity is always checked immediately in Adaptive Server Enterprise, while Adaptive Server Anywhere provides the WAIT_FOR_COMMIT option to control when integrity is checked. This presents difficulties when rows move between remote databases, as in territory realignment.

For example, suppose an Order table has a foreign key to a Customer table which has a foreign key to a SalesRep table. The Customer table is subscribed by sales rep. The Order table is also subscribed by sales rep (it has a redundant column maintained by a trigger).

When a row in Customer is updated to point to a new sales rep, a trigger fires to update the sales rep column in Order. The update on Customer is replicated as a delete to the old rep and an insert to the new rep. Similarly, the triggered update on Order is replicated as a delete to the old rep and an insert to the new rep.

The problem occurs because SQL Remote replicates the operations in the order they occur, which means the Customer row is deleted before the Order rows. This causes a referential integrity error.

•	Schema upgrades     Schema upgrades are difficult to manage when both consolidated and remote databases are Adaptive Server Enterprise databases. Passthrough to remote Adaptive Server Enterprise databases is difficult to carry out.

The problem is due to the need for a quiet system for schema upgrades (see Differences in functionality). Passthrough puts schema upgrade statements into the normal message stream. The operations that precede the schema upgrade (in the same message or a previous message) cannot possibly have been scanned from the transaction log into the stable queue before the schema change takes place.

•	Synchronize subscription    This is not implemented for Adaptive Server Enterprise remote databases.


APPENDIX B.  Supported Platforms and Message Links
  Replication and Synchronization Guide

    PART 4. Appendixes

 APPENDIX B.  Supported Platforms and Message Links

About this Appendix

This appendix summarizes the platforms and message links that SQL Remote supports.

 Supported message systems

 Supported operating systems


Supported message systems
  Replication and Synchronization Guide

    PART 4. Appendixes

      APPENDIX B.  Supported Platforms and Message Links

 Supported message systems

SQL Remote exchanges data among databases using an underlying message system. SQL Remote supports the following message systems:

•	File sharing    A simple system requiring no extra software.

•	FTP    Internet file transfer protocol.

•	SMTP/POP    Internet e-mail protocol.

•	MAPI    Microsoft Messaging Application Programming Interface, used in Microsoft products and in cc:Mail release 8 and later.

•	VIM    Vendor Independent Messaging, used in Lotus Notes and in some versions of Lotus cc:Mail.

Not all systems are supported on all operating systems. For all systems other than the file sharing system, you must have purchased and installed the appropriate message system software for SQL Remote to function over this system. SQL Remote does not include the underlying message system software.


Supported operating systems
  Replication and Synchronization Guide

    PART 4. Appendixes

      APPENDIX B.  Supported Platforms and Message Links

 Supported operating systems

SQL Remote for Adaptive Server Enterprise

SQL Remote for Adaptive Server Enterprise is available for the following operating systems and message links:

•	Windows NT    All message protocols.

•	Sun Microsystems Solaris/Sparc    File sharing, FTP, and SMTP/POP only.

•	Hewlett-Packard HP-UX    File sharing, FTP, and SMTP/POP only.

SQL Remote Open Server on IRIX
A bug in IRIX that was fixed in the IRIX 10.0.3 release EBF 7658 is required for the SQL Remote Open Server. ssqueue systems involving SGI/IRIX should make sure this patch is installed.

•	IBM AIX    File sharing only.

SQL Remote for Adaptive Server Anywhere

SQL Remote for Adaptive Server Anywhere is available for the following operating systems:

•	Windows 95/98    All message links.

•	Windows NT    All message links.

•	Windows CE    FILE and SMTP/POP links. For the file link, dbremote looks in \My Documents\Synchronized Files. On the desktop machine, the SQLREMOTE environment variable or directory message link parameter for the FILE link should be set to the following:

%SystemRoot%\Profiles\userid\Personal\ce-machine-name\ Synchronized Files

where userid and ce-machine-name are set to the appropriate values. With this setup, ActiveSync automatically synchronizes the message files between the desktop and CE system.

Check Mobile Devices [image] Tools [image] ActiveSync Options to ensure that file synchronization is activated.

  For information on setting message link parameters, see The file message system.

•	Sun Microsystems Solaris/Sparc    File sharing, FTP, and SMTP/POP only.

•	Hewlett Packard HP-UX    File sharing, FTP, and SMTP/POP only.

•	IBM AIX    File sharing, FTP, and SMTP/POP only.

•	Novell NetWare    File sharing, FTP, and SMTP/POP only.

•	Linux    File sharing, FTP, and SMTP/POP only.

For details of the supported UNIX operating system versions, see the SQL Anywhere Studio Read Me First for UNIX.