0% found this document useful (0 votes)

1K views324 pages

Shareplex 8 6 3 Administrator Guide en PDF

Uploaded by

Carlos Gonzalez

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views324 pages

Shareplex 8 6 3 Administrator Guide en PDF

Uploaded by

Carlos Gonzalez

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 324

Dell SharePlex 8.

6
Administrator Guide
Revision 2

Copyright 2015 Dell Inc. All rights reserved.

This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a
software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the
applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or
mechanical, including photocopying and recording for any purpose other than the purchasers personal use without the
written permission of Dell Software Inc.
The information in this document is provided in connection with Dell Software products. No license, express or implied, by
estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Dell
Software products. EXCEPT AS SET FORTH IN DELL SOFTWARES TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE
AGREEMENT FOR THIS PRODUCT, DELL SOFTWARE ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED
OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL DELL BE LIABLE FOR
ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY
TO USE THIS DOCUMENT, EVEN IF DELL SOFTWARE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Dell Software
makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and
reserves the right to make changes to specifications and product descriptions at any time without notice. Dell Software does
not make any commitment to update the information contained in this document.
If you have any questions regarding your potential use of this material, contact:
Dell Software Inc.
Attn: LEGAL Dept
5 Polaris Way
Aliso Viejo, CA 92656
Refer to our web site (www.software.dell.com) for regional and international office information.

SharePlex
Updated - November 2015
Software Version - 8.6

SharePlex 8.6
Administrator Guide

Contents
About this Guide

Conventions used in this guide

About Dell Software

Contacting Dell Software

Technical support resources

Overview of SharePlex

About source and target data

About sp_cop

About sp_ctrl

sp_ctrl

About the SharePlex architecture

SharePlex Directories

SharePlex Tables

SharePlex queues

SharePlex processes

How SharePlex replicates data

Understand the concept of synchronization

Characteristics of synchronized tables

Hidden out-of-sync conditions

Strategies for information availability

Reporting instances

Broadcast and cascade

Data warehousing

High availability and disaster recovery

Test before you deploy

Run SharePlex

Run SharePlex on Unix and Linux

Startup sequence on Unix and Linux

Start SharePlex on Unix and Linux

Identify SharePlex processes on Unix and Linux

Stop SharePlex on Unix and Linux

Shutdown Considerations on Unix and Linux

Run SharePlex on Windows

SharePlex 8.6
Administrator Guide

Startup Sequence on Windows

Start and stop SharePlex on Windows

Set SharePlex startup status on Windows

Set SharePlex process priority on Windows

Identify SharePlex processes on Windows

Shutdown Considerations on Windows

Run multiple instances of SharePlex

Run multiple instances of SharePlex from separate installations

Run multiple instances of SharePlex from one installation

How to run multiple sp_cop instances on Unix and Linux

How to run multiple sp_cop instances on Windows

Execute commands in sp_ctrl

How to run sp_ctrl

Start sp_ctrl

Exit sp_ctrl

Define a default port for sp_ctrl

Define a default host for sp_ctrl

Prepare an Oracle environment for replication

Set up Oracle redo logging to support SharePlex

Set the appropriate logging level

Ensure that the correct key is logged

Configure the archive logs

Set up Oracle database objects for replication

Ensure row uniqueness

Keys

Indexes

Bitmap indexes

Prevent triggers from firing on the target

Configure integrity constraints

Foreign key constraints

ONDELETECASCADE constraints

Check constraints

Prevent access to target objects

Ensure compatible source-target mapping

Configure sequences

Create objects and partitions

Set up an Oracle database to support SharePlex

Adjust OPEN_CURSORS to support Post cursors

SharePlex 8.6
Administrator Guide

Adjust the PROCESSES parameter to support connections

Adjust the log buffer size to improve posting

Adjust the SharePlex transaction table based on user volume

Control conversion of character sets

Set up SharePlex to support Oracle data

LOBs, LONGs, VARRAYs, and XML

Tune SharePlex based on Oracle data volume

Set system process priority

Enable Oracle direct path loads

Enable capture on Exadata machines

Set up TDE Support

Required privilege to capture TDE-protected data

Configure SharePlex to capture TDE-protected data

Create configuration files

How to create a configuration file

Create a configuration file

Structure of a configuration file

Additional configuration options

Database specifications in a configuration file

Target specifications in a configuration file

Routing specifications in a configuration file

Simple routing map

Compound routing map

Same-system routing map

Routing Considerations

Configuration examples by datasource and target

Replicate from a regular Oracle instance to a regular Oracle instance

Replicate from a regular Oracle instance to a non-Oracle database

Replicate from a regular Oracle instance to a file in XML or SQL format

Replicate from a regular Oracle instance to a JMS queue or topic

Replicate from and to an Oracle pluggable database (PDB) in a container database (CDB)*

Replicate to maintain a change history target

Use a script to build a configuration file

Replicate to, or from, a PDB

Capture from a PDB

Replicate to a PDB

Examples

Use Wildcards to specify multiple objects

Limitations of wildcard support

SharePlex 8.6
Administrator Guide

Supported wildcard syntax

Specify wildcarded names in the configuration file

Validate a wildcard specification

Examples

Define a unique key

Syntax for key definition

Example

Filter DML Operations

Configure a DML filter

Examples

View current DML filters

Restrictions

Map source and target columns

Guidelines for using column mapping

Configure column mapping

Configuration example

Build a configuration file using a script

Supported databases

Use config.sql

Use build_config.sql

Configure replication to non-Oracle targets

Configure replication to a Microsoft SQL Server target

Overview

Configure SharePlex on the source

Enable supplemental logging

Set SP_OCT_USE_SUPP_KEYS parameter

Configure replication

Configure SharePlex on the target

Configure replication to an SAP ASE target

Overview

Configure SharePlex on the source

Enable supplemental logging

Set SP_OCT_USE_SUPP_KEYS parameter

Configure replication

Configure SharePlex on the target

Set up ODBC

Set connection information with the connection command

Configure replication to an ODBC-compliant target

Overview

SharePlex 8.6
Administrator Guide

Configure SharePlex on the source

Enable supplemental logging

Set SP_OCT_USE_SUPP_KEYS parameter

Configure replication

Configure SharePlex on the target

Set up ODBC

Set connection information with the connection command

Map datatypes

Configure Replication to a JMS target

Overview

Configure SharePlex on the source

Enable supplemental logging

Set SP_OCT_USE_SUPP_KEYS parameter

Configure replication

Configure SharePlex on the target

Configure SharePlex on an Active MQ target

View and change JMS settings

Set recovery options

Control memory settings

Configure debugging

100

About the XML

100

Schema record template

100

Operation record template

101

Configure Replication to a SQL or XML file target

106

Overview

106

Configure SharePlex on the source

106

Configure SharePlex on the target

107

View and change target settings

107

Command examples

108

About the SQL

109

About the XML

109

Schema record template

109

Operation record template

110

File storage and aging

115

Configure a replication strategy

116

Configure replication to share or distribute data

116

Supported targets

116

Capabilities

117

Requirements

117

SharePlex 8.6
Administrator Guide

Conventions used in the syntax

117

Replicate within the local system

117

Replicate to a remote target system

118

Replicate to multiple target systems

119

Confgure replication to maintain a central data store

120

Supported targets

120

Capabilities

120

Requirements

120

Deployment options

120

Deploy with one instance of SharePlex on the target system

121

Deploy with multiple instances of SharePlex on the target system

122

Configuration

123

Recommended target configuration

123

Configure replication to maintain multiple peer databases

124

Supported targets

125

Capabilities

125

Requirements

125

Overview

125

Deployment

127

Evaluate the data

127

Configure replication

131

Develop conflict resolution routines

132

How to write a routine using the SharePlex generic interface

133

How to use use the SharePlex prepared routines

138

List the routines in conflict_resolution.SID

139

Configure replication through an intermediary system

141

Supported targets

141

Capabilities

141

Requirements

141

Conventions used in the syntax

142

Deployment options

142

Cascade with posting on intermediate system

143

Cascade with pass-through on intermediary system

144

Configure replication to maintain high availability

145

Supported targets

145

Capabilities

146

Requirements

146

Conventions used in the syntax

146

Configuration

147

SharePlex 8.6
Administrator Guide

Make the system ready for failover

147

Perform recovery procedures

147

Configure partitioned replication

148

Configure horizontally partitioned replication

148

Guidelines for using horizontally partitioned replication

148

How it works

149

Define partitions and schemes

150

How to create a column condition

152

Specify partition schemes in the configuration file

155

Configure vertically partitioned replication

156

Guidelines for using vertically partitioned replication

156

Configure vertically partitioned replication

157

Configure named queues

160

Configure named export queues

160

Benefits of named export queues

161

Considerations when using named export queues

162

Configure a named export queue

162

How to identify named export queues

163

Configure named post queues

163

Benefits of named post queues

164

Considerations when using named post queues

165

Configure a named post queue

165

How to identify a named post queue

166

Configure replication to maintain a change history target

167

Overview of the change-history target

167

Capabilities

167

Supported targets

168

Operations supported

168

Operations not supported

168

How SharePlex maintains change history

168

Configure change history

169

Create a change-history configuration file

169

Additional change history configuration options

170

Customize column names

170

Add the before image to each change row

170

Include all columns of an operation in the history

170

Disable change history of an operation type

170

Set rules and filters

171

SharePlex 8.6
Administrator Guide

Include COMMITs

171

Set up DDL Replication

172

DDL that SharePlex supports

172

Control DDL replication

172

Default DDL support

173

Expanded Auto-Add support

173

DDL support for objects outside the replication configuration

174

Filter DDL Replication

174

Best practices for ALTERTABLE DDL

176

Tables with VARRAY or ABSTRACT types

177

Tables with system-specific metadata

177

Tables that are renamed

177

ALTERTABLE...MOVE

177

DDL logging and error handling

178

Set up error handling

179

Continue to post when there is a DML error

179

Continue to Post when there is a DDL error

180

Increase the number of retries on error

180

Stop Post when data is out-of-sync

181

Transform data

182

Overview of transformation

182

Supported databases

182

Supported replication strategies

182

Supported operations

183

Considerations when using transformation

183

Deploy transformation

184

Create transformation routines

184

Complete the transformation file

189

Configure SharePlex security features

191

Secure connections to SharePlex

191

Requirements

191

Secure data with SSH

192

Requirements

192

Assign SharePlex users to security groups

194

Description of the SharePlex security groups

194

Create and populate SharePlex groups on Windows

194

Activate replication in an Oracle production environment

196

SharePlex 8.6
Administrator Guide

What is activation?

196

Activation commands

197

Activate a configuration file

197

View activation status

198

View configuration statistics

198

Deactivate a configuration file

198

Requirements for activating a configuration

198

Required authorization level

198

Pre-activation checklist

199

Understand the commands that you will use

200

Test the configuration file

200

Frequently Asked Questions about activation

201

Activate multiple configuration files

202

Activate replication with an Oracle hot backup on an active database

202

Preliminary considerations

202

Procedures

203

Activation with hot backup: all strategies except cascading

204

Activation with hot backup:cascading replication

205

Activate replication with an Oracle hot backup on a quiet database

207

Preliminary considerations

207

Procedure

208

Activate replication with Oracle transportable tablespaces

210

Preliminary considerations

210

Procedure

211

Activate replication with cold copy/transfer methods

212

Preliminary considerations

212

Procedure

213

Monitor SharePlex

215

View and terminate SharePlex processes

215

View events and errors

218

Monitor with sp_ctrl commands

220

Run monitor scripts on Unix

222

Requirements for using the monitoring scripts

222

Monitor capture with sp_logmon

223

Prepare to run sp_logmon

223

Run sp_logmon

224

Monitor events with sp_eventmon

224

Prepare to run sp_eventmon

225

Run sp_eventmon

225

SharePlex 8.6
Administrator Guide

Monitor processes with sp_ps

227

Prepare to run sp_ps

227

Run sp_ps

227

Monitor queues with sp_qstatmon

228

Prepare to run sp_qstatmon

228

Run sp_qstatmon

229

Run a monitor script on Windows

230

Configure and run Sp_Nt_Mon

230

Monitor replication with SNMP

232

Enable SNMP

232

Configure the SNMP agent

232

Configure the SNMP traps

232

Prevent and solve replication problems

234

Solve Oracle setup problems

234

Incorrect ORACLE_SID and/or ORACLE_HOME

234

More than one oratab file (Sun Solaris)

235

Asterisk as the ORACLE_SID entry

235

Legacy /etc/logingroups file (HP systems)

235

Solve Configuration Problems

235

SharePlex cannot locate the configuration

235

A configuration will not activate

236

Reasons for complete activation failure

236

Reasons individual objects fail to activate

238

Activation takes too long

238

Explanation of configuration command errors

239

Solve replication problems

241

Replication is too slow

241

Capture stopped

245

Post stopped

246

The post queue is not emptying

247

There is a failure to write and open queue error

248

The queues are corrupted

248

The post queue seems too large

248

You had to unexpectedly stop replication (Unix and Linux)

249

sp_cop is using too much CPU time

250

A source table is corrupted

251

SharePlex is running out of disk space

251

DDL is not replicating

252

Replicated DDL is not completely displayed in the Event Log

252

SharePlex 8.6
Administrator Guide

Post generates a shared memory error

252

Post generates a semaphore error

252

SharePlex does not run on a Windows system

253

Explanation of common replication error messages

254

Solve Synchronization Problems

260

How SharePlex reports out-of-sync conditions

260

Find and correct the problem before you resynchronize!

261

How to detect and correct common out-of-sync conditions

261

Cascading deletes on target objects

263

How to resynchronize objects

267

Solve other replication problems

271

A configuration was accidentally deleted

272

Conflict resolution generates compile errors

272

The reconcile command is slow to complete

272

Machine names cannot be resolved

272

A Cant unlink file error occurs on Windows systems

272

Solving connection errors

272

Solving compare command errors

273

Solving errors for other sp_ctrl commands

275

Repair out-of-sync Data

279

Overview of Compare and Repair

279

Overview of the server and client processes

279

How locks are managed

280

Before you use Compare and Repair

280

How to use the repair and compare commands

281

When to run a repair

282

How to run the compare and repair commands

282

Procedures to Maintain Oracle High Availability

283

Recover replication if the primary system fails

283

Supported databases

283

Requirements

283

Procedure 1: Move replication to the secondary system

284

Procedure 2: Move replication to the restored primary system

284

Recover replication if the secondary Oracle instance fails

288

Supported databases

288

Requirements

288

Procedure

288

Move replication during planned failover and failback

290

Supported databases

290

SharePlex 8.6
Administrator Guide

Requirements

291

Procedure

291

Make changes to an active replication environment

294

Change an active configuration file

294

Add or change table specifications in an active configuration

295

Supported databases

295

Procedure

295

Change Partitioned Replication

296

Add Oracle sequences to an active replication configuration

296

Supported databases

297

Add a sequence if the sequence does not populate a column

297

Add a sequence if the sequence populates a column

297

Remove objects from replication

298

Supported databases

299

Procedure

299

Make DDL changes in an active replication configuration

299

Supported databases

299

Requirements

300

Procedure

300

Make Oracle changes that affect replication

300

Supported databases

301

Move the location of ORACLE_HOME

301

Change the target ORACLE_SID

301

Change the SharePlex database account

302

Supported databases

302

Procedure

302

Change the name or IP address of a replication host

303

Description

303

Supported databases

303

Guidelines for using provision

303

Run provision

304

Undo changes made by provision

304

Known issues

305

Apply an Oracle application patch or upgrade

306

Before you patch or upgrade an application

306

Which procedure to use?

306

The effect of patches and upgrades on partitioned replication

307

Naming conventions used

308

Apply patch/upgrade to source then copy it to target

308

SharePlex 8.6
Administrator Guide

Supported databases

308

When to use this procedure

308

Overview of the procedure

309

Apply the patch/upgrade

309

Apply patch/upgrade to source and target

310

Supported databases

310

When to use this procedure

310

Overview of the procedure

311

Apply the patch/upgrade

311

Apply patch to source and replicate it to the target

312

Supported databases

312

When to use this procedure

312

Apply the patch/upgrade

312

Back up Oracle data on the source or target

313

Perform a partial backup of the source system

313

Perform a full backup on the source system

314

Tune the Capture process for Oracle sources

315

Overview

315

Disable LOB Mapping

315

Tune Capture on Exadata

316

Support frequent log switches

316

Tune the Post process for Oracle targets

317

Use Oracle INDEX hints

317

Tune SQL Caching

318

Adjust open cursors

319

Skip large maintenance transactions

320

Make small transactions faster

321

Increase the level of concurrency

321

Reduce the number of commits

321

Appendix A: Peer-To-Peer Diagram

322

Appendix B: SharePlex variables

323

SharePlex 8.6
Administrator Guide

About this Guide

This manual provides instructions for:

l Operating SharePlex
l Planning your replication strategy
l Preparing the environment for replication
l Configuring replication
l Starting replication
l Monitoring, tuning, and troubleshooting replication
l Failover/failback in a high-availability environment
l Performing administrative operations on replication systems

Conventions used in this guide

Conventions used in this manual

The following typographic conventions are used in this guide.
l Bold represents required components of a command or option that must be typed as shown.
l Italics represent variables defined, named or entered by the user.
l Bold Italics represents required user defined variables in example command strings.
l {Braces} enclose available required arguments.
l [Brackets] represent optional command components and may also be used in example command strings
to emphasize required user defined variables in long strings.
Example:
reconcile queue {queuename} for {datasource-datadest} [onhost]
l A vertical bar, or pipe character ( | ) within brackets or braces indicates that you can use only one of
the enclosed components.
Example:
abort service {service | all}
Names of commands, programs, directories and files are expressed in Arial Bold;
other names are expressed in capital letters using the default font.
Examples:
The sp_ctrl program is located in the bin directory.
Open the oramsglst file.
Find the value for ORACLE_HOME.
Click Apply.
System displays, such as prompts and command output, are expressed in Courier New.
Examples:
sp_ctrl(sysA)>
User is a viewer (level=3)
Windows menu items, dialog boxes, and options within dialog boxes are expressed in Arial Bold.
Example:
From the File menu, select Print.
System names are expressed generically or fictitiously. When necessary, the source system
(or primary system) is referred to as SysA. Target systems (or secondary systems)
are referred to as SysB, SysC, SysD, and so forth.

SharePlex 8.6
Administrator Guide

About Dell Software

Dell listens to customers and delivers worldwide innovative technology, business solutions and services they
trust and value. For more information, visit www.software.dell.com.

Contacting Dell Software

Technical Support:
Online Support
Product Questions and Sales:
(800) 306-9329
Contact Us:
http://software.dell.com/company/contact-us.aspx

Technical support resources

Technical support is available to customers who have purchased Dell software with a valid maintenance
contract and to customers who have trial versions. To access the Support Portal, go to
http://software.dell.com/support/.
The Support Portal provides self-help tools you can use to solve problems quickly and independently, 24 hours
a day, 365 days a year. In addition, the portal provides direct access to product support engineers through an
online Service Request system.
The site enables you to:
l Create, update, and manage Service Requests (cases)
l View Knowledge Base articles
l Obtain product notifications
l Download software. For trial software, go to Trial Downloads.
l View how-to videos
l Engage in community discussions
l Chat with a support engineer

SharePlex 8.6
Administrator Guide

1
Overview of SharePlex

SharePlex provides high-speed, log-based replication that supports a variety of topology configurations in
heterogeneous database environments. This chapter provides an overview of how SharePlex replication works.
It explains concepts surrounding SharePlex replication and provides an overview of SharePlex capabilities.
For more information about the platforms and databases that SharePlex supports, see the SharePlex
Release Notes.

Contents
About source and target data
About sp_cop
About sp_ctrl
About the SharePlex architecture
Understand the concept of synchronization
Strategies for information availability
Test before you deploy

About source and target data

SharePlex replication uses the concepts of source and target.
l The source data is the primary data that is to be replicated. This data resides on the source system.
l The target data is a full or subset copy of the primary data.This data resides on the target system. The
object of replication is to keep the source and target data synchronized, or in-sync. This means that the
state of the source data is reflected accurately by the target data, adjusting for any transformation that
is performed and for any time lag in the replication stream.
As changes are made to source data, SharePlex continuously replicates them to the target system. The target
data can take the form of any of the SharePlex-supported target types: tables in a database, messages in a JMS
queue, or XML or SQL records in a file that can be consumed by other software programs.
You can replicate data from one source to many targets in a direct or cascading configuration, and you can
replicate from many sources to one target.

SharePlex 8.6
Administrator Guide

About sp_cop
The sp_cop program coordinates the SharePlex replication processes: (Capture, Read, Export, Import, Post)
and the SharePlex queues, and it initiates all of the other background processes that perform specific tasks. It
also maintains communication with other systems in the replication network. In general, most SharePlex users
have little interaction with sp_cop other than to start and stop it. Once started, sp_cop runs in the
background.
l Only a SharePlex Administrator (member of the SharePlex admin group) can start or stop sp_cop.
l sp_cop must be started on all source and target systems involved in replication.
l Start sp_cop as soon as (or before) users access the data on the source system, so that all SharePlex
processes are ready to start processing transactions. That way, Capture can keep pace with the changes
that are made to the source data.
l If Capture loses pace with the rate at which source transactions are generated, the redo logs could
wrap before Capture is finished reading them. Log wrap is when the online Oracle redo logs reach their
maximum size and number and Oracle starts writing new logs over the existing ones. If SharePlex has
not captured all of the changes before the logs wrap, it reads the archive logs, but by then there could
be unacceptable latency between source and target data. In that case, it might be more practical to
resynchronize the data.
For more information about the replication processes, see About the SharePlex architecture.

About sp_ctrl
sp_ctrl
Use sp_ctrl to issue the commands that start, stop, configure, direct and monitor SharePlex activities. The sp_
ctrl program interacts internally with the sp_cnc (command and control) process, which is the child process of
sp_cop that executes the commands. Users do not interact with sp_cnc itself.

About the SharePlex architecture

This topic explains the basic components of SharePlex replication.
NOTE: This topic explains the default configuration of SharePlex. You can customize the SharePlex
configuration to add additional queues and processes for the purpose of isolating data streams or improving
performance.

SharePlex Directories
SharePlex uses two main directories:
The product directory: This is the SharePlex installation directory, where the SharePlex programs and
libraries are stored.

SharePlex 8.6
Administrator Guide

The variable-data directory: This is the SharePlex working directory, where the queue files, log files and other
components that comprise the current replication environment are stored.
NOTE: These directories are often referred to as productdir and vardir, respectively.
Do not remove, rename or edit any files or directories installed by SharePlex. Some directories contain hidden
files that are essential for replication. Some files appear empty but must exist under their original names
because they are referenced by one or more SharePlex processes. Some items in the directories are for use
only under the supervision of Dell Technical Support.
Utilities meant for general use in a production environment are documented in the published SharePlex
documentation. If you do not find documentation for a program in a SharePlex directory, do not attempt to run
it. Contact Dell Technical Support first.
The directory structure and files within the two main SharePlex directories differs slightly between the UNIX
and Windows platforms. Files and directories can vary from version to version of SharePlex, but the basic
structure appears as follows.

SharePlex product directory

SubContents
directory
bin

SharePlex executable files

data

Default parameter settings

install

(Unix and Linux only) Scripts related to installation, licensing and upgrades

lib

SharePlex shared libraries

util

SharePlex utilities

.appmodules

(Unix and Linux only) Hidden internal directory that contains raw executables. Do not use the
contents of this directory to launch processes.

.meta-inf

(Unix and Linux only) Hidden internal directory that contains meta information used during the
installation process.

SharePlex variable-data directory

SubContents
directory
config

Configuration files for this installation of SharePlex.

data

Status Database, configuration activation information, user-defined parameter settings, and other
user-defined files that direct replication activities.

Configuration internal database for each activation of a configuration file.

dump

Core files (if a process fails)

log

SharePlex log files

rim

Queue files (working data files)

save

Information about active and inactive configurations.

state

Information about the current state of SharePlex when a configuration is active, such as the
object and sequence caches.

SharePlex 8.6
Administrator Guide

SubContents
directory
temp

Used by the copy and append features and other SharePlex sync-related processes.

SharePlex Tables
Much of the replication process is controlled and tracked through a series of internal tables that are installed
into the source or target database during the installation of SharePlex. They are essential for SharePlex to
operate, so do not alter them in any way.
Table*

Description

DEMO_SRC

Used as the source table for the SharePlex demonstrations.

DEMO_DEST

Used as the target table for the SharePlex demonstrations.

SHAREPLEX_ACTID

Used by Capture to checkpoint its state.

SHAREPLEX_ACT_
MARKER

Not currently used.

SHAREPLEX_ANALYZE

Used by the analyze command.

SHAREPLEX_
CHANGE_OBJECT

Used by users to stop and resume replication for an object.

SHAREPLEX_
COMMAND

Used for the flush, abort and purge commands.

SHAREPLEX_CONFIG

Used by the activation and Capture processes to mark the start of a new activation.

SHAREPLEX_DATA

Used by the SharePlex wallet.

SHAREPLEX_
DATAEQUATOR

Used by the compare and repair commands and the Post process to synchronize their
operations.

SHAREPLEX_
DATAEQUATOR_
INSERT_TEMP

Used by the compare and repair commands.

SHAREPLEX_
DATAEQUATOR_
UPDATE_TEMP

Used by the compare and repair commands.

SHAREPLEX_
DATAEQUATOR_
DELETE_TEMP

Used by the compare and repair commands.

SHAREPLEX_DDL_
CONTROL

Used to refine control of DDL that is enabled for replication by the SP_OCT_
REPLICATE_ALL_DDL parameter.

SHAREPLEX_JOBS

Used by the sp_cnc process and the compare, repair, and copy commands to store
information about a job.

SHAREPLEX_JOB_
STATS

Used by the sp_cnc process and the compare, repair, and copy commands to store
information about a job.

SHAREPLEX_JOBS_
CONFIG

Used by the sp_cnc process and the compare, repair, and copy commands to disable
jobs.

SharePlex 8.6
Administrator Guide

Table*

Description

SHAREPLEX_LOB_
CACHE

Used by the Capture process when processing VARRAYs stored as LOB.

SHAREPLEX_LOBMAP

Used by the Capture process to map LOBIDs and rows when a table with LOB columns
does not have PK/UK logging enabled.

SHAREPLEX_LOGLIST

Used by the Capture process to track inactive RAC instances.

SHAREPLEX_MARKER

Used by the Read process when PK/UK logging is not enabled.

SHAREPLEX_OBJMAP

Used by the activation and Capture processes to define the objects in replication.

SHAREPLEX_
PARTITION

Used by users to define horizontal partitioning for a table in the replication

configuration.

SHAREPLEX_
PARTITION_CACHE

Used by the Capture process to map partition IDs to tables in replication.

SHAREPLEX_ROUTES

Used by the activation and Read processes to provide the target table name and
routing for every table in replication.

SHAREPLEX_SYNC_
MARKER

Used by the copy command and the Read and Post processes to sync their operations.

SHAREPLEX_TRANS

Used by the Post process to store checkpoints and to mark transactions that were
applied in a master-to-master configuration.

SHAREPLEX_
WILDCARD

Used by the activation and Capture processes to provide wildcard specifications by

which Capture determines whether a newly created table should be replicated.

* Additionally, SharePlex creates the SHAREPLEX_JOBID sequence for use by the sp_cnc process and the
compare, repair, and copy commands to provide a unique job ID.

SharePlex queues
Queues store the replicated data as it is transported from the source system to the target system. Queues are
part of a checkpoint recovery system that facilitates safe, asynchronous transport of data. Data travels through
the queues in the sequence in which it was generated.
Data is not read-released (deleted) from one queue until it is written to the next one. Data accumulates in the
queues on the source and target systems if the network, system, or database slows down or fails, or when a
replication process stops. When the problem or outage is resolved, SharePlex resumes processing from the
point where it stopped.
SharePlex replication uses the following queues:
l Capture Queue: The capture queue resides on the source system and stores captured data for further
processing by SharePlex. There is one capture queue for each data source that is being replicated. A
capture queue is identified by the datasource, for example o.oraA.
l Export Queue: The export queue resides on the source system. It holds data that has been processed by
SharePlex and is ready for transport to the target system. By default, there is one export queue on a
source system regardless of the number of active configurations or target systems. A default export
queue is identified by the name of the source system on which it resides, for example, SysA. You can
instruct SharePlex to create additional named export queues for more complex replication strategies.
See Configure named export queues.

SharePlex 8.6
Administrator Guide

l Post Queue: The post queue resides on the target system. It holds data that is ready for writing to the
target. On each target system, there is one post queue for the replication stream between a
datasource and its target. For example, if OraA and OraB are both replicating to OraC, there are two
post queues. A default post queue is identified by the name of the source system plus the datasource
and the target, for example SysA (o.oraA-o.oraB). You can instruct SharePlex to create additional
named post queues for more complex replication strategies. See Configure named post queues.
NOTE: All SharePlex queue files are created and maintained in the rim sub-directory of the SharePlex
variable-data directory.

SharePlex processes
SharePlex replicates data through a series of replication processes that are started by the main SharePlex
process, sp_cop.
l The Capture process: The Capture process reads the transaction logs or archive logs on the source
system for changes to objects that are configured for replication by SharePlex. The Capture process
writes the data to the capture queue, where it accumulates until the Read process is ready for it.
There is a separate Capture process for each datasource being replicated, each functioning
concurrently and independently. The Capture process is named sp_ocap (Oracle Capture).
l The Read process: The Read process operates on the source system to read data from the capture
queue and add routing information to the data. After processing the data, the Read process sends it to
the Export queue. The Read process is named sp_ordr (Oracle Reader).
l The Export process: The Export process operates on the source system to read data from the export
queue and send it across the network to the target system. By default, a source system has one Export
process for each of its target systems. For example, if there are two target systems, there are two
Export processes. Each Export process controls transmission of all data that is being replicated from a
source system to a target system. The Export process is the first part of the Export/Import transport
pair, which moves data between systems over a TCP/IP network. The Export process is named sp_xport.
l The Import process: The Import process is the second half of the Export/Import transport pair. It
operates on the target system to receive data and build a post queue. There is one Import process for
each Export process. For example, if there are two source systems (each with an Export process)
replicating data to a target system, there are two Import processes on the target. The Import process is
named sp_mport.
NOTE: It is possible to replicate data between Oracle instances on the same system. In this case
the Export and Import processes are not created. The Read process places data directly into a
post queue on that system.
l The Post process: The Post process operates on the target system to read the post queue and apply
the replicated operations to the target. There is a Post process for each post queue on a target system.
Multiple Post processes can operate simultaneously on a system. The Post process is sp_opst_mt when
configured to post to an Oracle database and sp_xpst when configured to post to a non-Oracle target.

SharePlex 8.6
Administrator Guide

All communication and movement of data by SharePlex is handled by an internal messaging and transport
system, using an asynchronous stream protocol with TCP/IP connections that is very efficient for large data
transfers. This method ensures optimal performance, reliability and restart capabilities, while conserving
communication bandwidth. SharePlex can replicate over any TCP/IP network, including WAN environments.
SharePlex processes recover from network failures. When the network is unavailable, data is queued on the
source system. SharePlex detects when the network is available again and resumes transmission.

How SharePlex replicates data

SharePlex reads the blocks of the redo logs and replicates transactional changes that are made to objects that
are specified in a configuration file. In the configuration file, you specify which data to replicate and the target
to which it is applied. When a configuration is activated. SharePlex replicates only the changes made to the
source data, providing a fast and reliable replication solution. For more information about configuration files,
see Create configuration files
From the information that it has about an operation, SharePlex creates one or more messages that are sent
from the Capture process to the Read process, and from the Read process to all of the other replication
processes in the replication stream. A message can reflect a SQL operation or an internal SharePlex operation,
but most of the time it is an INSERT, UPDATE, DELETE, COMMIT, TRUNCATE or a supported DDL operation.
Large operations like those on LONG or LOB columns can require more than one message because a message has
a size limitation. Other operations, such as array inserts of small records, have the inverse effect: There could
be one record for numerous operations. For example, an array insert of 70,000 rows might be accommodated
with only 700 messages, depending on the data.
In general, unless you are replicating numerous changes to LONGs and BLOBs, you can assume that the number
of messages shown in the status output for a process or queue approximately corresponds to the same number
of SQL operations.

SharePlex 8.6
Administrator Guide

The Post process reads messages from the post queue and applies the replicated data changes to the target. In
the case of a database target, Post constructs SQL statement to apply the data. In the case of non-database
targets, Post outputs data records in the format required by the target, for example a JMS queue.
The following explains the default ways that SharePlex builds SQL statements on the target system.
l If the change is an INSERT, SharePlex uses all of the columns in the row to build an INSERT statement.
l If the change is a DELETE, SharePlex uses only the key to build a WHERE clause to locate the correct
row. If a table lacks a key, SharePlex simulates one by using the values of all of the columns, except
LONG and LOB columns. You can specify columns to use as a key when you create the configuration file.
l If the change is an UPDATE, SharePlex uses the key plus the values of the changed columns to build a
WHERE clause to locate the correct row. Before applying changes to the database, the Post process
compares a pre-image of the values of the source columns to the existing values of the target columns.
The pre-image (also known as the before image) is the value of each changed column before the
UPDATE. If the pre-image and the existing target values match, confirming a synchronized state, Post
applies the changes. If not, then Post logs the operation to an error file and SharePlex returns an outof-sync error.
l If the change is an UPDATE or DELETE statement that affects multiple rows on the source machine,
SharePlex issues multiple statements on the target to complete the task. For example, an UPDATE
tableA set name = Lisa where rownum < 101 statement actually sends 100 UPDATE statements to
the target, even though only one statement was issued on the source.

Understand the concept of synchronization

The concept of synchronization applies mainly to table-to-table replication, where Post performs integrity
checks to make certain that only one row in the target matches the row change that is being replicated. It does
not apply to file, JMS, and change-history targets, which contain a record of every operation replicated by Post,
some of which may be identical over time. The Post process does not perform integrity checks on those targets.

Characteristics of synchronized tables

The basic characteristics of synchronized source and target tables are as follows (unless the transformation
feature is used).
l Corresponding columns in source and target tables have the same structure and datatypes.
l Data values in corresponding rows are identical.
l If a row exists in the source database, it exists in the target.
Ensuring data integrity is the responsibility of the Post process.
An out-of-sync condition occurs when:
l An INSERT is performed on the source data, but the row already exists in the target data when Post
attempts to apply the replicated INSERT. If Post attempts to insert a row that already exists in the
target table, based on the value of the key, it causes an error. The INSERT fails, and Post returns an outof-sync error.
l An UPDATE is performed on the source data, but one of the following occurs: the before image of the
source row (the values before the change) in the WHEREclause used by Post does not match the

SharePlex 8.6
Administrator Guide

current image of any row in the target (before the posting), or Post cannot locate the target row with a
key that matches the source key.
l A DELETEis performed on the source data, but Post cannot locate the target row by using the key. When
Post constructs its DELETE statement, it includes only the key value in its WHERE clause.

Hidden out-of-sync conditions

Post only verifies the integrity of the rows that are being changed by its current SQL operation. It does not
verify whether other rows in that table, or other tables, are out of synchronization in the target database.
Hidden out-of-sync conditions may not show up until much later, when a change is eventually made by
SharePlex to that data or a discrepancy is detected in the course of using that data.
Example of a detectable out-of-sync condition
Someone logs into the target and updates the COLOR column in the target table from blue to red in
Row1. Then, an application user on the source system makes the same change to the source table, and
SharePlex replicates it to the target. In the WHEREclause used by Post, the pre-image for the target
table is blue, but the current value in the target row is red. Post generates an out-of-sync error
alerting you to the out-of-sync condition.
Example of a hidden out-of-sync condition
Someone logs into the target and updates the COLOR column in the target table from blue to red in
Row2, but the change is not made to the source table and is not replicated. The two tables are now outof-sync, but there is no error message as in the previous example, because there is no Post involvement.
No matter how many subsequent updates are made to other columns in the row (SIZE, WEIGHT), the
hidden out-of-sync condition for the COLOR column persists (and users on the target have inaccurate
information) until someone updates the COLOR column in the source table. When that change is
replicated, Post compares the pre-images, and only then is there an error message.
The majority of time, the cause of out-of-sync data is not anything done wrong by replication, but rather DML
applied on the target, an incomplete backup restore, or some other hidden out-of-sync condition that can go
undetected a long time until an operation applied by Post finally affects that data and an error is returned.
Solving out-of-sync conditions can be time-consuming and disruptive to user activity. Once replication is
started, it is recommended that you:
l Prevent write access to the target tables, so that DML and DDL cannot be applied to them.
l Use the compare command to compare source and target data regularly to verify synchronization and
detect hidden out-of-sync conditions. For more information about the compare command, see the
SharePlex Reference Guide.

Strategies for information availability

Because SharePlex replicates over LAN and WAN connections, you can put a replica database to work as a
reliable, continuously updated alternate database that can be used in many different ways. The following
strategies enable you to get the right data to the people who need it, when they need it.

Reporting instances
Targets maintained by SharePlex are ideal for offloading report and query processing because they are
accessible while being kept up-to-date, and they can be optimized with keys and indexes designed for optimal

SharePlex 8.6
Administrator Guide

query performance. You can run reports all day long, without complaints about performance from your OLTP
users. Even during busy reporting times such as the end of the month or quarter, application response time will
be unaffected by heavy reporting. And, your organizations decision-makers will appreciate the accuracy of the
data reflected in the reports.

Broadcast and cascade

When many remote users access or use data stored in a primary database, you can move their processing to one
or more secondary databases that are kept current through SharePlex replication. That way, you can keep the
primary database and system optimized for transactions. SharePlex also can cascade ndata through an
intermediary system to remote systems, providing access for remote users who have no direct network
connection to the primary database.

Data warehousing
SharePlex can replicate from numerous source systems to one target system. It is ideal for consolidating data in
a data warehouse or a data mart so that information is available enterprise-wide for queries and reports. A high
degree of granularity in the data that you replicate and the option to transform replicated data to conform to a
different target structure are unique SharePlex features that enable you to populate your data warehouse
with the specific, timely information that users need to make good decisions.

High availability and disaster recovery

SharePlex can be used to maintain duplicate databases over local or wide-area networks. Production can move
to the alternate sites in an emergency or in a planned manner when routine maintenance is performed on the
primary server. SharePlex replication enables the secondary database to be used for queries and reporting.

SharePlex 8.6
Administrator Guide

Figure 1: SharePlex replication strategies at a glance

Test before you deploy

Before you implement SharePlex on production systems, Dell recommends performing tests in a mirror of the
production environment to ensure that you configured SharePlex properly to support your requirements.
Testing can uncover issues such as configuration errors and unexpected environmental issues, for example
network or resource issues that affect replication performance or availability.
Additionally, it is assumed that your organization has in place an infrastructure that supports the use of
enterprise applications such as SharePlex. These include, but are not limited to, the following:

SharePlex 8.6
Administrator Guide

l Availability and use of the database and SharePlex documentation

l Training programs for users
l Rollout and upgrade plans that ensure minimal interruption to business. When SharePlex is
implemented as part of an applications infrastructure, it is strongly recommended to test new
application functionality in conjunction with SharePlex in a non-production environment.
l Database or system maintenance procedures that consider SharePlex dependencies, such as the proper
shutdown of SharePlex processes and the preservation of unprocessed redo to accommodate system or
database maintenance.
l Sufficient security that prevent unauthorized persons from accessing SharePlex data records or making
configuration changes.
The SharePlex Professional Services team can help you prepare for, install, and deploy SharePlex in your
environment.

SharePlex 8.6
Administrator Guide

2
Run SharePlex

This chapter contains instructions for running SharePlex on UNIX, Linux, and Windows

Contents
Run SharePlex on Unix and Linux
Run SharePlex on Windows

Run SharePlex on Unix and Linux

On Unix and Linux systems, you start SharePlex by running the sp_cop program. After you activate a
configuration, sp_cop spawns the necessary child replication processes on the same system. Each instance of
sp_cop that you start is a parent to its own set of child replication processes. The sp_cop process must be
started on each system that is part of the replication configuration.
You can start sp_cop in one of two ways:
l From the operating system command line.
l At system startup as part of the startup file.
IMPORTANT: Run SharePlex from either the korn (ksh) or C shell (csh) shell.
l Do not use the Bourne shell (sh), because the way it handles background processes is not compatible
with SharePlex. If you must use the Bourne shell, switch shells to ksh or csh to run SharePlex, then exit
the shell and return to the Bourne shell.
l If using an Exceed X window emulator, switch from the default shell of POSIX to the ksh shell, then run
sp_cop from the ksh shell only.

Startup sequence on Unix and Linux

When you start systems that are involved in replication, start the components in this order:
1. Start the system.
2. Start the source and target databases.
3. Start SharePlex.
4. Start sp_ctrl.
5. Verify that the SharePlex processes are started by issuing the lstatus command in sp_ctrl.

SharePlex 8.6
Administrator Guide

sp_ctrl> lstatus
6. Allow users on the system.

Start SharePlex on Unix and Linux

To start SharePlex, you must log onto the system as a SharePlex Administrator. Your user name must be
assigned to the SharePlex admin group in the /etc/group file. For more information about user groups, see
Assign SharePlex users to security groups.
Table 1: SharePlex startup syntax
Method

Startup syntax

From root, with full path

$ /productdir/bin/sp_cop [-uidentifier] [-s] &

CDto the product directory

$ cd /productdir/bin
$ ./sp_cop [-u] [-s] &

From a startup script

#!/bin/ksh
cd productdir\bin
nohup sp_cop [-u] [-s] &

Table 2: Description of SharePlex startup syntax

Argument

Description

Causes SharePlex to run in the background.

nohup

Directs the startup of SharePlex to continue in the background after the current
user logs out.

-s

Starts sp_cop without starting the SharePlex replication processes (Capture,

Read, Export, Import, Post). Without -s, the replication processes start
automatically if there is an active configuration.
To start the replication processes after you start sp_cop with the -s option, use
the startup command. The startup command starts all processes at once.
Processes cannot be started individually after starting sp_cop with -s. Use the
stop command if you must stop individual processes. See the SharePlex
Reference Guide for more information about these commands.

-uidentifier

Starts sp_cop with a unique identifier. Use this option when there are multiple
instances of sp_cop running on a system, which is required for some SharePlex
configurations. See Run multiple instances of SharePlex.
Some suggestions for identifier are:
l the SharePlex port number (such as -u2100)
l the identifier of the database for which replication is running (such as uora12c)
l any descriptive identifier (such as -utest)

SharePlex 8.6
Administrator Guide

Identify SharePlex processes on Unix and Linux

Every session of sp_cop has a process ID number. The ID is returned after startup and then the command
prompt reappears. If a configuration was activated during a former session of sp_cop, replication begins
immediately. Without an active configuration, sp_cop runs passively in the background.

Stop SharePlex on Unix and Linux

To stop SharePlex, issue the shutdown command in sp_ctrl. This is a graceful shutdown that saves the state of
each process, performs a checkpoint to disk, read/releases buffered data, and removes child processes. Data in
the queues remains safely in place, ready for processing when sp_cop starts again. The shutdown process can
take some time if SharePlex is processing large operations.
You can use the force option with the shutdown command to forcefully shut down replication if necessary. It
terminates sp_cop immediately, bypassing normal shutdown procedures. See the SharePlex Reference Guide
for more information about this command.

Shutdown Considerations on Unix and Linux

You can safely shut down SharePlex for a short time while there is still transactional activity. The next time you
start SharePlex, replication resumes at the correct place in the redo logs or the archive logs, if needed.
However, the best practice is to leave SharePlex running while there is transactional activity. Otherwise,
SharePlex may need to process a large volume of redo backlog when you start it again, and there will be
latency between the source and target data.
If the redo logs wrap and the archive logs cannot be accessed, resynchronization of the source and target
data may be the only option. Take this possibility into account whenever you stop SharePlex while redo is still
being generated.
NOTE: If you want to shut down both SharePlex and the database, shut down SharePlex first. Otherwise,
SharePlex will interpret that the database is failing and generate a warning message.
As an alternative to stopping SharePlex, you can use the stop command in sp_ctrl to stop individual
SharePlex replication processes as needed. See the SharePlex Reference Guide for more information about
this command.

Run SharePlex on Windows

On Windows, SharePlex runs as a service named SharePlex port#, where port# is the port number that is used
by a particular instance of SharePlex. The service can be installed during the installation of SharePlex or at a
later time by running the SharePlex SpUtils progam. See the SharePlex Reference Guide for more information
about SpUtils.
NOTE: When directed in the documentation or other instructions to start or stop sp_cop on the Windows
platform, it means to start or stop the SharePlex service.

Startup Sequence on Windows

When you start systems that are involved in replication, start the components in this order:

SharePlex 8.6
Administrator Guide

1. Start the system.

2. Start the source and target databases.
3. Start the NuTCRACKER service in the Windows Administrative Tools control panel. This starts the MKS
Toolkit operating environment, which must be running in order to run SharePlex. See the SharePlex
Installation Guide for more information about the MKS Toolkit.
4. Start the SharePlex port# service. See Start and stop SharePlex on Windows
5. Start sp_ctrl from the bin sub-directory of the SharePlex product directory.
6. Verify that the SharePlex processes are started by issuing the lstatus command in sp_ctrl.
sp_ctrl> lstatus

Start and stop SharePlex on Windows

On Windows, the only way to start or stop SharePlex is by starting or stopping the SharePlex service. To control
the service, you can use the SpUtils utility or the Windows Administrative Tools control panel.
NOTE: Starting the SharePlex service automatically starts the SharePlex replication processes (Capture,
Read, Export, Import and Post). If you do not want those processes to start when the service starts, they
must be stopped with the stop command in sp_ctrl before you shut down the SharePlex service. They
will remain stopped until you issue the start command for each process that you want to start.

To control the SharePlex service with SpUtils

You can use SpUtils to install, start, stop, and check the status of the SharePlex service.
1. Log onto Windows as a SharePlex Administrator. Your user name must be assigned to the SharePlex
admin group. For more information, see Assign SharePlex users to security groups.
2. View the Windows services to make certain the NuTCRACKERservice is running. Start it, if needed.
3. Run the SpUtils utility from the desktop shortcut or the Programs menu.
4. Click the SharePlex Services tab of the utility.
5. Select the port number of the SharePlex instance that you want to control.
6. Do one of the following:
l Click Install to install the service. If Install is not shown, the service exists.
l Click Start to start the service. When Current State shows that the service is running, you can
close the utility. If Start is not shown, the service is either running already or not installed.
l Click Stop to stop the service. If Stop is not shown, the service is either stopped already or
not installed.
NOTE:You can also use the shutdown command in sp_ctrl to stop the SharePlex service.

To control the SharePlex service from Windows

The SharePlex service appears as an entry named SharePlex port# in the Services console of the
Administrative Tools control panel. Right-click the service name to start or stop the service.

SharePlex 8.6
Administrator Guide

Set SharePlex startup status on Windows

You can change the timing of SharePlex startup. By default, it is Automatic, meaning the service starts when
the system starts. You may need to contact a System Administrator to perform this task.
1. Open the Services console of the Administrative Tools control panel.
2. Right-click the SharePlex service name, then click Properties.
3. From the Startup type list, select the desired startup option. For assistance, click the Help link
in the dialog.

Set SharePlex process priority on Windows

IMPORTANT! Do not use the standard Windows Task Manager to set process priority for SharePlex.
On Windows systems, the NuTCRACKER operating environment controls the SharePlex processes. The SpUtils
utility has an option that enables you to run the Windows Task Manager with the required elevated
privileges to set the process priority. This procedure must be performed by a SharePlex Administrator.
Consult with the System Administrator to select an appropriate value based on the requirements of all
software running on the system.

To set SharePlex priority

1. Run SpUtils.
2. Select the TaskMgr tab.
3. Right click the SharePlex instance that you want to prioritize.
4. Select Set Priority, then select the desired priority level.

Identify SharePlex processes on Windows

In the Windows Task Manager, SharePlex appears as Sp_Copsrv.exe, representing the SharePlex sp_cop
process. The operating system controls the parent Sp_Copsrv.exe service. The parent Sp_Copsrv.exe process
spawns child Sp_Copsrv.exe processes one for each replication process (Capture, Read, Export, Import, Post,
sp_ctrl, and so forth.).
For a standard uni-directional configuration replicating through default queues to one target system, there are
following processes on a Windows system:
On the source system:
l One parent Sp_Copsrv.exe process.
l One Sp_Ocap (Capture) process plus one child Sp_Copsrv.exe process.
l One Sp_Ordr (Read) process plus one child Sp_Copsrv.exe process.
l One Sp_Xport (Export) process plus one child Sp_Copsrv.exe process.
l If there are any additional SharePlex processes running, such as sp_ctrl, there is an additional Sp_
Copsrv.exe process for each one.
On the target system:

SharePlex 8.6
Administrator Guide

l One parent Sp_Copsrv.exe process.

l One Sp_Mport (Import) process plus one child Sp_Copsrv.exe process.
l One Sp_Opst_Mt (Post) process plus one child Sp_Copsrv.exe process.
l If there are any additional SharePlex processes running, such as sp_ctrl, there is an additional Sp_
Copsrv.exe process for each one.
If there are no active replication configurations, the SharePlex processes do not start when you start the
service, and just the parent Sp_Copsrv.exe will be running.
To identify the parent Sp_Copsrv.exe process in the Windows Task Manager, look for the one that is using the
largest amount of memory. The child Sp_Copsrv.exe processes consume less memory than the parent process.
To identify which replication process is associated with a child Sp_Copsrv.exe process, look in the SharePlex
Event Log for the message stating when the replication process started. This entry provides the PID for that
process and the PID of the associated Sp_copsvr.exe process.

Shutdown Considerations on Windows

SharePlex 8.6
Administrator Guide

3
Run multiple instances of SharePlex

This chapter shows you how to configure and run multiple instances of SharePlex on one machine. For example,
when replication is configured from multiple source systems to a central target system, you can run multiple
instances of sp_cop to isolate the replication streams.

Contents
Run multiple instances of SharePlex from separate installations
Run multiple instances of SharePlex from one installation

Run multiple instances of SharePlex from

separate installations
IMPORTANT! This topic assumes that there is no active configuration. It assumes you are configuring multiple
instances of sp_cop as part of an initial setup of the replication environment.
This method provides a one-to-one relationship between the binaries and the variable-data directory. This
procedure creates autonomous SharePlex instances, with nothing in common between them. You start, control
and maintain each SharePlex instance separately, and there are no special setup requirements.
This method has the following benefits:
l Processes are easily isolated. You do not have to set environment variables to point to the correct port
and variable-data directory.
l You can upgrade or perform other maintenance one product directory at a time, or choose not to
perform those tasks.
l You can run the same or different versions of SharePlex on the same system.
The disadvantages are:
l You must install and upgrade each installation separately.
l More disk space is required to store the product files.
l In startup and shutdown scripts, and other places where you must map environment variables to
SharePlex components, you must map them for each installation.
To set up multiple instances of SharePlex in this configuration:
l Install each one separately. There should be one product directory and one variable-data directory per
installation.

SharePlex 8.6
Administrator Guide

l Install each one on a different TCP/IP port number.

l IMPORTANT! Make certain to create a different database account for each installation.
To install SharePlex, see the SharePlex Installation Guide.

Run multiple instances of SharePlex from

one installation
IMPORTANT! This topic assumes that there is no active configuration. It assumes you are configuring multiple
instances of sp_cop as part of an initial setup of the replication environment.
This method provides a one-to-many relationship between a set of binaries and two or more variable-data
directories. In this configuration, you create multiple variable-data directories and link each one to a unique
port number, each running a separate instance of sp_cop. This method has the following benefits:
l You install and upgrade only one installation of SharePlex. Maintenance procedures are performed for
only one installation.
l You conserve disk space, because you only store one set of SharePlex binaries and installed files.
l The customization of the SharePlex monitoring scripts (see Run monitor scripts on Unix) only need to be
done once, in one place.
l Startup and shutdown scripts only need to be created and run for one set of binaries.
The disadvantages are:
l Processes must be directed to each instance. You must set environment variables for each instance,
start sp_cop with the correct identifier for each instance, and set a port connection in sp_ctrl to ensure
that commands are directed to the correct instance.
l Upgrades apply to all instances of SharePlex.
l All sp_cop instances are the same version of SharePlex.

How to run multiple sp_cop instances on Unix and Linux

To run multiple instances SharePlex on the same Unix or Linux machine, you run multiple instances of the sp_
cop program, each running on a different port number. You link each sp_cop to a different variable-data
directory. Each variable-data directory is identified by the port number of its sp_cop. Connection information to
the source or target data store is linked to each sp_cop instance.

1. Assign port numbers

Assign each instance of sp_cop a unique port number.
l For each sp_cop instance, obtain one port number that will be used by that instance for both TCP and
UDP communication.
l For each sp_cop instance, use the same port number for the remote instances of sp_cop that will
process the same replication data stream as the instance you are configuring.
The sp_cop process listens on each system on TCP and UDP ports for communications from SharePlex processes
on other systems in the network, such as a command or exchange between the Export and Import processes. If

SharePlex 8.6
Administrator Guide

the ports are different, sp_cop on one system cannot connect to the sp_cop on another system to send or
receive messages.

2. Create variable-data directories

For each instance of sp_cop, create a variable-data directory, and assign each to one of the port numbers you
obtained. The variable-data directory contains the environment that is unique to a SharePlex instance.
1. Install SharePlex according to the instructions in the SharePlex Installation Guide. At the end of the
installation, you should have one product directory, one variable-data directory associated with a port
number, and one database account. This is your base instance of SharePlex.
2. Log in as a root user.
3. Shut down sp_cop if it is running.
4. Copy the original variable-data directory (with its sub-directories) to a new variable-data directory for
each instance of sp_cop that you want to run. Include the port number in each name, as shown in the
following examples.
cp -p -r /splex/vardir/splex2100 /splex/vardir/splex2101
cp -p -r /splex/vardir/splex2100 /splex/vardir/splex2102

3. Define the port numbers in the SharePlex environment

For each variable-data directory that you created, perform this procedure to set the port number that you
reserved for this instance of SharePlex.
1. Export the SP_SYS_VARDIR variable to point to one of the new variable-data directories, for example
splex2101 in the preceding example.
ksh shell:
export SP_SYS_VARDIR=/full_path_of_variable-data_directory
csh shell:
setenv SP_SYS_VARDIR /full_path_of_variable-data_directory
2. Export the SP_COP_TPORT and SP_COP_UPORT variables to point to the port number of the variabledata directory that you exported.
ksh shell:
export SP_COP_TPORT=port
export SP_COP_UPORT=port
csh shell:
setenv SP_COP_TPORT port
setenv SP_COP_UPORT port
3. Start sp_cop with the -u option, where port is the port number assigned to the exported variable-data
directory. (Leave no spaces between -u and the port number.)
$ /productdir/bin/sp_cop -uport&
4. Issue the following command to set the port number for the exported variable-data directory.
set param SP_COP_TPORT port

SharePlex 8.6
Administrator Guide

set param SP_COP_UPORT port

5. Shut down sp_cop.
6. In the rim sub-directory of the exported variable-data directory, delete the shstinfo.ipc and
shmaddr.loc files. (These files may not exist if sp_cop has never been started for this variable-data
directory.)
7. Repeat this procedure from step 1 for each additional variable-data directory.

4. Establish connections to the source or target data store

For each sp_cop instance, establish the connections that SharePlex will use to access the source or target data
of this SharePlex instance.
1. Export the SP_SYS_VARDIR variable to point to one of the new variable-data directories, for example
splex2101 in the example.
ksh shell:
export SP_SYS_VARDIR=/full_path_of_variable-data_directory
csh shell:
setenv SP_SYS_VARDIR /full_path_of_variable-data_directory
2. See the following:
Create a SharePlex account in an Oracle database
3. Repeat these steps for each variable-data directory.

5. Start sp_cop instances

You can now run separate instances of sp_cop and sp_ctrl as needed.
1. Export the SP_SYS_VARDIR environment variable to point to the variable-data directory of the first sp_
cop instance.
ksh shell:
export SP_SYS_VARDIR=/full_path_of_variable-data_directory
csh shell:
setenv SP_SYS_VARDIR /full_path_of_variable-data_directory
2. Start sp_cop with the -u option, where port is the port assigned to the sp_cop instance.
/splex/proddir/bin/sp_cop -u port &
3. In sp_ctrl, use the port command to set the session to the port number of the sp_cop instance you want
the commands to affect.
./sp_ctrl
port number
4. Repeat these steps for each instance of sp_cop that you want to run.
NOTE: If you receive an error message similar to the following, find out if someone else started a session of sp_
cop using the same port number and variable-data directory. If permissible, kill the processes associated with
that session, then start sp_cop again.
Error cleaning up previous shared memory segment ###.
Cannot delete because there are users attached.

SharePlex 8.6
Administrator Guide

Check if SharePlex processes are running and kill them if necessary.

How to run multiple sp_cop instances on Windows

To run multiple instances of SharePlex on the same Windows machine, you install and run a SharePlex service
for each instance, each with a different port number and variable-data directory.

1. Install the instances

1. Install SharePlex on the source and target systems according to the directions in the SharePlex
Installation Guide. This creates your initial instance of SharePlex.
2. Repeat the installation procedure for each SharePlex instance that you want to create, with the
following differences:
l Use the same product directory for each instance.
l Select or create a different variable-data directory for each instance.
l Select a different port number for each instance. The installation program locates available
ports, which you can override if necessary.
l When prompted for a license key, use the same license key for all instances. Make certain to
select the correct port each time.
l When you run database setup, use the correct port number for the instance, and use a different
name for each database account.

2. Start the SharePlex instances

All instances are controlled from the SpUtils utility.
1. Log onto Windows as a SharePlex Administrator (member of the spadmin group).
2. Run the SpUtils utility.
3. Select the SharePlex Services tab.
4. Select the port number for the instance of SharePlex that you want to start.
5. Under SharePlex Service Status, click Start. This starts the service for that instance.
6. When the Current State text box shows that the service has started, you can start another instance
of SharePlex.
7. Run Sp_Ctrl for the instance.
8. In Sp_Ctrl, use the port command to set the session to the port number of the sp_cop instance you
want the commands to affect.
sp_ctrl > port number

SharePlex 8.6
Administrator Guide

4
Execute commands in sp_ctrl

This chapter contains instructions for using the sp_ctrl command interface to execute commands that
configure, control, and monitor SharePlex. The sp_ctrl program resides in the bin sub-directory of the
SharePlex product directory.
NOTE: See the SharePlexReference Guide for more information about the commands shown in this topic.

Contents
How to run sp_ctrl
Define a default port for sp_ctrl
Define a default host for sp_ctrl

How to run sp_ctrl

You can run sp_ctrl on any machine where SharePlex is installed. The sp_cop program must be running in
order to run sp_ctrl; otherwise it displays an error message similar to this:
Your tcp port is not set properly or sp_cop is not running.

Start sp_ctrl
There are two ways to run sp_ctrl:
l from the command shell of the operating system to issue one command, for example:
$ /productdir/bin/sp_ctrl command [on host]
l by running the sp_ctrl command interface to issue one or more commands, for example:
$ /productdir/bin/sp_ctrl
sp_ctrl>command [on host]
where:
l productdir is the SharePlex product (installation) directory.
l command is the SharePlex command.
l onhost represents one of the command options that allow you to issue a command on the local
machine to control SharePlex on a remote machine (if supported by the command), as shown in the
following example.
$ /productdir/bin/sp_ctrl status on host:port

SharePlex 8.6
Administrator Guide

On Windows systems, you can run sp_ctrl from the Sp_Ctrl desktop shortcut or Windows Programs menu.
The sp_ctrl command line allows a total of 256 characters, including spaces.

Exit sp_ctrl
To exit the sp_ctrl command-line interface, issue the exit or quit command.
On Windows systems, you can simply close the sp_ctrl command prompt window.
The exit or quit command only closes the sp_ctrl session. It does not stop the SharePlex replication processes.

Define a default port for sp_ctrl

If there is only one instance of SharePlex on a system, sp_ctrl detects the port number. However, if you
configured more than one SharePlex instance on a system (where each one runs on a different port
number) you must use the port command to set the session of sp_ctrl to the instance for which you want
to issue commands.
sp_ctrl > port number
For more information about running multiple instances of SharePlex, see Run multiple instances of SharePlex.
For more information about the port command, see the SharePlexReference Guide.

Define a default host for sp_ctrl

To define a default machine for all interactive sp_ctrl sessions, use the host command. This command enables
you to enter a series of commands without using the onhost option for each one.
sp_ctr >hosthostname
The command changes the sp_ctrl prompt to include the host name:
sp_ctrl (sysA) >
The host setting applies only to the sp_ctrl session in which it is set.
To persist the host name, set the HOST variable. See Set SharePlex variables.

SharePlex 8.6
Administrator Guide

5
Prepare an Oracle environment for
replication

This chapter contains instructions for preparing an Oracle source or target database environment for
replication. The tasks outlined in this chapter must be performed before you perform initial synchronization to
start replication in your environment. Perform all tasks that apply to your data and to your replication
objectives.

Contents
Set up Oracle redo logging to support SharePlex
Set up Oracle database objects for replication
Set up an Oracle database to support SharePlex
Set up SharePlex to support Oracle data
Set up TDE Support

Set up Oracle redo logging to support

SharePlex
SharePlex captures from the online and archived Oracle redo logs. SharePlex supports redo logs and datafiles
that are stored on raw devices, on filesystem devices, and ASM instances.

Set the appropriate logging level

Minimal supplemental logging must be set before you activate the SharePlex replication configuration. In
addition, SharePlex recommends that both primary key and unique key supplemental logging be set, or that a
supplemental log group on unique columns be defined for every table in replication. When the key column
values for a row update are in the redo log, SharePlex does not have to fetch them from the database. On a
busy system, this greatly improves the performance of the Read process. Some SharePlex features require
primary key and unique key logging to be enabled.
ALTERTABLEDDL commands that change the rowid of a table can affect subsequent DML operations if the
primary or unique keys of the tables in replication are not being logged. When the keys are not logged,
SharePlex fetches their values based on the rowid. Any operation that changes the rowid, such as
ALTERTABLE...MOVE, can cause the wrong key values to be used for subsequent DML operations.
See Set up Oracle database objects for replication for more information about defining key values.

SharePlex 8.6
Administrator Guide

Ensure that the correct key is logged

When primary and unique key supplemental logging is enabled and a table does not have a primary key, Oracle
has to decide what type of unique key to log. If the table has multiple unique keys, Oracle determines the best
key to use and logs those column values for every UPDATE. If a table does not have any type of key, Oracle logs
all columns that are not a LONG or a LOB.
SharePlex must also identify a key to use to replicate data. Like Oracle, SharePlex chooses a key in this order:
l primary key if there is one
l the best (or only) unique key if there is one
l all the columns
If a table being replicated by SharePlex does not have a primary key, but does have multiple unique keys, it is
possible that the key columns that Oracle logs are not those that SharePlex requires.
See Set up Oracle database objects for replication for more information about defining key values.

Configure the archive logs

If the Capture process stops (or is stopped by a SharePlex user) while replication is active, Capture records its
location in the redo log and continues from that point when started again. If the redo logs wrap before Capture
starts again, Capture reads through the archive logs to locate the records it missed. If there is a long delay
before Capture starts again, Capture can lose pace with Oracle activity and there will be latency between the
source and target data.
To avoid Capture issues, configure archive logging to support faster and uninterrupted replication as follows:
Requirement

Description

Enable
archive
logging on
the source
system

Archive logging must be enabled on the source system. Otherwise, if the online logs wrap
before Capture is finished processing them, a resynchronization of the source and target data
will be necessary.

Time
compression
properly

Do not compress the archive logs until SharePlex is finished processing them. Otherwise,
SharePlex returns a "log wrap detected" message and will stop because it cannot process the
data. To determine the current log for SharePlex, issue the show capture command with the
detail option in sp_ctrl on the source system. You can compress any logs that were
generated before the current one.

Specify a
non-default
archive
location

If you are storing the archive logs in a location other than the Oracle default, set the SP_OCT_
ARCH_LOC parameter to the full path name of the directory where the archive logs are
located. If the redo logs wrap, SharePlex searches for the archive logs in Oracles archive log
list. If SharePlex does not find the archive log there, it searches the directory or directories
specified by the SP_OCT_ARCH_LOC parameter. To have Capture go directly to the SP_OCT_
ARCH_LOC location and skip the read of the Oracle log list, set the SP_OCT_CK_LOC_FIRST to
1.

Disable
archive
logging on
the target

You can disable archive logging on the target systems to eliminate unnecessary Oracle
activity on that system, except for high availability or peer-to-peer strategies.

Do not place

If the database uses ASM, the Oracle redo logs (online and archive) cannot be located under

SharePlex 8.6
Administrator Guide

Requirement

Description

logs at the
root ASM
location

the ASM root directory. SharePlex will not be able to read them at that location.

Read from
the archive
logs on
Exadata

Normally, SharePlex provides the least latency when reading from the online redo logs. On
Exadata, however, SharePlex can process higher volumes of data when reading from a
multiplexed archive location outside of the Exadata ASM file system. For more information,
see Tune Capture on Exadata.

NOTE: If Capture falls behind the pace at which Oracle generates redo volume, the following may apply:
l It might be more practical to resynchronize the data instead of waiting for SharePlex to restore parity
by capturing from the archive logs.
l It is possible to run out of disk space on the source system while Capture processes and queues the
operations that it missed.
l There is the potential for SharePlex to lose information needed for Post to construct SQL statements,
especially if the needed archive logs no longer are available. Always monitor disk space and latency
while SharePlex is running.

Set up Oracle database objects for

replication
This topic provides information about how to configure certain characteristics of Oracle database objects that
you will be replicating with SharePlex.

Ensure row uniqueness

SharePlex must have a way to ensure that the row it is changing on the target is the correct one that matches
the source row. This is accomplished by ensuring a one-to-one relationship through the use of keys and indexes.

Keys
SharePlex works fastest when there is a primary key or a unique key on all tables being replicated, especially
large tables and tables containing LONG columns. When choosing a key to use, SharePlex uses the best
available key column in the following order of priority.
l Primary key
l Unique key with the fewest columns, where at least one of the columns is NOT NULL
l Unique key with the fewest columns. If a key permits NULLs, SharePlex cannot ensure the uniqueness
of a row for UPDATEs and DELETES, so there is a possibility it could change the wrong row on the target
system. To control how SharePlex addresses keys that permit NULLs, set the SP_SYS_IN_SYNC
parameter. See the SharePlex Reference Guide for more information.
For best performance, it is recommended that you enable primary and unique key supplemental
logging. See Set the appropriate logging level for more information.

SharePlex 8.6
Administrator Guide

l If SharePlex cannot detect a key, it constructs a key using all of the columns except LONGs and LOBs.
This key is maintained internally and is not created on the table itself. This option is the least desirable
option, because the resultant WHERE clause causes Oracle to perform a full table scan on the target
table to find the row, and that significantly slows replication. Moreover, the use of a simulated key does
not always enforce uniqueness. For example, if there is a possibility that non-LONG columns in different
rows could contain identical values, but the LONG columns could have different values, the table can
be out of synchronization without being detected by you or SharePlex. The following example
illustrates the problem. The rows in the table are identical except for the LONG columns, and there is
no primary or unique key.
COLUMN A

COLUMN B COLUMN C (LONG)

100

200

300

Suppose a user on the source system changes Column A to 15 in the first row. When constructing the
SQL statement to apply the change to the target table, SharePlex constructs a key using Columns A
and B (UPDATE tablename SET Column A to 15 WHERE Column A = 10 and Column B = 20) to locate the
row to change. There are three rows that meet this criteria, so SharePlex could post the change to
the wrong row.

User-defined key
If a table does not have a primary or unique key, or if Oracle logs the wrong unique key for SharePlex, you can
specify columns for SharePlex to use as a key when you create the configuration file. This is known as a key
definition. The values in the specified columns should ensure uniqueness of the rows. When using a userdefined key:
l Create a supplemental log group for the table to specify the logging of those columns.
l Create an index on the target table and add the index to the SharePlex hints file, located in the
variable-data directory, which directs the Post process to use the index.
IMPORTANT! A user-defined key overrides any other key created for the table. This can be useful if you do not
want any of the existing keys to be used by SharePlex.
An alternative to a key definition is to create or use a unique index based on one or more columns that
establish uniqueness.

Changes to key values

SharePlex handles changes to the value of a key column without any special settings. However, if sequences
are used for keys and if there is a possibility that those values will be updated, create the sequences so that
the updates cannot result in a duplication of keys on the target system. Otherwise, if a new value is used to
apply an operation, and that value already exists as a key in another row in the target table, SharePlex will
return unique-key constraint violations and out-of-sync errors.
This type of error can happen when you update values using an x +n formula, where n is an incremental
increase. It is possible for one of the x +n values to equal an existing value. The following is an example,
where the values in the key column are increased by 1:
Key_Col
1
4

SharePlex 8.6
Administrator Guide

5
7
SQL> update table X set a=a+1; commit
The new values become the following, and they are replicated to the target system:
Key_Col
2
5
6
8
SharePlex performs the update in the order that the operations enter the redo log:
update x set a=2 where a=1; (Succeeds)
update x set a=5 where a=4; (Fails because a value of 5 already exists.)
update x set a=6 where a=5; (Succeeds)
update x set a=8 where a=7; (Succeeds)
The pre-image value that Post uses for the target sequence is the same as the increased value replicated from
the source. Oracle rejects the operation as a unique constraint violation. Another example would be a
transaction that updates A to B and then updates B to C.
IMPORTANT! If you plan to use peer-to-peer replication, see additional requirements for keys in Configure
replication to maintain multiple peer databases.

Indexes
The correct use of indexes is important in a replication environment. An index maintains the integrity of the
target data.
l When replicating a source table that has a unique index, the target table also should have a
unique index.
l All large tables should have a unique index on the target system. If there is no unique index, Oracle
scans the entire table in order to locate the rows to be changed by Post.
l Some applications do not use primary key constraints, and therefore a unique index is not created by
default. Often, however, there will be an index that was created, but not named, as a unique index
(not using CREATE UNIQUE INDEX command), although it was created on one or more columns populated
with unique values, such as a persons name and employee identification number. If no unique index
exists for a table, it is recommended that you create one or specify a user-defined key when you create
the configuration file. See Define a unique key for more information.
l Once you have identified or created a unique index, you can ensure that Oracle uses it by employing
the hints feature of SharePlex. See Use Oracle INDEX hints.
l Keep your indexes up-to-date, or it can slow the Post process. Rebuild the ones that are fragmented.
If there are too many indexes on a target table, Oracle must update them all as rows are added and deleted.
This slows the entire system, including replication. Consider limiting the number of indexes to the ones that
have the most utility.

SharePlex 8.6
Administrator Guide

l For applications that perform mostly one type of DML, consider the following:
l INSERTs: Use just a few indexes, to limit their maintenance.
l UPDATEs: Use an index on a column that does not change after an INSERT statement.
l DELETEs: Remove as many indexes as you can.
l If you run large batch jobs that do millions of SQL operations, remove unnecessary indexes before the
batch job, then rebuild them at the end. This makes SharePlex run faster, and you will have more
organized indexes afterward.
l If tables have foreign keys, make sure the appropriate columns are indexed so that modifications to the
foreign keys do not cause full table scans.

Bitmap indexes
For performance purposes, avoid the use of bitmap indexes while the Post process is applying the data. These
indexes can adversely affect the performance of the Post process.
If you must use bitmap indexes on target tables, weigh their benefit for queries against the their impact on the
transactions applied by Post:
l When Oracle adds, updates or deletes a bitmap entry, it effectively locks all the rows associated with
the bitmap segment.
l A bitmap segment can contain references to hundreds of rows. As a result, changes made by different
Post sessions (there is a Post session for every session on the source system) can block each other if their
work updates bitmap entries in the same bitmap segment.
l To proceed, Post must detect and resolve the blocking, which delays posting significantly if the number
of locks is high.
l In general, frequent inserts by multiple concurrent sessions into a table with bitmap indexes will incur
lock conflicts, but random update and delete activity on such a table will not. SharePlex follows the
Oracle recommendation to have a bitmap index on a more static table.
NOTE: Replicating bitmap indexes is not recommended. Every time you change a table with a bitmap
index, the index is rebuilt. This associated cost (Oracle time and resources) to rebuild is added to your
SQL UPDATE statement.

Prevent triggers from firing on the target

DML changes resulting from a trigger firing on the source system enter the redo log and, therefore, are
replicated and posted to the target database by SharePlex. Consequently, if the same trigger fires on the
target system and initiates the same DML changes (which already were made through replication) there will be
out-of-sync errors.
For example, if an INSERT to TableA on the source system triggers an INSERT into TableB, SharePlex replicates
both INSERTs to the target system. The Post process applies the first INSERT to TableA on the target system,
triggering an INSERT into TableB. Thus, when Post attempts to post the replicated INSERT to TableB, there will
be a unique-key violation. The row already exists because the trigger fired for TableA.
Triggers can be handled as follows, depending on your replication strategy:

SharePlex 8.6
Administrator Guide

Replication strategy

How to handle triggers on the target

High availability

1. Enable triggers for users other than SharePlex, either

in preparation for failover or because transactions are
performed on multiple source systems.

and
Peer-to-peer

Reporting, data sharing, other basic oneway replication

2. Disable triggers for the SharePlex user by running the

sp_add_trigger.sql script. This script puts a WHEN
clause into each triggers procedural statement that
tells it to ignore operations posted by the SharePlex
user.
Either disable triggers entirely on the target system or run the
sp_add_trigger.sql script to ignore operations posted by the
SharePlex user.

For important information about how to use the trigger scripts, see the SharePlex Reference Guide.

Configure integrity constraints

Integrity constraints have a effect on replication. Follow these guidelines to ensure that they are handled.

Foreign key constraints

Tables with foreign keys to one another must all be included in the replication configuration for accurate
replication. All tables with referential constraints must exist in the target database. If you leave one or more
out, the referential integrity could become corrupted.
NOTE: If constraints are DEFERRED on the target tables, the Post transaction can fail on the constraint
validation. To work around this problem, enable the SP_OPO_DISABLE_OBJNUM parameter to allow the
transaction to succeed. The underlying target table still remains out-of-sync until it is resynchronized.

ONDELETECASCADE constraints
SharePlex allows ONDELETECASCADE constraints to remain enabled on the target tables. Post detects the
ONDELETECASCADEdependencies and suppresses the posting of any replicated cascaded deletes to the
child tables.

To enable ONDELETECASCADE support

l Enable the logging of primary keys, unique index columns, and foreign key columns on the source.
l Set the following SharePlex parameters:
l SP_OPO_DEPENDENCY_CHECK parameter to 2
l SP_OCT_REDUCED_KEY parameter to 0
l SP_OPO_REDUCED_KEY parameter to 1 or 2 (recommended for optimal Post performance)
ONDELETECASCADE support is currently available for Oracle.

SharePlex 8.6
Administrator Guide

Check constraints
Disable check constraints on the target system. They add unnecessary overhead. These checks are
redundant in a well maintained, synchronized replication environment because they are satisfied on the
source system. For high-availability purposes, you can build a script that re-enables the constraints as part
of the failover procedure.

Prevent access to target objects

In all scenarios except peer-to-peer replication, the SharePlex database user must be the only user allowed to
perform DML or DDL on the target objects. If DML or DDL changes are made to target objects by other
individuals, jobs or applications, the target data may no longer reflect the state of the data on the source
system. See Understand the concept of synchronization for more information.

Ensure compatible source-target mapping

The following guidelines help you ensure that the source and target objects that you want to map in a
replication configuration are compatible.
l For most replication strategies, the name and/or owner of a source object can be different from that of
its target object. SharePlex replicates to the correct object because you specify it by owner and name
within the configuration file. For high-availability configurations, the owner and name of a source table
should be the same as the owner and name of the target table.
l Corresponding source and target columns must contain compatible datatypes (same type, size,
precision).
l Corresponding source and target rows must contain the same values unless transformation is being
used. See Transform data for more information. See Set up Oracle database objects for replication
l The names of the target columns must be identical to the names of the source columns, unless you use
column mapping in the configuration file. See Create configuration files for more information about
column mapping.
l A target table can have more columns than the source table. If the source and related target
column names are identical, SharePlex will ignore the extra columns in the target table. If the
source and target column names are not identical, SharePlex maps a one-to-one relationship in the
order that the columns are defined in each table (for example, map the first column in the source to
the first column in the target, map the second column to the second column, and so forth). If this is
not the mapping you want, you must use column mapping. See Create configuration files for more
information. To avoid Oracle errors if the extra (non-mapped) columns are NOT NULL, define default
values for those columns.
l A target table cannot have fewer columns than the number of columns in the source table, unless you
use vertically partitioned replication to replicate a subset of the source columns that matches, or has
fewer columns than, the target. See Configure vertically partitioned replication.

Configure sequences
SharePlex replicates changes to Oracle sequences that are made in an ALTER SEQUENCE and DROP SEQUENCE
commands and during DML transactions. It may not be necessary to replicate sequences in certain replication
strategies:

SharePlex 8.6
Administrator Guide

Replication strategy

Replicate
Sequences?

Notes

High availability

Yes

The way that SharePlex replicates sequences

allows users to begin using the failover
database immediately without worrying about
incrementing the sequences or reusing one.

Reporting, data sharing, other basic oneway replication

If sequences are unnecessary on the target

system, do not replicate them. It can slow
down replication. Even if a sequence is used to
generate keys in a source table, the sequence
values are part of the key columns when the
replicated rows are inserted on the target
system. The sequence itself does not have to
be replicated.

Peer-to-peer

SharePlex does not support peer-to-peer

replication of identical sequences. See
Configure replication to maintain multiple
peer databases for important instructions
concerning sequences in peer-to-peer
replication.

To configure sequences for replication

l Use caching and set the cache to increments of at least 20. When sequences are cached, SharePlex can
replicate the values as a group. When sequences are not cached, SharePlex must go to disk every time
a value is obtained from the sequence, which slows replication of more critical data.
l Specify sequences in the configuration by owner and name, as you would a table. See Create
configuration files.
l To ensure the uniqueness of sequences on the target system, the start value of the target sequence
must be larger than the start value of the source sequence. Use the following formula to determine the
target START_WITH value:
source_current_value+ (source_INCREMENT_BY_value x source_CACHE_value) =target_START_
WITH_value
IMPORTANT! (source_INCREMENT_BY_value x source_CACHE_value) should not exceed 2 GB, or
replication of sequences will fail.
SharePlex uses the ALTER SEQUENCE command to update sequences in a target database as follows:
l Change the increment value to:
source_INCREMENT_BY_valuexsource_CACHE_value
l Set to NOCACHE.
l UPDATE the sequence(s).
l ALTER the sequence(s) again by setting the following values:
Increment_value=source_INCREMENT_BY_value
Cache_value=source_CACHE_value
SharePlex treats ALTER SEQUENCE operations like a simple SELECT (UPDATE) to a sequence because the redo
log records make no distinctions between the two operations.

SharePlex 8.6
Administrator Guide

Create objects and partitions

Objects specified in the configuration file for replication must exist in the source instance before you activate
the configuration, unless they satisfy a wildcard definition and you are replicating DDL. If you are configuring
SharePlex to replicate supported DDL, the supported changes can be made to source objects while a
configuration is active.
If a table will be partitioned, create those partitions before you activate a configuration to begin replication
processing. Partitioning a table while it is actively replicating causes SharePlex to lose the identifying
information it has compiled, and DML from that table partition will not be replicated. You can add a partition to
a table already in replication, but you will need to reactivate the configuration to update that table in the
SharePlex object cache.

Set up an Oracle database to support

SharePlex
Certain Oracle database settings have an affect on replication and must be set appropriately.

Adjust OPEN_CURSORS to support Post cursors

SharePlex requires the value of the Oracle OPEN_CURSORS parameter to be set correctly. To view the OPEN_
CURSORS value, query the database using the following SQL statement:
select value from V$PARAMETER where name = 'open_cursors';
The Post process reserves 10 cursors for routine calls that are closed once they finish, plus a minimum of 2
cursors per transaction (or more if the SQL Cache option is enabled).
To determine the correct setting for OPEN_CURSORS, do one of the following:
If SQL Cache is enabled: To view the status of SQL Cache, issue the list param post command in sp_ctrl and
view the SP_OPO_SQL_CACHE_DISABLE parameter. A value of 0 means it is on, and a value of 1 means it is off.
If SQL Cache is not enabled: Estimate the peak number of concurrent updating transactions (sessions) that
your applications generate, and follow this formula:
10 + (peak number of concurrent transactions x 2) = minimum open cursors needed
The OPEN_CURSORS value can be modified or added if absent. Consult the Oracle documentation prior to
making changes to Oracle parameters.

Adjust the PROCESSES parameter to support

connections
The PROCESSES parameter in the init.ora file must be set to accommodate connections created by SharePlex
and the database users. Its value depends on whether a database is a source database, a target database, or
one that serves as both a source and target database.

Database is a source only

If a database serves only as a source, the following formula takes into account logins made by the Read process.

SharePlex 8.6
Administrator Guide

(peak number of source database sessions) + (background Oracle processes) + (value of SP_ORD_LDA_ARRAY_
SIZE parameter +3) = setting for PROCESSES

Database is a target only

The Post process creates as many connections on the target system as there are sessions on the source system
in order to maintain transaction consistency. The PROCESSES parameter on the target system must be set high
enough to accommodate all of those connections, plus:
l The background Oracle processes those connections generate
l The peak number of users expected to access the target database for queries
Use the following formula as a guide:
(peak number of source database sessions) + (peak number of target database sessions) + (background Oracle
processes) = setting for PROCESSES

Database is a source and target

If a database serves as both a source and a target, the following formula takes into account
connections made by:
l The Read process
l The Post process
l Background Oracle processes
l User connections
(peak number of source database sessions) + (peak number of target database sessions) + (background Oracle
processes) + (value of SP_ORD_LDA_ARRAY_SIZE parameter +3) = setting for PROCESSES

Adjust the log buffer size to improve posting

The number of database writers has an impact on replication, especially when there are numerous concurrent
transactions. Whenever a transaction is committed, its buffered data is flushed to disk. If most transactions are
small, but the buffer is large, this can cause slow posting. When a large transaction is committed while
another, more normal-sized transaction is committed, the second COMMIT must wait while the entire buffer is
flushed to disk.
Reducing the size of the buffer that is flushed to disk can speed the Post process. Try decreasing the size of the
log buffer to 1024 KB, or even 512 KB if possible.

Adjust the SharePlex transaction table based on

user volume
SharePlex updates the SHAREPLEX_TRANS table to maintain read consistency for the target database. You
might need to adjust the initrans setting of this table to improve replication performance and reduce
contention on that table:
l If the production database has between 500 and 1,000 concurrent users, rebuild the SHAREPLEX_TRANS
table to have an initrans of 30.

SharePlex 8.6
Administrator Guide

l If the production database has more than 1,000 concurrent users, rebuild the SHAREPLEX_TRANS table
to have an initrans value of 40.

Control conversion of character sets

For SharePlex to replicate all characters within the Oracle character sets that you are using, one of the
following must be true:
l The character sets are identical on the source and target
l The character set of the source database is a subset of the character set of the target database (all
characters contained on the source exist in the character set of the target)
The following character sets are tested and supported for SharePlex:
US7ASCII
UTF8
WE8ISO8859P1
AL16UTF16
AL32UTF8
KO16KSC5601
SharePlex allows an Oracle target database to perform character conversion. Post notifies Oracle of the
character encoding of the source data and Oracle performs any required conversion.
Depending on the character sets involved, the Oracle conversion might lead to data loss. For example:
Example 1: The Japanese character for 'rice' in the JA16SJIS character set has no corresponding symbol in the
US7ASCII character set. If you attempt to replicate this symbol into a US7ASCII database, Oracle converts it to a
'?' character.
Example 2: According to Oracle, the WE8ISO8859P1 character set is a superset of the US7ASCII character set, so
it is logical to assume that any character in US7ASCII is posted unconverted into a WE8ISO8859P1 target
database. This is true for characters in the range 0x00 to 0x7F. However, Oracle strips off the top bit of
characters in the range 0x80 to 0xFF. This "conversion" may result in data loss while replicating to a character
set that is a superset of the source.
NOTE: Oracle does not convert characters if the character sets are identical. Thus, posting
WE8ISO8859P1 data to a database with a character set of WE8ISO8859P1 bypasses the Oracle
conversion process.

To control character set conversion

By default SharePlex allows Oracle to perform character set conversion. The parameter that controls this
behavior is SP_OPO_NLS_CONVERSION. To prevent Oracle from performing the conversion, set this parameter to
0. The data will be posted as-is. For more information, see the SharePlex SharePlex Reference Guide.
NOTE: SharePlex will always convert NVARCHAR and NCLOB data if the NLS_NCHAR_CHARACTERSET of
the source database is not the same as that of the target database.

SharePlex 8.6
Administrator Guide

Set up SharePlex to support Oracle data

This topic contains setup guidelines that apply to specific Oracle datatypes. These guidelines should be
addressed before you start replication for the first time.

LOBs, LONGs, VARRAYs, and XML

l Tables that contain a LOB or LONG should have a primary key or unique key defined on them. If a table
does not have a key, SharePlex builds its own key from all of the columns except LONGs or LOBs. If a LOB
or LONG is the only difference between two rows that otherwise satisfy the Post WHERE clause, then
Post may update the wrong row.
l Dedicate one or more named export queues to tables that contain LOBs. This automatically creates
separate Export processes and named post queues with their own Post processes. By separating the
processing of LOB datatypes from that of other data, you can improve the overall speed of replication.
See Configure named export queues.
l

To ensure that SharePlex has enough shared memory when replicating LOBs, increase the SP_QUE_
POST_SHMSIZE parameter to an initial setting of 60 MB. If SharePlex generates shared memory segment
errors such as "Error: sp_cop process sp_mport/sp_opst_mt killed due to SIGSEGV,"
increase the setting. NOTE: A larger shared memory segment can result in a large amount of swap
space being used on the system, so make sure enough disk space is available.

l If the database is using the cost-based optimizer (CBO) and there are large numbers of LOBs in the
tables that you are replicating, incorporate the SHAREPLEX_LOBMAP table into the analysis schedule.
This table is updated frequently and must be analyzed frequently so that its indexes remain efficient.

Tune SharePlex based on Oracle data volume

For best performance when transaction volume is either very high or very low, certain parameter changes are
recommended before replication starts.
To determine the correct values, refer to the following table under the column that corresponds to the daily
archive log volume of your database.
NOTE: For environments generating between 5 GB and 15 GB of archive log volume daily, the default settings
for SharePlex parameters are sufficient, and no action is needed.
To change the parameters, use the set param command in sp_ctrl. Contact Dell Technical Support if you
need assistance. For more information about SharePlex parameters and commands, see the SharePlex
Reference Guide.

Recommended settings per archive volume

Parameter

Less than
5GB/day

Between 5GB
and 15GB/day

Greater than
15GB/day

Where to set the parameter

SP_OCT_CHECKPOINT_
FREQ

500

Default

5000

source system

SP_ORD_CDA_LIMIT

Default

source system

SP_ORD_DELAY_

Default

500

source system

SharePlex 8.6
Administrator Guide

Parameter

Less than
5GB/day

Between 5GB
and 15GB/day

Greater than
15GB/day

Where to set the parameter

SP_ORD_LDA_ARRAY_
SIZE

Default

source system

SP_ORD_RMSG_LIMIT

Default

2000

source system

SP_IMP_WCMT_
MSGCNT

100

Default

2500

target system

SP_COP_IDLETIME

120

Default

600

source and target systems

RECORDS

Set system process priority

If Oracle or other processes are assigned resource priority, SharePlex can be left with a default setting and
little resource allocation. Oracle increases its CPU utilization during peak processing. If SharePlex loses pace
with Oracle, you can try increasing its process priority.

To set process priority on Unix

Use the nice command. Consult with the System Administrator to select an appropriate value based on the
requirements of all software running on the system. A root user can modify the niceness value of any process.
The SharePlex Administrator user can adjust the niceness value of SharePlex.

To set process priority on Windows

1. Run SpUtils.
2. Select the TaskMgr tab.
3. Right click the SharePlex instance that you want to prioritize.
4. Select Set Priority, then select the desired priority level.

Enable Oracle direct path loads

By default SharePlex replicates changes made to tables through a SQL*Loader direct-path load
(DIRECT=TRUE keyword parameter). There can be only one load per table (PARALLEL=FALSE), although there
can be simultaneous loads on different tables. The database must be in archive mode, and table logging
must be enabled.
If you expect the direct-path load to be sustained for a long time on the source system, it might be more
efficient to load the data to the target database directly, instead of relying on replication. A large direct-path
load can cause Capture to lose pace with changes that enter the redo logs from user application activity.
After the load, you should disable check constraints. You can leave ONDELETECASCADE constraints enabled.
The SP_OCT_REPLICATE_DLOAD parameter controls whether or not direct-path loads are replicated. To disable
replication of direct-path loads, change this parameter to 0. For more information, see the SharePlex
Reference Guide.

SharePlex 8.6
Administrator Guide

Enable capture on Exadata machines

To capture data from an Exadata system, the SP_OCT_USE_OCI parameter must be set to 1. For more
information, see the parameter documentation in the SharePlex ReferenceGuide.
If you need to adjust capture performance after replication starts, see Tune Capture on Exadata.

Set up TDE Support

SharePlex uses the TDE Master Encryption Key to decrypt TDE-protected data that must be replicated.
SharePlex uses the Oracle wallet password to access the TDE Master Encryption Key.
If the wallet opens successfully, Capture connects to the decryption module and processes the data. If the
wallet does not open, Capture remains in the initialization state until either the wallet is opened or the
process is stopped. The initialization state that is displayed in the show capture command is "Capture state:
Waiting for open wallet."
NOTE: The SharePlex copy/append command does not support TDE. For full information on the Oracle features
that SharePlex supports, see the SharePlex Release Notes.

Required privilege to capture TDE-protected data

To decrypt TDE-protected data from the redo log, the SharePlex Administrator must open Oracle Wallet using
the wallet password. By default, only the Oracle Wallet owner-user has read and write permissions for this file.
You can either start as the owner of the wallet, or you can grant read permission to the file to the dba group,
because the SharePlex Administrator user is a member of that group.

Configure SharePlex to capture TDE-protected data

To configure SharePlex to support TDE-protected data, two setup tools must be run:
l (If this was not done during installation) Run Oracle Setup. When prompted to enable TDE replication,
type "y" and then enter the fully qualified path to the TDE wallet file, including the wallet file name,
when prompted. See Create a SharePlex account in an Oracle database for more information.
l Run the sp_wallet utility to provide the Oracle Wallet password to SharePlex.

To run sp_wallet
1. On the source system, start SharePlex from the SharePlex product directory. You are prompted to
run sp_wallet.
*** To enable TDE replication, run sp_wallet and provide the wallet
password ***
2. Run sp_wallet.
./sp_wallet
wallet password: walletpw
Wallet loaded into SharePlex

SharePlex 8.6
Administrator Guide

To change the TDE master encryption key

If you need to change the TDE Master Encryption Key while a SharePlex configuration is active, take the
following steps to ensure that SharePlex continues to replicate the TDE-protected data after the changes.
1. Quiesce the source database.
2. Make sure that Capture finishes processing the remaining data in the redo log.
3. Shut down SharePlex.
4. Change the TDE Master Encryption Key.
5. Restart SharePlex.
6. Run the sp_wallet utility to provide SharePlex with the new TDE Master Encryption Key.
./sp_wallet

SharePlex 8.6
Administrator Guide

6
Create configuration files

This chapter contains the information that you need to know in order to create a configuration file.
SharePlex takes direction from the configuration file to determine which tables to replicate and where to
send the replicated data. This file also provides any special processing instructions, such as column mapping
and data filtering.

Contents
How to create a configuration file
Database specifications in a configuration file
Target specifications in a configuration file
Routing specifications in a configuration file
Configuration examples by datasource and target
Use a script to build a configuration file
Replicate to, or from, a PDB
Use Wildcards to specify multiple objects
Define a unique key
Filter DML Operations
Map source and target columns
Build a configuration file using a script

How to create a configuration file

To configure SharePlex to replicate data, you create a configuration file. This is an ASCII text file in which
you specify:
l The data that you want SharePlex to replicate, including any filtering or partitioning of rows or columns
l The target name and type
l The system (and database if applicable) to which the data must be delivered.
Only a SharePlex Administrator or operator has the authority to create a configuration file.
When your configuration file is completed and the SharePlex environment is set up to support your replication
objectives, you activate the configuration with the activate config command to begin replication.
Additional information:

SharePlex 8.6
Administrator Guide

l See Activate replication in an Oracle production environment for more information about the timing and
process for activating a configuration file.
l See the SharePlex Reference Guide for more information about the activate config command.

Create a configuration file

You can create a configuration file by hand or, if your data structure supports it, you can automate the creation
of a configuration file. For more information, see Build a configuration file using a script.
Create the configuration file on the system from which data is to be replicated, typically the source system,
but strategies such as active-active replication require configuration files on more than one system.

To create a configuration file

1. Run sp_ctrl from the bin sub-directory of the SharePlex product directory.
2. In sp_ctrl, issue the create config command.
sp_ctrl> create config config_name
This command opens a file in the default text editor that is set for the operating system. NOTE: You can
change the default editor that sp_ctrl uses. See Set a default editor for sp_ctrl.
3. Complete the configuration file as shown in Structure of a configuration file.
IMPORTANT! All configurations must reside in the config sub-directory of the SharePlex variable-data
directory. Configuration files outside this directory cannot be activated. SharePlex places configurations
in this directory by default when you create them through the sp_ctrl interface with the create config
command. If you create the configuration directly through a text editor, make certain to save it to the
config sub-directory.

Structure of a configuration file

A basic configuration file looks like the following:
# comment: basic SharePlex configuration file
Datasource:o.SID

#source specification

target specification

routing map

source_owner.object1

target_owner.object1

routing_map

source_owner.object2

target_owner.object2

routing_map

source_owner.object3

target_owner.object3

routing_map

The basic components of a configuration file are as follows. See Additional configuration options for additional
configuration options.
Component

Description

Syntax examples

# Comments

Lines that describe the file or provide other

information about the contents to viewers, but
are not used by SharePlex. Precede each

# This is a comment.

SharePlex 8.6
Administrator Guide

Component

Description

Syntax examples

comment line with a pound (#) sign. Comments

may be entered anywhere in the configuration
file.
Datasource
specification

Syntax that specifies the source database. This

component must always be the first noncommented line of a configuration file. It has the
following syntax elements, all on the same line
with no spaces:

Datasource:o.SID

l The keyword Datasource followed by a

colon (:). The word "Datasource" is not
case-sensitive.
l The database specification. See Database
specifications in a configuration file.
Source
specification

The fully qualified name of a supported Oracle

source object, in the form of owner.object, or a
wildcard substitution that specifies multiple
source objects.

src_owner.table
src_owner.sequence

See Use Wildcards to specify multiple objects for

more information about using wildcards.
Target specification

The target to which the replicated data is

applied. Targets supported by SharePlex are:
l A table in a relational database, or a
wildcard substitution for multiple tables.
l An Oracle sequence (or wildcard
specification).

tgt_owner.table
tgt_owner.sequence
!file[:tgt_owner.table]
!jms[:tgt_owner.table]
!cdc:tgt_owner.table

l A file that contains XML or SQL records.

l A JMS queue or topic.
l A change-history table that maintains a
record of all changes made to a source
table (also known as change data capture)
See Target specifications in a configuration file.
Routing map

One or more routes that send the data to the

system that contains the target object specified
with the target specification. A route consists of
the following:

[email protected]
[email protected]
[email protected]_alias
[email protected]_name

l The name of the machine that contains

the target database, file, or JMS object to
which data is replicated.

host

l (Database targets only) The @ symbol

followed by the database specification.
See Database specifications in a

Compound routing map:

[email protected]

[email protected][email protected]

SharePlex 8.6
Administrator Guide

Component

Description

Syntax examples

configuration file.

[...]

NOTES:
l The database specification is
absent if the target is JMS or a
file.
l There can be no spaces between
any characters in the routing map.
l You can replicate between
objects in the same database or
different databases on the same
system.
l For additional information, see
Routing specifications in a
configuration file.

Additional configuration options

The following are additional configuration options that can be added to the configuration file:
See Filter DML Operations to prevent INSERTs, UPDATEs, or DELETEs from being replicated.
See Map source and target columns
See Define a unique key
See Configure partitioned replication to divide, parallelize, and filter data to meet specific requirements.
See Configure named queues to divide and parallelize data for increased control and throughput.

Database specifications in a configuration

file
A database specification is required in the following components of the configuration file:
l the datasource (source data) specification
l routing map (target data) specification
Database

Database type*

Database Identifiers

Oracle source or target

Depending on the Oracle database configuration, use

one of the following. This is the string that SharePlex
will use to connect to the database.
l The Oracle SIDof a regular (non-CDB) Oracle
database, as in o.ora12.

SharePlex 8.6
Administrator Guide

Database

Database type*

Database Identifiers
l The tns_alias of a pluggable database (PDB) in
an Oracle container database (CDB), as in
o.pdb1.
l The global tns_alias of an Oracle RAC cluster,
as in o.rac1. SharePlex connects to an Oracle
RAC instance through this tns_alias, which is
mapped locally on each node to the Oracle SID
of the local Oracle instance. For more
information about creating this alias, see
Configure SharePlex in a Cluster in the
SharePlex Installation Guide.

Non-Oracle target

Use to specify the name of a non-Oracle target

database, as in r.mydb. IMPORTANT! Use the actual
name, not the ODBC datasource name (DNS). If the
name is case-sensitive, specify it that way.
See Configure replication to non-Oracle targets for
more information about configuring SharePlex to
replicate to a non-Oracle target.

Oracle change-history
target

Use in a routing map to specify the Oracle SID, tns_

alias, or global RAC tns_alias of an Oracle change
history database, as in o.ORA12CH. In this
configuration, SharePlex applies all source
transactions as INSERTs to the target tables, to
maintain a history of every operation performed. For
more information, see Configure replication to
maintain a change history target.

* NOTE: The dot is required.

Target specifications in a configuration file

The following table shows how to specify a target table or non-table target in a configuration file.
Target

Target Specification

Description

Database table

tgt_owner.table

The fully qualified name of a database table.

Database sequence

tgt_owner.sequence

The fully qualified name of an Oracle sequence.

File

!file[:tgt_owner.table]

The !file designator directs Post to write each change

operation to a file in SQL or SML format. The file name
is applied internally by SharePlex.
Optionally, you can specify the fully qualified name of
a target table if the data will be consumed by a
process that ultimately applies it to a database table.
See Configure Replication to a SQL or XML file target.

SharePlex 8.6
Administrator Guide

Target

Target Specification

Description

JMS

!jms[:tgt_owner.table]

The !jms designator directs Post to write each change

operation to a JMS queue or topic in XML format. The
queue or topic name can be defined by using the
target command.
Optionally, you can specify the fully qualified name of
a target table if the data will be consumed by a
process that ultimately applies it to a database table.
See Configure Replication to a JMS target.

Change history table

!cdc:tgt_owner.table

The !cdc designator directs Post to insert every data

change to the table as a new row, rather than overlay
the old data with new data. Specify the fully qualified
name of the change history table.
See Configure replication to maintain a change history
target.

Routing specifications in a configuration

file
The following instructions show you how to build a routing map. A routing map sends replicated data to the
correct target on the correct target system.

Simple routing map

A simple routing map sends replicated data from one source object to one target object.
Datasource:o.SID

src_owner.table

tgt_owner.table2

host2[@database_specification]

src_owner.table

tgt_owner.table3

host3[@database_specification]

Compound routing map

A compound routing map sends replicated data from one source object to multiple target objects. It enables
you to specify the source and target objects once for all routes, rather than type a separate configuration entry
for each route. Only one target specification can be used in a compound routing map, so all of the target
objects must be identical as follows:
l All one type:All the same database object type or all a JMS queue or all a JMS topic or all a file (but no
combination of these).
l All with the same fully qualified name, including any table specifications in a JMS or file target
specification.

SharePlex 8.6
Administrator Guide

l All having identical column or key mappings, if used (see Define a unique key and Map source and
target columns).
NOTES:
l Certain routing limitations apply when using vertically partitioned replication. See Configure
vertically partitioned replication.
l If any target has a different qualified name from the other targets of the same source object, you
must use a simple routing map for that target.
Datasource:o.SID

src_owner.table

tgt_owner.table

host1[@database_specification]+host2[@database_
specification][...]

Same-system routing map

You can replicate between objects that are in the same database or in different databases on the same system.
You can replicate between objects that have the same name, so long as their owners are different.
When SharePlex replicates between objects on the same system, it does not create Import and Export
processes. You can force SharePlex to create Import and Export processes by using the following routing map. If
you do not need the Import or Export processes, omit the host* portion of the routing map.

Configuration with replication to objects in the same database

Datasource:o.
database1

src_owner.table

tgt_owner.table

host*host[@database1]

Configuration with replication to objects in a different database on the same system

Datasource:o.
database1

src_owner.table

tgt_owner.table

host*host[@database2]

Routing Considerations
l By default, SharePlex supports replication to a maximum of 19 direct target systems. That is the
maximum number of processes that can read the export queue. To replicate to more than 19 targets,
use named export queues. With each additional queue that you add, you can replicate to 19 additional
targets. See Configure named export queues.
l Each instance of sp_cop on a system permits a maximum of 1024 different routes. This limitation
includes each route that uses a different named post queue (see Configure named post queues.) If
your replication strategy requires more than 1024 routes, consider using one or more intermediary
systems to divide the routes among multiple sp_cop instances. See Configure replication to share or
distribute data).

SharePlex 8.6
Administrator Guide

l By default, each sp_cop instance allows a total of 25 queues on a system. There will always be one
capture queue on a source system and one post queue on a target. Therefore, you can have as many as
24 named export queues on a source system and 24 named post queues on a target system. If a system
serves as both a source and target, you will have both a capture queue and a post queue. That allows
you to create up to 23 named queues of either type (or a mix of both). If system memory permits, you
can change the number of allowed queues by setting the SP_QUE_MAX_QUEUES parameter. See the
SharePlex Reference Guide for more information about this parameter.

Configuration examples by datasource

and target
These are examples of basic configuration files according to each possible datasource type and target type.

Replicate from a regular Oracle instance to a regular

Oracle instance
Datasource:o.SID

src_owner.table

tgt_owner.table

[email protected]

Example
The following example replicates table SCOTT.EMP from Oracle instance oraA to target table SCOTT.EMP2 in
Oracle instance oraB on target system sysprod.
Datasource:o.oraA
SCOTT.EMP
SCOTT.EMP2

[email protected]

Replicate from a regular Oracle instance to a nonOracle database

Datasource:o.SID

src_owner.table

tgt_owner.table

[email protected]_name

Example
The following example replicates table SCOTT.EMP from Oracle instance oraA to target table Scott2.Emp2 in
ODBC-compliant database mydb on target system sys2. The target table is case-sensitive.
Datasource:o.oraA
SCOTT.EMP
"Scott2"."Emp2"

[email protected]

NOTE: The support of OpenTarget databases (except Microsoft SQL Server and SAP ASE) is currently in beta
release only. SQL Server and ASE support is GA. Questions or support requests for these features should be

SharePlex 8.6
Administrator Guide

emailed to [email protected]. For more information about the SharePlex beta

program, see the SharePlex Release Notes.

Replicate from a regular Oracle instance to a file in

XML or SQL format
Datasource:o.SID

src_owner.table

!file

host

Example
The following example replicates table SCOTT.EMP from Oracle instance oraA to a file on target
system sysprod.
Datasource:o.oraA
SCOTT.EMP
!file

sysprod

Replicate from a regular Oracle instance to a JMS

queue or topic
Datasource:o.SID

src_owner.table

!jms

host

Example
The following example replicates table SCOTT.EMP from Oracle instance oraA to a JMS queue on target
system sysprod.
Datasource:o.oraA
SCOTT.EMP
!jms

sysprod

Replicate from and to an Oracle pluggable database

(PDB) in a container database (CDB)*
Datasource:
o.PDBalias

src_owner.table

tgt_owner.table

[email protected]

Example
This example replicates table SCOTT.EMP from an Oracle PDB that uses the tns_alias of aliasA to target table
SCOTT.EMP in an Oracle PDB that uses the tns_alias of aliasB on target system sysprod.

SharePlex 8.6
Administrator Guide

Datasource:o.aliasA
SSCOTT.EMP
SCOTT.EMP

[email protected]

* You can also replicate data from an Oracle PDB to any other supported target. See Replicate to, or from, a PDB
for more information.

Replicate to maintain a change history target

Datasource:o.SID

src_owner.table

!cdc:tgt_owner.table

[email protected]

Example
The following example replicates table SCOTT.EMP from Oracle instance oraA to change-history target table
SCOTT.EMP2 in Oracle instance oraB on target system sysprod.
Datasource:o.oraA
SCOTT.EMP
!cdc:SCOTT.EMP2

[email protected]

See Configure replication to maintain a change history target for more information.

Use a script to build a configuration file

SharePlex provides the following scripts that can be used to automate the building of your configuration file
if the source and target object names are identical. These scripts support Oracle Database source and
targets only.
Option

Description

To get more
information

config.sql

Builds a configuration file that includes all tables and sequences that are in the
database. Source and target object names must be identical.

See Build a
configuration
file using a
script

build_
config.sql

Builds a configuration file that includes all tables in a schema. Source and target
object names must be identical.

See Build a
configuration
file using a
script

Replicate to, or from, a PDB

SharePlex supports replication to and from a Pluggable Database (PDB) in an Oracle multitenant container
database (CDB). This support is available on Unix and Linux platforms only.

Capture from a PDB

SharePlex can replicate data from one PDB to:

SharePlex 8.6
Administrator Guide

l another PDB in the same CDB

l a PDB in a different CDB
l a regular (non-PDB) target

To capture from a PDB

l In the configuration file, specify the tns_alias of a PDB as the datasource. For example, if the tns_alias is
pdb1, the datasource specification is:
Datasource: o.pdb1
l You can replicate from as many pluggable databases (PDBs) in the same CDB as desired: Create a
separate configuration file for each PDB. Because each PDB is a different datasource, all configurations
can be active at the same time.
l If replicating from more than one PDB on a system, use named export queues to separate the data
streams from each one. This allows you to issue SharePlex commands that affect configurations, such as
purge config or abort config, for one configuration without affecting the other configurations. See
Configure named export queues.

Replicate to a PDB
SharePlex can replicate data from a regular source database to a PDB in a target Oracle CDB. In one
configuration file, you can replicate to any number of target PDBs in the same CDB or a different CDB.

To replicate to a PDB
Specify the tns_alias of the target PDB in the routing map, as shown in the following example where pdb2 is
the target:
[email protected]

Examples
Example 1: This example shows two configuration files, one replicating from pdb1 and the other replicating
from pdb2, both replicating data to pdb3.
Datasource: o.pdb1
hr.emp
hr2.emp2

[email protected]

Datasource: o.pdb2
sales.cust
sales2.cust2

[email protected]

Example 2: This example shows one configuration file replicating from pdb1 to pdb2 and pdb3, both targets
being on different systems.
Datasource: o.pdb1
hr.sal
hr2.sal2
hr.sal
hr3.sal3

[email protected]
[email protected]

SharePlex 8.6
Administrator Guide

Use Wildcards to specify multiple objects

You can specify multiple objects in one entry of the configuration file by using standard wildcards. You can also
exclude objects from a wildcard specification. If no tables meet the wildcard criteria, activation continues
without error.
The use of wildcards enables you to specify all of the objects in a schema, while also being able to exclude
objects from that schema that you do not want to be replicated.
The use of wildcards enables new objects in the schema to be added to replication automatically if they satisfy
the wildcard criteria. If new tables that satisfy a wildcarded entry in an active configuration are added to the
database, SharePlex automatically begins to replicate them by default. No reactivation is needed.
If you do not want new tables to be added into replication automatically, set the SP_OCT_AUTOADD_ENABLE
parameter to 0.
sp_ctrl> set param SP_OCT_AUTOADD_ENABLE 0

Limitations of wildcard support

Wildcards are not allowed anywhere in a configuration entry that includes the following:
l Vertically partitioned replication (see Configure vertically partitioned replication)
l Horizontally partitioned replication (see Configure horizontally partitioned replication)
l Key definition (see Define a unique key)
l Column mapping (see Map source and target columns)
The tables that use these features must be specified in the configuration file separately.

Supported wildcard syntax

SharePlex supports the following SQL wildcards
l Percent (%) wildcard to specify a string. (See the Validate a wildcard specification.)
l Underscore (_) wildcard to specify a single-character.
l For table names that contain a percent sign or an underscore character (for example emp_salary),
SharePlex recognizes the backslash (\) as an escape character to denote the character as a literal,
not a wildcard.

Specify wildcarded names in the configuration file

Use this template for help when specifying a wildcarded name in the configuration file.

Configuration with wildcarded object names

Datasource:o.SID

expand src_owner.wildcard_name [not

(list)]

tgt_owner.wildcard_name

routing_map

SharePlex 8.6
Administrator Guide

Description of syntax elements

Component

Description

expand

Indicates that the specification contains wildcard characters that

must be expanded. When SharePlex detects the expand
keyword, it queries Oracle for all objects that match the criteria
in the wildcard specification. Without this required keyword, the
wildcard characters are assumed to be part of an explicit object
name, and no wildcard expansion is performed.
NOTE:Leave a space between expand and the start of the source
object specification.

src_owner.wildcard_name

l src_owner is the owner of the source objects. Owner

names cannot be wildcarded. If wildcards are used in the
owner name, SharePlex assumes that they are part of the
owner (schema) name.
l wildcard_name is the wildcarded name of the source
objects.
The name of the objects on the source must be the same as the
name of the objects on the target, but the objects may belong to
different owners (or reside in different schemas).

not (list)

An exclusion list that defines objects to omit from the wildcard

expansion. Use this option to exclude objects that you do not want
to be replicated. NOTE: This not keyword does not have the same
meaning as the SQLwildcard NOT operator.
l The not keyword and parentheses are required elements.
l list is a comma-separated list of tables in the same
schema, either wildcarded or explicit. Example: not
(spo%, gen%, product).
Leave a space before and after the not keyword. A space is
allowed after each comma in the list.
NOTE: If an object that satisfies a wildcard is listed
elsewhere in the configuration file, that entry overrides
the processing or routing specified in the wildcarded
entry. In this case, a not clause is not needed. See the
Examples.

tgt_owner.wildcard_name

l tgt_owner is the owner of the target objects.

l wildcard_name is the wildcarded name of the target
objects.
The target specification must be in the form of owner.%. Partially
expanded target wildcarded names are not supported, such as
owner.tab%.

routing_map

Any valid routing map. See Routing specifications in a configuration

file .

SharePlex 8.6
Administrator Guide

Validate a wildcard specification

To confirm that a wildcard specification will produce the specific list of tables that you want to replicate, issue
the verify config command in sp_ctrl before you activate the configuration. This command produces a list of
the objects that SharePlex will capture and replicate, as well as any problems that occurred. For more
information about this command, see the SharePlex Reference Guide.

Examples
Examples of valid wildcard specifications
Example 1: The following wildcard specification directs SharePlex to activate all tables owned by scott,
where the table name is like prod% except if the table name is like %temp%. All tables that match this
description are replicated to tables of the same names on the target in the hal schema. Note that SharePlex
automatically upshifts the names, so that it actually activates all tables where the table name is like 'PROD%'
but not like '%TEMP%'.
Datasource:o.sidA
expand scott.prod% not (%temp%)

hal.%

[email protected]

Example 2: The following example shows how you can specify special handling for one of the tables in a
wildcarded specification, in this case the photo table. All tables but photo are routed through the default post
queue. The separate entry for the photo table overrides the wildcarded entry and processes the photo table
through a named post queue. For more information, see Configure named post queues.
Datasource:o.sidA
cust.%
cust.%
cust.photo
cust.photo

[email protected]
hostB:[email protected]

The following are additional examples of valid wildcard specifications

Datasource:o.sidA
expand scott.%test%

scott.%

Datasource:o.sidA
expand scott.%t__t%

fred.%

[email protected]

Datasource:o.sidA
expand scott.% not (spo%, gen%, prodct)
Datasource:o.sidA
expand scott.prod% not (%temp%)

hal.%

scott.%

[email protected]

Examples of invalid wildcard specifications

The following example contains a wildcarded schema, which is not permitted.
Datasource:o.sidA
expand rob%.%test%

scott.%

[email protected]

The following example contains a partially wildcarded target object name, which is not permitted.
Datasource:o.sidA
expand scott.%test%

scott.%obj%

[email protected]

SharePlex 8.6
Administrator Guide

Define a unique key

If a table was not created with a primary or unique key, you can specify columns to use as a key when you
specify the object in the configuration file. SharePlex uses the specified columns as a unique key in its WHERE
clause to locate target rows for posting.
NOTES:
l Without a primary or unique key, SharePlex uses all of the columns of a table (or all of the columns in a
column partition) as a key, which slows replication performance.
l When a key definition is specified for a table that has a PRIMARY or UNIQUE key, the key definition
overrides the defined key.
The columns that you specify as a key must meet the following criteria:
l They cannot be LONG or LOB columns.
l They must be able to uniquely identify a row. Otherwise, replication could return out-of-sync errors or
post to incorrect target rows.
l They must be part of the column partition if the table is configured for vertically partitioned
replication. When using the exclude column notation in vertical partitioning, the excluded columns
cannot be used in the key definition. For more information about partitioned replication, see Configure
partitioned replication.
l Include the columns in a supplemental log group. Otherwise, SharePlex must query the database for
their values.

Syntax for key definition

To create a key definition, type a space after the source object and use the following syntax, including the
parentheses.
src_owner.table !key (column_list)
where:
l !key is a required keyword.
l column_list is a list of columns to include in the key. Separate column names with commas. A space
after the comma is optional.
Datasource:o.SID

src_owner.table !key (col_name, col2_name, ...)

tgt_owner.table

[email protected]

Example
Datasource:o.ora1
scott.tab !key(name,ID)

scott.tab2

sysB@oraB

SharePlex 8.6
Administrator Guide

Filter DML Operations

You can configure SharePlex to filter any type of DML operation so that the operation is not replicated to the
target table. DML filtering is compatible with most other SharePlex configuration syntax. See the Restrictions.

Configure a DML filter

To configure a DML filter, add the following syntax to the source table specification. Leave a space between the
table specification and the filter specification. You can specify multiple operation types to filter. Any additional
syntax for other features, such as a column list or key definition, must follow the DMLfilter specification.
!dml(DML_type[,DML_type][,...])
Where DML_type is one of the following:
DML_type input

Operation type

INSERT

DELETE

UPDATE

Examples
Example 1
The following example filters DELETE operations from being replicated to the target table.
scott.emp !dml(d) scott.emp [email protected]
Example 2
The following example filters DELETEs and INSERTs so that only UPDATEs are replicated to the target table. This
example also shows how a DML filter is compatible with a column mapping specification.
scott.stock !dml(d,i) (ID, name, store) scott.stock (SKU, product, location) [email protected]

View current DML filters

Use the verify config command to view the DML that is being filtered for each table in the configuration file.
This command can be used for an active or inactive configuration file.
sp_ctrl> verify config myconfig
7: "SCOTT"."EMP" "SCOTT"."EMP" [email protected]
Filter out >>>>> DELETES
Unique Key : (EMPLOYEE_ID)

SharePlex 8.6
Administrator Guide

Restrictions
l The copy and compare commands do not support tables that include DML filtering in their
specifications.
l If there are multiple specifications of a source table in the configuration file, the DML filter specification
must be identical for all of them. Multiple specifications of the same source table occur if you are
routing to multiple targets without using a compound routing map (see Routing specifications in a
configuration file), or if you are combining full-table replication with horizontally partitioned replication
(see Configure horizontally partitioned replication).

Map source and target columns

When source and target column names are different, you can specify an explicit column mapping in the
configuration file, to ensure that Post applies row data to the correct target columns.

Guidelines for using column mapping

l To use column mapping, you must map every column in a source table to a column in the target table,
even if only some source and target names are different. When some columns are mapped but not
others, the entry is considered to be a column partition for vertically partitioned replication, and data
changes for non-listed columns are not replicated.
l You can use horizontally partitioned replication and column mapping for the same source table, but you
cannot combine column mapping with vertically partitioned replication.
l A target table can have more columns than the source table, but there must at least be a target
column for every source column.
l ALTER TABLE to add a column to a table that is configured with column mapping is not supported.

Configure column mapping

The following syntax creates a column map. For more information about the configuration file, see Create
configuration files.
Datasource:o.SID

src_owner.table (src_col,src_col,...)

tgt_owner.table (tgt_col,tgt_col,...)

routing_map

Configuration component

Description

src_owner.table and tgt_

owner.table

The specifications for the source and target tables, respectively.

(src_col,src_col,...)

A list of the source columns.

Follow these rules to specify a column list:
l A column list must be enclosed within parentheses.

SharePlex 8.6
Administrator Guide

Configuration component

Description
l Separate each column name with a comma. A space after the
comma is optional.
l The maximum length of a column list is 174820 bytes (the
maximum line length allowed in a configuration file).

(tgt_col,tgt_col,...)

A list of the target columns.

l List the target columns in the same logical order as their
corresponding source columns. This is required regardless of the
actual order of the target columns in the table, so that
SharePlex builds the correct map in the object cache. For
example, a change to the second column in the source list is
replicated to the second column in the target list.
l The syntax rules for the source list also apply to the target list.

routing_map

The routing map. You can use a simple routing map, such as sysb@oraB,
or a compound routing map, such as sysb@oraB+sysc@oraC.

Configuration example
Datasourceo.oraA
sales.prod (ID,name,vendor,length,width)
mfg.prod
(UPC,product,supplier,length,depth)
[email protected]

Build a configuration file using a script

SharePlex provides the following scripts to automate the building of a configuration file.
l config.sql: configure all tables and optionally all sequences in the database.
l build_config.sql: configure multiple or all tables in a schema

Supported databases
Oracle

Use config.sql
The config.sql script enables you to build a configuration that lists all of the tables, and optionally all of the
sequences, in all of the schemas of a database. This script saves time when establishing a high-availability
replication strategy or other scenario where you want the entire database to be replicated to an identical
secondary database.

SharePlex 8.6
Administrator Guide

Conditions for using config.sql

l Source and target table names must be the same.
l The script does not configure objects in the SYS, SYSTEM, and SharePlex schemas. These schemas
cannot be replicated since they are system and/or instance-specific.
l The script does not support partitioned replication. You can use the copy config command to copy the
configuration file that the script builds, then use the edit config command to add entries for tables
that use partitioned replication. Activate the new configuration file, not the original one.
l You can use the edit config command to make any other changes as needed after the
configuration is built.

To run config.sql
1. Change directories to the config sub-directory of the SharePlex variable-data directory. The config.sql
script puts configurations in the current working directory, and SharePlex configurations must reside in
the config sub-directory.
cd /vardir/config
2. Log onto SQL*Plus as SYSTEM.
3. Run config.sql using the full path from the util sub-directory of the SharePlex product directory.
@ /proddir/util/config.sql
Refer to the following table when following the prompts.
Prompt

What to enter

Target
machine

The name of the target machine, for example SystemB.

Source
database
SID

The ORACLE_SID of the source (primary) Oracle instance, for example oraA. Do not include the
o. keyword. The ORACLE_SID is case-sensitive.

Target
database
SID

The ORACLE_SID of the target (destination) Oracle instance, for example oraB. Do not include
the o. keyword. The ORACLE_SID is case-sensitive.

Replicate
sequences

Enter y to replicate sequences or n not to replicate sequences.

Shareplex
oracle
username

The name of the SharePlex user in the source database. This entry prevents the SharePlex
schema from being replicated, which would cause replication problems. If a valid name is not
provided, the script fails.

NOTE: The name assigned by SharePlex to the configuration is config.file. If you run the script again to create
another configuration file, it overwrites the first file. To preserve the original file, rename it before you create
the second one.

Next steps:
l If any tables or owners are case-sensitive, open the configuration file with the edit config command in
sp_ctrl, then use the text editor to enclose case-sensitive table and owner names within double-quote
marks, for example scott.emp. The script does not add the quote marks required by Oracle to

SharePlex 8.6
Administrator Guide

enforce case-sensitivity.
sp_ctrl> edit config filename
l To ensure that the configuration is in the correct location, issue the list config command. If the name of
the configuration is not shown, it was created in the wrong directory. Find the file and move it to the
config sub-directory of the variable-data directory.
sp_ctrl> list config

Use build_config.sql
The build_config.sql script enables you to build a configuration that contains multiple (or all) tables in a
schema. It is an interactive script that prompts for each component of the configuration step by step. Instead of
entering the information for each object and the routing individually, you can use a wildcard to select certain
tables at once, or you can select all of the tables in the schema.

Conditions for using build_config.sql

l Source and target table names must be the same.
l The script does not support sequences. Before you activate the configuration that the script builds, you
can use the edit config command in sp_ctrl to add entries for sequences.
l The script does not support partitioned replication. You can use the copy config command to copy the
configuration that the script builds, then use the edit config command to add entries for the tables
that use partitioned replication. Activate the new configuration, not the original.
l The script does not configure objects in the SYS, SYSTEM, and SharePlex schemas. These schemas
cannot be replicated since they are system and/or instance-specific.
l You can run build_config.sql for different schemas, then combine those configurations into one
configuration by using a text editor. Make certain to eliminate all but one Datasource:o.SID line, which
is the first non-commented line of the file. Do not move the file out of the config sub-directory.
l You can use the edit config command to make any other changes as needed after the
configuration is built.

To run build_config.sql
1. Change directories to the config sub-directory of the SharePlex variable-data directory. The build_
config.sql script puts configurations in the current working directory, and SharePlex configurations
must reside in the config sub-directory.
cd /vardir/config
2. Log onto SQL*Plus as SYSTEM.
3. Run build_config.sql using the full path from the util sub-directory of the SharePlex product directory.
@ /proddir/util/build_config.sql
Refer to the following table when following the prompts.
Prompt

What to enter

Target machine

The name of the target machine, for example SystemB.

Source database SID

The ORACLE_SID of the source (primary) Oracle instance, for example oraA. Do not

SharePlex 8.6
Administrator Guide

Prompt

What to enter
include the o. keyword. The ORACLE_SID is case-sensitive.

Target database SID

The ORACLE_SID of the target (destination) Oracle instance, for example oraB. Do not
include the o. keyword. The ORACLE_SID is case-sensitive.

Owner of the source

database tables

The owner of the source tables.

Owner of the target

database tables

The owner of the target tables.

Table name to
Do one of the following:
include (blank for all)
l Press Enter to accept the default, which selects all tables that belong to the
source owner.
l Enter a wildcard (%) character and a string to select certain tables, for
example %e_salary%.
l Enter an individual table name.
Name of the output
file to create

A name for the configuration. The script gives the file a .lst suffix, for example Scott_
config.lst.

Next steps:
l If any tables or owners are case-sensitive, open the configuration with the edit config command in sp_
ctrl, then use the text editor to enclose case-sensitive table and owner names within double-quote
marks, for example scott.emp. The script does not add the quote marks required by Oracle to
enforce case-sensitivity.
sp_ctrl> edit config filename
l To ensure that the configuration is in the correct location, issue the list config command. If the name of
the configuration is not shown, it was created in the wrong directory. Find the file and move it to the
config sub-directory of the variable-data directory.
sp_ctrl> list config

SharePlex 8.6
Administrator Guide

7
Configure replication to non-Oracle
targets

This chapter contains instructions for configuring SharePlex to replicate data from Oracle Database to Open
Target (non-Oracle) targets. Post must be configured to process data to the intended target in the correct
manner and format. This chapter guides you through the Post configuration process for each supported target.
NOTE: The support of OpenTarget databases (except Microsoft SQL Server and SAP ASE) is currently in beta
release only. SQL Server and ASE support is GA. Questions or support requests for these features should be
emailed to [email protected]. For more information about the SharePlex beta
program, see the SharePlex Release Notes.

Contents
Configure replication to a Microsoft SQL Server target
Configure replication to an SAP ASE target
Configure replication to an ODBC-compliant target
Configure Replication to a JMS target
Configure Replication to a SQL or XML file target

SharePlex 8.6
Administrator Guide

Configure replication to a Microsoft SQL

Server target
Overview
SharePlex can post replicated Oracle data to a Microsoft SQL Server target database through an Open Database
Connectivity (ODBC) interface. These instructions guide you through the configuration processes that are
required to support this target.
NOTE: For the datatypes and operations that are supported when using SharePlex to replicate to a SQL Server
target, see the SharePlex Release Notes.

Configure SharePlex on the source

When replicating data to a non-Oracle database, configure SharePlex on the source system as follows.

Enable supplemental logging

On the source system, enable PK/UK supplemental logging in the Oracle source database. SharePlex must
have the Oracle key information to build an appropriate key on the target.
SQL> ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY, UNIQUE) COLUMNS;

Set SP_OCT_USE_SUPP_KEYS parameter

On the source system, set the SP_OCT_USE_SUPP_KEYS parameter to a value of 1. This parameter directs
SharePlex to use the columns set by Oracle's supplemental logging as the key columns when a row is updated
or deleted. When both supplemental logging and this parameter are set, it ensures that SharePlex can always
build a key and that the SharePlex key will match the Oracle key.
See the SharePlex Reference Guide for more information about this parameter.

Configure replication
On the source system, create a SharePlex configuration file. See Create configuration files for full information
about your options for creating a configuration file based on your replication strategy. The following
configuration file template shows the correct routing map for a non-Oracle target database:
Datasource:o.SID
src_owner.table

tgt_owner.table

[email protected]_name

where:
l SID is the Oracle SID of the source Oracle database.

SharePlex 8.6
Administrator Guide

l src_owner.table is the owner and name of the source table.

l tgt_owner.table is the owner and name of the target table.*
l host is the name of the target system.
l r. identifies the target as non-Oracle.
l database_name is the name of the target database. IMPORTANT! database_name must be
the actual name of the database, not a data source name (DSN).
* IMPORTANT!If target owner or table name is defined in the database as anything other than UPPERCASE, be
certain to:
l Type the name in the correct case.
l Enclose the name in quotation marks, for example "MySchema"."MyTable".

Source configuration example

The following configuration file replicates table HR.EMP from Oracle instance ora112 to target table
Region1.Emp in database mydb on target system sysprod. The target table is case-sensitive.
Datasource:o.ora112
HR.EMP

"Region1"."Emp"

[email protected]

Configure SharePlex on the target

1. If you have not done so already, install the Microsoft SQL Server ODBC Driver. It must be that driver,
not the Microsoft SQL Server Native Client, or SharePlex will return an error when you run mssql_
setup to configure Post to connect to the database. To tell the difference between the two drivers:
l The Microsoft SQL Server ODBC Driver has versions such as 06.02.9200.
l The Microsoft SQL Server Native Client has versions such as 11.00.3513.
2. Create a Data Source Name (DSN) for the SQLServer database on the target Windows system. Make
certain to select an authorization type of With SQLServer authentication using a login ID and
password entered by the user. Test the DSN and make certain you can connect to the database
through ODBC before proceeding to the next step.
3. If you did not do so when you installed SharePlex, run the mssql_setup utility, which performs the
following target setup:
l Establish a SharePlex database account with privileges to post to the target SQL Server database
l Establish a target connection configuration
l Install tables and indexes for use by SharePlex and owned by the SharePlex account
See Create a SharePlex account in a SQL Server database.

SharePlex 8.6
Administrator Guide

Configure replication to an SAP ASE target

Overview
SharePlex can post replicated Oracle data to an SAP ASE target database through an Open Database
Connectivity (ODBC) interface. These instructions guide you through the configuration processes that are
required to support this target.
NOTE: For the platforms, datatypes and operations that are supported when using SharePlex to replicate to a
Sybase target, see the SharePlex Release Notes.
Make certain to download the correct ODBC driver for your database.

Configure SharePlex on the source

Enable supplemental logging
To replicate to a non-Oracle target, enable PK/UK supplemental logging in the Oracle source database.
SharePlex must have the Oracle key information to build an appropriate key on the target,

Set SP_OCT_USE_SUPP_KEYS parameter

To replicate to a non-Oracle database target, set the SP_OCT_USE_SUPP_KEYS parameter to a value of 1. This
parameter directs SharePlex to use the columns set by Oracle's supplemental logging as the key columns when
a row is updated or deleted. When both supplemental logging and this parameter are set, it ensures that
SharePlex can always build a key and that the SharePlex key will match the Oracle key.
See the SharePlex Reference Guide for more information about this parameter.

Configure replication
On the source, create a SharePlex configuration file that specifies capture and routing information. The
components that are required in a configuration file vary, depending on your replication strategy. However,
the most important part of the configuration file as it relates to replication to a non-Oracle target is the portion
of the routing map after the @ symbol.
NOTE: See Create configuration files for additional information about creating a configuration file.
To configure replication to a non-Oracle target, use the following syntax in the configuration file:
Datasource:o.SID
src_owner.table

tgt_owner.table

[email protected]_name

where:
l SID is the Oracle SID of the source Oracle database.

SharePlex 8.6
Administrator Guide

l src_owner.table is the owner and name of the source table.

Source configuration example

The following configuration file replicates all tables in schema PROD from Oracle instance ora112 to database
mydb on target system sysprod.
Datasource:o.ora112
MY_SCHEMA.MY_TABLE

"MySchema2"."MyTable2"

[email protected]

Configure SharePlex on the target

Set up ODBC
1. Install and test the ODBC driver that is appropriate for your target ODBC-compliant database. SharePlex
provides the OTS utility for testing the ability of SharePlex to connect to and post through ODBC. For
more information, see OTS in the utilities section of the SharePlex Reference Guide.
2. On the target system, configure ODBC connection information for use by Post to connect to the target
database. You have the following options for configuring this connection information:
l On Windows, create a user or system DSN (Data Source Name) by using Data Sources (ODBC) in
the Administrative Tools section of the Windows control panel. See the Windows
documentation or your system administrator. If using a DSN, you must set the Post user name
and password for the target database with the connection comand. See Configure replication
to an SAP ASE target.
l On Unix and Linux, you can do either of the following:
l Configure a user or system DSN on the target system according to the instructions
provided with the database. Test the DSN by using it to connect to the target database. If
the connection is successful, copy the ODBC configuration files to the odbc subdirectory
of the SharePlex variable-data directory. Set the LD_LIBRARY_PATH environment
variable to the location of the database ODBC driver.
or...
l Set the ODBC connection information in the Post configuration. See Set connection
information with the connection command.

SharePlex 8.6
Administrator Guide

Set connection information with the connection command

Use the connection command to:
l Set the Post user name and password if you created a DSN.
l Set all of theODBC connection information if a DSN does not exist.
1. Create a user account for SharePlex in the target database. This account must be granted the privileges
to connect, query the metadata structures of the database, create and update tables in the SharePlex
database or schema, and perform full DML and supported DDL operations. Make certain that this user
can connect successfully to the database through ODBC outside SharePlex.
2. Run sp_ctrl.
3. Execute the connection command with the set option, once for each keyword.
connection r.database_name set keyword=value

Option1: Input when a DSN exists

Keyword

Value to enter

user

The database user assigned to SharePlex

password

The password for the SharePlex user

dsn

The DSN of the database.

IMPORTANT! user, password, and dsn are the only required
keywords if a DSN exists.

Option 2: Input when a DSN does not exist (Unix and Linux)
Keyword

Value to enter

user

The database user assigned to SharePlex

password

The password for the SharePlex user

port

The database port number.

server

The name or IP address of the database server.

driver

The full path to the ODBC driver on the database server.

Option 3: Connect string when a DSN does not exist (Unix and Linux)
Keyword

Value to enter

user

The database user assigned to SharePlex

SharePlex 8.6
Administrator Guide

Keyword

Value to enter

password

The password for the SharePlex user

connect_string

A user-defined connection string. When using your own

connection string, make certain it includes all of the required
elements to make a successful ODBC connection, but omit the
user name and password. Use the connection command with
the user and password options to supply user information.

Connection command examples

Examples based on the following generic sample ODBC.ini file:
[Database]
Driver

= Database Driver

Description

= ODBC driver for database

Server

= server1.mycorp.com

Port

= 1234

Trace

= false

UseCursor

= 1

[Database]
Description

= ODBC driver for database

Driver

= /database/ODBC/lib/databasedriver.so

Setup

= /database/ODBC/lib/databasedriver.so

Driver64

= /database/64/ODBC/lib/databasedriver.so

(DSN exists)
connection r.mydb set user=myuser
connection r.mydb set password=mypassword
connection r.mydb set dsn=mydsn

(DSN does not exist)

connection r.mydb set user=myuser
connection r.mydb set password=mypassword
connection r.mydb set port=1234
connection r.mydb set server=server1
connection r.mydb set driver=/database/ODBC/lib/databasedriver.so

(DSN does not exist, use connection string)

connection r.mydb set user=myuser

SharePlex 8.6
Administrator Guide

connection r.mydb set password=mypassword

connection r.mydb set connect_
string=driver=/database/ODBC/lib/databasedriver.so;server=server1;port=1234;uid=myuser;pwd=m
ypassword

Remove a connection value

Use connection with the reset option to remove SharePlex connection settings.

To remove a specific connection value

connection r.database_name reset keyword

To remove all connection values

connection r.database_name reset

Examples
connection r.mydb reset port
connection r.mydb reset

View connection values

Use connection with the show option to view SharePlex connection settings.

To view connection values for a database

connection r.database_name show

To view connection settings for all local databases

connection show all

SharePlex 8.6
Administrator Guide

Configure replication to an ODBCcompliant target

Overview
SharePlex can connect to a database that supports Open Database Connectivity (ODBC). This connection
configuration type supports the following databases:
l Microsoft SQL Server (if not using the mss_setup utility)
l SAP ASE (formerly Sybase)
l Other ODBC-compliant databases
NOTE: For the platforms, datatypes and operations that are supported by SharePlex, see the SharePlex
Release Notes.
NOTE: The support of OpenTarget databases (except Microsoft SQL Server and SAP ASE) is currently in beta
release only. SQL Server and ASE support is GA. Questions or support requests for these features should be
emailed to [email protected]. For more information about the SharePlex beta
program, see the SharePlex Release Notes.
Make certain to download the correct ODBC driver for your database.

Configure SharePlex on the source

Set SP_OCT_USE_SUPP_KEYS parameter

SharePlex 8.6
Administrator Guide

NOTE: See Create configuration files for additional information about creating a configuration file.
To configure replication to a non-Oracle target, use the following syntax in the configuration file:
Datasource:o.SID
src_owner.table

tgt_owner.table

[email protected]_name

where:
l SID is the Oracle SID of the source Oracle database.
l src_owner.table is the owner and name of the source table.
l tgt_owner.table is the owner and name of the target table.*
l host is the name of the target system.
l r. identifies the target as non-Oracle.
l database_name is the name of the target database. IMPORTANT! database_name must be
the actual name of the database, not a data source name (DSN).
* IMPORTANT!If target owner or table name is defined in the database as anything other than UPPERCASE, be
certain to:
l Type the name in the correct case.
l Enclose the name in quotation marks, for example "MySchema"."MyTable".

Source configuration example

The following configuration file replicates all tables in schema PROD from Oracle instance ora112 to database
mydb on target system sysprod.
Datasource:o.ora112
MY_SCHEMA.MY_TABLE

"MySchema2"."MyTable2"

[email protected]

Configure SharePlex on the target

SharePlex 8.6
Administrator Guide

l Configure a user or system DSN on the target system according to the instructions
provided with the database. Test the DSN by using it to connect to the target database. If
the connection is successful, copy the ODBC configuration files to the odbc subdirectory
of the SharePlex variable-data directory. Set the LD_LIBRARY_PATH environment
variable to the location of the database ODBC driver.
or...
l Set the ODBC connection information in the Post configuration. See Set connection
information with the connection command.

Set connection information with the connection command

Option1: Input when a DSN exists

Keyword

Value to enter

user

The database user assigned to SharePlex

password

The password for the SharePlex user

dsn

The DSN of the database.

IMPORTANT! user, password, and dsn are the only required
keywords if a DSN exists.

Option 2: Input when a DSN does not exist (Unix and Linux)
Keyword

Value to enter

user

The database user assigned to SharePlex

password

The password for the SharePlex user

port

The database port number.

server

The name or IP address of the database server.

driver

The full path to the ODBC driver on the database server.

SharePlex 8.6
Administrator Guide

Option 3: Connect string when a DSN does not exist (Unix and Linux)
Keyword

Value to enter

user

The database user assigned to SharePlex

password

The password for the SharePlex user

connect_string

A user-defined connection string. When using your own

Connection command examples

Examples based on the following generic sample ODBC.ini file:
[Database]
Driver

= Database Driver

Description

= ODBC driver for database

Server

= server1.mycorp.com

Port

= 1234

Trace

= false

UseCursor

= 1

[Database]
Description

= ODBC driver for database

Driver

= /database/ODBC/lib/databasedriver.so

Setup

= /database/ODBC/lib/databasedriver.so

Driver64

= /database/64/ODBC/lib/databasedriver.so

(DSN exists)
connection r.mydb set user=myuser
connection r.mydb set password=mypassword
connection r.mydb set dsn=mydsn

(DSN does not exist)

connection r.mydb set user=myuser
connection r.mydb set password=mypassword
connection r.mydb set port=1234

SharePlex 8.6
Administrator Guide

connection r.mydb set server=server1

connection r.mydb set driver=/database/ODBC/lib/databasedriver.so

(DSN does not exist, use connection string)

connection r.mydb set user=myuser
connection r.mydb set password=mypassword
connection r.mydb set connect_
string=driver=/database/ODBC/lib/databasedriver.so;server=server1;port=1234;uid=myuser;pwd=m
ypassword

Remove a connection value

Use connection with the reset option to remove SharePlex connection settings.

To remove a specific connection value

connection r.database_name reset keyword

To remove all connection values

connection r.database_name reset

Examples
connection r.mydb reset port
connection r.mydb reset

View connection values

Use connection with the show option to view SharePlex connection settings.

To view connection values for a database

connection r.database_name show

To view connection settings for all local databases

connection show all
NOTE: The support of OpenTarget databases (except Microsoft SQL Server and SAP ASE) is currently in beta
release only. SQL Server and ASE support is GA. Questions or support requests for these features should be
emailed to [email protected]. For more information about the SharePlex beta
program, see the SharePlex Release Notes.
IMPORTANT:
l SharePlex provides configuration utilities for Oracle Database and Microsoft SQL Server. The initial setup
for these databases is performed during the installation of SharePlex. To update the Oracle setup, run
the utility. To update the SQL Server setup, run the mss_setup utility. See the SharePlex Reference
Guide for information about these utilities. For other supported databases, use the setup in this topic.
l For the platforms, datatypes and operations that are supported when using SharePlex to replicate to an
ODBC target, see the SharePlex Release Notes.

SharePlex 8.6
Administrator Guide

Map datatypes
To support the accurate posting of replicated Oracle ALTERTABLEcommands to the correct datatypes in an
ODBC-compliant target, you need to map Oracle datatypes to the datatypes of the target database. Use the
target command with the set datatype option to perform this mapping.
NOTE: For DML operations, SharePlex queries the target database to determine the appropriate
datatype mapping for replicated data.

To map datatypes
target r.database [queue queuename ] set datatype src_datatype=tgt_datatype
Where: src_datatype is the Oracle datatype and tgt_datatype is the target datatype to which you are
mapping the Oracle datatype.
See the following table for mapping options.
Property

Description

src_datatype

The Oracle source datatype that you are mapping to a target datatype.
Valid values are:
anydata
blob
char
clob
date
double
float
long
longraw
number
raw
timestamp
timestamp_tz
varchar

tgt_datatype

A valid datatype for the target. The source datatype will be mapped to
this datatype.

For more information about the target command, see the SharePlex Reference Guide.

SharePlex 8.6
Administrator Guide

Configure Replication to a JMS target

Overview
The SharePlex Post process can connect and write to a JMS (Java Messaging Service) queue or topic. The data is
written as XMLrecords that include the data definitions, the operation type, and the changed column values.
This data is written as a sequential series of operations as they occurred on the source, which can then be
posted in sequential order to a target database or consumed by an external process or program.
NOTE: For the platforms, datatypes and operations that are supported when using SharePlex to replicate to
JMS, see the SharePlex Release Notes.

Configure SharePlex on the source

When replicating data to JMS, configure the source database and SharePlex on the source system as follows.

Enable supplemental logging

Set SP_OCT_USE_SUPP_KEYS parameter

Configure replication
On the source, create a SharePlex configuration file that specifies capture and routing information. The
structure that is required in a configuration file varies, depending on your replication strategy, but this shows
you the required syntax for routing data through a JMS queue or topic.
Datasource:o.SID
src_owner.table

!jms[:tgt_owner.table]

host

where:
l SID is the Oracle SID of the source Oracle database.
l src_owner.table is the owner and name of the source table.

SharePlex 8.6
Administrator Guide

l !jms is a required keyword indicating SharePlex is posting to JMS.

l tgt_owner.table is optional and specifies the owner and name of the target table. Use if either
component is different from that of the source table. Allow no spaces between !jms and tgt_
owner.table. Type case-sensitive names in the correct case and enclose them within double quotes, as
in "MySchema"."MyTable"
l host is the name of the target system.
NOTE:For more information about how to create a configuration file, see Create configuration files.

Source configuration example

Datasource:o.ora112
MY_SCHEMA.MY_TABLE

!jms:"MySchema2"."MyTable2"

sysprod

Configure SharePlex on the target

These instructions establish the Java provider on the target and configure the SharePlex Post process to
connect to a JMS structure.
Configure SharePlex on an Active MQ target

Configure SharePlex on an Active MQ target

These instructions configure the SharePlex Post process to post to an Active MQ queue or topic.
The following directory naming conventions are used in the examples in this procedure:
Name

The Active MQ client installation directory

SharePlex

The SharePlex installation directory

amq

The working directory for Active MQ within the SharePlex directory.

To configure post to the ActiveMQ target

1. Install and configure the latest version of Java Runtime Engine (JRE) on the SharePlex target server.
2. Create the activemq directory under SharePlex/lib/providers.
shareplex/lib/providers/amq
3. Download and expand the ActiveMQ files to the activemq directory under SharePlex/lib/providers.
4. Configure the JAVA_HOME and JRE_HOME variables to point to the activemq directory.
5. Add the new JAVA_HOME to the PATH variable.
6. Set all values of producerFlowControl="true" to "false". Additional content about this parameter is
available at: http://activemq.apache.org/producer-flow-control.html.
7. Copy the following provider JAR files and HS dependencies to the directory that you created.
shareplex/lib/providers/amq/activemq-all.jar

SharePlex 8.6
Administrator Guide

shareplex/lib/providers/amq/slf4j.jar
8. Start sp_cop. (Do not activate the configuration yet.)
9. Run sp_ctrl.
10. Issue the target command to configure Post to post to the JMS queue or topic. The following are
example commands.
See View and change JMS settings for command explanations and options.

If posting to a JMS queue:

sp_ctrl> target x.jms set jms factory_
class=org.apache.activemq.jndi.ActiveMQInitialContextFactory
sp_ctrl> target x.jms set jms provider_url=tcp://w2k3-64bit:61616
sp_ctrl> target x.jms set jms lib_location=shareplex/lib/providers/amq
sp_ctrl> target x.jms set jms queuename=SHAREPLEX.Q1

If posting to a JMS topic:

View and change JMS settings

To view current property settings for output to JMS, use the following command:
target x.jms show
To change a property setting, use the following target command.
target x.jms [queue queuename] set jms property=value
where:
l queue queuename is the name of a Post queue. Use this option if there are multiple Post processes.
l property and value are shown in the following table.
Table 3: JMS target properties
Property

Input Value

Default

factory_class=factory_class

Required keyword. Fully qualified class name of the

factory class. Sets the JNDI environmental property
java.naming.factory.initial to specify the class name of
the initial context factory for the provider.

None

provider_url=url

Required keyword. RMI URL with no object name

None

SharePlex 8.6
Administrator Guide

Property

Input Value

Default

component. This sets the JNDI environmental property

java.naming.provider.url to specify the location of the
registry that is being used as the initial context.
lib_location=path

Required keyword. Path to the directory where you

installed the JAR files.

None

destination={queue | topic}

Messaging domain. Valid values are queue (port-to-port)

or topic (publisher-subscriber model).

queue

factory_name=factory_name

Name of a JNDI connection factory lookup. You can

specify multiple names with a comma-separated list, for
example: (jndi.name1, jndi.name2).

None

user=user

Name of the user that is attaching to JMS. If

authentication is not required, omit this and the
password option.

None

password=password

Password of the JMS user.

None

queuename=JMS_queuename

Name of the JMS queue or topic.

OpenTarget

persistent={yes | no}

yes logs messages to disk storage as part of send

operations.

yes

no prevents logging.
session_transacted ={yes|no}

no directs Post to issue a JMS commit for every

replicated message, making each one immediately
visible and consumable. This is the default.

yes directs Post to issue a JMS commit (to make messages

visible and consumable) at these intervals:
l Before the data is read-released from the Post
queue, as controlled by the value set for the SP_
OPX_READRELEASE_INTERVAL parameter.
l Every JMS write, as controlled by the value set
for the SP_OPX_CHECKPOINT_FREQ parameter,
until the SP_OPX_READRELEASE_INTERVAL is
reached.
properties

None
Use this option if the JMS provider that you are using
cannot consume messages that contain the default set of
properties supplied by SharePlex. It enables you to
remove or add properties. Supply the properties as a
comma-delimited list.
l To add a property, specify it as name=value.
l To remove a SharePlex property, prefix the name
with a dash. For example this string removes two
SharePlex properties: -JMSXDeliveryCount,JMSXGroupSeq.

SharePlex 8.6
Administrator Guide

Property

Input Value

Default

client_id

Use this option if the JMS provider that you are using
cannot consume messages that contain the default
SharePlex client ID. Set this value to the client ID that
your provider accepts.

None

Set recovery options

If the JMS process aborts suddenly, or if the machine that it is running on aborts, row changes may be written
twice to the JMS target. The consumer must manage this by detecting and discarding duplicates.
Every record of every row-change operation in a transaction has the same transaction ID and is also marked with
a sequence ID. These attributes are id and msgIdx, respectively, under the txn element in the XML output
(see About the XML).
The transaction ID is the SCN at the time the transaction was committed and the sequence ID is the index of the
row change in the transaction. These two values are guaranteed to be the same if they are re-written to the
JMS queue in a recovery situation.
If desired, you can configure the target to include additional metadata with every row-change record by using
the following command:
target target [queue queuename] set metadata property[, property]
Table 4: Optional JMS metadata properties
Property

Description

time

The time the operation was applied on the source.

userid

The ID of the database user that performed the operation.

trans

The ID of the transaction that included the operation.

size

The number of operations in the transaction.

Example
target jms set metadata time, userid, trans, size

To reset the metadata

target target [queue queuename] reset metadata

To view the metadata

target target [queue queuename] show metadata

Control memory settings

If you configured Post to process large amounts of transactions to JMS through multiple named Post queues, you
may need to allocate more memory to the Post JMS bridge. The default settings are 256MB and 512MB.

To increase the JMS bridge memory

Open the openbridge.ini file and set the following parameters in the format shown:

SharePlex 8.6
Administrator Guide

-Xms=512m
-Xmx=1024m
-XX:PermSize=512m
-XX:MaxPermSize=1024m

Configure debugging
You can configure Post to log whether each write to a queue or topic succeeded or failed. This is controlled
with the debugging setting.

To enable debugging
Open the openbridge.ini file and set the -OB_debugToLog parameter to true.
-OB_debugToLog=true

About the XML

The XML format is separated into operation and schema "types" for easier consumption. They are actually the
same when viewed from an XSD perspective and are not distinct types. The template XML represents all
possible attributes and elements. The individual XML represents the bare minimum output for each
supported operation.
After startup, the first time that Post writes a change record for any given table, it first writes a schema record
for that table. Each schema record contains the table name and details of interest for each columns. A schema
record is written only once for each table during a Post run, unless there is a change to that schema, and then
a new schema record is written. If Post stops and starts, schema records are written again, once for each table
as Post receives a change record for it.

Schema record template

<?xml version="1.0" encoding="UTF-8" ?>
<?opentarget version="1.0" ?>
<opentarget>
<txn
id="xs:integer"
oracleTxnId="xs:string"
commitTime="xs:dateTimeStamp" />
<tbl
name="xs:string"
utcOffset="xs:integer"
<cmd ops="schema">
<schema>
<col
name="xs:string"
xmlType="xs:string"
key="xs:boolean"
nullable="xs:boolean"
length="xs:integer"

SharePlex 8.6
Administrator Guide

100

/>
</schema>
</cmd>
</tbl>
</opentarget>

Table 5: Explanation of schema template (* = optional)

Element

Attribute

Description

txn

Transaction metadata

ID of current transaction

oracleTxnId
*

Oracle transaction ID

commitTime
*

Transaction commit timestamp

tbl

Table metadata

name

Fully qualified name of the table

utcOffset

UTC offset in the log

cmd

Operation metadata (In the case of a schema, there are no operations.)

ops

Type of record generated for this table. For a schema, the value is schema.

schema

Column metadata

col

Metadata for a column (One of these elements appears for every record in the
table.)

name

Name of the column

xmlType

XML data type

key

Key flag (true, false)

nullable

Nullable flag

length

Length of the column

Operation record template

<?xml version="1.0" encoding="UTF-8" ?>
<?opentarget version="1.1" ?>
<opentarget>
<txn
id="xs:integer"
msgIdx="xs:integer"
msgTot="xs:integer"
oracleTxnId="xs:string"

SharePlex 8.6
Administrator Guide

101

commitTime="xs:dateTimeStamp"
userId="xs:string" />
<tbl
name="xs:string"
<cmd ops="xs:string">
<row id="xs:string">
<col name="xs:string"></col>
<lkup>
<col name="xs:string"></col>
</lkup>
</row>
</cmd>
</tbl>
</opentarget>
Table 6: Explanation of operation template (* = optional)
Element

Attribute

Description

txn

Transaction metadata for the operation

ID of current transaction

msgIdx

Index of current record in the transaction

msgTot*

Total number of messages in transaction

oracleTxnId
*

Oracle transaction ID, taken from the System Change Number (SCN)

commitTime
*

Transaction commit timestamp

userId *

User ID that performed the operation

tble

Table metadata

name

Fully qualified table name

cmd

Operation metadata

ops

Operation type (insert, update, delete, truncate)

row

Metadata of the row that changed in the operation

Oracle ROWID

col

Change data for a column (One of these elements appears for every changed
column in the operation.)

name

Column name with the after value for that column

lkup

Before image for use in update and delete operations

col

Before image of column (One of these elements appears for every changed column
in the operation.)

name

Column name with the before value or the key value (depending on the operation)
for that column

NOTE:The id and msgIdx attributes together uniquely identify an operation.

SharePlex 8.6
Administrator Guide

102

Supported datatypes
The following table shows how Oracle datatypes are converted to XML.
Oracle type

XML type

BLOB

base64Binary

CHAR

string

CLOB

string

DATE

dateTime

FLOAT

decimal

LONG

string

NCHAR

string

NCLOB

string

NUMBER

decimal

NVARCHAR2

string

RAW

base64Binary

ROWID

string

VARCHAR2

string

INTERVAL YEAR TO MONTH

yearMonthDuration

INTERVAL DAY TO SECOND

dayTimeDuration

TIMESTAMP

dateTime

TIMESTAMP WITH TIME ZONE

dateTimeStamp

TIMESTAMP WITH LOCAL TIME ZONE

dateTimeStamp

Sample XML records

Source table
This is the table for which the sample operations are generated.
SQL> desc products
Name

Null?

Type

PRODUCT_ID

NOT NULL

NUMBER

DESCRIPTION

VARCHAR2(600)

PRICE

NUMBER

Source DML operations

insert into products values (230117, Hamsberry vintage tee, cherry, 4099);
commit;

SharePlex 8.6
Administrator Guide

103

update products set price=3599 where product_id=230117 and price=4099;

commit;
delete products where product_id=230117;
commit;
truncate table products;

Schema record
<?xml version="1.0" encoding="UTF-8"?>
<?opentarget version="1.1"?>
<opentarget>
<txn id="2218316945" commitTime="2014-10-10T13:18:43" userId="85"
oracleTxnId="3.10.1339425" />
<tbl name="MFG.PRODUCTS" utcOffset="-5:00">
<cmd ops="schema">
<schema>
<col name="PRODUCT_ID" xmlType="decimal" key="true" nullable="false" length="22" />
<col name="DESCRIPTION" xmlType="string" key="false" nullable="true" length="600" />
<col name="PRICE" xmlType="decimal" key="false" nullable="true" length="22" />
</schema>
</cmd>
</tbl>
</opentarget>

Insert record
<?xml version="1.0" encoding="UTF-8"?>
<?opentarget version="1.1"?>
<opentarget>
<txn id="2218316945" msgIdx="1" msgTot="1" commitTime="2014-10-10T13:18:43"
userId="85" oracleTxnId="3.10.1339425" />
<tbl name="MFG.PRODUCTS">
<cmd ops="ins">
<row id="AAAmDbAAEAAApRrAAA">
<col name="PRODUCT_ID">230117</col>
<col name="DESCRIPTION">Hamsberry vintage tee, cherry</col>
<col name="PRICE">4099</col>
</row>
</cmd>
</tbl>
</opentarget>

Update record
<?xml version="1.0" encoding="UTF-8"?>
<?opentarget version="1.1"?>
<opentarget>
<txn id="2218318728" msgIdx="1" msgTot="1" commitTime="2014-10-10T13:19:12"
userId="85" oracleTxnId="1.17.970754" />
<tbl name="MFG.PRODUCTS">
<cmd ops="upd">
<row id="AAAmDbAAEAAApRrAAA">
<col name="PRICE">3599</col>

SharePlex 8.6
Administrator Guide

104

Delete record
<?xml version="1.0" encoding="UTF-8"?>
<?opentarget version="1.1"?>
<opentarget>
<txn id="2218319446" msgIdx="1" msgTot="1" commitTime="2014-10-10T13:19:25"
userId="85" oracleTxnId="5.23.1391276" />
<tbl name="MFG.PRODUCTS">
<cmd ops="del">
<row id="AAAmDbAAEAAApRrAAA">
<lkup>
<col name="PRODUCT_ID">230117</col>
</lkup>
</row>
</cmd>
</tbl>
</opentarget>

Truncate record
<?xml version="1.0" encoding="UTF-8"?>
<?opentarget version="1.1"?>
<opentarget>
<txn id="2218319938" commitTime="1988-01-01T00:00:00" userId="85"
oracleTxnId="11.4.939801" />
<tbl name="MFG.PRODUCTS">
<cmd ops="trunc" />
</tbl>
</opentarget>

SharePlex 8.6
Administrator Guide

105

Configure Replication to a SQL or XML

file target
Overview
SharePlex can post replicated Oracle data to a file formatted as SQL or XML. This data is written as a sequential
series of operations as they occurred on the source, which can then be posted in sequential order to a target
database or consumed by an external process or program.
This chapter guides you through the configuration process to support replication to this target.
NOTE: For the platforms, datatypes and operations that are supported when using SharePlex to replicate to a
SQL or XML file, see the SharePlex Release Notes.

Configure SharePlex on the source

On the source, create a SharePlex configuration file that specifies capture and routing information. The
structure that is required in a configuration file varies, depending on your replication strategy, but this shows
you the required syntax for routing data to a SQL or XML file.
Datasource:o.SID
src_owner.table

!file[:tgt_owner.table]

host

where:
l SID is the Oracle SID of the source Oracle database.
l src_owner.table is the owner and name of the source table.
l !file is a required keyword that directs Post to write to a file.
l tgt_owner.table is optional and specifies the owner and name of the target table. Use if either
component is different from that of the source table.
l host is the name of the target system.
NOTE:For complete instructions for creating a configuration file, see Create configuration files.

Source configuration example:

The following example replicates the parts table in schema PROD from Oracle instance ora112 to a file on
target system sysprod.
Datasource:o.ora112
PROD.parts

!file

sysprod

SharePlex 8.6
Administrator Guide

106

Configure SharePlex on the target

To output data in XML format
By default, SharePlex formats data that it writes to a file in XML format, and you do not need to run target
setup unless you want to change properties of the output file (see View and change target settings.)

To output data in SQL format

1. Start sp_cop.
2. Start sp_ctrl.
3. Issue the following required target commands to output the records in SQL. NOTE:Use all lower-case
characters.
target x.file [queue queuename] set format record=sql
target x.file [queuequeuename] set sql legacy=yes
where: queue queuename constrains the action of the command to the SharePlex Post process that is
associated with the specified queue.
These properties are described in View and change target settings, with other optional properties that
you can set.

View and change target settings

To view current property settings for output to a file, use the following command:
target x.file show
To change a setting, use the following target command.
target x.file [queue queuename] set [category] property=value
where: category, property, and value are shown in the following table.
NOTE: For XML output, you can change the file and data properties only.
Table 7: File target properties
Category Property

Input value

Default

file

location
=pathname

Path name under the SharePlex variable-data

directory where you want the file to be created

opx

file

max_
records=number

Maximum size of the file, measured by the number of

records

50,000

file

max_
size=megabytes

Maximum size of the file, measured in megabytes

file

max_
time=seconds

Maximum number of seconds to wait before switching

files

300

file

record_

Maximum size of a record, in number of characters

132

SharePlex 8.6
Administrator Guide

107

Category Property

Input value

Default

length=number
data

date=format

Date format

yyyy-MMddTHH:mm:ss

data

decimal
=character

Decimal character

. (period)

data

enotation
=notation

Exponential notation

data

record={SQL |
XML}

Format of the output records, either SQL or XML

xml

data

timestamp
=format

Timestamp format

yyyy-MMddTHH:mm:ss.ffffffffff

sql

add_rownum=
{yes | no}

yes to include or no to exclude row numbers

add_rownum={yes |
no}

sql

begin_
transaction={yes
| no}

yes to include or no to exclude begin transaction

records

begin_transaction=
{yes | no}

sql

comment
=character

Character that marks a comment

comment=character

sql

concatenate
=character

Character that concatenates strings

concatenate
=character

sql

end_
transaction={yes
| no}

yes to include or no to exclude end transaction

records

end_transaction={yes
| no}

sql

legacy={yes | no} Required in SharePlex 8.6. Use legacy SQL date and
timestamp formatting of:

legacy={yes | no}

MMDDYYYYHH24MISS and
MMDDYYYYHH24MISS.FFFFFF(yes/no)
sql

name_
delimiter
=character

Character that delimits SID, table, owner, column

names

name_
delimiter=character

sql

record_
terminator
=character

Character that terminates the SQL

record_
terminator=character

Command examples
This sets the record format to SQL for a post process with a named queue of myqueue1.
target x.file queue myqueue1 set format record=sql
This sets the maximum file size to contain no more than 320 records.
target x.file queue myqueue1 set file max_size = 320

SharePlex 8.6
Administrator Guide

108

About the SQL

Every transaction in a SQL-formatted file is headed by a comment that includes the transaction sequence
within the SQL file and a unique transaction ID. A comment line at the end of the SQL file has the number of
lines in the file. For example, the following is a SQL file with one transaction. In this example the transaction id
is 2-113319. The file has nine lines.
/installed/vardir> cat opx/0000000010_20140305140820_legacy.sql
-- 0000000001 2-113319 03052014140813 03052014140813
DELETE FROM "ROBIN"."TEST_TYPES" WHERE ORA_NUMBER = '22345' AND ROWNUM = 1;
INSERT INTO "ROBIN"."TEST_TYPES" (ORA_NUMBER, ORA_DATE, ORA_RAW, ORA_ROWID,
ORA_FLOAT, ORA_CHAR, ORA_VARCHAR2, ORA_TIMESTAMP, ORA_TIMESTAMP_TZ,
ORA_TIMESTAMP_LTZ) VALUES('22345', '08132066000000', '0123456789ABCDEF'
, 'AAAAAAAAAAAAAAAAAA', '12350', 'Character ', 'Variable data'
, '10201998021300.22000', '06172002080000.00000', '06172002160000.00000');
COMMIT;
-- EOF 0000000009

About the XML

Schema record template

SharePlex 8.6
Administrator Guide

109

Table 8: Explanation of schema template (* = optional)

Element

Attribute

Description

txn

Transaction metadata

ID of current transaction

oracleTxnId
*

Oracle transaction ID

commitTime
*

Transaction commit timestamp

tbl

Table metadata

name

Fully qualified name of the table

utcOffset

UTC offset in the log

cmd

Operation metadata (In the case of a schema, there are no operations.)

ops

Type of record generated for this table. For a schema, the value is schema.

schema

Column metadata

col

Metadata for a column (One of these elements appears for every record in the
table.)

name

Name of the column

xmlType

XML data type

key

Key flag (true, false)

nullable

Nullable flag

length

Length of the column

Operation record template

<?xml version="1.0" encoding="UTF-8" ?>
<?opentarget version="1.1" ?>
<opentarget>

SharePlex 8.6
Administrator Guide

110

<txn
id="xs:integer"
msgIdx="xs:integer"
msgTot="xs:integer"
oracleTxnId="xs:string"
commitTime="xs:dateTimeStamp"
userId="xs:string" />
<tbl
name="xs:string"
<cmd ops="xs:string">
<row id="xs:string">
<col name="xs:string"></col>
<lkup>
<col name="xs:string"></col>
</lkup>
</row>
</cmd>
</tbl>
</opentarget>
Table 9: Explanation of operation template (* = optional)
Element

Attribute

Description

txn

Transaction metadata for the operation

ID of current transaction

msgIdx

Index of current record in the transaction

msgTot*

Total number of messages in transaction

oracleTxnId
*

Oracle transaction ID, taken from the System Change Number (SCN)

commitTime
*

Transaction commit timestamp

userId *

User ID that performed the operation

tble

Table metadata

name

Fully qualified table name

cmd

Operation metadata

ops

Operation type (insert, update, delete, truncate)

row

Metadata of the row that changed in the operation

Oracle ROWID

col

Change data for a column (One of these elements appears for every changed
column in the operation.)

name

Column name with the after value for that column

lkup

Before image for use in update and delete operations

SharePlex 8.6
Administrator Guide

111

Element

Attribute

Description

col

Before image of column (One of these elements appears for every changed column
in the operation.)

name

Column name with the before value or the key value (depending on the operation)
for that column

NOTE:The id and msgIdx attributes together uniquely identify an operation.

Supported datatypes
The following table shows how Oracle datatypes are converted to XML.
Oracle type

XML type

BLOB

base64Binary

CHAR

string

CLOB

string

DATE

dateTime

FLOAT

decimal

LONG

string

NCHAR

string

NCLOB

string

NUMBER

decimal

NVARCHAR2

string

RAW

base64Binary

ROWID

string

VARCHAR2

string

INTERVAL YEAR TO MONTH

yearMonthDuration

INTERVAL DAY TO SECOND

dayTimeDuration

TIMESTAMP

dateTime

TIMESTAMP WITH TIME ZONE

dateTimeStamp

TIMESTAMP WITH LOCAL TIME ZONE

dateTimeStamp

Sample XML records

Source table
This is the table for which the sample operations are generated.
SQL> desc products
Name

Null?

Type

SharePlex 8.6
Administrator Guide

112

PRODUCT_ID

NOT NULL

NUMBER

DESCRIPTION

VARCHAR2(600)

PRICE

NUMBER

Source DML operations

insert into products values (230117, Hamsberry vintage tee, cherry, 4099);
commit;
update products set price=3599 where product_id=230117 and price=4099;
commit;
delete products where product_id=230117;
commit;
truncate table products;

SharePlex 8.6
Administrator Guide

113

SharePlex 8.6
Administrator Guide

114

File storage and aging

Post writes to a series of files. The active working file is prepended with the label of current_ and is stored in
the opx/current subdirectory of the variable-data directory.
Output Format

Name of Current File

SQL

current_legacy.sql

XML

current_prodsys.XML

IMPORTANT: Do not open or edit the current_ file.

Post uses the max_records, max_size and max_time parameters to determine the point at which to start a
new active file. When this switch occurs, Post moves the processed data to a sequenced file in the opx
subdirectory of the variable-data directory. The file names include the name of the post queue, the time and
date, and an incrementing ID.
SQL files:
/installed/vardir> ls -1 opx
0000000000_20140305130858_legacy.sql
0000000001_20140305131130_legacy.sql
0000000002_20140305131212_legacy.sql
0000000003_20140305133835_legacy.sql
0000000004_20140305134028_legacy.sql
XML files:
/installed/vardir> ls -1 opx
0000000000_20140305130858_prodsys.XML
0000000001_20140305131130_prodsys.XML
0000000002_20140305131212_prodsys.XML
0000000003_20140305133835_prodsys.XML
0000000004_20140305134028_prodsys.XML

To force a file switch

The current file cannot be viewed or consumed without stopping Post. To access the data in the current file,
you can use the target command with the switch option to move the data to a sequenced file, from which it can
then be consumed or viewed. After issuing this command, the switch occurs after Post processes a new record.
target x.file [queue queuename] switch

SharePlex 8.6
Administrator Guide

115

8
Configure a replication strategy

This chapter contains instructions for configuring SharePlex to support different replication objectives.
Production implementations can vary widely from basic configurations with one source and target, to multiple
instances of SharePlex with named queues,multiple targets, partitioned data, and more.
It is difficult to foresee and document every possible way that an organization may want to deploy SharePlex.
The goal of this documentation is to present instructions for setting up the basic deployment types in a way
that is clear enough for you to be able to combine them and expand upon them to suit your needs. Additional
deployment assistance is available through our Professional Services organization.

Contents
Configure replication to share or distribute data
Confgure replication to maintain a central data store
Configure replication to maintain multiple peer databases
Configure replication through an intermediary system
Configure replication to maintain high availability

Configure replication to share or

distribute data
These instructions show you how to set up SharePlex for the purpose of sharing or distributing data from
one source system to one or more target systems. This strategy supports business requirements such as
the following:
l reporting to support real-time decision making
l data sharing to support research and transparency requirements
l data integration throughout an enterprise
l customer service inquiries and other query-intensive applications
l data auditing and archiving

Supported targets
Oracle and non-Oracle targets

SharePlex 8.6
Administrator Guide

116

Capabilities
This replication strategy supports the following:
l Replication to one or more target systems
l Replication between schemas or databases on the same system
l Identical or different source and target names
l Use of vertically partitioned replication
l Use of horizontally partitioned replication
l Use of named export and post queues

Conventions used in the syntax

In the configuration syntax in this topic, the placeholders represent the following:
l source_specification[n] is the fully qualified name of a source object (owner.object) or a wildcarded
specification.
l target_specification[n] is the fully qualified name of a target object or a wildcarded specification.
l host is the name of a system where SharePlex runs. Different systems are identified by appending a
letter to the names, like hostB.
l db is a database specification. The database specification consists of either o. or r. prepended to the
Oracle SID, tns_names alias, or database name, as appropriate for the connection type. A database
identifier is not required if the target is JMS or a file.
IMPORTANT!
l See Create configuration files for more information about the components of a configuration file.

Replicate within the local system

Replication on the same system supports the following configurations:

SharePlex 8.6
Administrator Guide

117

l Within one Oracle instance, replicate to different tables within the same schema or to the same table
in different schemas.
l Replicate to from an Oracle instance to any SharePlex-supported target on the same system.
On the Windows platform, SharePlex does not support replication between Oracle databases that reside on the
same system, but you can replicate to non-Oracle targets on the same system.

Configuration options
Datasource:o.SID

source_specification1

target_specification1

hostA[@db]

source_specification2

target_specification2

hostA[@db]

Example
This example shows how you can replicate data to the same Oracle instance, to a different Oracle instance
(Unix and Linuxonly), and to different target types, all on the same local system.
Datasource:o.oraA
hr.emp
hr.sal
fin.*
act.*

hr.emp2
hr.sal2
fin.*
!file

[email protected]
[email protected]
[email protected]
hostA

Configuration when using SharePlex Manager

Replication from and to the same machine omits an Export process. However, SharePlex Manager expects an
export queue to exist. If using this configuration with SharePlex Manager, you must explicitly configure an
export queue as follows. The hostA* component in the routing map creates the export queue and an Export
process, which sends the data to an Import process, then the post queue.
Datasource:o.SID

source_specification1

target_specification1

hostA*hostA[@db]

source_specification2

target_specification2

hostA*hostA[@db]

Replicate to a remote target system

Configuration options
Datasource:o.SID

source_specification1

target_specification1

hostB[@db]

source_specification2

target_specification2

hostB[@db]

Example
The last line in this example shows how you can replicate data to different target types on the same remote
target system.

SharePlex 8.6
Administrator Guide

118

Datasource:o.oraA
hr.emp
hr.sal
fin.*

hr.emp2
hr.sal2
!file

[email protected]
[email protected]
hostB

Replicate to multiple target systems

This topology is known as broadcast replication. It provides the flexibility to distribute different data to
different target systems, or all of the data to all of the target systems, or any combination as needed. It
assumes the source system can make a direct connection to all of the target systems. All routing is handled
through one configuration file.
See also Configure replication through an intermediary system.

Configuration options
If the target specification is identical on all targets
If the target specification of a source object is identical on all target systems, you can use a compound routing
map, rather than type a separate entry for each route. See Create configuration files for more information
about target specifications.
Datasource:o.SID

source_specification1

target_specification1

hostB[@db]+hostC[@db][+...]

source_specification2

target_specification2

hostC[@db]+hostD[@db][+...]

If the target specification is not identical on all targets

l When the target specification of a source object is different on some or all target systems, you must use
a separate configuration entry to specify each one that is different.
l You can use a compound routing map for routes where the target specifications are identical.
Datasource:o.SID

source_specification1

target_specification1

hostB[@db]

source_specification1

target_specification2

hostC[@db]

Example
NOTE: The last entry in this example shows the use of horizontally partitioned replication to distribute
different data from the sales.accounts table to different regional databases. See Configure horizontally
partitioned replication.
Datasource:o.oraA
hr.emp
hr.emp
hr.emp
cust.%
sales.accounts

hr.emp2
hr."Emp_3"
!jms
cust.%
sales.accounts

[email protected]
[email protected]
hostX
[email protected][email protected]
!regions

SharePlex 8.6
Administrator Guide

119

Confgure replication to maintain a

central data store
These instructions show you how to set up SharePlex for the purpose of consolidated replication: replicating
from multiple source systems to one central target system. This strategy supports business requirements such
as the following:
l Real-time reporting and data analysis
l The accumulation of big data into a central data store/mart or warehouse

Supported targets
Oracle and non-Oracle targets

Capabilities
This replication strategy supports the following:
l Identical or different source and target names
l Use of vertically partitioned replication
l Use of horizontally partitioned replication
l Use of named export and post queues

Requirements
l Prepare the system, install SharePlex, and configure database accounts according to the instructions in
the SharePlex Installation Guide.
l Prepare the environment for replication. See Prepare an Oracle environment for replication.
l No DML or DDL should be performed on the target tables except by SharePlex. Tables on the target
system that are outside the replication configuration can have DML and DDL operations without affecting
replication.
l Each source system must replicate a different set of data to the central target. If any source systems
replicate the same data to the central target system, it is considered to be active-active replication,
and conflict resolution routines must be used to determine which source "wins" when the same row is
updated from two different sources at the same time. To establish active-active replication, see
Configure replication to maintain multiple peer databases.

Deployment options
You have two options for deploying SharePlex to replicate from many source systems to one target system.
l Deploy with one instance of SharePlex on the target system
l Deploy with multiple instances of SharePlex on the target system

SharePlex 8.6
Administrator Guide

120

In either deployment, if any source system cannot make a direct connection to the target system, you can use
cascading replication for that route to enable SharePlex to cascade the data an intermediary system that
allows connection to the target. See Configure replication through an intermediary system.
NOTE: The SharePlex compare and repair commands cannot be used in a cascading configuration.

Deploy with one instance of SharePlex on the

target system
You can use one instance of SharePlex to process all incoming data on the target. For each source system,
SharePlex creates an Import process on the central target system when replication starts. That, in turn,
creates post queues and Post processes for each source-target replication stream, all controlled by one sp_cop
process. You can control each source-target stream separately, but the post queues all share the same
SharePlex variable-data directory on the target system.
A deployment with a single variable-data directory has the following potential risks:
l An event that interrupts processing to and from the disk that contains the variable-data directory will
affect all replication streams.
l Any cleanup utilities that you use will affect all of the replication streams, because the cleanup is
performed across the entire variable-data directory.
l A purge config command that is issued on one source system also deletes the data that is replicated
from the other source systems, because the purge affects the entire variable-data directory. The use of
named post queues eliminates this risk, but adds complexity to the naming, monitoring and
management of the SharePlex objects in the deployment.

To use this deployment

l Install SharePlex in the normal manner, with one port number and one variable-data directory on each
system (sources and target).
l Make certain that when you install SharePlex, you create a database account for SharePlex for each
installation.
l IMPORTANT! Use the same port number for SharePlex on all systems.

SharePlex 8.6
Administrator Guide

121

Deploy with multiple instances of SharePlex on the

target system
You can deploy multiple instances of SharePlex on the target, one for each source system. A SharePlex
instance is composed of the following elements:
l A unique sp_cop process
l A unique variable-data directory
l A unique port number on which sp_cop runs
l A unique database account that the processes of that instance use to interact with the database.
By running multiple, distinct instances of SharePlex, you can isolate each source-target replication stream from
the others. It enables you to:
l Avoid contention problems that can occur if multiple processes must compete for access to the same
queues in a single variable-data directory.
l Purge one configuration, or clean up and resynchronize one replication stream, while allowing the
others to continue processing data.
l Place the variable-data directories on separate disks so that problems with one disk do not affect the
variable-data directories on the other disks.

To use this deployment

Install on the target system first, if possible. This enables you to establish a port number for each variable-data
directory, which you can then refer to when you set up SharePlex on the corresponding source system.

Steps on the target system

Select either of the options presented in Run multiple instances of SharePlex to establish independent
instances of SharePlex on the target. If you already installed SharePlex on the target and an original variabledata directory, database account, and port number exist, you can dedicate that instance to one of the source
systems, and then create additional instances on the target per those instructions.

Steps on the source systems

Install one instance of SharePlex on each source system, as directed in the SharePlex Installation Guide. Match
the port numbers of those instances to the port numbers of their associated target variable-data directories. If

SharePlex 8.6
Administrator Guide

122

you already installed SharePlex on the source systems, you can change the port numbers as needed. See Set
the SharePlex port number.

Configuration
Create a configuration file on each source system that replicates the objects from that system to the central
target. For more information about creating a configuration file, see Create configuration files.
Datasource:o.SID

source_specification

target_specification

central_host[@db]

where:
l SID is the Oracle SID of the source Oracle database. This specification can also be a tns_alias if capturing
from a RAC cluster or a PDB.
l source_specification is the fully qualified name of a source object (owner.object) or a wildcarded
specification.
l target_specification is the fully qualified name of a target object (owner.object) or a wildcarded
specification.
l central_host is the target system.
l db is a database specification. The database specification consists of either o. or r. prepended to the
Oracle SID, tns_names alias, or database name, as appropriate for the connection type. A database
identifier is not required if the target is JMS or a file.

Example
This example is an Oracle example, but the target can be any supported SharePlex target. The example shows
data from datasource oraA on hostA and datasource oraB on hostB replicating to oraC on system hostC.

Data from hostA

Datasource:o.oraA
hr.*
fin.*

hr.*
fin*

[email protected]
[email protected]

hr.*
mfg.*

[email protected]
[email protected]

Data from hostB

Datasource:o.oraA
cust.*
mfg.*

Recommended target configuration

Each source system in a consolidated configuration sends a discrete data stream that flows to its own Post
process on the target. You can assign a unique identifier of your choosing to each source system, and then
configure the Post process to include that identifier in each insert or update that it posts on the target.
By identifying rows in this manner, your environment is prepared to support the SharePlex compare and repair
commands (which require a source ID) as well as any other work that may require the selection or identification

SharePlex 8.6
Administrator Guide

123

of rows by their source. The compare and repair processes will use the source ID value to select only the rows
that are valid for that source.

To configure each Post to write a source ID

1. Create or alter the target table to include a column named SHAREPLEX_SOURCE_ID. This is the column
that will contain the source ID value.
NOTE: You can change this name by running the target command with the set metadata option, before
continuing further. See target for more information.
2. Choose a unique ID for each of the source systems. Any single alphanumeric string is permitted.
3. On the target, run sp_ctrl for each Post process.
4. For each Post process, issue the target command with the set source option. This command sets the
source ID that will be posted by that Post process. The following example shows the command for three
Post processes:
sp_ctrl> target sys4 queue Q1 set source east
sp_ctrl> target sys4 queue Q2 set source central
sp_ctrl> target sys4 queue Q3 set source west

Configure replication to maintain multiple

peer databases
These instructions show you how to set up SharePlex for the purpose of maintaining multiple databases where
applications on each system can make changes to the same data, while SharePlex keeps all of the data
synchronized through replication. This is known as peer-to-peer, or active-active, replication. In this strategy,
the databases are usually mirror images of each other, with all objects existing in their entirety on all systems.
Although similar in benefit to a high-availability strategy, the difference between the two is that peer-to-peer
allows concurrent changes to the same data, while high availability permits changes to the secondary database
only in the event that the primary database goes offline.
This strategy supports the following business requirements:
l Maintain the availability of mission-critical data by operating multiple instances in different locations.
l Distribute heavy online transaction processing application (OLTP) loads among multiple points of access.
l Limit direct access to an important database, while still enabling users outside a firewall to make
updates to their own copies of the data.
An example of peer-to-peer replication is an e-commerce company with three identical databases. When users
access the application from a web browser, the web server connects to any of those databases sequentially in a
round-robin configuration. If one of the databases is unavailable, the server connects to a different available
database server. Thus the configuration serves not only as a failover resource, but also as a means of
distributing the load evenly among all the peers. Should the company need to produce business reports, user
access to one of the databases can be stopped temporarily, and that database can be used to run the reports.
NOTE: Data changes made in peer-to-peer replication are prevented from looping back from one
machine to another because Capture ignores transactions performed on the local system by the
Post process.

SharePlex 8.6
Administrator Guide

124

Peer-to-peer replication is not appropriate for all replication environments. It requires a major commitment to
database design that might not be practical when packaged applications are in use. It also requires the
development of conflict resolution routines to prioritize which transaction SharePlex posts to any given
database if there are multiple changes to the same data at or near the same time.

Supported targets
Oracle targets

Capabilities
This replication strategy supports the following:
l Use of named export and post queues
This replication strategy does not support the following:
l Replication of LOBs. If tables with LOBs are included in replication the LOBs will be bypassed by conflict
resolution, causing the potential for data to be out of synchronization.
l Column mapping and partitioned replication is not appropriate in a peer-to-peer configuration.

Requirements
l Tables involved in peer-to-peer replication must have primary keys, and each key must be unique
among all of the databases that will be involved in replication.
l Enable archive logging on all systems.
l Prepare the environment for replication. See Prepare an Oracle environment for replication.
l You must understand the concepts of synchronization as outlined in Understand the concept of
synchronization.

Overview
In peer-to-peer replication, DML changes are allowed on copies of the same tables in different databases,
usually on different systems, while SharePlex keeps them all current through replication. If a record is
changed in more than one database at (or near) the same time, conflicts can occur, and conflict-resolution logic
must be applied to resolve the discrepancy.

What is a conflict?
A conflict is defined as an out-of-sync condition source and target tables are not identical. You can predict
that out-of-sync (conflict) situations will occur when a DML statement constructed by SharePlex fails to
execute on a row in the target table because of the following reasons:
l An INSERT is performed on the source data, but the row already exists in the target data when Post
attempts to apply the replicated INSERT. If Post attempts to insert a row that already exists in the
target table, based on the value of the key, it causes an error. The INSERT fails, and Post returns an out-

SharePlex 8.6
Administrator Guide

125

of-sync error.
l An UPDATE is performed on the source data, but one of the following occurs: the before image of the
source row (the values before the change) in the WHEREclause used by Post does not match the
current image of any row in the target (before the posting), or Post cannot locate the target row with a
key that matches the source key.
l A DELETEis performed on the source data, but Post cannot locate the target row by using the key. When
Post constructs its DELETE statement, it includes only the key value in its WHERE clause.

What causes a conflict in peer-to-peer replication?

To understand how SharePlex determines a conflict, refer to the following examples of normal and conflict
situations. In the examples, three systems (SysA, SysB and SysC) are used.
The following tables are used in the example:
Scott.employee_source
jane.employee_backup
The column names and definitions are identical:
EmpNo
SocSec
EmpName
Job
Salary
Dept

number(4) not null,

number(11) not null,
char(30),
char(10),
number(7,2),
number(2)

The values for both tables in a synchronized state are:

EmpNo (key)

SocSec

EmpName

Job

Salary

Dept

111-22-3333

Mary Smith

Manager

50000

111-33-4444

John Doe

Data Entry

20000

000-11-2222

Mike Jones

Assistant

30000

000-44-7777

Dave Brown

Manager

45000

Example of peer-to-peer replication without a conflict

1. At 9:00 in the morning, UserA on SysA changes the value of the Dept column to 2, where EmpNo is 1.
SharePlex replicates that change to SysB and SysC, and both databases remain synchronized.
2. At 9:30 that same morning, UserB on SysB changes the value of Dept to 3, where EmpNo is 1. SharePlex
replicates that change to SysA and SysC, and the databases are still synchronized.
Now the row looks like this:
EmpNo (key)
1

SocSec
111-22-3333

EmpName
Mary Smith

Job
Manager

Salary
50000

Dept
3

Example of peer-to-peer replication with an UPDATE conflict

1. At 11:00 in the morning, UserA on SysA updates the value of Dept to 1, where EmpNo is 1. At 11:02 that
morning, the network fails. Captured changes rest in the export queues on all systems.

SharePlex 8.6
Administrator Guide

126

2. At 11:05 that morning, before the network is restored, UserB on SysB updates the value of Dept
to 2, where EmpNo is 1. The network is restored at 11:10 that morning. Replication data
transmission resumes.
3. When SharePlex attempts to post the change from UserA to the database on SysB, it expects the value
in the Dept column to be 3 (the pre-image), but the value is 2 because of the change made by UserB.
Because the pre-images do not match, SharePlex generates an out-of-sync error.
4. When SharePlex attempts to post the change from UserB to SysA, it expects the value of the
column to be 3, but the value is 1 because of the change made by UserA. SharePlex generates an
out-of-sync error.
5. When SharePlex attempts to post the changes made by UserA and User B to the database on SysC,
both of those statements fail because the pre-images do not match. SharePlex generates an outof-sync error.
NOTE: See Appendix A: Peer-To-Peer Diagram in the appendixes for a visual representation of this scenario.

Deployment
To deploy peer-to-peer replication, perform the following tasks:
1. Evaluate the data for suitability to a peer-to-peer environment. Make any recommended alterations.
2. Configure replication so that data from each system replicates to all other systems in the peer-to-peer
environment.
3. Develop conflict resolution routines that direct the action of the Post process when there is a conflict
because Post cannot locate a row, or when a row that needs to be changed already was changed.
4. List the routines in conflict_resolution.SID. SharePlex refers to this file to determine the correct
procedure to use when a conflict occurs.

Evaluate the data

To successfully deploy SharePlex in a peer-to-peer configuration, you must be able to:
l isolate keys
l prevent changes to keys
l control sequence generation
l control trigger usage
l eliminate cascading deletes
l designate a trusted host
l define priorities
These requirements must be considered during the architectural phase of the project, because they demand
cooperation with the application. Consequently, many packaged applications are not suitable for a peer-topeer deployment because they were not created within those guidelines.
Following are more detailed explanations of each of the requirements.

SharePlex 8.6
Administrator Guide

127

Keys
The only acceptable key in peer-to-peer replication is a primary key. If a table has no primary key but has a
unique, not-NULL key, you can convert that key to a primary key. LONG columns cannot be part of the key.
If you cannot assign a primary key, and you know all rows are unique, you can create a unique index
on all tables.
The primary key must be unique among all of the databases in the peer-to-peer replication network, meaning:
l it must use the same column(s) in each corresponding table in all databases.
l key columns for corresponding rows must have the same values.
The primary key must be created to contain enough information about a row so there can be no question about
the uniqueness of that row, and so that there will be a conflict if a replicated operation would violate
uniqueness. Additionally, the primary key value cannot be changed.
Using only a sequence as the primary key probably will not suffice for peer-to-peer replication. For example,
suppose the sample table uses sequences to generate values for key column EmpNo. Suppose UserA gets the
next sequence value on SysA and inserts a row for Jane Wilson. UserB gets the next sequence value on SysB
and also inserts a row for Jane Wilson. Even if the sequence numbers are different on each system, so there
are no unique key violations on the replicated INSERTs, data integrity is compromised because there are now
two entries for Jane Wilson in the databases, each with a different key. Subsequent UPDATEs will fail. The
solution is to include other unique columns in the key, so that there is enough information to ensure
uniqueness and ensure a conflict that can then be resolved through resolution logic.

Sequences
SharePlex does not support peer-to-peer replication of sequences. If the application uses sequences to
generate all or part of a key, there must be no chance for the same range of values to be generated on any
other system in the peer-to-peer configuration. You can use a sequence server or you can maintain sequences
separately on each server and make sure you partition a unique range to each one. Dell recommends using n+1
sequence generation (where n = the number of systems in replication). Depending on the type of application,
you can add a location identifier such as the system name to the sequence value in the primary key to enforce
uniqueness.

Triggers
DML changes resulting from triggers firing on a source system enter the redo log and are replicated to the
target system by SharePlex. If the same triggers fire on the target system, they return out-of-sync errors.
To handle triggers in a peer-to-peer configuration, you can do either of the following:
l Disable the triggers.
l Keep them enabled, but alter them to ignore the SharePlex user on all instances in the peer-to-peer
configuration. SharePlex provides the sp_add_trigger.sql script for this purpose. This script puts a
WHEN clause into the procedural statement of the trigger that tells it to ignore the Post process. For
more information about triggers and this script, see Set up Oracle database objects for replication.

ONDELETECASCADEconstraints
ONDELETECASCADEconstraints can remain enabled on all instances in the peer-to-peer replication
configuration, but you must set the following parameters to direct Post to ignore those constraints:

SharePlex 8.6
Administrator Guide

128

l SP_OPO_DEPENDENCY_CHECK parameter to 2
l SP_OCT_REDUCED_KEY parameter to 0
l SP_OPO_REDUCED_KEY parameter to 0 or 1

Balance values maintained by using UPDATEs

Applications that use UPDATE statements to record changes in quantity, such as inventory or account balances,
pose a challenge for peer-to-peer replication. The following example of an online bookseller explains the
reason why.
The booksellers Inventory table contains the following columns.
Book_ID (primary key)
Quantity
Suppose the following sequence of events takes place:
1. A customer buys a book through the database on one server. The quantity on hand reduces from 100
books to 99. SharePlex replicates that UPDATE statement to the other server. (UPDATE inventory SET
quantity = 99 WHERE book_ID = 51295).
2. Before the original UPDATE arrives, another customer buys two copies of the same book on another
server (UPDATE inventory SET quantity = 98 WHERE book_ID = 51295), and the quantity on that server
reduces from 100 books to 98.
3. When the Post process attempts to post the first transaction, it determines that the pre-image (100
books) on the first system does not match the expected value on the second system (it is now 98 as a
result of the second transaction). Post returns an out-of-sync error.
A conflict resolution procedure could be written, but how would the correct value be determined? The correct
value in both databases after the two transactions should be 97 books, but no matter which of the two UPDATE
statements is accepted, the result is incorrect.
For this reason, peer-to-peer replication is not recommended for applications maintaining account or inventory
balances using UPDATEs. If you can use a debit/credit method of maintaining balances, you can use INSERT
statements (INSERT into inventory values n,...) instead of UPDATE statements. INSERT statements do not
require a before-and-after comparison with a WHERE clause, as do UPDATE statements.
If your application must use UPDATE statements, you can write a conflict resolution procedure to determine
the absolute (or net) change resulting from different UPDATE statements on different systems. For example, in
the case of the preceding online bookseller example, when the first customers purchase is replicated to the
second system, the following conflict resolution procedure fires:
if existing_row.quantity <> old.quantity then old.quantity - new.quantity = quantity_change;
update existing_row set quantity = existing_row.quantity - quantity_change;
The conflict resolution logic tells SharePlex that, if the quantity value of the existing row in the target
database (98) does not equal the old value (pre-image of 100), then subtract the new value (the replicated
value of 99) from the pre-image to get the net change (1). Then, issue an UPDATE statement that sets the
Quantity column to 98-1, which equals 97.
When the second users change is replicated to the first system, the same conflict resolution procedure fires.
In this case, the net change (pre-image of 100 minus the new value of 98) is 2. The UPDATE statement on this
system also results in a value of 97, which is 99 (the existing row value after the first customers purchase)
minus the net change of 2. The result of this procedures logic is that the Quantity columns on each system are
updated to 97 books, the net effect of selling three books.
The following example illustrates this concept using an account balance within a financial record:

SharePlex 8.6
Administrator Guide

129

account_number (primary key)

balance
1. Suppose a row (an account) in the example table has a balance of $1500 on SysA. CustomerA makes a
deposit of $500 on that system. The application uses an UPDATE statement to change the balance to
$2000. The change is replicated to SysB as an UPDATE statement (such as UPDATE...SET balance=$2000
WHERE account_number=51295).
2. Before the change arrives, CustomerAs spouse makes a withdrawal of $250 on SysB, and the application
updates the database on that system to $1250. When CustomerAs transaction arrives from SysA and Post
attempts to post it to SysB, there is a conflict, since the pre-image from the source system is $1500, but
the pre-image on the target is $1250 because of the spouses transaction not a match.
You can write a conflict resolution routine to accommodate this kind of transaction by calculating the absolute
(or net) change in the account, then using that value to resolve the conflict. For example:
if existing_row.balance <> old.balance then old.balance - new.balance = balance_change; update
existing_row set balance = existing_row.balance - balance_change;
The result of this procedure would be to update the account balance to $1750, the net effect of depositing
$500 and withdrawing $250. On SysB, the routine directs SharePlex to subtract the new (replicated) balance of
2000 from the old balance of 1500 for a net change of -500. The UPDATE statement sets the balance value to
1250 - (-500) = 1750, the correct value.
On SysA, the replicated value of 1250 is subtracted from the old balance of 1500 to get the net change of 250.
The UPDATE statement subtracts that value from the existing balance of 2000 to get the correct value of 1750.

Priority
When the environment is established to avoid or resolve conflict when SharePlex searches for the correct
row to change, the only remaining conflict potential is on fact data which change to accept when the
values for the same column in the same row differ on two or more systems. For this, your application must
be able to accept the addition of timestamp and source columns, with source being the name of the local
system for the table.
The following explains how those columns play a vital role when using a conflict resolution routine to
establish priority.

Trusted source
You must assign a particular database or server to be the prevailing, or trusted, source for two reasons:
l The conflict resolution routine has the potential to get quite large and complex the more systems you
have. There are bound to be failures that require resynchronization at some point. One of the systems
in the configuration must be considered the true source from which all other systems will be
resynchronized if necessary.
l You can write your conflict resolution routines so that operations from the trusted source system take
priority over conflicting operations from other systems. For example, changes on the server at corporate
headquarters could take priority over the same changes made by a branch office.

Timestamp
It is recommended that you include a timestamp column in the tables and assign priority in the conflict
resolution routine to the earliest or latest timestamp. However, the timestamp must not be part of a key, or it
will cause conflicts. SharePlex cannot locate rows if a key value changes and the key value will change if one
of the columns is a timestamp.

SharePlex 8.6
Administrator Guide

130

For timestamp priority to work, you must make sure all of the servers involved agree on the date and time.
Tables on servers in different time zones can use Greenwich Mean Time (GMT).
The default date format for SharePlex conflict resolution is MMDDYYYY HH24MISS. Tables with default dates
must use that format, or conflict resolution will return errors. Before creating a table with a default date, use
the following command to change the date format in SQL*Plus.
ALTER SESSION SET nls_date_format = 'MMDDYYYYHH24MISS'

Configure replication
The configuration files on the systems in a peer-to-peer configuration are identical with the exception of the
datasource specification and the routing.

Conventions used in the syntax

In the configuration syntax in this topic, the placeholders represent the following items in the environment.
This documentation assumes three systems, but there can be more.
l hostA is the first system.
l hostB is the second system.
l hostC is the third system.
l ownerA.object is the fully qualified name of an object on hostA or a wildcarded specification.
l ownerB.object is the fully qualified name of an object on hostB or a wildcarded specification.
l ownerC.object is the fully qualified name of an object on hostC or a wildcarded specification.
l oraA is the Oracle instance on hostA.
l oraB is the Oracle instance on hostB.
l oraC is the Oracle instance on hostC.
IMPORTANT!
l See Create configuration files for more information about the components of a configuration file.

Configuration on hostA
Datasource:o.oraA

ownerA.object

ownerB.object

[email protected]

ownerA.object

ownerB.object

[email protected]

ownerA.object

ownerC.object

[email protected]

ownerA.object

ownerC.object

[email protected]

Note:If all owner names and table names are the same on all systems, you can use a compound routing map for
each of these configuration files. For example, the compound routing for replication from hostA is as follows:
Datasource:o.oraA
owner.object

owner.object

[email protected][email protected]

SharePlex 8.6
Administrator Guide

131

Configuration on hostB
Datasource:o.oraB

ownerB.object

ownerA.object

[email protected]

ownerB.object

ownerA.object

[email protected]

ownerB.object

ownerC.object

[email protected]

ownerB.object

ownerC.object

[email protected]

Configuration on hostC
Datasource:o.oraC

ownerC.object

ownerA.object

[email protected]

ownerC.object

ownerA.object

[email protected]

ownerC.object

ownerB.object

[email protected]

ownerC.object

ownerB.object

[email protected]

Example
Datasource:o.oraA
hr.emp
hr.sal
cust.%

hr.emp
hr.sal
cust.%

[email protected]
[email protected]
[email protected]

Develop conflict resolution routines

To create conflict resolution routines, you write PL/SQL procedures that direct the action of SharePlex when a
conflict occurs. Business rules vary widely from company to company, so it is impossible to create a standard set
of conflict resolution rules and syntax that apply in every situation. You will probably need to write your own
routines. It is good practice to write more than one procedure, such as making site or system priority the
primary routine and timestamp a secondary routine. SharePlex invokes one routine after another until one
succeeds or there are no more procedures available.
SharePlex provides the following tools that can be used as a basis for your routines:
l A generic PL/SQL interface that you can use to write basic routines based on DML operation types. See
How to write a routine using the SharePlex generic interface.
l Packaged routines that perform basic conflict resolution based on a key or column value, which can be
used as a backup measure in case the custom routines fail. See How to use use the SharePlex
prepared routines.
IMPORTANT!
l This documentation provides guidelines, examples and templates to assist you, but do not use them as
your own routines.
l Test your conflict resolution routines before you put them into production to make sure they work as
intended, and to make sure that one routine does not counteract another one.

SharePlex 8.6
Administrator Guide

132

l By default, SharePlex does not stop for out-of-sync conditions. If failed attempts at conflict resolution
are not resolved, the databases can become more and more out of synchronization. Check the Event Log
frequently to monitor for out-of-sync warnings by using the show log command in sp_ctrl. See the
SharePlex Reference Guide for more information about show log and other SharePlex commands.
l Updates are occasionally made to the conflict resolution logic, so refer to the Release Notes and
documentation for your version of SharePlex for any additional information that augments or supersedes
these instructions.

How to write a routine using the SharePlex generic interface

SharePlex provides a generic conflict resolution PL/SQL package that can be used to pass information to and
from the procedural routines that you write. Before you get started, understand the following guidelines:
l The same PL/SQL package is used for both generic conflict resolution and transformation (its name is sp_
cr). Use either generic conflict resolution or transformation for a table, but not both. Transformed
tables cannot be compared by SharePlex and conflict resolution cannot succeed. If both are used,
SharePlex only calls the transformation routine. If appropriate, you can use generic conflict resolution
and transformation for different tables in the same configuration. For more information about
transformation, see Transform data.
l Conflict resolution cannot be used for DDL changes.
l Any table to be accessed through PL/SQL for conflict resolution requires implicitly granted privileges
from the owner of the object to SharePlex.
l Conflict resolution does not support changes to LONG or LOB columns.
NOTE: If you ran the SharePlex conflict resolution demonstration in the SharePlex Installation Guide, you can
view a sample generic conflict resolution routine by viewing the od_employee_gen routine that was installed
in the database used for the demonstration.

Procedure interface
Follow this template to create your procedure.
(table_info in outsplex.sp_cr.row_typ, col_values insplex.sp_cr.col_def_tabtyp)
where:
l splex is the SharePlex schema.
l sp_cr is the name of the package that contains the PL/SQL record and table structures.
l row_typ is the name of the PL/SQL record that passes in/out variables (see Package definition).
l col_def_type is the name of the PL/SQL table that stores column information (see col_def_type table).

SharePlex 8.6
Administrator Guide

133

"source_rowid VARCHAR2(20),
"target_rowid VARCHAR2(20),
"statement_type VARCHAR2(6),
"source_table VARCHAR2(78),
"target_table VARCHAR2(78), \n\t"
"oracle_err NUMBER,
"status NUMBER,
"action NUMBER,
"reporting NUMBER
");

IN variables
For each row operation that causes a conflict, SharePlex passes this metadata information to your procedure.
Variable

Description

src_host

The name of the source system (where the operation occurred). It is

case-sensitive and is passed using the same case as on the source
system, for example SysA . If there are named post queues in use on the
target system, this variable consists of the name of the post queue, for
example postq1.

src_ora_sid

The ORACLE_SID of the source database. It is case-sensitive and is passed

in the same case as in the oratab file, Windows Registry or V$PARAMETER
table.

src_ora_time

The timestamp of the change record in the source redo log.

source_rowid

The row ID of the source row. It is passed as a literal within single

quotes, for example 123456.

target_rowid

The row ID of the corresponding row in the target database. SharePlex

obtains the row ID by querying the target database. It is passed as a
literal within single quotes, for example 123456. If the row cannot be
found using the PRIMARY key, the value is NULL.

statement_type

A letter, either I, U or D, indicating whether the operation is an INSERT,

UPDATE or DELETE statement.

source_table

The owner and name of the source table, expressed as owner.table.

This value is case-sensitive and matches the way the table is named in
the database. It is passed within double quotes, for example
"scott"."emp."

target_table

The owner and name of the target table, expressed as owner.table. This
value is case-sensitive and matches the way the table is named in the
database. It is passed within double quotes, for example "scott"."emp."

oracle_err

This is different, depending on whether the procedure is being used for

conflict resolution or transformation.
Transformation: SharePlex passes a value of 0 for this variable. This
variable is only used for conflict resolution.
Conflict resolution: The Oracle error number that caused the conflict.

OUT variables
These variables direct the action of SharePlex based on whether the procedure succeeded or failed).

SharePlex 8.6
Administrator Guide

134

Variable

Description

status

Defines whether or not the procedure succeeded. You must specify a

value for this parameter.
l A value of 0 implies successful execution. It acts differently,
depending on whether the procedure is used for conflict
resolution or transformation.
Transformation: Post does not write any SQL. SharePlex does not
write any error messages to the Event Log when transformation
succeeds. It continues its processing by reading the next
replicated operation in the post queue.
l Conflict resolution: A value of 0 directs SharePlex to proceed
with the SQL statement. SharePlex does not write any log
entries to the Event Log when conflict resolution succeeds.
l A value of 1 implies that the procedure was unsuccessful. In this
case, the action SharePlex takes depends on what you specified
as the action variable.
l (Transformation only) A value of 7 implies unsuccessful
execution and instructs the Post process to stop.

action

Defines the action that you want SharePlex to take. This is different,
depending on whether the procedure is used for transformation or
conflict resolution.
Transformation: You must specify a value of 0 for this parameter, which
directs SharePlex NOT to post the SQL statement. Your transformation
routine is responsible for posting the results of the transformation
either to the target table or another table. The outcome of this action
depends on what you specify for the reporting variable
Conflict resolution: Specifies the action to take as a result of an
unsuccessful conflict resolution procedure. You must specify a value for
this parameter.
l A value of 0 directs SharePlex NOT to post the SQL statement.
The outcome of this action depends on what you specify for the
reporting variable.
l The value of 1 is reserved for internal SharePlex use. Do not use
it.
l A value of 2 directs SharePlex to try the next conflict resolution
procedure that you listed in the conflict resolution file, if one
exists.

reporting

Determines how SharePlex reports unsuccessful procedural results. You

SharePlex 8.6
Administrator Guide

135

Variable

Description
l A value of 3 directs SharePlex to write the failed SQL statement
to the SID_errlog.sql log and report an error to the Event Log.

col_def_type table
SharePlex creates a col_def_tabtyp PL/SQL table for each replicated operation. This table stores column
information. It is different depending on whether the procedure is used for transformation or conflict
resolution.
l Transformation: For each row operation, SharePlex writes column information to col_def_type.
l Conflict resolution: For each row operation that causes a conflict, SharePlex writes column information
to col_def_tabtyp.
All fields are passed by SharePlex to your routine, although not all will have values if SharePlex cannot
locate the row.
Following is the datatype that is used to populate the col_def_tabtyp table.
type col_def_typ is record
(column_name
user_tab_columns.column_name%type
,datatype
user_tab_columns.datatype%type
,is_key boolean
,is_changed
boolean
,old_value
varchar2(32764)
,new_value
varchar2(32764)
,current_value varchar2(32764)
);
type col_def_tabtyp is table of col_def_typ

Description of col_def_tabtyp
Column

Description

column_name

Tells your procedure the name of the column that was replicated from
the source table, for example emp_last_name. This value is not casesensitive.

datatype

Tells your procedure the datatype of the data in the replicated column,
for example VARCHAR2. This value is always in capital letters.

is_key

Tells your procedure whether or not the column is a key column. If it is

a key column, SharePlex passes a value of TRUE. If the column is not
part of a key, SharePlex passes a value of FALSE.

is_changed

SharePlex 8.6
Administrator Guide

136

Column

Description
a value for a changed key column.
Conflict resolution only: If a key value also was changed on the
target system, SharePlex will not be able to locate the correct
row, and conflict resolution could fail.
l For DELETEs, is_changed is always FALSE, because SharePlex
replicates only the key values for a DELETE statement.

old_value

Tells your procedure the old value of the replicated column, before it
was changed on the source system. This column is NULL for INSERTs,
because the row did not exist in the target database before the INSERT.
Conflict resolution only: This is the pre-image against which SharePlex
compared the source and target columns as part of its synchronization
check for UPDATEs and DELETEs. If the old value passed by SharePlex
does not match the current_value value obtained from the target row,
then there is a conflict.

new_value

Tells your procedure the new value of the replicated column, as

changed on the source system.

current_value

Tells your procedure the current value of the column in the target
table. If SharePlex cannot locate the target row, the value is NULL .

Example entries in col_def_tabtyp table per operation type

The following tables illustrate the possible outcomes of each type of operation.

INSERT operation
column_name

is_changed

old_value

new_value

current_value1

is_key

TRUE

NULL

bind

NULL

FALSE

TRUE

NULL

bind

NULL

TRUE

FALSE

NULL

TRUE | FALSE

1 When

an INSERT fails, it is because a row with the same PRIMARY key already exists in the target database.
SharePlex does not return the current value for INSERTs.

UPDATE operation
column_name

is_changed

old_value

new_value

current_value1, 2

is_key

TRUE

bind

NULL | target_value

FALSE

bind

NULL

NULL | target_value

TRUE

bind

NULL | target_value

TRUE

1 (Conflict

resolution) When an UPDATE fails, it is because SharePlex cannot find the row by using the PRIMARY
key and the pre-image. If the row cannot be found, SharePlex searches for the row by using only the PRIMARY
key. If SharePlex finds the row, it returns the current value for the key column as well as the changed
columns. If SharePlex cannot find the row by using just the PRIMARY key, then SharePlex returns a NULL.

SharePlex 8.6
Administrator Guide

137

2 (Transformation) For

an UPDATE, SharePlex cannot locate a row using the PRIMARY key and the pre-images,
because the pre-images are different due to transformation. As an alternative, it searches for the row using
just the PRIMARY key. If it finds it, SharePlex returns the current value for the key column as well as the
changed columns. If it cannot locate the row using just the PRIMARY key, then current_value is NULL

DELETE operation
column_name

is_changed

old_value

new_value

current_value1

is_key

FALSE

bind

NULL

TRUE

1 When

a DELETE fails, it is because SharePlex could not find the row by using the PRIMARY key. Therefore,
SharePlex returns a NULL.

How to use use the SharePlex prepared routines

SharePlex provides the following optional prepared routines for use in conjunction with custom routines. These
options can be used with basic and generic conflict resolution formats. There are no limitations on column
types with the following prepared procedures.
!UpdateUsingKeyOnly prepared routine
!MostRecentRecord(column_name) prepared routine

!UpdateUsingKeyOnly prepared routine

SharePlex provides this prepared conflict resolution routine for UPDATE operations. It provides conflict
resolution that relies solely on the key value of the changed row.
Normally, when SharePlex builds a SQL statement to post data, the WHERE clause uses both the key and the
pre-image of the columns that changed to ensure synchronization. The !UpdateUsingKeyOnly routine directs
SharePlex to post the data even though the pre-image values do not match, assuming the keys match.
If appropriate, this routine can be used as the sole routine for UPDATEs, but with the understanding that it
does not include logic that assigns priority, such as system or time priority, in case of multiple concurrent
UPDATEs. To avoid out-of-sync errors, Dell recommends using !UpdateUsingKeyOnly in conjunction with specific
custom routines, relying on !UpdateUsingKeyOnly as a final option if the custom routines fail.
IMPORTANT: !UpdateUsingKeyOnly must be the last entry in the list of routines, thus assigning it last priority.
In the following example, when there is a conflict for owner.table1 during an UPDATE, SharePlex calls the two
custom routines first (in order of priority) and then calls the !UpdateUsingKeyOnly routine.
owner.table1
owner.table1
owner.table1

u
u
u

owner.procedure_up_A
owner.procedure_up_B
!UpdateUsingKeyOnly

The !UpdateUsingKeyOnly name is case sensitive. It must be typed exactly as shown in these instructions, with
no spaces between words. Do not list an owner name with this routine in the configuration file. See List the
routines in conflict_resolution.SID.
For INSERT and DELETE operations, custom logic must be used.

!MostRecentRecord(column_name) prepared routine

SharePlex provides this prepared conflict resolution routine for UPDATE and DELETE operations. It provides
conflict resolution based on the value of column_name.

SharePlex 8.6
Administrator Guide

138

Normally, when SharePlex builds a SQL statement to post data, the WHERE clause uses both the key and the
pre-image of the columns that changed to ensure synchronization. The !MostRecentRecord routine directs
SharePlex to post data even though the pre-image value doesn't match. It will make the change to the current
row based on the comparison of the column_name specified. If the value of the column_name sent over is
greater than the target column_name value, it will apply the changes. This routine can be used in a time
based replication to resolve conflicts.
The following is an example of this routine specified in the conflict resolution file. See List the routines in
conflict_resolution.SID.
owner.table1
owner.table1
owner.table1

u
u
u

owner.procedure_up_A
!UpdateUsingKeyOnly
!MostRecentRecord(C2)

C2 is the column_name which is a TIMESTAMP datatype

List the routines in conflict_resolution.SID

After you create the conflict resolution procedure(s), construct the conflict resolution file. This file tells
SharePlex which procedures to use for which objects and operation types, and in which order.

Where to find this file

A blank conflict_resolution.SID file, where SID is the ORACLE_SID of the target instance, was included in the
data sub-directory of the SharePlex variable-data directory when SharePlex was installed. Use the file on the
target system.
If this file does not exist, you can create one in ASCII format in an ASCII text editor. It must be named conflict_
resolution.SID, where SID is the ORACLE_SID of the target instance. Note: the SID is case-sensitive.
IMPORTANT! There can be only one conflict_resolution.SID file per active configuration.

How to make entries in the file

Use the following template to link a procedure to one or more objects and operation types.
owner.object

{i | u | d | iud}

owner.procedure

where:
l owner.object is the owner and name of a target object, or a wildcarded entry. (See Syntax rules)
l i| u | d is the type of operation that creates the conflict that is resolved with the specified procedure.
You can specify any or all operation types, for example id or iud. Upper or lower case are both valid.
l owner.procedure is the owner and name of the conflict resolution procedure that will handle the
specified object and operation type.

SharePlex 8.6
Administrator Guide

139

l You can use an underscore (_) to denote a single-character wildcard. For table names that contain an
underscore character (for example emp_sal), SharePlex recognizes the backslash (\) as an escape
character to denote the underscore as a literal and not a wildcard, for example: like:scott.%\_corp\_
emp. If you are not using the LIKE operator, the backslash escape character is not required if an object
name contains an underscore.
l The order in which you list the procedures in the conflict resolution file determines their priority of use
(in descending order). If you list a table-specific procedure, SharePlex uses it before procedures that
are specified with a wildcarded object name.
l You a comment line anywhere in the file. Start a comment line with the pound symbol (#).

Example conflict resolution file

scott.sal
like:scott.%\_corp\_emp
like:scott.%\_corp\_emp
like:scott%
scott.cust

IUD
IUD
IUD
IUD
U

scott.sal_cr
scott.emp_cr1
scott.emp_cr2
scott.emp_cr3
scott.sal_cr

How it works:
l The scott.sal_cr routine is used for the scott.sal table before the scott.emp_cr1 procedure is used for
that table.
l The scott.emp_cr1 procedure is used before the scott.emp_cr2 procedure for all tables meeting the
search criteria, and so forth.
l For scott.cust, a procedure is called for UPDATEs before the other routines are used for all operations.

How to specify SharePlex prepared routines in the file

To use the SharePlex prepared routines for all tables in the replication configuration, use the !DEFAULT
parameter instead of specifying an owner and object name.
A custom routine takes priority over a SharePlex prepared routine. A prepared routine is used only if the
custom routine fails. This is true regardless of the order in which the !DEFAULT-associated routine appears
in the file.
The !DEFAULT parameter is case-sensitive. It must be typed in all capital letters.
In the following example, the !UpdateUsingKeyOnly procedure is used for UPDATEs and DELETEs for all tables,
including james.table1, although the user-defined procedures listed for james.table1 take precedence.
!DEFAULT
!DEFAULT
james.table1
james.table1
james.table1

U
D
U
I
D

!UpdateUsingKeyOnly
!UpdateUsingKeyOnly
james.procedure_upd
james.procedure_ins
james.procedure_del

How to change the file during replication

You can change the conflict resolution file any time during replication to add and remove tables and
procedures. After you change the conflict resolution file, stop and re-start the Post process.

SharePlex 8.6
Administrator Guide

140

Configure replication through an

intermediary system
These instructions show you how to set up cascading replication, also known as multi-tiered replication.This
stragegy replicates data from a source system to an intermediary system, and then from the intermediary
system to one or more remote target systems.
Cascading replication can be used to support various replication objectives as a workaround in such conditions
as the following:
l Your replication strategy exceeds the 1024 routes that are allowed directly from a given source system:
You can send data to the intermediary system and then broadcast to the additional targets from there.
l The source has no direct connection to the ultimate target, because of firewall restrictions or other
factors. You can cascade to a system that does allow remote connection from the source system.
To use a cascading strategy, the source machine must be able to resolve the final target machine name(s),
although the ability to make a direct connection is not required.

Supported targets
Oracle intermediary
Oracle or non-Oracle targets

Capabilities
This replication strategy supports the following:
l Replication to one or more target systems
l Identical or different source and target names
l Use of vertically partitioned replication
l Use of horizontally partitioned replication
l Use of named export and post queues

SharePlex 8.6
Administrator Guide

141

IMPORTANT! These instructions assume you have a full understanding of SharePlex configuration files. They
use abbreviated representations of important syntax elements. See Create configuration files for more
information.

Conventions used in the syntax

Deployment options
To cascade data, you have the following options:
l If there is an Oracle database on the intermediary system, you can configure SharePlex to post to that
database and then capture the data again to replicate it to one or more remote targets.
l If there is not a database on the intermediary system, you can configure SharePlex to import, queue,
and then export the data to one or more remote targets. There is no Capture process on the system.
This is known as a pass-through configuration. It passes the data directly from the source system to the
target(s).

SharePlex 8.6
Administrator Guide

142

Cascade with posting on intermediate system

To use this configuration:
l Oracle is the only supported database type for this purpose.
l A database account for SharePlex must exist for this database. This account is usually created when
SharePlex is installed. See the SharePlexInstallation Guide for more information.
l Triggers must be disabled in the intermediary database, as well as on the target system.
l DDL replication is not supported from an intermediary system to the target systems. It is supported only
from the source system to the intermediary system. To disable the replication of DDL on the
intermediary system, disable the SP_OCT_REPLICATE_DDL and SP_OCT_REPLICATE_ALL_DDL parameters.
l You create two configuration files:one on the source system, and one on the intermediary system.
l Enable archive logging on the source and intermediary systems in case the redo logs wrap before
Capture is finished with them.

Configuration options on source system

This configuration replicates from the source system to the database on the intermediary system.
NOTE: In this template, hostB is the intermediary system.
Datasource:o.SID

source_specification1

target_specification1

[email protected]

source_specification2

target_specification2

[email protected]

Example on source system

Datasource:o.oraA

SharePlex 8.6
Administrator Guide

143

hr.emp
hr.sal
cust.%

hr.emp2
hr.sal2
cust.%

[email protected]
[email protected]
[email protected]

NOTE: In this same configuration, you could route data from other source objects directly to other
targets, without cascading through the intermediary system. Just specify the appropriate routing on a
separate line.

Configuration options on intermediary system

This configuration captures the data from the database on the intermediary system, then replicates it to the
target system(s). The tables that were the target tables in the source configuration are the source tables in
this configuration. The target can be any supported SharePlex target.
Datasource:o.SID

source_specification1

target_specification1

hostC[@db][+...]

source_specification2

target_specification2

hostD[@db][+...]

Example on intermediary system

Datasource:o.oraB
hr.emp
hr.sal
cust.%

hr.emp2
hr.sal2
cust.%

[email protected]
[email protected][email protected]
!cust_partitions

NOTE: The last entry in this example shows the use of horizontally partitioned replication to distribute
different data from the sales.accounts table to different regional databases. See Configure horizontally
partitioned replication.

Required parameter setting on intermediary system

Set the SP_OCT_REPLICATE_POSTER parameter to 1. This instructs the Capture process on the intermediary
system to capture the changes posted by SharePlex and replicate them to the target system. (The default is 0,
meaning that Capture ignores Post activity on the same system.)
In sp_ctrl, issue the following command. The change takes effect the next time Capture starts.
set param SP_OCT_REPLICATE_POSTER 1

Cascade with pass-through on intermediary system

To use this configuration:
l An Oracle instance must be installed on the intermediary system, and an ORACLE_SID must exist in the
oratab file (Unix and Linux systems) or the Windows Registry. The database can be empty.
l DDL replication is not supported.
l You create one configuration file, which is on the source system.

Configuration options on source system

NOTE:In this template, hostB is the intermediary system.
Datasource:o.SID

SharePlex 8.6
Administrator Guide

144

source_specification1

target_specification1

hostB*hostC[@db]

source_specification2

target_specification2

hostB*hostD[@db][+hostB*hostE[@db][+...]

source_specification3

target_specification3

hostB*hostX[@db]+hostY[@db]

l The hostB*host syntax configures the pass-through behavior.

l If using a compound routing map where all data passes through the intermediary system first, make
certain to use the hostB* component in each target route.
l You can also use a compound routing map where data from a source object is replicated directly to one
target, and also through the intermediary system to another target, as in the third line of this
configuration file.

Example
Datasource:o.oraA
hr.emp
hr.emp
cust.%

hr.emp2
hr."Emp_3"
cust.%

hostB*[email protected]
hostB*[email protected]
hostB*[email protected][email protected]

Configure replication to maintain high

availability
These instructions show you how to set up SharePlex for the purpose of high availability: replicating to a
secondary database that is a mirror of the source database. This strategy uses bi-directional replication with
two SharePlex configurations that are the reverse of each other. The configuration on the secondary (standby)
machine remains in an activated state with the Export process on that system stopped in readiness for failover
if the primary machine fails.
This strategy supports business requirements such as the following:
l Disaster recovery
l Continuous operation of business applications throughout maintenance cycles or mechanical failures
In this strategy, SharePlex\ operates as follows:
l Under normal conditions, SharePlex replicates changes from the primary database to the
secondary database.
l When the primary system or database is offline and users are transferred to the secondary
system, SharePlex captures their changes and queues the data on that system until the primary
system is restored.
l When the primary system is restored, SharePlex updates it with those changes and then resumes
capture and replication from the primary database.

Supported targets
Oracle target

SharePlex 8.6
Administrator Guide

145

Capabilities
This replication strategy supports the use of named export and post queues.
NOTE: Column mapping and partitioned replication is not appropriate in a high availability configuration. Source
and target objects can have different names but this makes the management of a high-availability structure
more complicated.

Requirements
l Prepare the system, install SharePlex, and configure database accounts according to the instructions in
the SharePlex Installation Guide.
l Prepare the environment for replication. See Prepare an Oracle environment for replication.
l All objects must exist in their entirety on both systems.
l The target objects must have the same structure and qualified names as their source objects.
l Enable archive logging on all systems.
l Create a script that denies INSERT, UPDATE and DELETE operations to all users except SharePlex.
For failover purposes, the following are required:
l Make the applications used on the primary system available on the secondary system.
l Copy non-replicated database objects and critical files outside the instance to the secondary system.
l Create a script that grants INSERT, UPDATE and DELETE privileges to all users, which can be run during a
failover procedure.
l Create a script that enables constraints on the secondary system to be used during a failover
procedure.
l Develop a failover procedure for relocating users to the secondary system.
NOTE: If you use an Oracle hot backup to create the secondary instance, keep the script. It can be modified to
re-create the primary instance.

Conventions used in the syntax

In the configuration syntax in this topic, the placeholders represent the following:
l hostA is the primary system.
l hostB is the secondary system.
l ownerA.object is the fully qualified name of an object on hostA or a wildcarded specification.
l ownerB.object is the fully qualified name of an object on hostB or a wildcarded specification.
l oraA is the Oracle instance on hostA.
l oraB is the Oracle instance on hostB.
IMPORTANT!
l See Create configuration files for more information about the components of a configuration file.

SharePlex 8.6
Administrator Guide

146

Configuration
A high availability configuration uses two configurations that are the reverse of each other. To replicate all
objects in the database, you can use the config.sql script to simplify the configuration process. See Build a
configuration file using a script

Configuration on the source system (primary system)

Datasource:o.oraA

ownerA.object

ownerB.object

[email protected]

Configuration on the target system (secondary system)

Datasource:o.oraB

ownerB.object

ownerA.object

[email protected]

Make the system ready for failover

1. On the secondary system (the one that will initially be the passive system) run sp_ctrl and then issue
the following command to stop the Export process on the secondary system so that nothing accidentally
happening on the secondary system (such as a scheduled job changing data) gets replicated back to the
primary system. This is the required state of SharePlex on that system until there is a need for a role
switch between systems.
2. Perform initial synchronization and startup. See Activate replication in an Oracle production
environment. You will activate the source configuration during this procedure.
3. Making sure the Export process is stopped on the secondary system, activate the configuration on that
system. The configuration on the secondary machine remains in an activated state, but the stopped
Export process and lack of user activity ensure that the system remains static in readiness for failover.
4. Monitor the SharePlex instance that is linked to the secondary Oracle instance to make sure no nonSharePlex DDL or DML changes were performed. You can do this as follows: View the status of the export
queue on the secondary system using the qstatus command in sp_ctrl. The queue should be empty,
because the Capture process on a system ignores the Post process on that system. If there are any
messages in the export queue, it means those transactions originated on the secondary system or the
SP_OCT_REPLICATE_POSTER parameter was mistakenly enabled. See the SharePlex Reference Guide for
more information about SharePlex commands and parameters.
5. Maintain backups of replication files as recommended in SharePlex best practices.

Perform recovery procedures

If a system fails in your high-availability environment, see Procedures to Maintain Oracle High AvailabilityThese
procedures help you to move replication to a secondary system and then move it back to the primary system
when it is restored.

SharePlex 8.6
Administrator Guide

147

9
Configure partitioned replication

This chapter contains instructions for using the advanced SharePlex configuration options of horizontally
partitioned and vertically partitioned replication. These options provide an additional level of flexibility to
divide, parallelize, and filter data to meet specific requirements. Before proceeding, make certain you
understand the concepts and processes in Create configuration files.

Contents
Configure horizontally partitioned replication
Configure vertically partitioned replication

Configure horizontally partitioned

replication
Use horizontally partitioned replication to divide the rows of a table into separate processing streams. You can
use horizontally partitioned replication to:
l Replicate a subset of rows to the target, while retaining the rest of the rows in the source.
l Replicate different subsets of rows to different targets.
l Divide the replication of a source table into parallel Post processes for faster posting to the
target table.

Guidelines for using horizontally partitioned

replication
The following are guidelines to follow if you are considering a configuration that combines horizontally
partitioned replication with vertically partitioned or full-table replication.
l You can combine horizontally partitioned and vertically partitioned replication for maximum control
over which information is distributed, and to where.
For example:
A company has a headquarters and regional divisions. The headquarters maintains the corporate
database, and each region maintains a regional database. The headquarters uses vertically
partitioned replication to share some of the column data of a table to those locations, while

SharePlex 8.6
Administrator Guide

148

retaining other sensitive data at headquarters. Row changes made to the shared columns are
further partitioned horizontally, for replication to the appropriate regional database.
l Horizontally partitioned replication can be used in conjunction with full-table replication for the same
table, for example to route groups of rows to different reporting systems and all rows to a failover
system. However, SharePlex does not support that combination if vertically partitioned replication is
also used for the same table.

How it works
To implement horizontally partitioned replication, you define the following components.

Define partitions
A partition is a subset of the rows in a table that you want to replicate. To create a partition, you create a
column condition based on a WHEREclause.
Use one or more column conditions for the following purposes:
o Use a column condition to replicate only a subset of the rows of a table. For example, you can replicate
only those rows where the value of the YEAR column is greater than 2000.
o Use multiple column conditions to partition the rows of a table so that each set of rows replicates to a
different target. For example: replicate changes where the value of the REGIONcolumn is EAST to one
location and rows where REGIONis WEST to a different location.

o Use multiple column conditions to divide the rows of a table into parallel processing streams (parallel
Export-Import-Post streams) for faster posting to the target table. For example, you can improve the
flow of replication to a heavily updated target table. This use of column conditions for this purpose is
appropriate only if the table contains a column that enables you to split the processing evenly among

SharePlex 8.6
Administrator Guide

149

parallel Post processes.

NOTE: On a Windows system, the use of numerous queues may require the number of semaphores to be
increased. If Post returns the error message "shs_SEMERR: an error occurred with the semaphore,"
see Post generates a semaphore error in the Solve replication problems topic.

Define partition schemes

A partition scheme is a logical container for related row partitions and is the element that is used in the
configuration file to direct SharePlex to use horizontal partitioning. For example, a simple partition scheme
named CORPORATE.SALES (for the table of the same name) could have four column conditions, each
replicating the appropriate data subsets of the CORPORATE.SALEStable to different regional sales offices.

Specify partition schemes in the configuration file

To direct SharePlex to use a specific partition scheme for a source table, you specify the partition scheme as
the routing map in the configuration file. SharePlex obeys the specifications of the partition scheme to process
the row subsets.

Define partitions and schemes

These instructions help you to define your partitions and link them to partition schemes. You define and link
partitions by using the SHAREPLEX_PARTITIONtable.
NOTE: This table was installed in the SharePlex schema on the source system during the installation
of SharePlex.
Use one SHAREPLEX_PARTITION table for all configurations that replicate data from the same Oracle instance.
Enclose case-sensitive names in double quote marks, for example "Scott"."emp".

To define a partition
For each group of row subsets that you want to define as a partition, use a standard INSERT statement to enter
the information described in "SHAREPLEX_PARTITION columns and input into the SHAREPLEX_PARTITIONtable.

To route a partition to multiple targets

If a row partition must be sent to multiple target tables and the owner or table names are not all identical, do
the following:

SharePlex 8.6
Administrator Guide

150

l Issue and commit a separate INSERT statement for each target table that has a different owner or name
from the other target tables.
l Each INSERT must be identical, except to specify the appropriate name values in the TARGET_
TABLE_OWNER and TARGET_TABLE_NAME columns, in relation to the target system specified in the
ROUTE column.
l When you create an entry for this partition scheme in the configuration file, specify any target table.
SharePlex will detect the other target names when the configuration is activated.
l Set the SP_ORD_FIRST_FIND parameter to 0 so that SharePlex checks all of the column conditions in the
partition scheme. By default SharePlex assumes that any given row change will satisfy only one column
condition in the partition scheme. For more information, see the SharePlex Reference Guide.
Table 10: SHAREPLEX_PARTITION columns and input
Column

Datatype

Input

PARTITION_SCHEME

VARCHAR2(30)

The name of the partition scheme for which

you are creating a row partition.
You can:
l Define any number of partition
schemes for each table in the
replication configuration.
l Link any column condition to multiple
partition schemes.
l Use any or all of your partition
schemes in a configuration file. Only
those that are listed in an active
configuration file are active.

DESCRIPTION

VARCHAR2(61)

A description of the partition. You can enter

a NULL value, but if you are creating
numerous partitions, it helps to identify or
describe each one, for example to give each
partition a name.

TARGET_TABLE_OWNER

VARCHAR2(30)

The owner of the target table. This can be

one of the following:
l A NULL value if there is only one
target owner name across all routes.
l If you are sending the partition to
multiple target tables with different
owner names, specify one of the
owner names. See To route a
partition to multiple targets.

TARGET_TABLE_NAME

VARCHAR2(30)

The name of the target table. This can be

one of the following:
l A NULL value if there is only one
target table name across all routes.

SharePlex 8.6
Administrator Guide

151

Column

Datatype

Input
l If you are sending the partition to
multiple target tables with different
names, specify one of the target
names. See To route a partition to
multiple targets.

ROUTE

VARCHAR2(1024)

The routing map for this partition.

l Specify a standard SharePlex routing
map, for example: [email protected]. A
route with a named export or post
queue is supported. See Configure
named export queues and Configure
named post queues for more
information about named queues.
Compound routing maps are also
supported. See Create configuration
files.
l If routing to multiple target systems
where the names of the target
owners or tables (or both) are
different, you must use a separate
INSERT statement for each one. See
To route a partition to multiple
targets.

PRIORITY

NUMBER

NULL. This column is reserved for use by

SharePlex.

ORDER

NUMBER

NULL. This column is reserved for use by

SharePlex.

OPTIONS

VARCHAR2(32)

NULL

COL_CONDITIONS

VARCHAR2(1024)

Use standard WHEREconditional syntax such

as ((region_id = West) and region_id is not
null). You can specify as many column
conditions as needed. See How to create a
column condition for additional instructions.

How to create a column condition

The following are guidelines for creating column conditions.

Choose appropriate columns

Use columns whose values will not change, such as PRIMARY or UNIQUE key columns. The objective is to avoid a
partition shift, where changes made to the conditional columns of a partition can cause the underlying data to
satisfy the conditions of a different (or no) partition.
Partition shift case 1: The column value is updated so that the new value no longer satisfies any
column condition:

SharePlex 8.6
Administrator Guide

152

l SharePlex performs the operation, but future operations on that row are not replicated. The reason:
the row no longer satisfies a column condition.
l

The source and target tables of the original partition are now out of synchronization, but Post
returns no errors.

Partition shift case 2: A row that satisfies one column condition gets updated to meet a different condition:
l Post cannot find a matching target row. The reason: the original change was not replicated because it
did not meet the column condition.
l Post returns an out-of-sync error.
You have the following options for repairing the out-of-sync rows that are caused by changes to the values of
column conditions:
l Set the SP_ORD_HP_IN_SYNC parameter to a value of 1. This setting directs SharePlex to detect and
correct the out-of-sync condition. Enabling this parameter causes some performance degradation,
depending on how many tables are configured for horizontally partitioned replication. For more
information about this parameter, see the SharePlex Reference Guide.
l Use the compare command to repair the out-of-sync rows. For more information about this command,
see the SharePlex Reference Guide.
NOTE:If you are using a column other than a key to base the column condition on, and you notice reduced
performance with horizontally partitioned replication enabled, add a log group for that column.

Use supported datatypes

SharePlex supports the following datatypes in column conditions:
CHAR
DATE
NUMBER
LONG VARCHAR
VARCHAR
VARCHAR2
NOTES:
l For the DATE datatype, SharePlex uses nls_date_format, with the syntax specified as
MMDDSYYYYHH24MISS. For example:
hiredate<1111 2011000000
l Horizontally partitioned replication does not support the following:
l Oracle TO_DATE function.
l VARRAYs and abstract datatypes.
l UPDATEs or INSERTs on LONG columns larger than 100k.
l LOB columns.
l Sequences.
l TRUNCATEs of an Oracle partition.

SharePlex 8.6
Administrator Guide

153

Use standard conditional syntax

The following list shows the conditional syntax that SharePlex supports in a column condition, where:
l value can be a string or a number. Enclose strings and dates within single quote marks (west). Do not
use quote marks for numbers (10).
l column is the name of a column in the table that you are configuring to use horizontally partitioned
replication.
column=value
not(column=value)
column>value
value>column
column<value
column<=value
column>=value
column<>value
column!=value
columnlikevalue
columnbetweenvalue1andvalue2
not(columnbetweenvalue1andvalue2)
columnis null
columnis not null
Conditions can be combined into nested expressions with parentheses and the AND, OR, and NOT logical
connectives.

Example column conditions

not (col1 = 5)
(col2 = 5) and not (col3 = 6)
((col1 is not null) and (col2 = 5))

Additional guidelines
l NULLs are replicated by SharePlex in cases such as this one: not (department_id = 90). If department_
id is NULL, it is replicated. To avoid replicating records with NULLs, include the column is not null
syntax as part of the condition, for example: not (department_id = 90) and department_id is not null.
l If parentheses are not used to indicate operator precedence, SharePlex supports operator precedence
in the same order that Oracle does. For example, a condition NOT x AND y behaves the same way as
(NOT x) AND y. A condition x AND y OR z behaves the same as (x AND y) OR z. When a condition
includes parentheses, the explicit precedence is respected.
l Do not:
l include references to other tables in the column condition.
l exceed the 1024 bytes maximum defined storage.
l During the activation of a configuration that refers to partition schemes, SharePlex verifies the syntax in
the column conditions of those schemes. If any syntax is incorrect, the activation fails. SharePlex prints
an error to the Event Log that indicates where the error occurred.

SharePlex 8.6
Administrator Guide

154

Specify partition schemes in the configuration file

Use one configuration file for all of the data that you want to replicate from a given datasource, including
tables that will have full-table replication and those that will use partitioned replication. For general
instructions on creating a configuration file, see Create configuration files. To configure entries for horizontally
partitioned replication, use the following syntax.
Datasource:o.SID

src_owner.table

tgt_owner.table

!partition_scheme

routing_map

Where:
l src_owner.table and tgt_owner.table are the specifications for the source and target tables,
respectively.
l ! partition_scheme is the name of the partition scheme to use for the specified source and target
tables. The ! is required. The name is case-sensitive. Compound routing of multiple partition schemes is
not supported, for example !schemeA+schemeB. Create a separate entry for each partition scheme
that you want to use for the same source table. See Examples.
l ! routing_map is a placeholder routing map. It is required only if a route that you used in a partition
scheme is not listed somewhere in the configuration file. This applies to different named queue routes
as well as to routes to different target hosts. All routes must be listed in the configuration file so that
SharePlex can build a routing cache. This requirement usually is satisfied if partitioned replication is
combined with full-table replication. However, if a route in a partition scheme does not appear in a
regular (non-partitioned) configuration entry or the entry for a different partition, you must provide a
placeholder routing map for that route on a separate configuration line. You can use a compound
routing map if the names of all target tables are identical. See Examples.

Examples
Configuration file entry to specify a partition scheme
Datasource:o.myora

scott.emp

scott.emp_2

!partition_emp

scott.cust

scott.cust_2

!partition_cust

Correct way to specify multiple partition schemes for the same source table
Datasource:o.myora

scott.emp

scott.emp_2

!partition_schemeA

scott.emp

scott.emp_3

!partition_schemeB

Correct way to specify placeholder routing map

! targsys1
! [email protected][email protected]

SharePlex 8.6
Administrator Guide

155

Configure vertically partitioned replication

Use vertically partitioned replication to replicate a subset of the columns of a table. For example, you
can replicate data changes made to C1, C2, C3, and C4, but not changes made to C5 and C6, as shown in
the diagram.

Guidelines for using vertically partitioned replication

Follow these guidelines when creating a configuration file that includes vertically partitioned replication.
l Vertically partitioned replication is appropriate for reporting and other data sharing strategies, but it is
not appropriate for high availability environments. Once you configure a table for vertically partitioned
replication, SharePlex does not recognize the other columns, so data in those columns is not replicated.
l You can combine horizontally partitioned and vertically partitioned replication for maximum control
over which information is distributed, and to where.
For example:
A company has a headquarters and regional divisions. The headquarters maintains the corporate
database, and each region maintains a regional database. The headquarters uses vertically
partitioned replication to share some of the column data of a table to those locations, while
retaining other sensitive data at headquarters. Row changes made to the shared columns are
further partitioned horizontally, for replication to the appropriate regional database.
l A table cannot be configured to replicate some columns to one target system and all columns to
another (combination of vertically partitioned replication and full-table replication). You can, however,
configure full-table replication to an identical table on one target, and then configure vertically
partitioned replication from that target to a second target that contains the table that requires only
the partition columns.

SharePlex 8.6
Administrator Guide

156

l A target table can, but does not have to, contain all of the same columns as its source table. The target
can contain just the columns being replicated from the source table. The names of corresponding
source and target columns do not need to be the same. Corresponding columns must contain the same
datatypes (same type, size, precision).
l ALTER TABLE to add a column to a table configured for vertically partitioned replication is not
supported.

Configure vertically partitioned replication

To configure vertically partitioned replication, you specify either a column partition or an excluded column
partition in the configuration file:
l A column partition replicates data changes that are made to the specified columns.
l An excluded column partition replicates all data changes except those made to the specified columns.
Use one configuration file for all of the data that you want to replicate from a given datasource, including
tables that will have full-table replication and those that will use partitioned replication. For general
instructions on creating a configuration file, see Create configuration files. To configure entries for vertically
partitioned replication, use the following syntax.
Datasource:o.SID

src_owner.table (src_col,src_col,...)

tgt_owner.table [(tgt_col,tgt_col,...)]

routing_map

src_owner.table !(src_col,src_col,...)

tgt_owner.table

routing_map

Configuration component

Description

src_owner.table and tgt_

owner.table

The specifications for the source and target tables, respectively.

(src_col, src_col,...)

The source columns to be replicated. Can be one of the following:

and
!(src_col,src_col,...)

l (src_col, src_col,...) specifies a column partition that lists

columns to replicate.
l !(src_col,src_col,...) specifies an excluded column partition that
lists columns not to replicate. The remaining columns comprise
the actual column partition.
NOTE: When using an excluded column partition, the corresponding
source and target column names must be identical, and the excluded
columns cannot be used in a key definition. See Define a unique key for
more information.
Follow these rules to specify either type of column partition:
l There can be one partition per source table.
l A column list must be enclosed within parentheses.
l Separate each column name with a comma. A space after the
comma is optional.
l The maximum length of a partition is 174820 bytes (the maximum
line length allowed in a configuration file). Therefore, the actual

SharePlex 8.6
Administrator Guide

157

Configuration component

Description
number of columns that you can list depends on the length of
each name.
l The columns can be contiguous or non-contiguous in the source
table. For example, you can replicate the first, third and
seventh columns of a table.
l Key columns are not required to be included in the partition.
l If using horizontally partitioned and vertically partitioned
replication together for this table, all of the columns in the
partition scheme must be part of the column condition.

(tgt_col,tgt_col,...)

The target columns. Use this option to map source columns to target
columns that have different owners or names. If the source and target
columns have identical owners or names, the target columns can be
omitted.
To map source columns to target columns, follow these rules:
l The syntax rules for the source column partition also apply to
the target column list.
l The target columns must have identical definitions as their
source columns, except for their names.
l List the target columns in the same logical order as their
corresponding source columns. This is required regardless of the
actual order of the target columns in the table, so that
SharePlex builds the correct correlations in the object cache.
For example, a change to the second column in the source list is
replicated to the second column in the target list.

routing_map

The routing map for the column partition. The routing map can be one of
the following:
l If using horizontally partitioned replication for the source table,
specify a partition scheme, as in: !partition_scheme. See
Configure horizontally partitioned replication for more
information.
l If not using horizontally partitioned replication for the source
table, specify a routing map as follows:
l Use a simple routing map like [email protected] if replicating
the column partition to one target. A route with a named
export or post queue is supported. See Configure named
export queues and Configure named post queues for
more information about named queues.
l Use a compound routing map like
[email protected][email protected] if replicating the column
partition to multiple target systems. IMPORTANT! A
compound routing map must be used, rather than listing
multiple targets in separate entries, because only one

SharePlex 8.6
Administrator Guide

158

Configuration component

Description
column condition per source table can be listed in the
configuration file. To use a compound routing map, the
owners and names of all of the target tables must be
identical. For more information about using a compound
routing map, see Replicate objects to multiple targets.

Configuration examples
The following is a vertically partitioned replication configuration replicating to multiple targets by using
a compound routing map. To use a compound routing map for this source table, all targets must be
named scott.sal.
Datasourceo.oraA

scott.emp (c1,c2)

scott.sal

[email protected][email protected]

The following is a vertically partitioned replication configuration replicating to a single target where the target
columns have different names from those of the source.
Datasourceo.oraA

scott.emp (c1,c2)

scott.sal (c5,c6)

[email protected]

The following configuration file is not valid because it repeats the same column partition of scott.emp (c1, c2)
twice in the configuration file.
Datasourceo.oraA

scott.emp (c1,c2)

scott.cust (c1,c2)

[email protected]

scott.emp (c1,c2)

scott.sales (c1,c2)

[email protected]

SharePlex 8.6
Administrator Guide

159

10
Configure named queues

This chapter contains instructions for using the advanced SharePlex configuration options of named queues.
These options provide an additional level of flexibility to divide and parallelize data to meet specific processing
and routing requirements. Before proceeding, make certain you understand the concepts and processes in
Create configuration files.

Contents
Configure named export queues
Configure named post queues

Configure named export queues

A named export queue is an optional, user-defined export queue that is attached to its own Export process.
SharePlex creates each named Export queue and associated Export process in addition to the default export
queue-process pair. When SharePlex creates a named export queue-process pair, it also creates a dedicated
Import process, post queue, and Post process on the target to contain that data stream.
You direct SharePlex to create one or more named export queues when you create your configuration file. Any
data that is not configured for processing through a named export queue is processed through the default
export queue.

SharePlex 8.6
Administrator Guide

160

Benefits of named export queues

Use named export queues to isolate the replication of:
l Individual configurations: By default, SharePlex sends data from all active configurations through one
export queue-process pair per target system, but the use of named Export queues enables you to
separate each of those replication streams into its own export queue and Export process. In this way,
you ensure that purge config or abort config commands that are issued for one configuration do not
affect any of the others.
l Selected database objects: You can use a named export queue to isolate certain objects such as tables
that contain LOBs. Because each named export queue has its own Import process, post queue, and Post
process on the target, you are able to isolate the data the entire way from source to target. For more
information about the benefits of named post queues, see Configure named post queues.
Additional benefits:
l You can stop the Export or Import process for one data stream, while allowing the others to continue
processing.
l You can set SharePlex parameters to different settings for each export queue-process pair. This
enables you to tune the performance of the Export processes based on the objects replicating
through each one.

SharePlex 8.6
Administrator Guide

161

Considerations when using named export queues

l Make certain that each queue name is unique.
l You can combine named export queues with default export queues. Tables in the configuration with a
standard routing map (targetsys@database_spec without a named queue specification) are replicated
through a default export queue.
l All tables with referential integrity to one another must be in the same export queue.
l See Create configuration files for limitations that affect the number of queues that you can create.
NOTE: On a Windows system, the use of numerous queues may require the number of semaphores to be
increased. If Post returns the error message "shs_SEMERR: an error occurred with the semaphore,"
see Post generates a semaphore error in the Solve replication problems topic.

Configure a named export queue

Use the following syntax to define a routing map that includes a named export queue.
source_host:export_queuename*target_host[@database]

Configuration with named export queue in routing map

Datasource:o.SID

src_owner.table

tgt_owner.table

source_host:export_queue*target_host[@database_
specification]

Routing component

Description

source_host

The name of the source system.

export_queue

The name of the export queue. Queue names are case-sensitive on all
platforms. Use one word only. Underscores are permissible, for
example:
sys1:export_q1*[email protected]

Required component that separates the source routing component from

the target routing component.

target_host

The name of the target system.

database specification

One of the following, required if the target is a database:

o.oracle_SID
o.tns_alias
o.PDBname
r.database_name
c.oracle_SID

NOTES:

SharePlex 8.6
Administrator Guide

162

l Allow no spaces between any components in the syntax of the routing map.
l For more information about the components of a configuration file, see Create configuration files.

Examples

The following configuration files show two different datasources that are being replicated to two different
databases on the same target system. Each datasource is routed through a named export queue.
Datasource:o.oraA
scott.emp
scott.sales

scott.emp
scott.sales

sysA:QueueA*[email protected]
sysA:QueueA*[email protected]

scott.prod
scott.cust

sysA:QueueB*[email protected]
sysA:QueueB*[email protected]

Datasource:o.oraB
scott.prod
scott.cust

The following shows how to separate a table that contains LOBs from the rest of the tables by using named
export queues.
Datasource:o.oraA
scott.cust
scott.sales
scott.prod
scott.emp_LOB

scott.cust
scott.sales
scott.prod
scott.emp_LOB

sysA:QueueA*[email protected]
sysA:QueueA*[email protected]
sysA:QueueA*[email protected]
sysA:QueueB*[email protected]

Alternatively, you could simply define a named export queue for the LOB table and allow the remaining tables
to be processed through the default export queue.
Datasource:o.oraA
scott.cust
scott.sales
scott.prod
scott.emp_LOB

scott.cust
scott.sales
scott.prod
scott.emp_LOB

[email protected]
[email protected]
[email protected]
sysA:lobQ*[email protected]

How to identify named export queues

You can view named export queues through sp_ctrl:
l Use the qstatus command to view all queues on a system.
l Use the show command to view all Export processes with their queues.
See the SharePlex Reference Guide for more infomation about theses commands.

Configure named post queues

A named post queue is an optional component of the routing map in the configuration file. A named post queue
is a user-defined post queue with its own Post process, which together operate in parallel to the default post

SharePlex 8.6
Administrator Guide

163

queue and Post process. You can define one or more named post queue-process pairs to establish a set of
parallel Post replication streams.

Benefits of named post queues

You can use named post queues to isolate data from different tables into two or more separate Post streams. By
using named post queues, you can improve posting performance by isolating objects such as the following that
cause processing bottlenecks:
l objects that have LOB columns. Named post queues are recommended for objects that contain LOBs.
l objects that involve large transactions.
l any objects whose operations you want to isolate.
Process the remaining objects through additional named post queues, or use the default post queue. Objects
in the configuration file with a standard routing map (host@target) are replicated through a default post queue.
You can use horizontal partitioning to divide the rows of very large tables into separate named post queues as
an added measure of parallelism. See Configure horizontally partitioned replication.
You can set SharePlex parameters to different settings for each queue-process pair. This enables you to tune
the performance of the Post processes based on the objects replicating through each one.

SharePlex 8.6
Administrator Guide

164

Considerations when using named post queues

l See Replicate objects to multiple targets for limitations that affect the number of queues you
can create.
l Assign each post queue a unique name.
l If objects are linked by relational dependencies, process all of those objects through the same named
post queue. If interdependent objects are not replicated through the same post queue, parent and
child operations may be applied out of order and will cause database errors. As an alternative to
processing interdependent objects through the same queue, you can disable their referential
constraints on the target. This may be acceptable, because the constraints are satisfied on the source
system and then replicated to the target.
l When using multiple Posts, the target objects might not be changed in the same order as the
corresponding source objects, possibly causing the target database to be inconsistent with the source
database at any given point in time.
l If you implement named post queues for objects in an active configuration (thus changing the routing)
SharePlex locks those objects to update its internal directions.
NOTE: On a Windows system, the use of numerous queues may require the number of semaphores to be
increased. If Post returns the error message "shs_SEMERR: an error occurred with the semaphore,"
see Post generates a semaphore error in the Solve replication problems topic.

Configure a named post queue

If you are using named export queues, SharePlex creates a named post queue-process pair for each one by
default. If you are not using named export queues, use the following syntax to define a named post queue in
the configuration file by adding the :queue component to the routing map:
host:queue@target

Configuration with named post queue in routing map

Datasource:o.SID

src_owner.table

tgt_owner.table

host:queue[@database_specification]

Routing component

Description

host

The name of the target system.

A colon. This is a required component.

queue

The unique name of the post queue. Queue names are case-sensitive on
all platforms. One word only. Underscores are permissible, for example:
sys2:[email protected]

@database_specification

(If the target is a database)

l The ampersand (@) is a required component.
l Specify the database with one of the following:
o.oracle_SID

SharePlex 8.6
Administrator Guide

165

Routing component

Description
o.tns_alias
o.PDBname
r.database_name

NOTES:
l Allow no spaces between any components in the syntax of the routing map.
l For more information about the components of a configuration file, see Create configuration files.

Examples
The following configuration creates one post queue named Queue1 that routes data from table scott.emp and
another post queue named Queue2 that routes data from table scott.cust.
Datasource:o.oraA
scott.emp
scott.cust

scott.emp
scott.cust

sysB:[email protected]
sysB:[email protected]

The following shows how a named post queue is specified when you are routing data in a pass-through
configuration using an intermediary system. For more information about this replication strategy, see Configure
replication to share or distribute data.
Datasource:o.oraA
scott.emp

scott.emp

sysB*sysC:[email protected]

How to identify a named post queue

A named post queue is identified by the datasource (source of the data) and one of the following:
l the name of an associated named export queue (if the Import is linked to a named export queue)
l the user-assigned post-queue name (if the Import is linked to a default export queue).
You can view named post queues through sp_ctrl:
l Use the qstatus command to view all queues on a system.
l Use the show command to view all Post processes with their queues.
See the SharePlex Reference Guide for more infomation about theses commands.

SharePlex 8.6
Administrator Guide

166

11
Configure replication to maintain a
change history target

This chapter contains instructions for how to configure SharePlex to maintain a change-history target.
SharePlex enables you to maintain this history, while also replicating the same data set to maintain up-todate targets.

Contents
Overview of the change-history target
Configure change history

Overview of the change-history target

A change history target differs from a replication target in that a change history target maintains a record of
every change that occurs to a source object or objects, rather than simply maintaining a mirror of the current
state of the source data. While regular replication overlays current target data with change data, change
history inserts the change data to the target as a new record. The old data is preserved as a step-by-step
record of change. The historical data can be queried and analyzed for such purposes as data mining or resolving
customer disputes.
By using SharePlex to maintain change history on a secondary server, you can offload the overhead from the
production database. Such overhead includes the SQL work of adding the history rows, the extra storage of
those rows, and the query activity against the historical data.
NOTE: File and JMS targets support change history by default, because every source change is written
as a separate XML record. There is no overlaying of old data with new. Metadata that is supported for
these targets is included automatically when Post writes the XML. For a list of supported metadata, see
the target command in the SharePlex Reference Guide.

SharePlex 8.6
Administrator Guide

167

l Use of named export and post queues

l Combination of regular replication and change-history replication of the same source object(s)

Supported targets
Oracle target

Operations supported
SharePlex supports adding a change history row for these operations:
l INSERT
l UPDATE
l DELETE
l TRUNCATE
l ALTER TABLE to DROP COLUMN (NOTE: for ADD COLUMN, Post adds a column to the table, but does not
create a change history row.)

Operations not supported

l Changes made to UDT or VARRAY columns
l DBMS_LOB operation that is used to change a part of a LOB column (The value stored for that column on
the target will not be the complete LOB column.)

How SharePlex maintains change history

In a change history configuration, each target table serve as a history table that records every change
made to the source data as a continuous series of rows. Each new change row that SharePlex inserts
includes the following:
l the values of the key columns
l the after image of the changed columns. For inserts and updates, the after image consists of the new
values of the columns that were changed (or added in the case of an insert). For deletes, the after
image consists of the key values plus the other columns set to null.
l (optionally) a set of metadata values that provide context for the change. For example, there is
metadata that captures the userid of the user who made the change and the source system where the
change was made (useful when change data is tracked from multiple databases).
SharePlex can be configured to include the before image of update operations in the history or to control which
operation types are included in the history. For example, you could include only updates and deletes.

SharePlex 8.6
Administrator Guide

168

Configure change history

To configure change history, you use special syntax in the SharePlex configuration file and, optionally,
configure filter rules and other attributes to customize the history to your needs.

Create a change-history configuration file

1. Make certain that SharePlex is installed and the system is prepared according to the instructions in the
SharePlex Installation Guide.
2. Create the history tables with the same name and structure as the source tables whose history they
will track, but omit all constraints on all columns. Target tables must not have PRIMARY KEY, FOREIGN
KEY, UNIQUE, NOT NULL, or CHECK constraints, nor can columns be defined with a DEFAULT value.
Because this is a history of changes, a row may have the same image as another row that has the same
key. Post does not perform integrity checks on a change-history target.
3. Disable triggers on the target tables.
4. Allow no DML or DDL to be performed on the target tables except by SharePlex.
5. On the source system, create a configuration file using the follpowing syntax. For more information
about how to create a configuration file, see Create configuration files.
Datasource:o.SID

src_owner.table

!cdc:tgt_owner.table

[email protected]

where:
l o.SID is the source Oracle instance.
l src_owner.table is the fully qualified name of a source object (owner.object) or a wildcarded
specification.
l !cdc: identifies the target as a change-history table.
l tgt_owner.table is the fully qualified name of the target history table or a wildcarded
specification.
l host is the target system.
l c.SID specifies the target Oracle instance.
6. (Optional) Run the following script on the target tables to add default metadata columns with their
default names. Post automatically populates the default metadata columns without any additional
configuration. You can customize the script to meet your requirements.
product_dir/util/add_change_tracking_columns.sql
The script only adds the default columns. To add optional columns, or to change a column name, use
the target command to add them to the Post configuration. For a list of default and optional metadata
columns, see the target command in the SharePlex Reference Guide.
NOTE: The default columns are automatically added to new tables that are added to the SharePlex
change history configuration.

SharePlex 8.6
Administrator Guide

169

Additional change history configuration options

This section describes how you can customize the SharePlex change history configuration.

Customize column names

You can use the target command with the colname option to customize the name of any metadata column. For
instructions, see the SharePlex Reference Guide.

Add the before image to each change row

You can include the before image of updates by setting the SP_OPO_TRACK_PREIMAGE parameter to U. This
parameter causes Post to insert two rows to a history table for every change made to the tracked source table:
one for the after image and one for the before image. The before image is composed of the key values plus the
before values of the columns that were changed, unless the SP_OCT_USE_SUPP_KEYS parameter is used.
When before images are enabled, the SHAREPLEX_SOURCE_OPERATION column values for the two
records will be:
UPDATE BEFORE
UPDATE AFTER
NOTE: The before row will not include the before image of any LOB columns, because the redo log does not
contain the before image of LOBs.
You can override the global setting of SP_OPO_TRACK_PREIMAGE at the table level by using the set cdc
preimage option of the target command.
For more information about SP_OPO_TRACK_PREIMAGE and the target command, see the SharePlex
Reference Guide.

Include all columns of an operation in the history

To include the values of all table columns in each history record, rather than only the changed columns,
configure the following:
1. Turn on supplemental logging for all columns of the source tables that are being tracked. For example:
Alter table emp ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;
2. Set the SP_OCT_USE_SUPP_KEYS parameter to 1.
NOTE: When both SP_OCT_USE_SUPP_KEYS and SP_OPO_TRACK_PREIMAGE are enabled, the before image
includes all column values as they were before the change.

Disable change history of an operation type

To disable the change history of a DML operation type, set the SP_OPO_TRACK_OPERATIONS parameter to the
appropriate value or values. Separate values with a slash (/). For example, to maintain change history only for
inserts and updates, change the parameter to I/U.The default is I/U/D which sends all DML operation types to
the history records.

SharePlex 8.6
Administrator Guide

170

Set rules and filters

You can use the set rule option of the target command to apply conditions on columns to control whether a
change is applied to the target history table. For example, you can specify a rule that if column 1 and column 3
are changed, then apply the operation and discard any changes that apply to other columns. For instructions,
see the SharePlex Reference Guide.

Include COMMITs
By default, the COMMIT record is not included in the history tables. To configure Post to insert a row for every
COMMIT, set the SP_OPO_TRACK_COMMITS parameter to 1.

SharePlex 8.6
Administrator Guide

171

12
Set up DDL Replication

This chapter contains the information that you need to know in order to replicate DDL that is supported
by SharePlex.

Contents
DDL that SharePlex supports
Control DDL replication
Filter DDL Replication
Best practices for ALTERTABLE DDL
DDL logging and error handling

DDL that SharePlex supports

SharePlex replicates certain DDL changes that are written to the redo logs. Changes that bypass the redo logs
are not replicated.
For details on the DDL that SharePlex supports, see the SharePlexSharePlex Release Notes.
In a cascading configuration, DDL replication is supported only from the source system to the intermediary
system, but not from the intermediary system to target systems. For more information about cascading
replication, see Configure replication through an intermediary system.
DDL against objects owned by the SharePlex user or against system-owned objects is not replicated.
NOTE:
Because the source and target databases can be of different versions in SharePlex replication, the
source and target objects can be different. When DDL is applied to the target, it may fail if the operation
is forbidden on the target but allowed on the source.
For a list of objects for which DDL is supported, see the SharePlex Release Notes.

Control DDL replication

By default, SharePlex replicates some DDL for objects that are listed in the active configuration (explicitly or by
wildcard), but you can expand this support with parameter settings.
IMPORTANT!

SharePlex 8.6
Administrator Guide

172

l For the most current information about supported DDL and requirements or limitations, see the
SharePlex Release Notes provided with this release. That information may supercede what is
documented here.
l DDL replication is supported only to Oracle targets, except for ALTERTABLE to ADDCOLUMN or
DROPCOLUMN, which are supported for all SharePlex targets.
SharePlex provides default DDL support for objects in the configuration file. You can expand this support
through parameter settings.

Default DDL support

By default SharePlex replicates the TRUNCATETABLEcommand and the ALTERTABLEcommand to ADDor
DROPcolumns when:
l the affected object exists in the source and target at the time of activation and
l its name is listed in the configuration file (explicitly or through wildcard).
This functionality is controlled by the SP_OCT_REPLICATE_DDLparameter. A setting of 1 replicates ALTER but
not TRUNCATE. A setting of 2 replicates TRUNCATE but not ALTER. The default setting of 3 replicates ALTER
and TRUNCATE.
By default, the SharePlex Auto-Add feature is also enabled to provide DDL support for tables and indexes that
are created after activation. When SharePlex detects a CREATEstatement for one of these objects and its
name satisfies a wildcard in the configuration file, SharePlex does the following:
l replicates the CREATE to add the object to the target
l adds the object to replication
l maintains that object through future DDL and DML changes
The Auto-Add feature is controlled by the SP_OCT_AUTOADD_ENABLE parameter, which is set to 1 (enabled)
by default.
See the SharePlex Reference Guide for details about this parameter.

Expanded Auto-Add support

You can expand Auto-Add support to add new materialized views to replication if their names satisfy a wildcard
specification in the active configuration file.

To auto-add materialized views

1. Make certain the SP_OCT_AUTOADD_ENABLE parameter is set to 1.
2. Set the SP_OCT_AUTOADD_MV parameter to 1. The SP_OCT_TARGET_COMPATIBILITY parameter must be
set to at least 8.6.2.

SharePlex 8.6
Administrator Guide

173

DDL support for objects outside the replication

configuration
You can configure SharePlex to replicate DDL for tables and indexes that are not listed in the configuration file.
SharePlex replicates metadata changes for those objects, but does maintain data changes to them. The objects
must exist in the source and target prior to configuration activation.

To replicate DDL for objects outside the replication configuration

Set the SP_OCT_REPLICATE_ALL_DDLparameter to 1.
See the SharePlex Reference Guide for details about this parameter.

Filter DDL Replication

You can filter the objects for which DDL is replicated when the SP_OCT_REPLICATE_ALL_DDL parameter
is enabled.
NOTE: DDL filtering is only allowed for objects outside the replication configuration. All DDL performed
on objects inside the replication configuration must be replicated to keep the source and target
metadata consistent so that DML succeeds.
DDL filtering is controlled in the SHAREPLEX_DDL_CONTROL table that is installed in the SharePlex schema.
Name

Type

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

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

DDL_PARAMETER

NUMBER

DDL_CODE

NUMBER

SCHEMA_FILTER

VARCHAR2(32)

OBJECT_FILTER

VARCHAR2(32)

IMPORTANT! The DDL_PARAMETER column is not active column as of this release of SharePlex.
To filter DDL, insert a row into the table with the desired values in the active columns.
These are the rules for filtering the DDL:
l SCHEMA_FILTERfilters DDL by a schema name.
l OBJECT_FILTERfilters DDL by an object name.
l DDL_CODE filters by the code number of a DDL type. See DDL codes.
l You can use SCHEMA_FILTER with or without OBJECT_FILTER to filter out DDL by schema name, object
name, or both.
l You can use DDL_CODE to filter out specific DDL by its code number.
l Do not use SCHEMA_FILTER and/or OBJECT_FILTER with DDL_CODE. Filter by schema and/or object, or
filter by DDL code, but not both.
l If there are no rows in the table, no filtering is performed.

SharePlex 8.6
Administrator Guide

174

l If any column contains NULL, no filtering is performed for the object represented by the column (DDL
code, schema, object).

Examples
The following filters out of replication the DDL for ALTERTABLE:
INSERT INTO SPLEX.SHAREPLEX_DDL_CONTROL (DDL_CODE, SCHEMA_FILTER, OBJECT_FILTER)
values (0x0F,null,null);
The following filters out of replication all DDL for all objects that begin with TEST_ in any schema:
INSERT INTO SPLEX.SHAREPLEX_DDL_CONTROL (DDL_CODE, SCHEMA_FILTER, OBJECT_FILTER)
values (null,null,'TEST_%');

DDL codes
/** DDL codes **/
#define DDL_CODE_CREATE_TABLE 0x01
#define DDL_CODE_CREATE_CLUSTER 0x04
#define DDL_CODE_DROP_CLUSTER 0x08
#define DDL_CODE_CREATE_INDEX 0x09
#define DDL_CODE_DROP_INDEX 0x0A
#define DDL_CODE_ALTER_INDEX 0x0B
#define DDL_CODE_DROP_TABLE 0x0C
#define DDL_CODE_CREATE_SEQUENCE 0x0D
#define DDL_CODE_ALTER_SEQUENCE 0x0E
#define DDL_CODE_ALTER_TABLE 0x0F
#define DDL_CODE_DROP_SEQUENCE 0x10
#define DDL_CODE_GRANT 0x11
#define DDL_CODE_REVOKE 0x12
#define DDL_CODE_CREATE_SYNONYM 0x13
#define DDL_CODE_DROP_SYNONYM 0x14
#define DDL_CODE_CREATE_VIEW 0x15
#define DDL_CODE_DROP_VIEW 0x16
#define DDL_CODE_CREATE_PROCEDURE 0x18
#define DDL_CODE_ALTER_PROCEDURE 0x19
#define DDL_CODE_RENAME 0x1C
#define DDL_CODE_COMMENT_TABLE_COL 0x1D
#define DDL_CODE_CREATE_DB_LINK 0x20
#define DDL_CODE_DROP_DB_LINK 0x21
#define DDL_CODE_ALTER_DATABASE 0x23
#define DDL_CODE_ALTER_USER 0x2B

SharePlex 8.6
Administrator Guide

175

#define DDL_CODE_CREATE_USER 0x33

#define DDL_CODE_CREATE_ROLE 0x34
#define DDL_CODE_DROP_USER 0x35
#define DDL_CODE_DROP_ROLE 0x36
#define DDL_CODE_CREATE_SCHEMA 0x38
#define DDL_CODE_CREATE_TRIGGER 0x3B
#define DDL_CODE_ALTER_TRIGGER 0x3C
#define DDL_CODE_DROP_TRIGGER 0x3D
#define DDL_CODE_ANALYZE_TABLE 0x3E
#define DDL_CODE_ANALYZE_INDEX 0x3F
#define DDL_CODE_ANALYZE_CLUSTER 0x40
#define DDL_CODE_DROP_PROCEDURE 0x44
#define DDL_CODE_CREATE_TYPE 0x4D
#define DDL_CODE_DROP_TYPE 0x4E
#define DDL_CODE_ALTER_ROLE 0x4F
#define DDL_CODE_ALTER_TYPE 0x50
#define DDL_CODE_CREATE_TYPE_BODY 0x51
#define DDL_CODE_DROP_TYPE_BODY 0x53
#define DDL_CODE_TRUNCATE 0x55
#define DDL_CODE_ALTER_VIEW 0x58
#define DDL_CODE_CREATE_FUNCTION 0x5B
#define DDL_CODE_ALTER_FUNCTION 0x5C
#define DDL_CODE_DROP_FUNCTION 0x5D
#define DDL_CODE_CREATE_PACKAGE 0x5E
#define DDL_CODE_ALTER_PACKAGE 0x5F
#define DDL_CODE_DROP_PACKAGE 0x60
#define DDL_CODE_CREATE_PACKAGE_BODY 0x61
#define DDL_CODE_ALTER_PACKAGE_BODY 0x62
#define DDL_CODE_DROP_PACKAGE_BODY 0x63
#define DDL_CODE_CREATE_DIRECTORY 0x9D
#define DDL_CODE_DROP_DIRECTORY 0x9E
#define DDL_CODE_ASSOCIATE_STATISTICS 0xA8
#define DDL_CODE_DISASSOCIATE_STATISTICS 0xA9

Best practices for ALTERTABLE DDL

The following are best practices for replication of ALTERTABLE replication.

SharePlex 8.6
Administrator Guide

176

Tables with VARRAY or ABSTRACT types

Do not add a VARRAY column or abstract datatype column if you plan to issue an ALTER TABLE to drop a column
or set a column unused soon thereafter. SharePlex must query the database to obtain information about this
data type. If the second DDL was performed before SharePlex was able to process the first DDL, the query will
fail because the metadata is already changed.

Tables with system-specific metadata

If some metadata is system-specific, such as the storage parameters of database objects, there may be
unexpected results when DDL on that metadata is replicated. For example, SharePlex replicates all of the
storage parameters for a source Oracle object, even though only some of them were changed with the ALTER
TABLE command. If the source and target objects were not created with the same storage parameters, one of
two things can happen: either the target table will assume the storage of the source table or, if the DDL is not
supported by the target, an error will be generated.
Example: consider a source table with MAXEXTENTS 525 and MINEXTENTS 20, and a target table with
MAXEXTENTS 505 and MINEXTENTS 4. If the MAXEXTENTS of the source object is changed to unlimited,
SharePlex will replicate both the MAXEXTENTS change and the non-changed MINEXTENTS of 20. This
causes Oracle error 01570, because MINEXTENTS cannot be larger than the extents currently allocated.
Alternatively, if the MINEXTENTS is changed to 1 on the source, but MAXEXTENTS is not changed,
SharePlex replicates both, which results in target parameters of MAXEXTENTS 525 and MINEXTENTS 1.

Tables that are renamed

When ALTER TABLE RENAME is issued on a source table that is currently in replication, SharePlex changes the
name of the table in the active configuration file by commenting out the old configuration line and adding a
new line at the end of the configuration file. If the source and target table names are the same, both are
changed to the new name. Otherwise, just the source name is changed. The following is an example:When
ALTER TABLE RENAME is issued on a source table that is currently in replication, SharePlex changes the name of
the table in the active configuration file by commenting out the old configuration line and adding a new line at
the end of the configuration file. If the source and target table names are the same, both are changed to the
new name. Otherwise, just the source name is changed. The following is an example:
# Table scott.table1 renamed to scott.table2 August 5, 2003 10:14
scott.table2 scott.table2 [email protected]
Whether the Post process stops on RENAME operations or not depends on the setting of the SP_OPO_STOP_ON_
DDL_ERR parameter.

ALTERTABLE...MOVE
ALTERTABLEDDL commands that change the rowid of a table can affect subsequent DML operations if the
primary or unique keys of the tables in replication are not being logged. When the keys are not logged,
SharePlex fetches their values based on the rowid. Any operation that changes the rowid, such as
ALTERTABLE...MOVE, can cause the wrong key values to be used for subsequent DML operations.

SharePlex 8.6
Administrator Guide

177

DDL logging and error handling

SharePlex has separate DDL logs on the source and target machines. All of the DDL that Capture and Post
process is logged. If a SQL operation issued by Post fails, Post logs the command name and object along with the
Oracle error.
The Capture log is named as follows:
ORACLE_SID_ocap_ddl_log_number.log
For example,
o.ora10_ocap_ddl_01.log
The Post log is named as follows:
ORACLE_SID_machine_name_opo_ddl_log_number.log
For example,
o.ora10a_irvspxub_opo_ddl_01.log
SharePlex prints replicated DDL to the Event Log, but it may be truncated. The complete DDL is printed in the
DDL log for the Post process.
By default, Post stops on DDL errors. An error usually indicates that the database component for which the DDL
was executed on the source system does not exist in the target database. The default setting of the SP_OPO_
STOP_ON_DDL_ERR parameter stops Post on DDL errors, so that subsequent DML on that object does not fail.
This enables you to correct the problem and keep the databases synchronized. For more information about this
parameter, see the SharePlex Reference Guide.

SharePlex 8.6
Administrator Guide

178

13
Set up error handling

This chapter contains an overview of the tools that SharePlex provides to handle errors that are returned by
the Post process.

Contents
Continue to post when there is a DML error
Continue to Post when there is a DDL error
Increase the number of retries on error
Stop Post when data is out-of-sync

Continue to post when there is a DML error

You can configure Post to ignore specific Oracle DML errors and continue processing. Post determines which
messages to ignore based on the list in the oramsglist file. The file is installed with a small list of errors by
default, but you can remove any of them as desired.
When Posts ignores an error, it writes the error to the SharePlex Event Log. Post also logs the error and the SQL
statements that caused the error to the Error log. This log is named SID_errlog.sql log file and is stored in the
data directory in the SharePlex variable-data directory. For more information about these logs, see View events
and errors.
NOTE: There are certain errors that Post will not ignore, and it will stop for those messages even if they are
listed in the oramsglist file.
IMPORTANT: Use caution when using this feature. It could result in hidden out-of-sync conditions. Enable
this parameter only if your target users cannot tolerate replication lag and it is acceptable to have some
out-of-sync data. Check the SID_errlog.sql log frequently to see if there were errors that could cause
replication problems.

To configure Post to continue on errors

1. On the target system, change directories to the data sub-directory of the SharePlex variable-data
directory.
2. Find the oramsglist file.
3. If replication is not active, open the file in a text editor. If replication is active, make a copy of the file
and then open the copy in the editor.
4. Increase the number on the first line by the number of errors that you are adding. This number must

SharePlex 8.6
Administrator Guide

179

be equal to the total number of errors that are in the file. For example, in the following file there are
10 errors listed.
ora@sys1dad > vi oramsglist
10
604
900
902
908
909
910
911
932
960
1026
5. Starting at the end of the file, add the number of each Oracle error, one per line as shown in the
example. The messages need not be in numerical order.
6. Save and close the file.
7. Stop Post (if running).
sp_ctrl> stop post
8. If you edited a copy of the oramsglist file, save the copy to the original name of oramsglist.
9. Change the value of the SP_OPO_CONT_ON_ERR parameter to 1.
sp_ctrl> set param SP_OPO_CONT_ON_ERR 1
10. Start Post.
sp_ctrl> start post

Continue to Post when there is a DDL error

By default, Post stops on DDL errors. An error usually indicates that the database component for which the DDL
was executed on the source system does not exist in the target database. The default setting of the SP_OPO_
STOP_ON_DDL_ERR parameter stops Post on DDL errors, so that subsequent DML on that object does not fail.
This enables you to correct the problem and keep the databases synchronized. For more information about this
parameter, see the SharePlex Reference Guide.

Increase the number of retries on error

Post will retry certain failed operations when there is the possibility that they will succeed with another
attempt. The main operations that Post will retry are TNS write failures, connection failures, or locks on tables
when Post needs to apply a TRUNCATE.
To increase the likelihood that the failed operations are successful, you can increase the SP_OPO_RETRIES_MAX
parameter so that Post tries the operation more times. At the same time, increase the SP_OPO_RETRY_DELAY_
TIME parameter to increase the time interval between the attempts. That gives the lock or other blocking
operation enough time to be resolved between attempts.

SharePlex 8.6
Administrator Guide

180

If the Post process is set to continue on error (SP_SYS_SUSPEND_ON_ERROR=0) or if the error message is listed in
the oramsglist file (see Continue to post when there is a DML error), Post moves on to the next transaction in
the queue. In all other cases, Post stops after it reaches the maximum allowed attempts.
IMPORTANT: Reducing this parameter can cause the data to accumulate in the queues, possibly causing them
to exceed the available disk space.
For more information, see SP_OPO_RETRIES_MAX in the SharePlex Reference Guide.

Stop Post when data is out-of-sync

By default Post does not stop when it determines that a row is out of synchronization. It logs the SQL statement
and data to the ID_errlog.sql log file (where ID is the database identifier) and then continues processing to
avoid replication lag.
You can configure Post to stop when it encounters an out-of-sync condition by setting the SP_OPO_OUT_OF_
SYNC_SUSPEND parameter to 1.
If you use this feature, make certain to monitor replication frequently. If Post stops, latency increases and data
accumulates in the queues. For more information, see SP_OPO_OUT_OF_SYNC_SUSPEND in the SharePlex
Reference Guide.

SharePlex 8.6
Administrator Guide

181

14
Transform data

This topic contains instructions for using the transformation feature of SharePlex. Transformation enables
SharePlex to manipulate data before, or instead of, posting it to a target.

Contents
Overview of transformation
Considerations when using transformation
Deploy transformation

Overview of transformation
Transformation directs the Post process to call a PL/SQL procedure (defined as a transformation routine)
instead of applying a SQL operation to the target database. Transformation enables replicated data to be
manipulated before, or instead of, posting to a target.
For example, if a source table and its target table are dissimilar in construction like when a persons first and
last name are in one column in the source table but in separate columns in the target table you can write a
transformation routine to convert the data for those columns so that replication succeeds. You can use
transformation routines to convert datatypes, units of measurement, or character sets. You can use them
instead of database triggers to reduce I/O overhead, and for many other business requirements.
When you specify transformation for a table, Post takes no action on the replicated data. Instead, it passes
data values to your transformation routine, enabling you to control both the form and destination of the data
with the procedure. You can post to the target table, post to an alternate location, or both. Therefore,
when writing your routine, is your responsibility to include in your procedure the necessary SQL operations
for posting.

Supported databases
Oracle source and target only

Supported replication strategies

Transformation is a convenient way to use SharePlex to transfer data from one table to another without
concern for maintaining identical structure or data. This makes it practical for reporting, broadcast, and data
mart and warehousing applications.

SharePlex 8.6
Administrator Guide

182

Transformation is not suitable for peer-to-peer or high-availability replication environments. High availability
requires identical databases that are kept synchronized by replication. For peer-to-peer replication
SharePlex must be able to detect and resolve conflicts when there are concurrent changes to the same
record. When data is transformed, SharePlex cannot compare before and after values to verify
synchronization and detect conflicts.

Supported operations
Transformation supports only INSERT, UPDATE and DELETE operations. You can do the following when
developing procedures:
l You can create one procedure for all three operation types, or you can create a procedure for each
operation type.
l You can use one procedure for all tables, or use different procedures for different tables. SharePlex
allows this through the use of wildcards to specify the tables.
If a transformation routine is specified for an individual table, and the table also is part of a group of tables for
which another routine is specified, only the table-specific routine is used for that table when the associated
DML operation occurs.

Considerations when using transformation

Because transformation changes data and because SharePlex does not post the data, transformation changes
the behavior of replication. It is a customization of SharePlex processing. Review the following considerations
before implementing transformation to ensure that your transformation procedures succeed.

Privileges
Any table that will be accessed through PL/SQL for transformation requires implicitly granted privileges from
the owner of the object to SharePlex.

Keys
A PRIMARY or UNIQUE key is required for all tables using transformation. SharePlex locates the target row for
UPDATEs and DELETEs by using the key, which enables it to return values to your transformation routine from
the target table for UPDATE operations. Do not allow keys to be changed on the target system, or SharePlex
will not be able to locate the row to pass values to your routine.

Test your routines

Test your transformation routines before you put them into production to make sure they work as intended,
and to make sure that one routine does not counteract another one. When data is transformed, SharePlex
cannot compare before and after values to verify synchronization, which is a measure of whether the routines
are performing correctly. The only way to confirm synchronization is to use the compare command with the key
option. This option restricts the comparison to just the key values and is not a complete confirmation of
synchronization. It only detects missing or extra rows. It does not (and cannot) indicate whether values in nonkey columns are properly correlated to those in the source columns, because the target data was transformed.
For those reasons, the repair command cannot be used to resynchronize data. You must devise your own
resynchronization procedures based on your companys business rules and the database environment.

SharePlex 8.6
Administrator Guide

183

Dates
The default date format for SharePlex transformation is MMDDYYYY HH24MISS. Tables with default dates must
use that format, or transformation will return errors. Before creating a table with a default date, use the
following command to change the date format in SQL*Plus.
ALTER SESSION SET nls_date_format = 'MMDDYYYYHH24MISS'

Other considerations
l Transformation does not support changes to LOB and LONG columns.
l The processing overhead for passing data to your procedure, combined with that of executing the
procedure itself, degrades overall performance on the target system compared to normal replication
and posting.
l The same PL/SQL package is used for both generic conflict resolution and transformation (its name is sp_
cr). Use either generic conflict resolution or transformation for a table, but not both. Transformed
tables cannot be compared by SharePlex and conflict resolution cannot succeed. If both are used,
SharePlex only calls the transformation routine. If appropriate, you can use generic conflict resolution
and transformation for different tables in the same configuration. For more information about conflict
resolution, see Configure replication to maintain multiple peer databases.

Deploy transformation
Deployment of transformation involves the following steps.
l Create configuration entries for the source and target tables to be transformed. There are no special
configuration procedures for tables that use transformation. Configure them as you would any other
table. See Create configuration files.
l Create transformation routines.
l Complete the transformation file

Create transformation routines

Write your transformation routines with dynamic PL/SQL procedural language. Use parameters and record and
table structures defined in the public package named sp_cr. This package was installed in the SharePlex
schema in the database. The package uses the following parameters.

SharePlex 8.6
Administrator Guide

184

l row_typ is the name of the PL/SQL record that passes in/out variables (see Package definition).
l col_def_type is the name of the PL/SQL table that stores column information (see col_def_type table).

Package definition
SharePlex defines PL/SQL record and table structures in a public package named sp_cr in the SharePlex
database schema. The package uses the following parameters.
"CREATE or REPLACE PACKAGE %s.sp_cr AS
"TYPE row_typ IS RECORD
"(src_host VARCHAR2(32),
"src_ora_sid VARCHAR2(32),
"src_ora_time VARCHAR2(20),
"source_rowid VARCHAR2(20),
"target_rowid VARCHAR2(20),
"statement_type VARCHAR2(6),
"source_table VARCHAR2(78),
"target_table VARCHAR2(78), \n\t"
"oracle_err NUMBER,
"status NUMBER,
"action NUMBER,
"reporting NUMBER
");

IN variables
For each row operation that causes a conflict, SharePlex passes this metadata information to your procedure.
Variable

Description

src_host

The name of the source system (where the operation occurred). It is

src_ora_sid

The ORACLE_SID of the source database. It is case-sensitive and is passed

in the same case as in the oratab file, Windows Registry or V$PARAMETER
table.

src_ora_time

The timestamp of the change record in the source redo log.

source_rowid

The row ID of the source row. It is passed as a literal within single

quotes, for example 123456.

target_rowid

The row ID of the corresponding row in the target database. SharePlex

obtains the row ID by querying the target database. It is passed as a
literal within single quotes, for example 123456. If the row cannot be
found using the PRIMARY key, the value is NULL.

statement_type

A letter, either I, U or D, indicating whether the operation is an INSERT,

UPDATE or DELETE statement.

source_table

The owner and name of the source table, expressed as owner.table.

This value is case-sensitive and matches the way the table is named in
the database. It is passed within double quotes, for example
"scott"."emp."

SharePlex 8.6
Administrator Guide

185

Variable

Description

target_table

oracle_err

This is different, depending on whether the procedure is being used for

OUT variables
These variables direct the action of SharePlex based on whether the procedure succeeded or failed).
Variable

Description

status

Defines whether or not the procedure succeeded. You must specify a

action

SharePlex 8.6
Administrator Guide

186

Variable

Description
The outcome of this action depends on what you specify for the
reporting variable.
l The value of 1 is reserved for internal SharePlex use. Do not use
it.
l A value of 2 directs SharePlex to try the next conflict resolution
procedure that you listed in the conflict resolution file, if one
exists.

reporting

Determines how SharePlex reports unsuccessful procedural results. You

must specify a value for this parameter.
l A value of 0 directs SharePlex NOT to report an error or write
the failed SQL statement to the SID_errlog.sql log.
l Values 1 and 2 are reserved for internal SharePlex use. Do not
use them.
l A value of 3 directs SharePlex to write the failed SQL statement
to the SID_errlog.sql log and report an error to the Event Log.

Description of col_def_tabtyp
Column

Description

column_name

Tells your procedure the name of the column that was replicated from
the source table, for example emp_last_name. This value is not case-

SharePlex 8.6
Administrator Guide

187

Column

Description
sensitive.

datatype

Tells your procedure the datatype of the data in the replicated column,
for example VARCHAR2. This value is always in capital letters.

is_key

Tells your procedure whether or not the column is a key column. If it is

a key column, SharePlex passes a value of TRUE. If the column is not
part of a key, SharePlex passes a value of FALSE.

is_changed

Tells your procedure whether or not the column value has changed. If it
is changed, SharePlex passes a value of TRUE. If the column is not
changed, SharePlex passes a value of FALSE.
l For INSERTs, is_changed is TRUE for non-NULL values, because
none of the columns existed in the database. If a NULL value is
inserted, is_changed is FALSE.
l For UPDATEs, is_changed is TRUE for non-key columns. For key
columns, is_changed normally is FALSE, but SharePlex will pass
a value for a changed key column.
Conflict resolution only: If a key value also was changed on the
target system, SharePlex will not be able to locate the correct
row, and conflict resolution could fail.
l For DELETEs, is_changed is always FALSE, because SharePlex
replicates only the key values for a DELETE statement.

old_value

new_value

Tells your procedure the new value of the replicated column, as

changed on the source system.

current_value

Tells your procedure the current value of the column in the target
table. If SharePlex cannot locate the target row, the value is NULL .

Example entries in col_def_tabtyp table per operation type

The following tables illustrate the possible outcomes of each type of operation.

INSERT operation
column_name

is_changed

old_value

new_value

current_value1

is_key

TRUE

NULL

bind

NULL

FALSE

TRUE

NULL

bind

NULL

TRUE

FALSE

NULL

TRUE | FALSE

SharePlex 8.6
Administrator Guide

188

1 When

an INSERT fails, it is because a row with the same PRIMARY key already exists in the target database.
SharePlex does not return the current value for INSERTs.

UPDATE operation
column_name

is_changed

old_value

new_value

current_value1, 2

is_key

TRUE

bind

NULL | target_value

FALSE

bind

NULL

NULL | target_value

TRUE

bind

NULL | target_value

TRUE

1 (Conflict

DELETE operation
column_name

is_changed

old_value

new_value

current_value1

is_key

FALSE

bind

NULL

TRUE

1 When

a DELETE fails, it is because SharePlex could not find the row by using the PRIMARY key. Therefore,
SharePlex returns a NULL.

Complete the transformation file

To direct SharePlex to call transformation routines instead of posting SQL operations, use the
transformation.SID file, where SID is the ORACLE_SID of the target database. Before executing a SQL operation,
Post reads this file to determine if there is a transformation routine that it must call.

Where to find this file

A blank transformation.SID file, where SID is the ORACLE_SID of the target instance, was included in the data
sub-directory of the SharePlex variable-data directory when SharePlex was installed. Use the file on the
target system.
If this file does not exist, you can create one in ASCII format in an ASCII text editor. It must be named
transformation.SID, where SID is the ORACLE_SID of the target instance. Note: the SID is case-sensitive.
IMPORTANT! There can be only one transformation.SID file per active configuration.

How to make entries in the file

Use the following template to link a procedure to one or more objects and operation types.
owner.object

{i | u | d | iud}

owner.procedure

SharePlex 8.6
Administrator Guide

189

where:
l owner.object is the owner and name of a target object, or a wildcarded entry. (See Syntax rules)
l i| u | d is the type of operation to be transformed by the specified procedure. You can specify any or all
operation types, for example id or iud. Upper or lower case are both valid.
l owner.procedure is the owner and name of the procedure that will handle the specified object and
operation type.

Syntax rules
l There must be at least one space between the object specification, the operation type specification,
and the procedure specification.
l You can use the LIKE operator and a SQL wildcard (%) to specify multiple objects by using a search
string. (See the Example.)
l You can use an underscore (_) to denote a single-character wildcard. For table names that contain an
underscore character (for example emp_sal), SharePlex recognizes the backslash (\) as an escape
character to denote the underscore as a literal and not a wildcard, for example: like:scott.%\_corp\_
emp. If you are not using the LIKE operator, the backslash escape character is not required if an object
name contains an underscore.
l You a comment line anywhere in the file. Start a comment line with the pound symbol (#).

Example transformation file

scott.sal
like:scott.%\_corp\_emp
like:scott%
scott.cust

IUD
IUD
IUD
U

scott.sal_tr
scott.emp_tr1
scott.emp_tr2
scott.sal_tr

How to change the file during replication

You can change the transformation file any time during replication to add and remove tables and procedures.
After you change the file, stop and re-start the Post process.

SharePlex 8.6
Administrator Guide

190

15
Configure SharePlex security features

SharePlex provides a number of security features that help protect replicated data on the local system
and during transfer across a network. This chapter provides guidelines for the configuration and use of
these features.

Contents
Secure connections to SharePlex
Secure data with SSH
Assign SharePlex users to security groups

Secure connections to SharePlex

SharePlex provides host authorization security that verifies whether or not SharePlex processes on specific
remote systems are authorized to connect to the local system for service and command requests. To
implement host authorization, you create an ASCII text file named auth_hosts in the data sub-directory of the
SharePlex variable-data directory and then populate it with the names of systems being granted connection
permission.

Requirements
l If used, the auth_hosts file must contain valid entries. If this file exists but is empty or contains invalid
entries, SharePlex sends an error message similar to the following example to the Event Log:
unauthorized connection attempt.
l If an auth_hosts file does not exist on a system, SharePlex accepts all requests from all systems that
attempt to connect to sp_cop.
l The name of the local system must be the first non-commented line of this file, or host authorization
will not function.
l All entries, including comments, must end with a return.

To configure the auth_hosts file

NOTE: Begin comment lines with a pound character (#).
1. Run an ASCII text editor such as vi (Unix and Linux), NotePad (Windows), or WordPad (Windows) to open a
blank file. If you are using a Unix and Linux text editor, change directories to the data sub-directory of
the SharePlex variable-data directory before you run the editor.

SharePlex 8.6
Administrator Guide

191

2. On the first non-commented line, enter the full machine name of the local system, for
example:Localhost.mycorp.com.
3. On the next non-commented line, enter one of the following:
Value

Description

all

Grants connection authorization to processes on all remote systems.

hostname

Grants connection authorization to the specified host. Enter the fully qualified
machine name, for example remotehost.mycorp.com. Specify as many host names
as needed, each on its own line.

4. Save the file as auth_hosts in the data sub-directory of the SharePlex variable-data directory. If running
multiple instances of sp_cop, make certain to save the file to the correct variable-data directory.

Example
Note the name of the local host is on the first non-commented line.
#Comment: first line is local host name.
Localhost.mycorp.com
#Comment: remaining lines are remote hosts.
remotehost.mycorp.com
remotehost2.mycorp.com
remotehost3.mycorp.com

Secure data with SSH

SharePlex uses the SSH Secure ShellTM utility to provide encryption for network services such as secure
remote login and other services over an insecure network. Using SSH with SharePlex requires the use of local
port forwarding (also known as tunneling) within the SSH configuration. Port forwarding allows you to establish a
secure SSH session and then tunnel TCP connections through it.

Requirements
l Purchase and install the SSH software. SSH is not included with Shareplex.
l SharePlex can be configured to work with SSH software between a source system and one target
system. If a source replicates to multiple targets, only one of the routes can be configured with SSH.
l This feature is supported on Unix and Linux.

To set up SharePlex to use SSH

1. On the source and target systems, choose an available local port to be used as the tunnel port. For
peer-to-peer and high availability replication, the port must be the same number on both systems. For
other replication strategies, choose a different port on each system.

SharePlex 8.6
Administrator Guide

192

2. On the source system, issue the following command from the command prompt. This command connects
to the target system to set up the tunnel.
$ ssh -L source_port:target_host:target_port userid@target_host -N -f
where:
l -L specifies that the specified port on the local host (acting as the client) is to be forwarded to
the remote host and port.
l source_port is the port number on the source system.
l target_host is the name of the target system.
l target_port is the port on the target system.
l userid is your Unix and Linux user ID. You will be prompted for the password.
l -N specifies not to execute a remote command. This is used just to forward a port (protocol
version 2 only).
l -f forces the SSH shell to work in the background just before command execution. If this
argument is omitted, the terminal window you are using must be kept open. SSH cannot be
started with nohup.
Refer to your SSH documentation for more information about these commands.
3. (If using multiple SharePlex instances) On the source system, export the correct variable-data directory
for the instance of sp_cop for which you are setting up SSH.
ksh shell:
export SP_SYS_VARDIR=/full_path_of_variable-data_directory
csh shell:
setenv SP_SYS_VARDIR /full_path_of_variable-data_directory
4. On the source system, start sp_cop. For more information about starting SharePlex, see Run SharePlex.
5. On the source system, run sp_ctrl from the bin subdirectory of the product directory.
6. In sp_ctrl, set the SP_XPT_USE_LOCALHOST parameter in one of the following ways.
l If there is only one target system, set the parameter with the following syntax:
sp_ctrl> set param SP_XPT_USE_LOCALHOST 1
l If there are multiple targets, use the following command to set up a tunnel to the target that
will use SSH. Replication to the other target systems will connect directly in the normal fashion.
sp_ctrl> set param SP_XPT_USE_LOCALHOST to host 1
where: host is the name of the target system that will use the tunnel.
7. In sp_ctrl, use the list param command with the modified option to verify the parameter setting. If the
setting is correct, you can activate a configuration at this point.
sp_ctrl> list param modified
8. If there is an active configuration, stop and then start sp_cop to make the new parameter
setting active.
To stop sp_cop:
sp_ctrl> shutdown /productdir/bin/sp_cop &
To start sp_cop:

SharePlex 8.6
Administrator Guide

193

$ /productdir/bin/sp_cop &

Assign SharePlex users to security groups

To monitor, control, or change SharePlex replication, a person must be assigned to one of the SharePlex
security groups on the systems where he or she will be issuing commands. Each group corresponds to an
authorization level, which determines which SharePlex commands a person can issue. To execute a command,
a user must have that commands authorization level or higher.

Description of the SharePlex security groups

Refer to the following table to determine the group and authorization level that you want to grant each
SharePlex user.

User Authorization Levels and Roles

Auth
level
1

User type

User
group

User roles

Administration

spadmin* You need at least one user with Administrator rights on each source and
target system.
Can issue all SharePlex commands. Commands that can only be issued by
a SharePlex Administrator are:
l startup, shutdown
l all configuration commands relating to an active configuration
l all parameter commands except list param
l start capture
l stop capture
l abort capture
l truncate log
IMPORTANT! See the Installer Checklist for important information about
the local groups that must contain an entry for the SharePlex
Administrator.

Operator

spopr

Viewer

spview

Can issue all SharePlex commands except those listed above.

Can view lists, status screens, and logs to monitor replication only.

NOTE: The default name for the SharePlex administrator group is spadmin, but you can designate any group or
specify any name for that group during installation.

Create and populate SharePlex groups on Windows

On Windows, the SharePlex groups are created in the Windows User Accounts control panel by the SharePlex
installer. To assign users to these groups, use that control panel after you install SharePlex.

SharePlex 8.6
Administrator Guide

194

Users can verify their authorization levels by issuing the authlevel command in sp_ctrl.

SharePlex 8.6
Administrator Guide

195

16
Activate replication in an Oracle
production environment

This chapter contains instructions for the initial startup of replication from an Oracle source database to an
Oracle target database on production systems.

Contents
What is activation?
Activation commands
Requirements for activating a configuration
Frequently Asked Questions about activation
Activate multiple configuration files
Activate replication with an Oracle hot backup on an active database
Activate replication with an Oracle hot backup on a quiet database
Activate replication with Oracle transportable tablespaces
Activate replication with cold copy/transfer methods

What is activation?
When you activate a configuration, through the activate config command in sp_ctrl, SharePlex does
the following:
l Copy the source data to the target database to establish an initial synchronization point. SharePlex does
not establish or populate the target database, but it does capture and store active source transactions
while the target is being established.
l Activate (read) the configuration file to build a series of internal structures that identify objects and
routes. Only one configuration can be active for any given datasource at a time. Configurations for
different datasources on a system can be active at the same time.
l Start the processes that maintain the capture and replication of source transactions.
l Reconcile replicated data with the copied data. SharePlex applies transactions that occurred after the
copy was taken and discards transactions that occurred before the copy (and thus were applied by the
copy and would be redundant if applied by replication). The reconcile process is only required for
procedures that start replication while the source database is active.
During the activation of a configuration file, SharePlex performs the following procedures.

SharePlex 8.6
Administrator Guide

196

1. Assign an activation ID
SharePlex assigns an activation ID number to each configuration activation and its associated replication
processes and queues. A configuration can be activated many times, and this ID keeps track of each one. This
number is stored in the SHAREPLEX_ACTID internal table and is transparent to SharePlex users.

2. Create an object cache

SharePlex builds an object cache to map the Oracle object IDs of the tables and sequences to their names. For
tables, the object cache includes standard metadata needed to support replication: the name, size, and type
of columns, NOT-NULL constraints, and whether a column is part of a key. For tables using partitioned
replication, additional information is stored.

3. Add a configuration change marker

SharePlex places a configuration-change marker in the data stream. This marker directs sp_cop to
generate a new set of replication processes and queues. If another configuration is active for the same
datasource, the marker deactivates it, causing the removal of the old processes and queues after the data
they contain is posted.

4. Lock the tables, add the activation marker, unlock

SharePlex locks the tables that are listed in the configuration file so that it can obtain the information it needs
in a read-consistent state. As many tables can be locked concurrently as there are locking threads available.
When SharePlex locks a table, it places an activation marker in the data stream that tells the Capture process
to start (or stop) replicating that table.
NOTE: If an application uses NOWAIT locking on tables in the replication configuration, the NOWAIT could fail if
it attempts to obtain a lock on an object that is already locked because it is being activated.
SharePlex locks the following:
l All tables added to replication (new and reactivated configurations)
l All tables removed from replication (reactivated configurations)
l All tables where routes changed (reactivated configurations)

5. Unlock the tables

Each table is locked for a very short time, just long enough to activate a table. Replication of each table begins
as soon as its activation is complete. Should one or more table fail to activate, SharePlex continues with the
activation of the other tables. Users can access the data in a source table when the activation lock is released.

Activation commands
Use sp_ctrl commands to activate, deactivate and view information about a configuration activation. For more
information about these commands, see the SharePlex Reference Guide.

Activate a configuration file

Use the activate config command to activate a configuration file. This command retains control of the sp_ctrl
command line until the activation is finished.

SharePlex 8.6
Administrator Guide

197

View activation status

Use the show activate command in sp_ctrl to view the status of all activation activity on a source system.
If there are two or more concurrent activations, the command displays their status in the order in which
they started.

View configuration statistics

Use the show config command in sp_ctrl to view statistics for active configurations. This command displays the
status of a configuration (active or inactive), the datasource, the date and time the configuration was activated,
and the number of objects that are configured.

Deactivate a configuration file

Use the deactivate config or abort config command to deactivate a configuration. The purposes of these
commands are different, but both deactivate a configuration file.
l deactivate config gracefully terminates replication for an active configuration. It stops all Capture
activity for the configuration, posts all data currently in the queues, and removes the associated
SharePlex processes and queues.
l abort config is a forceful deactivation. It stops all replication activity for the configured datasource on
the source and target systems, whether or not data in the queues has been posted.
Deactivating or aborting a configuration stops replication. If users continue making changes to the configured
objects, the source and target data can go out of synchronization.

Requirements for activating a

configuration
Activation of a configuration is an event that requires a series of actions to be taken in a timely manner,
uninterrupted. Therefore, it is important to have all of your preparations done ahead of time, leaving nothing
in question.
You can activate a configuration if you performed the following minimal requirements.

Required authorization level

Only a SharePlex Administrator can activate a configuration.
Additional users should be assigned to monitor SharePlex and perform basic operational procedures.
For more information about SharePlex user groups and authorization levels, see Assign command
authorization levels.

SharePlex 8.6
Administrator Guide

198

Pre-activation checklist
Before you activate, make certain all of the following setup procedures were performed.
Requirement

Documentation
to read

Make certain all installation-related tasks were performed.

SharePlex
Installation
Guide

Understand how to start and stop the sp_cop program.

Run SharePlex

Understand how to issue SharePlex commands.

Execute
commands in
sp_ctrl

Create and prepare the objects that you want to replicate.

Set up Oracle
database
objects for
replication

Make recommended adjustments to the database configuration to support replication.

Set up an
Oracle
database to
support
SharePlex

Enable transaction logging to the level required for the data that you are replicating.

Set up Oracle
redo logging to
support
SharePlex

Ensure that SharePlex can communicate over the network.

Set SharePlex parameters to support specific data types.

Set up
SharePlex to
support Oracle
data

Enable DDL replication (if applicable)

Set up DDL
Replication

Create a configuration file

Create
configuration
files

Configure target properties in Post (non-Oracle targets)

Configure Post
to support a
non-Oracle
target

Plan and configure SharePlex to support your replication strategy

Configure a
replication
strategy

Set up optional SharePlex features

Configure
SharePlex
security
features

SharePlex 8.6
Administrator Guide

199

Requirement

Documentation
to read
Transform data

Open and mount the source and target databases.

Database
documentation

Prevent DDL operations, including TRUNCATE, during activation. Where permitted, DML
changes are the only permissible changes during activation.

Database
documentation

Understand the commands that you will use

You will use several commands during the activation of replication. It is recommended that you review the
documentation for these commands to understand the functions that they perform and their syntax. The main
commands are as follows:
l To activate the configuration to start replication in production, you run the activate config command.
See What is activation? and the activate config documentation in the SharePlex Reference Guide.
l To compare the replicated transactions against the data that was applied by the method used for initial
data synchronization, you run the reconcile command. This command discards transactions that already
were applied to the source when the copy was made, and therefore should be prevented from being
applied to the target. See the SharePlex Reference Guide.

Test the configuration file

Before you activate a configuration in production, perform a test activation by using the verify config
command. If there are syntax errors, misspellings or duplicate entries in the configuration file, the entire
activation will fail.
This command will test the configuration to find and report the following conditions:
l Verify the syntax of the entries in the configuration file.
l Report an error if the source object is not a table or sequence.
l Report if a host name specified in a route is unreachable.
l Report if there are duplicate specifications for a single object.
l Report if a table specification will be skipped and the reason why.
l List the qualifying objects included under wildcard specifications.
The verify config command does not verify how long the activation will take, nor will it verify the target
objects or database connection (as represented by the database identifier listed in the routing map.)
For more information, see the verify config command in the SharePlex Reference Guide.

SharePlex 8.6
Administrator Guide

200

Frequently Asked Questions about

activation
What happens during activation?
During activation, SharePlex gets the information it needs to identify and understand the objects that
are configured for replication and build routing maps. For more information, see What is activation?.

How long does activation take?

The length of time that activation takes varies, depending on the size, number and structure of the
configured objects.

Do users have to stop access to the data?

No. Each source table is briefly locked so SharePlex can build its internal object information. Then the
lock is released. This happens very quickly and may not even be noticeable by users. However, if a
business application has NOWAIT locking, the SharePlex lock may cause the application to fail if it
attempts to obtain a lock on an object that is being activated.

Can DDL be performed during activation?

No. Only DML changes are permitted on objects that are being activated. Once activation is finished, DDL
can be performed, but keep in mind that if the DDL is not the kind supported by SharePlex and
configured for replication, the DDL may cause the source and target objects to become out of
synchronization.

Can I activate multiple configurations for the same datasource?

No. You can create as many configurations for the same Oracle source data (meaning in the same Oracle
instance) but only one can be active at the same time.

Can I activate configurations for different datasources at the same time?

Yes. See Activate multiple configuration files.

Can I test a configuration before I activate it?

Yes. This is highly recommended. Use the verify config command. See Requirements for activating a
configuration.

Can I interrupt an activation to make changes?

Yes and no. Activation is meant to be an uninterrupted procedure that initiates replication while
maintaining the same series of transactional events as those appearing in the redo log. You can use the
abort config command to terminate an activation, but you may then need to clean out the queues and
resynchronize the source and target data again. Ideally, you should have a tested configuration file
ready to be activated and be prepared to issue commands to the database and to SharePlex.

SharePlex 8.6
Administrator Guide

201

Can I activate against a quiet database?

Yes, but the database must be mounted and open.

Can I increase the number of activation threads?

Yes. The number of threads is controlled globally by the SP_OCF_THREAD_COUNT parameter, which
must be set before you issue the activate config command. You can override this value for a particular
activation by using the threads option when you issue the activate config command.

Activate multiple configuration files

You can activate one configuration per datasource (Oracle instance) on a system. For example, if there are
ConfigA, ConfigB and ConfigC for instance ora10, you can activate only one of them at a time. Activating another
configuration for the same datasource automatically deactivates the first one.
However, if ConfigA replicates data from o.OraA and ConfigB replicates data from o.OraB, you can activate both
of those configurations at the same time. Replication for those configurations can operate concurrently.

To activate multiple configuration files

The activation process retains control of the sp_ctrl interface until the activation is finished. Because an
activation can take a significant amount of time, you can use different configurations in different sessions of sp_
ctrl. Activate the first configuration, then open another session of sp_ctrl to activate the second one. Open as
many sessions of sp_ctrl as you have configurations to activate.
The number of activation threads is controlled by the SP_OCF_THREAD_COUNT parameter, which is a global
setting for the instance of SharePlex. When activating more than one configuration concurrently, you can
override this value for a particular activation by using the threads option when you issue the activate
config command.

Activate replication with an Oracle hot

backup on an active database
Use this procedure to use an Oracle hot backup to establish a target Oracle instance and activate replication
without quieting the source database. This procedure involves using the reconcile command to ensure that
transactions which occurred after the point of backup are applied to the target, while eliminating redundant
replicated transactions that are already captured by the backup.

Preliminary considerations
Read these points before you proceed.

Supported databases
Oracle source and Oracle target

SharePlex 8.6
Administrator Guide

202

Supported replication strategies

All replication strategies are supported with the following limitations:
Limitation
applies to:

Description

Consolidated
replication
(many
sources to
one target)

To establish consolidated replication, the use of a hot backup from all source systems is not
possible. A backup from one source will override the data that was applied by a backup from a
different source. You can use a hot backup of one of the source instances to establish a target
instance, and then use another copy method to apply the objects from the other source
instances. Possible methods include:
l Export/import (see Activate replication with cold copy/transfer methods)
l FTP (see Activate replication with FTP)
l Transportable tablespaces (see Activate replication with Oracle transportable
tablespaces)

Peer-topeer

To establish peer-to-peer replication, you must:

1. Quiet all of the systems except the trusted source system for the duration of this
procedure.
2. Move all users to the trusted source system, and then follow this procedure.
Only after this procedure has been performed on all of the secondary systems may users may
resume activity on them.

Windows
systems

To use a hot backup between Windows systems, the target system must have an instance
already created containing an identical ORACLE_SID and directory structure created with the
Oracle creation tools. Oracle runs as a service on Windows, and the Registry entries must exist
before starting the database recovery process. The database can start empty, because the
hot backup will populate it.

Requirements
l [Unix and Linux systems] Verify that the ORACLE_SID and ORACLE_HOME in the oratab file are correct for
the instance you will be establishing with the hot backup. The SID must be the SID used in the routing
map in the configuration file that you will be activating.
l Read the requirements in Requirements for activating a configuration before you start this procedure.
l Make certain a SharePlex database account exists in the source database (only). This account usually is
created when SharePlex first is installed. See the SharePlex Installation Guide for more information.

Procedures
There are two procedures for activation with a hot backup, depending on your replication strategy.
Activate replication with an Oracle hot backup on an active database
Activation with hot backup:cascading replication

SharePlex 8.6
Administrator Guide

203

Activation with hot backup: all strategies except cascading

Use this procedure for all replication strategies except cascading replication where SharePlex will be posting
to a database on the intermediary system.
1. On the source and target systems, go to the bin sub-directory of the SharePlex product directory, and
start sp_cop and sp_ctrl.
2. On both systems, verify that the SharePlex processes are running.
sp_ctrl> status
3. On the target system, stop the Post process. This allows replicated data to accumulate in the post
queue until the database has been recovered and reconciled.
sp_ctrl> stop post
4. On the source system, run the Oracle hot backup.
5. When the backup is finished, activate the configuration on the source system.
sp_ctrl> activate config filename
6. On the source system, monitor activation status.
sp_ctrl> show activate
NOTE: The command retains control of sp_ctrl until activation is finished.
7. When activation is complete, switch log files on the source system.
svrmgr1> alter system switch logfile;
8. Do one of the following:
l To recover the database to a sequence number, make a note of the highest archive-log
sequence number.
l To recover the database to a Oracle System Change Number (SCN), pick an SCN to recover to on
the target database.
9. On the target system, do one of the following:
l If recovering to a sequence number, recover the database from the hot backup using the UNTIL
CANCEL option in the RECOVER clause, and cancel the recovery after Oracle has fully applied the
log from the previous step.
l If recovering to a SCN, recover the database from the hot backup using the UNTIL CHANGE scn
option in the RECOVER clause, and cancel the recovery after Oracle has applied the logs
matching the SCN from the previous step.
10. On the target system, open the database with the RESETLOGS option.
11. On the target system, run on the database. When prompted for the SharePlex database user, enter n to
choose the existing user and password (these were copied in the backup).
Would you like to create a new SharePlex user [y]. n
NOTE: SharePlex can remain running during the setup process.
12. [Optional] If you are using named post queues and are unsure of the queue names, issue the
qstatus command.
sp_ctrl> qstatus
13. On the target system, issue the reconcile command as follows, depending on the recovery option you

SharePlex 8.6
Administrator Guide

204

chose. If you are using named post queues, issue the command for each one.
l If recovering to a sequence number, substitute the sequence number of the log that you noted
previously.
sp_ctrl> reconcile queue queuename for datasource-datadest seq sequence_number
Example: reconcile queue SysA for o.oraA-o.oraA seq 1234
l If recovering to a SCN, substitute the SCN that you noted previously.
sp_ctrl> reconcile queue queuename for datasource-datadest scn scn_number
Example: reconcile queue SysA for o.oraA-o.oraA scn 0123456789
NOTE: The command retains control of sp_ctrl until the reconcile process is finished.
14. On the target system, run the cleanup.sql script to truncate the SharePlex internal tables. Instructions
for running this script are in the SharePlex Reference Guide.
15. On the target system, disable triggers on the tables, or run the sp_add_trigger.sql utility script so that
the triggers ignore the SharePlex user.
16. On the target system, disable check constraints and scheduled jobs that perform DML.
17. [Partitioned replication only] If you are using vertically partitioned or horizontally partitioned
replication for any tables, delete the unneeded columns and rows from those tables.
18. [High availability only] On the target (secondary) system, stop Export.
sp_ctrl> stop export
19. [High availability and peer-to-peer only] On the target (secondary) system, activate the configuration so
that SharePlex is ready in the event of failover.
sp_ctrl> activate config filename
20. On the target system, start the Post process. The two instances are now in synchronization, and
SharePlex will continue replicating to maintain synchronization.
sp_ctrl> start post
21. [Optional] If this was only a partial backup, drop the tablespaces that were not copied over during the
hot backup.

Activation with hot backup:cascading replication

Use this procedure for cascading replication where SharePlex will be posting to a database on the
intermediary system.
You will apply the backup to the intermediary system first (represented as sysB), and then to the target
system (represented as sysC).
1. On all systems, go to the bin sub-directory of the SharePlex product directory, and start sp_
cop and sp_ctrl
2. On all systems, verify that the SharePlex processes are running.
sp_ctrl> status
3. On the intermediary and target systems, stop the Post process. This allows replicated data to
accumulate in the post queue until the databases are recovered.
4.

sp_ctrl> stop post

SharePlex 8.6
Administrator Guide

205

5. On the source system, run the Oracle hot backup to the intermediary and target systems.
6. When the backup is finished, activate the configuration on the source system.
sp_ctrl> activate config filename
7. On the source system, view activation status.
sp_ctrl> show activate
NOTE: The command retains control of sp_ctrl until activation is finished.
8. When activation is complete, switch log files on the source system.
svrmgr1> alter system switch logfile;
9. Make a note of the highest archive-log sequence number.
10. On the intermediary system, recover the database from the hot backup using the UNTIL CANCEL option
in the RECOVER clause, and cancel the recovery after Oracle has fully applied the log from the
previous step.
11. On the intermediary system, open the database with the RESETLOGS option.
12. On the intermediary system, run on the database. When prompted for the SharePlex database user,
enter n to choose the existing user and password (these were copied in the backup).
Would you like to create a new SharePlex user [y]. n
NOTE: SharePlex can remain running during the setup process.
13. [Optional] If you are using named post queues and are unsure of the queue names, issue the
qstatus command.
sp_ctrl> qstatus
14. On the intermediary system, issue the reconcile command for each post queue. For seq sequence_
number, substitute the sequence number of the log that you noted previously.
sp_ctrl> reconcile queue queuename for datasource-datadest seq sequence_number
Example: reconcile queue SysA for o.oraA-o.oraA seq 1234
15. On the intermediary system, run the cleanup.sql script to truncate all of the SharePlex internal tables.
Instructions for running this script are in the SharePlex Reference Guide.
16. On the intermediary system, disable triggers on the tables, or run the sp_add_trigger.sql utility script
so that the triggers ignore the SharePlex user.
17. On the intermediary system, disable check constraints and scheduled jobs that perform DML.
18. On the intermediary system, set the SP_OCT_REPLICATE_POSTER parameter to 1. This directs SharePlex
to capture posted changes on that system and replicate them to the target system.
sp_ctrl> set param SP_OCT_REPLICATE_POSTER 1
19. [Partitioned replication only] If you are using vertically partitioned or horizontally partitioned
replication for any tables, delete the unneeded columns and rows from those tables.
IMPORTANT! Do not start any Post processes yet.
20. On the target system, recover the database from the hot backup using the UNTIL CANCEL option in the
RECOVER clause, and cancel the recovery after Oracle has fully applied the log that you reconciled to in
the previous steps taken on the intermediary system.
21. On the target system, open the database with the RESETLOGS option.

SharePlex 8.6
Administrator Guide

206

22. On the target system, run on the database. When prompted for the SharePlex database user, enter n to
choose the existing user and password (these were copied in the backup).
Would you like to create a new SharePlex user [y]. n
NOTE: SharePlex can remain running during the setup process.
23. On the target system, run the cleanup.sql script to truncate the SharePlex internal tables. Instructions
for running this script are in the SharePlex Reference Guide.
24. On the target system, disable triggers on the tables, or run the sp_add_trigger.sql utility script so that
the triggers ignore the SharePlex user.
25. On the target system, disable check constraints and scheduled jobs that perform DML.
26. [Partitioned replication only] If you are using vertically partitioned or horizontally partitioned
replication for any tables, delete the unneeded columns and rows from those tables.
27. On the intermediary system, activate the configuration file.
sp_ctrl> activate config filename
28. On the intermediary system, monitor activation status.
sp_ctrl> show activate
NOTE: The command retains control of sp_ctrl until activation is finished.
29. On the intermediary and target systems, start the Post process. All instances are now in
synchronization, and SharePlex will continue replicating to maintain synchronization.
sp_ctrl> start post
30. [Optional] If this was only a partial backup, drop the tablespaces that were not copied over during the
hot backup.

Activate replication with an Oracle hot

backup on a quiet database
Use this procedure to use an Oracle hot backup to establish a target Oracle instance and activate replication if
user activity can be stopped while the procedure is performed. This procedure can be used for all replication
configurations.

Preliminary considerations
Read these points before you proceed.

Supported databases
Oracle source and Oracle target

Supported replication strategies

All but high-availability. This procedure is not appropriate for a high-availability strategy because it requires
the source database to be quieted while the backup is taken and the configuration file is being activated.
Certain limitations apply:

SharePlex 8.6
Administrator Guide

207

Limitation
applies to:

Description

Consolidated
replication
(many
sources to
one target)

Windows
systems

Requirements
l [Unix and Linux systems] Verify that the ORACLE_SID and ORACLE_HOME in the oratab file are correct for
the instance you will be establishing with the hot backup. The SID must be the SID used in the routing
map in the configuration file that you will be activating.
l Read the requirements in Requirements for activating a configuration before you start this procedure.
l Users must stop accessing the production database while the hot backup and configuration activation
take place.
l Make certain a SharePlex database account exists in the source database (only). This account usually is
created during SharePlex installation. See the SharePlex Installation Guide for more information.

Procedure
NOTE: If you are not using cascading replication, ignore all references to an intermediary system. For more
information about cascading replication, see Configure replication through an intermediary system.
1. On the source system, complete the Oracle hot backup.
2. On the source system, stop user access to the source database by shutting it down and opening it in
restricted mode.
3. On the source system, switch the redo logs
svrmgr1> alter system switch logfile;
4. Keep a record of the sequence number of the current log.
5. On all systems, start sp_cop and sp_ctrl from the bin sub-directory of the SharePlex product directory.
6. On all systems, verify that sp_cop and sp_ctrl are running.
sp_ctrl> status
7. On the intermediary and target systems, stop Post. Stopping Post allows replicated data to accumulate

SharePlex 8.6
Administrator Guide

208

in the post queue until the databases have been recovered.

sp_ctrl> stop post
8. On the source system, activate the configuration file.
sp_ctrl> activate config filename
9. On the source system, view activation status.
sp_ctrl> show activate
NOTE: The command retains control of sp_ctrl until activation is finished.
10. When the activation is finished, allow users to resume access to the source database.
11. List the archive logs on the intermediary and target systems. Delete any logs made after the one for
which you made a record.
12. On the intermediary and target systems, recover the database to the log number that you recorded.
Make sure a full recovery is performed.
13. On the intermediary and target systems, open the database.
14. On the intermediary and target systems, run for the target instance. When prompted for the SharePlex
database user, enter n to choose the existing user and password (these were copied in the backup).
Would you like to create a new SharePlex user [y].n
NOTE:SharePlex can remain running during the setup.
15. On the intermediary and target systems, run the cleanup.sql script to truncate the SharePlex internal
tables. Instructions for running this script are in the SharePlex Reference Guide.
16. On the intermediary and target systems, disable triggers on the tables, or run the sp_add_trigger.sql
utility script so that the triggers ignore the SharePlex user.
17. On the intermediary and target systems, disable check constraints and scheduled jobs that
perform DML.
18. [Partitioned replication only] If you are using vertically partitioned or horizontally partitioned
replication for any tables, delete the unneeded columns and rows from those tables on the
intermediary and target systems.
19. [Intermediary system only] On the intermediary system, set the SP_OPO_REPLICATE_POSTER
parameter to 1. This directs SharePlex to capture posted changes on that system and replicate them
to the target system.
sp_ctrl> set param SP_OCT_REPLICATE_POSTER 1
20. On the intermediary system, activate the configuration file.
sp_ctrl> activate config filename
21. On the intermediary system, monitor activation status.
sp_ctrl> show activate
NOTE: The command retains control of sp_ctrl until activation is finished.
22. When activation is finished, start the Post process on the intermediary and target systems. All instances
are now in synchronization, and SharePlex will continue replicating to maintain synchronization.
sp_ctrl> start post
23. [Optional] If this was only a partial backup, drop the tablespaces that were not copied over during the

SharePlex 8.6
Administrator Guide

209

hot backup.

Activate replication with Oracle

transportable tablespaces
Use this procedure to use the Oracle transportable tablespaces feature to establish a target Oracle instance
and activate replication. It enables you to synchronize and resynchronize numerous objects quickly and with
minimal downtime. It allows you to export just the metadata (data dictionary) and then copy the data files. This
method also moves indexes so that there is no need to rebuild them in the target database, and you can move
multiple tablespaces at one time.
NOTE: This document does not provide instructions for how to use transportable tablespaces. This procedure
should be performed by someone who has a solid understanding of database copy methods.

Preliminary considerations
Read these points before you proceed.

Supported databases
Oracle source and Oracle target

Supported replication strategies

All replication strategies. This procedure may not appropriate for a high-availability strategy if the source
database cannot be quieted even briefly.

Requirements
l Read the requirements in Requirements for activating a configuration before you start this procedure.
l Make certain a SharePlex database account exists in the source database (only). This account usually is
created when SharePlex is first installed. See the SharePlex Installation Guide for more information.

Naming conventions used

In this procedure, the "source" system is one of the following:
l The source system of a single-direction replication configuration, including cascading replication.
l All source systems of a consolidated replication configuration.
l The trusted source system in a peer-to-peer replication configuration.
In this procedure, the "intermediary" system only needs to be part of this procedure if SharePlex will be
posting to, and capturing from, an intermediary system in a cascading configuration.
In this procedure, the "target" system is one of the following:
l The target system of a single-direction replication configuration, including cascading and consolidated
replication.
l The secondary systems in a peer-to-peer replication configuration.

SharePlex 8.6
Administrator Guide

210

In this procedure, the SharePlex commands in the procedure apply to all sp_cop instances that apply to the
replication strategy you are using (for example, all sp_cop processes on a target in consolidated replication).

Procedure
1. On the source system, set the source tablespaces that you want to copy to READ ONLY.
svrmgr1> alter tablespace name read only;
2. On the source system, activate the configuration file.
sp_ctrl> activate config filename
3. On the source system, start sp_cop and sp_ctrl from the bin sub-directory of the SharePlex
product directory.
4. On the source system, verify that sp_cop and sp_ctrl are running.
sp_ctrl> status
5. On the intermediary and target systems, stop Post. Stopping Post allows replicated data to accumulate
in the post queue until the databases have been recovered.
sp_ctrl> stop post
6. On the source system, export the metadata to an export file.
7. When the export is finished, copy the datafiles to another location on the source system. This minimizes
the impact on the source database of copying the files to the target system.
8. Set the source tablespaces back to read/write mode.
svrmgr1> alter Tablespace name read write;
9. If any of the copied datafiles and tablespaces exist in the intermediary or target database, drop them so
that the copied files can be applied.
10. Copy the files from the new location on the source system to the intermediary and target systems.
11. On the intermediary and target systems, use the Oracle import utility to import the metadata and the
tablespace definitions.
12. On the intermediary and target systems, set the tablespace(s) to read/write mode.
13. On the intermediary and target systems, open the Oracle instances.
14. On the intermediary and target systems, disable triggers on the tables, or run the sp_add_trigger.sql
utility script so that the triggers ignore the SharePlex user.
15. On the intermediary and target systems, disable check constraints and scheduled jobs that
perform DML.
16. [Partitioned replication only] If you are using vertically partitioned or horizontally partitioned
replication for any tables, delete the unneeded columns and rows from those tables on the
intermediary and target systems.
17. [Intermediary system only] Set the SP_OPO_REPLICATE_POSTER parameter to 1. This directs SharePlex
to capture posted changes on that system and replicate them to the target system.
sp_ctrl> set param SP_OCT_REPLICATE_POSTER 1
18. [Intermediary system only] Activate the configuration file.
sp_ctrl> activate config filename

SharePlex 8.6
Administrator Guide

211

19. [High availability] On the target system, stop the Export process.
sp_ctrl> stop export
20. [High availability and peer-to-peer replication] Activate the configuration on the target system(s).
sp_ctrl> activate config filename
21. Start Post on the intermediary and target systems. SharePlex begins executing the SQL statements that
have been collecting in the post queue, keeping the source and target data in sync.
sp_ctrl> start post
22. [Peer-to-peer replication] Allow users to access the databases on all systems.

Activate replication with cold

copy/transfer methods
Use this procedure to synchronize the source and target data with the following utilities:
l Import/Export/Data Pump
l Store/Restore from tape
l FTP
NOTE: This document does not provide instructions for how to perform the chosen copy method. This
procedure should be performed by someone who has a solid understanding of database copy methods.

Preliminary considerations
Read these points before you proceed.

Supported databases
Oracle source and Oracle target

Supported replication strategies

All but high-availability. This procedure is not appropriate for a high-availability strategy because it requires
the source database to be quieted while the configuration file is being activated.

Requirements
l [Unix and Linux systems] Verify that the ORACLE_SID and ORACLE_HOME in the oratab file are correct for
the instance you will be establishing with the hot backup. The SID must be the SID used in the routing
map in the configuration file that you will be activating.
l Read the requirements in Requirements for activating a configuration before you start this procedure.
l Users must stop accessing the production database while the copy and configuration activation
take place.
l The target instance must exist.

SharePlex 8.6
Administrator Guide

212

l Make certain SharePlex database accounts exist in the source and target databases. This account
usually is created during installation. See the SharePlex Installation Guide for more information.

Naming conventions used

Procedure
1. On the source system, stop user access to the objects that are in the replication configuration.
l If deploying consolidated replication, you can either stop access to all of the source systems at
once and make the copies at the same time, or you can synchronize each source system one at a
time using these instructions.
l If deploying peer-to-peer replication, stop access to all databases in the peer group, including
the trusted source.
2. Copy the files from the source system to the intermediary and target systems.
3. On the source system, start sp_cop and sp_ctrl.
4. On the source system, activate the configuration file (all files if using consolidated replication).
sp_ctrl> activate config filename
5. On the intermediary and target systems, start sp_cop and sp_ctrl.
6. On the intermediary and target systems, stop Post. Stopping Post allows any data that gets replicated
before the target data is established to collect in the post queue.
sp_ctrl> stop post
7. On the source system, allow users to resume access to the source database.
8. On the source system, verify that the sp_cop, Capture, and Read processes are running.
sp_ctrl> status
9. Start and mount the intermediary and target databases, but do not allow users access.
10. On the intermediary and target systems, apply the copy to the database.
11. On the intermediary and target systems, disable triggers on the tables, or run the sp_add_trigger.sql

SharePlex 8.6
Administrator Guide

213

utility script so that the triggers ignore the SharePlex user.

12. On the intermediary and target systems, disable check constraints and scheduled jobs that
perform DML.
13. [Partitioned replication only] If you are using vertically partitioned or horizontally partitioned
replication for any tables, delete the unneeded columns and rows from those tables on the
intermediary and target systems.
14. [Intermediary system only] Set the SP_OPO_REPLICATE_POSTER parameter to 1. This directs SharePlex
to capture posted changes on that system and replicate them to the target system.
sp_ctrl> set param SP_OCT_REPLICATE_POSTER 1
15. [Intermediary system only] Activate the configuration file.
sp_ctrl> activate config filename
16. [Peer-to-peer] Activate the configuration file on the target systems.
17. Start Post on:
l The intermediary system
l The trusted source and all other targets in a peer group
l All other targets
NOTE: SharePlex will start executing SQL statements that accumulated in the post queue.
18. [Peer-to-peer] On the target systems in the peer group, allow users to resume access to the database.

SharePlex 8.6
Administrator Guide

214

17
Monitor SharePlex

This chapter contains an overview of the tools that SharePlex provides to detect errors and monitor the
replication processes. Like any mission-critical software, SharePlex should be monitored regularly for situations
or events that could interfere with processing, especially those that could result in loss of data
synchronization.

Contents
View and terminate SharePlex processes
View events and errors
Monitor with sp_ctrl commands
Run monitor scripts on Unix
Run a monitor script on Windows
Monitor replication with SNMP

View and terminate SharePlex processes

Viewing and terminating processes on Unix and Linux systems
On Unix and Linux systems, you can use the ps -ef | grep sp_ command to display all of the major and
background SharePlex processes that are running.

SharePlex 8.6
Administrator Guide

215

Sample display using ps -ef | grep sp_: This command issued in System V produces a basic display of all
the SharePlex processes that are running, including background processes with which users do not
interact. This command in other Unix versions returns similar information. It returns, from left to right:
l The user ID
l The process ID number of the process
l The process ID of the parent process that spawned the process
l How long the process has been running
l The start time of the process
l The terminal on which the process is running
l The amount of CPU time the process has consumed
l The command that started the process
To kill any of those processes, use the kill or kill -9 command.
$ kill PID
Or...
$ kill -9 PID

Viewing SharePlex processes on Windows systems

You can view the SharePlex processes on Windows systems in the following ways:
l From the Command Prompt console using the tlist program provided with the Share- Plex software (also
available in the Microsoft Windows Resource Kit).
l From the Windows Task Manager or the DTaskmgr utility provided with SharePlex.

SharePlex 8.6
Administrator Guide

216

Terminating SharePlex processes on Windows systems

You cannot terminate SharePlex processes through the Windows Task Manager. The NuTCRACKER environment
controls the SharePlex processes, so you need to run DTaskmgr, a special version of the Task Manager with
special privileges that is provided with the SharePlex software. To determine which process to kill, see How to
identify Sp_Copsrv.exe processes on Windows systems in the SharePlex Administrators Guide.
You can terminate SharePlex processes on Windows systems using the following tools:
l DTaskmgr
l KillSharePlex.bat
l Kill

Terminating processes with DTaskmgr

DTaskmgr can be run directly from its location in the SharePlex product directory. When run this way, it
displays all of the processes on the system, including processes for other applications.
1. Double-click the DTaskmgr icon in the bin sub-directory of the SharePlex product directory, or run it
from the Start menu by navigating to its location in the SharePlex programs group.
Click the Processes tab.

2.
3. Highlight the SharePlex process that you want to terminate.
4. Click End Process. A warning message prompts for confirmation of your intent to kill the process.
5. Click Yes to terminate the process.

Terminating processes with KillSharePlex.bat

KillSharePlex.bat is a batch file that terminates all SharePlex processes at once, without displaying them.
There is no user interface; the program works in the background without prompts or confirmation when it is

SharePlex 8.6
Administrator Guide

217

finished. To run KillSharePlex.bat, doubleclick its icon in the bin sub-directory of the SharePlex product
directory.

Terminating processes with kill

DTaskmgr does not work if Windows Terminal Server is installed. In that case, use the kill program provided
with SharePlex in the bin sub-directory of the SharePlex product directory. (This command also is available in
the Windows Resource Kit from Microsoft).
1. From the Start menu, select Run.
2. In the Open text box, type the characters cmd to open the Windows Command Prompt.
3. At the prompt, change directories to the bin sub-directory of the SharePlex product directory.
4. Type the tlist command and then press Enter. A list of processes is displayed.
5. At the command prompt, type kill followed by either the Process ID number or name of the process you
want to kill. You can terminate any SharePlex process in this manner. Most SharePlex processes begin
with Sp_. To view all of them, look in the bin sub-directory in the SharePlex product directory.

If a process survives the kill command, try the /F option with the kill command to force the termination.

View events and errors

SharePlex reports errors and other abnormal conditions in the following ways.

SharePlex 8.6
Administrator Guide

218

Event Log
SharePlex reports operational errors, notices and warning conditions to the Event Log, which is a file
named event_log that resides in the log sub-directory of the SharePlex variable-data directory. The Event
Log provides a perpetual step-by-step record of replication activities, errors, and events. It can be viewed
directly from the Unix and Linux command-line or through the show log command in the sp_ctrl commandline interface. SharePlex provides a script for unattended monitoring of this log. See Monitor events with
sp_eventmon.
The Event Log can help you replay the sequence of events that led up to a problem. Examples of replication
events include:
l Start or stop of sp_cop or a replication process
l Execution of a command in sp_ctrl
l Oracle errors
l Failure of a network connection or SharePlex process
l Start or stop of a utility or script
l Login or logout of a user
User-issued commands are recorded for every SharePlex command that is issued for that instance of SharePlex.
It is useful when something has affected replication and you want to see if one or more users caused it. For
example, if Post is not running, the log may show that it was stopped by a user, the date and time it was issued,
and the command that was used.
NOTE: A user-issued command appears in the Event Log as a notice, as in the following example:
Notice 08-07-02 16:13:24.641582 23696 1 User command: rjones activate config
1route (from irvspxu14)
Each entry in the Event Log includes:
l The date and time of the event.
l A description of the event and any related messages (error or non-error).
l The events process ID number, if it is associated with a SharePlex process.

Status Database
The Status Database is generated when you issue the show statusdb command in sp_ctrl. It contains a detailed
summary of the conditions reported in the Event Log, including events that did not generate an error message
or warning at the sp_ctrl user interface. This information alerts you to potential problems and helps you
resolve existing ones. The Status Database may refer you to the Event Log for a more detailed explanation of a
warning, notice or event. The Status Database is viewed through the sp_ctrl command-line interface but the
file itself resides in the log sub-directory of the SharePlex variable-data directory.

Error Log
When the Post process detects that source and target tables are out of synchronization, it logs the first 100 SQL
statements and data for the out-of-sync transactions to an error file on the target system named ID_errlog.sql.
(ID is the identifier of the SharePlex target, for example a target database.) You can use this log to determine
the extent of the out-of-sync condition, and you can use the SQL statements to repair target tables if the
condition is not too severe, after first correcting the cause of the problem. This file resides in the log subdirectory of theSharePlex variable-data directory.

SharePlex 8.6
Administrator Guide

219

Process logs
When a SharePlex process cannot process a record, that record is logged to the Event Log and also to a log file
in the log sub-directory of the SharePlex variable-data directory. The process logs are primarily used for
debugging and are viewed only through shell commands or a text editor.
The names of the process logs consist of the datasource identifier (such as the ORACLE_SID), the short name of
the process (ocap, ord, opo, rcl), the file number, and the file extension (.log).
Examples:
Capture: ora10_ocap02.log
Read: ora10_ord01.log
Post: ora10_opo03.log
Reconcile: ora10_rcl01.log
The aging of old log files is performed in a circular pattern. Up to three logs can exist at any given point,
including the current one. When the current file reaches 50 MB in size, the logging moves to a new file. When 3
logs fill up, the process starts overwriting them, starting with the oldest one. The numbering begins with 01
and ends with 03.

Activation log
When you activate a configuration, it generates a log named SID_oconf##.log in the log sub-directory of the
SharePlex variable data directory. To view the activation log, use shell commands or a text editor.

Compare/repair log
The compare and repair commands log errors, messages and warnings to thelog sub-directory of theSharePlex
variable-data directory under either the sp_desrvr or sp_declt process name. For more information about
viewing these logs, see the compare commands in the SharePlexReference Guide.

Monitor with sp_ctrl commands

The information commands in sp_ctrl help you monitor different aspects of replication. Issue them
frequently to:
l Monitor for out-of-sync tables.
l Verify that replication processes are running.
l View the number of replicated messages in the queues.
l View the Event Log to view warnings, errors and other notifications.
l View process statistics that are helpful for tuning and problem solving.
l Detect tables or operations that are slowing down the replication process.

List of information commands

Command

Auth. level

Description

append status

Displays status and results of the append using and append

commands.

SharePlex 8.6
Administrator Guide

220

Command

Auth. level

Description

copy status

Displays status and results of the copy using and copy

commands.

compare status

Displays the status and results of the compare using and

compare commands.

lstatus

Displays detailed information about the state of SharePlex

replication.

job status

Displays current status and history for append, compare, copy

and repair commands.

orainfo

Displays the Oracle database information.

qstatus*

Displays the state of the capture, export and post queues.

repair status

Disaplys the status and results of the repair and repair using
commands.

report

Displays append, compare, copy and/or repair history for a

table.

show

Displays the source and destination of the data being

processed by each replication process on a system, and
displays the status of each process.

show activate

Displays the status of all configuration activation activity on a

source system.

show capture

Displays brief or detailed statistics for the Capture process for

use in tuning and problem solving.

show config

Displays properties of the active configuration.

show export

Displays the number of messages sent to the target system(s).

show import

Displays the number of messages received from the source

system(s).

show log

Displays the Even Log, Command Log, Verify Log, Trace Log, or a
process log.

show post

Displays brief or detailed statistics for the Post process for use
in tuning and problem solving.

show read

Displays brief or detailed statistics for the Read process for use
in tuning and problem solving.

show sql

Displays the current or last SQL statement processed by the

Post process.

show statusdb*

Displays the Status Database, which contains records of

important replication events.

show sync*

Displays information about out-of-sync conditions.

status*

Displays an overview of the state of SharePlex replication.

See the SharePlex Reference Guide for details about these commads.

SharePlex 8.6
Administrator Guide

221

Run monitor scripts on Unix

This topic explains how to use the SharePlex monitoring scripts on Unix or Linux systems to notify you of events
and conditions that can adversely affect replication. These scripts provide a monitoring mechanism without the
need for frequent status checks through sp_ctrl. They can be run independently or through scheduled jobs.
SharePlex provides the following scripts:
l sp_eventmon monitors the SharePlex Event Log and reports errors that you specify in a special file.
l sp_logmon monitors how well Capture is keeping pace with the changes entering the redo logs. If
Capture loses pace by a specified number of logs, sp_logmon alerts you before the logs wrap so that you
can take corrective action.
l sp_ps monitors the SharePlex processes and notifies you if one or more are stopped so that you can
correct the problem before the logs wrap or the queues exceed available disk space.
l sp_qstatmon monitors the status of the SharePlex queues and sends a warning if the backlog exceeds a
threshold (limit) that you define. This enables you to take corrective action before the queues exceed
available disk space and replication is adversely affected.
IMPORTANT!
l These scripts run on Unix or Linux systems only.
l These scripts must be run in the ksh shell.
l The monitoring scripts are overwritten with new scripts during patches and upgrades of SharePlex.
Before you install the patch or upgrade, rename your existing scripts so that your customizing is
retained. After applying the patches, update the new scripts with your customizing. Do not rename the
existing scripts to replace the updated scripts, or you could lose important improvements or fixes.

Requirements for using the monitoring scripts

l All monitoring scripts must remain together in the directory where they were installed.
l The scripts must be customized to reflect your environment, such as the type of e-mail or the
paging available.
l To use the monitoring scripts, start sp_cop with the -uname name option, where name can be an
identifier of your choice. Suggestions are:
l the SharePlex port number
l the ORACLE_SID of the instance for which replication is being monitored
l the SharePlex Administrators name
l SharePlex must be running prior to executing a monitoring script.
l Verify the ORACLE_HOME (the path to the ORACLE_HOME directory) for each Oracle instance
being monitored.
l The monitoring scripts make use of sp_ctrl commands. Before you use the scripts, make a link in the util
sub-directory to the sp_ctrl binary in the bin sub-directory of the SharePlex product directory. Do not
copy the binary itself, because that makes it difficult to maintain patches to sp_ctrl.
l Users of the monitoring utilities must have the following rights:

SharePlex 8.6
Administrator Guide

222

l Local access to sp_ctrl and permission to run the script on the system on which the sp_cop to be
monitored is running.
l Korn (ksh) shell access and ps permission from the Unix or Linux command line.
l Read, write and execute permissions to the directory where the scripts reside.
l The permission on the iwgrep utility must be 755.
l The monitoring utilities use the mailx program to send e-mail notifications. Before using a script, make
sure mailx is configured to send e-mail on all systems where the monitoring scripts will be deployed.
l Paging requires that your service provider supports receiving e-mails on your paging device.
l To kill any of the processes generated by these scripts, use the kill -9 command. The kill command
alone does not kill all of the processes.

Monitor capture with sp_logmon

The sp_logmon monitoring script helps prevent situations where you must resynchronize because the redo
logs wrapped before Capture was finished reading them. It monitors the redo log group that Oracle currently is
writing to and determines which log SharePlex is reading. If Capture loses pace by a specified number of logs,
sp_logmon generates a warning in the logmon.log file and in an e-mail message, if that option is enabled. This
gives you time to correct the cause of the delay and restore the archive logs, if necessary.

Prepare to run sp_logmon

Before running the script, perform the following tasks.

Satisfy requirements
See the requirements in Run monitor scripts on Unix for usage requirements. NOTE:The script must be run in
the ksh shell.

Define email addresses

To use the e-mail notification feature, define the e-mail address(es) in the script before running it.
1. Open the script in the app-modules directory of the SharePlex product directory.
2. Add any number of address strings after the MailUserName= variable. Use the full e-mail and/or pager
address. Separate multiple entries with a comma, as shown in the following example:
[email protected],[email protected]
IMPORTANT! If the person modifying the script is someone other than a SharePlex user, he or she needs to have
these Oracle privileges:
l CONNECT privileges
l SELECT privileges for the V$LOG table
l SELECT privileges for the SharePlex internal tables

SharePlex 8.6
Administrator Guide

223

Run sp_logmon
Run the script from the util sub-directory of the SharePlex product directory, not from app-modules. When you
run it from the util directory, you actually make a soft link that runs a utility which first sets up the correct
environment before running the script itself.

Syntax
nohup sp_logmon-pport-tinterval-linteger [-m] /dev/null&
Table 11: Required arguments
Argument

Description

nohup
sp_
logmon

Directs the script to continue running in the background if the user logs out. This ensures
continuous monitoring. The sp_logmon component runs the script.

-pport

Sets the port number for the instance of sp_cop that you are monitoring. You can monitor
different SharePlex instances by running sp_logmon for each one, using different values for this
argument.

-tinterval

Sets the time interval between scans in seconds. The value can be any positive integer.

-l integer

Sets the maximum permissible number of redo logs between where Oracle is writing and where
Capture is reading. This value triggers the warning generated by sp_logmon. Valid values are
positive integers from 1 to the number of redo logs in the group.

Runs the script in the background.

Table 12: Optional arguments

Argument

Description

/dev/null

Redirects the notification output to the /dev/null device on the local system so that the
monitoring process continues to run in the background and generate output. To have the output
appear on screen, omit this argument.

-m

Enables the e-mail/paging option. Without this parameter, sp_logmon only logs errors to the log
file.

Monitor events with sp_eventmon

The sp_eventmon monitoring script monitors the SharePlex Event Log (event_log) at set intervals for entries
relating to key replication events. You can define the scan interval and the error messages you want the script
to detect. Each scan starts where the previous one stopped to keep the impact on the system minimal and
prevent duplicate warnings.
The sp_eventmon script takes the following actions after each scan of the Event Log:
l When sp_eventmon detects an error that you defined, it prints a notification to the error.splex log file
and an e-mail message, if that option is enabled.
l It logs each error, the error Event Log line number of the error, the sp_cop instance name (typically
the port number), and the time and date of the errors occurrence.

SharePlex 8.6
Administrator Guide

224

The script relies on the iwgrep program, the error_list file (described later), and a marker file named
username.mrk (where username is derived from the string that you enter with the -s argument when you
run sp_eventmon). These three components must be kept in the same directory as the script, or it will
not function.
NOTE: The username.mrk file prevents duplicate warning messages from being sent to the log and to your email or pager. Without this file, the script starts scanning the Event Log from the beginning every time it starts.
Warnings that were previously generated are sent again.

Prepare to run sp_eventmon

Before running the script, perform the following tasks.

Satisfy requirements
See the requirements in Run monitor scripts on Unix for usage requirements. NOTE:The script must be run in
the ksh shell.

Define error messages

The sp_eventmon script scans for events listed in the error_list file, located in the util sub-directory of the
SharePlex product directory. View that file for more information about the supported errors. You can add
custom error strings to the error_list file by editing it in any ASCII text editor. Open the file and place each
error string on a separate line.

Set IW_HOME
The IW_HOME variable in the script must be set to the correct value on each machine. This variable must point
to the directory in which the monitoring scripts and iwgrep reside.
If the path is not correct:
1. Open the script in the app-modules directory of the SharePlex product directory.
2. Set the path as shown in the following example:
IW_HOME=/export/home/splex/monscripts

Define e-mail addresses

Run sp_eventmon
NOTES:
l If you are running multiple instances of sp_eventmon, each instance must be run under the name of a
different operating system user. Each username.mrk file will have a different username.

SharePlex 8.6
Administrator Guide

225

l Use the truncate log command in sp_ctrl to truncate the Event Log frequently when you are running
the sp_eventmon script. If the log grows too large, the iwgrep program cannot grep from it properly.
When you issue the truncate log command, remove the username.mrk file. The next time you run sp_
eventmon it will create a new file. See the SharePlex Reference Guide for more information about the
truncate log command.
l When there is an existing Event Log with errors in it and the script is running, issue the truncate
log command and then delete the sp_cop_name.mrk file, where sp_cop_name is the value used in
the -s argument when the script was run. This file is in the util sub-directory of the SharePlex
product directory.

To run sp_eventmon
Run the script from the util sub-directory of the SharePlex product directory, not from app-modules. When you
run it from the util directory, you actually make a soft link that runs a utility which first sets up the correct
environment before running the script itself.

Syntax
nohup sp_eventmon -s 'sp_copname' -t interval-p path [-n name] [-m] /dev/null &
Table 13: Required arguments
Argument

Description

nohup
Directs the script to continue running in the background if the user logs out. This ensures
sp_
continuous monitoring. The sp_eventmon component runs the script.
eventmon
-s 'sp_
copname'

Sets the name of sp_cop that was used when sp_cop was started with the -u option. The name
of sp_cop must be enclosed within single quote marks. You can use this parameter more than
once to monitor multiple sp_cop instances on a system. Without this parameter, sp_eventmon
will not start.

Runs the script in the background.

-t interval

Sets the time interval between scans in seconds. The value can be any positive integer.

Table 14: Optional arguments

Argument

Description

-ppath

Sets the path to the SharePlex variable-data directory. Without this variable, sp_eventmon
assumes the default path.

/dev/null

-n name

Sets the name of the Event Log if it is something other than the default name event_log.

-m

Enables the e-mail/paging option. Without this option, sp_eventmon only logs errors to the log
file.

SharePlex 8.6
Administrator Guide

226

Monitor processes with sp_ps

The sp_ps monitoring utility monitors all SharePlex processes, including child processes, associated with a
specified sp_cop instance. It scans the processes at regular intervals and reports abnormal conditions to one or
more log files. It can monitor multiple installations of SharePlex on one or more systems, and it supports unidirectional and bi-directional (peer-to-peer) configurations.

Prepare to run sp_ps

Before running the script, perform the following tasks.

Satisfy requirements
See Run monitor scripts on Unix for usage requirements. NOTE:The script must be run in the ksh shell.

Set the scan interval

The scan interval specifies how long the sp_ps program waits between checks. The default is 2,000 seconds. To
specify a different scan interval, follow these steps.
1. Open the sp_ps file in the app-modules directory of the SharePlex product directory.
2. Set the interval= parameter to the required scan interval. Use any positive integer, for example:
interval=1500

Define email addresses

To use the e-mail notification feature, define the e-mail address(es) in the script before running it.
1. Open the script in the app-modules directory of the SharePlex product directory.
2. Add any number of address strings after the MailUserName= variable. Use the full e-mail and/or pager
address. Separate multiple entries with a comma, as shown in the following example:
[email protected],[email protected]
NOTE: The e-mail/paging option is enabled by default for sp_ps, but confirm that it was not changed. In the
script, MAILOPTION=TRUE enables e-mail notifications and MAILOPTION=FALSE disables them.

Run sp_ps
Run the script from the util sub-directory of the SharePlex product directory, not from app-modules. When you
run it from the util directory, you actually make a soft link that runs a utility which first sets up the correct
environment before running the script itself.

Syntax
nohup sp_ps ['sp_cop -uname'] CONFIGURATION[> /dev/null] [&]

SharePlex 8.6
Administrator Guide

227

Table 15: Required arguments

Argument

Description

nohup sp_ps

Directs the script to continue running in the background if the user logs out. This
ensures continuous monitoring. The sp_ps component runs the script.

'sp_cop -uname'

Use this parameter if you are running more than one sp_cop process. Use it to specify
each one of those processes that you want to monitor. This argument must reflect
exactly the same name that was used when sp_cop was started with the -u option. It
must be enclosed within single quote marks.Without the -uname option, sp_ps assumes
you want to monitor the sp_cop that uses the default SharePlex port of 2100. For more
information about running multiple sp_cop processes, see theSharePlex Administration
Guide .

CONFIGURATION

Specifies the type of configuration of the SharePlex instance being monitored. This value
must be entered in CAPITAL letters. Valid values:
SOURCE Use for uni-directional replication to monitor the Capture, Read and Export
processes on the source system.
TARGET Use for uni-directional replication to monitor the Import and Post processes
on the target system.
MULTI-SOURCE Use for peer-to-peer replication. It directs the script to monitor the
Capture, Read, Export, Import and Post processes on each system.
NOTE:If replicating between source and target tables on the same system, there are no
Export or Import processes.

> /dev/null

Redirects the notification output to the /dev/null device on the local system so that the
monitoring process can continue to run in the background and generate output. To have
the output appear on screen, omit this argument

(Ampersand) Runs the script in the background.

Monitor queues with sp_qstatmon

The sp_qstatmon script monitors the status of the capture and post queues for message backlogs. You can
configure the script to alert you if the number of messages in a queue exceeds a defined threshold (limit),
indicating that there is a potential data, system or network problem. This gives you time to correct the
problem before the queues exceed their allocated space on the filesystem.
After each analysis of the queues, the sp_qstatmon script prints a notice in the capstat.log file for the capture
queue or the poststat.log file for the post queue, as well as an e-mail message if that option is enabled.

Prepare to run sp_qstatmon

Before running the script, perform the following tasks.

Satisfy requirements
See the requirements in Run monitor scripts on Unix for usage requirements. NOTE:The script must be run in
the ksh shell.

SharePlex 8.6
Administrator Guide

228

Assign permission to create temporary files

The script creates some temporary files in the util sub-directory of the SharePlex product directory. Assign
write permission to that directory to the sp_qstatmon module.

Define email addresses

To execute sp_qstatmon with e-mail notification, you must first must define the e-mail address(es) in the
script. Notification messages are sent to all addresses coded in the script. Unless email notification is enabled,
sp_qstatmon only logs errors to the log file.
You can specify as many addresses as you want.
1. Open the sp_qstatmon script in any ASCII text editor.
2. Add the address strings after the MailUserName= variable. Use the full e-mail and/or pager address.
Separate multiple entries with a comma, as shown in the following example.
[email protected], [email protected]
3. Save and close the file.

Run sp_qstatmon
Run the script from the util sub-directory of the SharePlex product directory, not from app-modules. When you
run it from the util directory, you actually make a soft link that runs a utility which first sets up the correct
environment before running the script itself.

Syntax
nohup sp_qstatmon -vpath-tn-pport_number [-cinteger] [-dinteger] [-m] > /dev/null &
Table 16: Required arguments
Argument

Description

nohup sp_ Directs the script to continue running in the background if the user logs out. This ensures
qstatmon continuous monitoring. The sp_qstatmon component runs the script.
-vpath

Sets the path to the SharePlex variable data directory for the instance of sp_cop that you want
to monitor. Without this variable, sp_qstatmon fails and prints an error message requesting a
valid path.

-t n

Sets the time interval between scans in seconds. This value can be any positive integer.

-pport

Sets the port number for the instance of sp_cop that you are monitoring. You can monitor
different SharePlex instances by running sp_qstatmon for each one, using different values for
this argument.

Runs the script in the background.

Table 17: Optional arguments

Argument

Description

/dev/null

SharePlex 8.6
Administrator Guide

229

Argument

Description

-c integer

Sets the number of messages in the capture queue at which the script issues a warning message.
This value can be any positive integer. Without this parameter, sp_qstatmon defaults to 100
messages.

-dinteger

Sets the number of messages in the post queue at which the script issues a warning message.
This value can be any positive integer. Without this parameter, sp_qstatmon defaults to 100
messages.

-m

Enables the e-mail/paging option. Without this parameter, sp_qstatmon only logs errors to the
log file.

Run a monitor script on Windows

This topic explains how to use the Sp_Nt_Mon monitoring script on Windows systems. Sp_Nt_Mon runs in the
background monitor SharePlex and notify you of events and conditions that can adversely affect replication.
This script provides a monitoring mechanism without the need for frequent status checks through sp_ctrl.
IMPORTANT! Do not rename this script.
The Sp_Nt_Mon script detects and reports the following conditions by email:
l The status of the Capture, Read, Export, Import, Post, and Sp_Copsrv.exe processes.
l The volume of the capture and post queues.
l Latency between redo logs being processed by Oracle and by SharePlex.
l Specific messages in the Event Log (described later in this topic)

Configure and run Sp_Nt_Mon

You configure, start, and stop SpMonitor in the same interface in the SpClient utility.
1. Run SpClient from the SharePlex programs group in the Windows programs menu.
2. On the SpClient toolbar, click the SpMonitor button.
3. Select the port number of the instance of SharePlex that you want to monitor, then click
Configure Monitor.
4. Refer to the following table to modify the sp_nt_mon.txt file. Sp_Nt_Mon reads input from this file. To
make comments in this file, start each comment line with the #symbol.
Property

Default
Value

Description

Time
Interval

60
seconds

The time interval between monitoring polls.

Send
Email
alert

1
Enables (1) or disables (0) email alerts. Email is the only reporting option. A
(enabled) value of 0 disables the functionality of the monitoring script.

SMTP

none

The name of the SMTP server for the e-mail account.

SharePlex 8.6
Administrator Guide

230

Property

Default
Value

Description

none

Specifies one or more email addresses that will receive monitor notifications.
Separate each email address with a space, for example:

Server
Name
Email
Address

Email Address: [email protected]

[email protected]
Cop
Capture

0 (do not
monitor)

Specifies processes to monitor. To monitor a process, set a value of 1. For

example, to monitor only sp_cop, Capture and Export, set it as follows:
Cop: 1

Read

Capture: 1

Export

Import

Export: 1

Post

Import: 0
Post: 0
Capture
Threshold

0 (do not
monitor)

Sets the maximum number of messages a queue can contain before an alert
message is triggered. Set a value for each queue that you want to monitor.
Set this value to a number well below the amount of disk space allowed to
this queue. This gives you enough time to add disk space or resolve any
problems that are causing the backlog.

0 (do not
monitor)

Enables (1) or disables (0) the monitoring of supported Event Log messages.
The following messages are monitored:

Post
Threshold
Monitor
the Event
Log

SharePlex was shutdown

System call error
Queue partition is full
Host is down
Internal error
Out of sync
Poster failure
Parameter was changed Activate config
Deactivate config
Bad config file
sp_cop was shutdown
Child process failed
Error
ORA-error number errors

SharePlex 8.6
Administrator Guide

231

Property

Default
Value

Description

Monitor
Redo Logs

0 (do not
monitor)

Enables (1) or disables (0) the monitoring of capture latency, which is the
number of redo logs that Oracle has processed ahead of SharePlex in the
redo stream.

Redo
Threshold

2 logs

Sets a value for the maximum permissible number of logs for Oracle to be
ahead of SharePlex in the redo stream. When the value is reached, an alert is
triggered. Use when Monitor Redo Logs is enabled.

5. Click Start to run the script. The script starts and the word Start becomes Stop. The script runs
continuously to monitor SharePlex until you click Stop.

Monitor replication with SNMP

SharePlex provides agent support for Simple Network Management Protocol (SNMP) on all Unix, Linux, and
Windows platforms supported by SharePlex replication. The error text for the event is included in the trap and
is the same error that appears in the Event Log.
NOTE: SharePlex provides only agent support for SNMP. It only sends SNMP traps. SharePlex does not
provide an SNMP signal daemon (SNMP manager) to intercept the traps. Use the SharePlex SNMP feature
only if you have a Network Management Station (NMS) to manage SNMP signals. The SharePlex SNMP
agent is named iwsnmptrap and is installed with SharePlex in the bin sub-directory of the SharePlex
product directory. Do not run this program.

Enable SNMP
To enable SNMP monitoring of SharePlex replication, use the set param command to set the SP_SLG_SNMP_
ACTIVE parameter to 1. By default, the parameter is set to 0 (disabled).

Configure the SNMP agent

To configure the agent to communicate with the NMS, use the set param command to set the following
parameters. Each parameter must have a value if the SP_SLG_SNMP_ACTIVE parameter is enabled.
Parameter

Value

SP_SLG_SNMP_HOST

The name of the system (host) to which the traps will be sent

SP_SLG_SNMP_COMMUNITY

The community to which the traps will be sent

SP_SLG_SNMP_MJR_ERRNUM

The major error number to be used by the traps

SP_SLG_SNMP_MNR_ERRNUM

The minor error number to be used by the traps

Configure the SNMP traps

The following is a list of events for which the agent can send a trap. To enable an SNMP trap for an event, use
the set param command to set the corresponding parameter to a value of 1. By default all traps are disabled

SharePlex 8.6
Administrator Guide

232

(parameter value of 0).

SharePlex Event

Parameter

SharePlex logic errors and errors that cause processes to exit

SP_SLG_
SNMP_INT_
ERROR

System-related errors encountered by SharePlex

SP_SLG_
SNMP_SYS_
ERROR

Other SharePlex errors

SP_SLG_
SNMP_
ERROR

Replication is out of synchronization

SP_SLG_
SNMP_
OUT_OF_
SYNC

SharePlex starts up

SP_SLG_
SNMP_
STARTUP

SharePlex shuts down

SP_SLG_
SNMP_
SHUTDOWN

A SharePlex process starts

SP_SLG_
SNMP_
LAUNCH

A SharePlex process stops

SP_SLG_
SNMP_EXIT

SharePlex 8.6
Administrator Guide

233

18
Prevent and solve replication problems

This section contains solutions to many of the common questions and problems that can arise during replication,
and it also suggests preventive measures for avoiding problems.

Contents
Solve Oracle setup problems
Solve Configuration Problems
Solve replication problems
Solve Synchronization Problems
Solve other replication problems

Solve Oracle setup problems

This section helps you diagnose problems that might occur when you run the database setup program known as
Oracle Setup ora_setup. Database setup establishes an Oracle account for SharePlex and installs the
SharePlex objects in the SharePlex schema.

Incorrect ORACLE_SID and/or ORACLE_HOME

If database setup failed or if SharePlex cannot interact with Oracle, you might have specified the wrong
ORACLE_SID and/or ORACLE_HOME for the Oracle instance. SharePlex uses the ORACLE_SID to identify the
instance where the source data resides. On Unix and Linux systems, SharePlex references the ORACLE_HOME
to locate the Oracle shared libraries.

Methods for determining the ORACLE_SID

You can view the ORACLE_SID in a few different ways.
l On any platform, you can query the V$PARAMETER table through SQL*Plus.
SQL> select name, value from V$parameter where name = db_name;
l On Unix and Linux, you can view the oratab file.
HP-UX and IBM AIX systems
$cd /etc

Sun Solaris systems

OntheSolarisplatform,theoratabfileistypically

SharePlex 8.6
Administrator Guide

234

$more oratab
Youwillseeadisplaysimilartothis:
ora10:/qa/oracle/ora10/product
Inthisexample,ora10istheORACLE_SIDand
/qa/oracle/ora10/ productistheORACLE_HOME
directory.

locatedinthevar/opt/oracledirectory.Sometimes
thereisanoratabfileinthe/etcdirectoryaswell.If
thereisanoratabfileinthe/etcdirectory,remove,
renameorrelocateittopreventproblemsfor
SharePlex.

l On Windows systems, you can view the Windows Registry under HKEY_LOCAL_
MACHINE\SOFTWARE\ORACLE.
After you determine the correct ORACLE_SID (and ORACLE_HOME, if using Unix), try running the setup
program again.

More than one oratab file (Sun Solaris)

On Solaris systems, the oratab file is typically located in the /var/opt/oracle directory, but because other
platforms store the oratab file in the /etc directory, there could be a second oratab in the /etc directory. If
that is true, either move, rename or delete it, and then try running the setup program again.

Asterisk as the ORACLE_SID entry

Sometimes, the oratab file has an * (asterisk) symbol instead of a value for the ORACLE_SID of the instance that
will be replicated. An asterisk can cause database setup to fail. Ensure that a valid ORACLE_SID is in the oratab
file, and then try running the setup program again.

Legacy /etc/logingroups file (HP systems)

Sometimes there is an /etc/logingroups file on an HP system. This file existed on HPUX systems prior to the
adaptation of POSIX standards. To allow backward compatibility, HP-UX gives priority to /etc/logingroups, and
uses the /etc/group file only if /etc/ logingroups does not exist. That can interfere with replication, because
SharePlex installs groups into the /etc/group file. To resolve the problem, edit the /etc/group file to make its
entries identical to those in the /etc/logingroups file, then delete the etc/logingroups file.

Solve Configuration Problems

This section reviews many common problems and solutions encountered during configuration activation.
TIP: Many configuration problems can be prevented by using the verify config command in sp_ctrl before you
activate a configuration or reactivate one containing new or changed objects. The verify config command
reviews the configuration to help ensure that basic requirements for activation and replication have been
satisfied. See Chapter 1 for more information about this and other SharePlex commands.

SharePlex cannot locate the configuration

If SharePlex cannot locate the configuration that you want to activate, verify the directory where it resides.
Configurations must reside in the config sub-directory of the SharePlex variable-data directory for SharePlex to
find them. If you used the config.sql or build_config.sql script to create the configuration and the working

SharePlex 8.6
Administrator Guide

235

directory was not the config sub-directory, the configuration was put in whatever working directory you were
using. Locate the configuration and move it to the config sub-directory.
When you create a configuration through sp_ctrl using the create config command, SharePlex automatically
puts the configuration file in the config sub-directory. If you used that command and SharePlex still cannot find
the file, check to see if someone moved or deleted the file.
If you issue a configuration command, such as edit config filename, and you get an error on the file name,
perhaps you typed it incorrectly. SharePlex configuration names are case-sensitive. CONFIG_1 is not the same
as Config_1 or config_1. If you are confident that you entered the correct name, then the configuration file has
been moved or deleted.

A configuration will not activate

If SharePlex cannot activate one or more tables when activation is used, it will continue to activate the other
ones and display the names of the ones that failed in the SID_oconf##.log file or in the show activate
command display. However, there are several things can cause the entire activation of a configuration to fail.
Common error messages for configuration activation problems are:
Bad configuration file
The Oracle sid SID specified in the config file is invalid.
The following are causes and solutions for activation failures.

Reasons for complete activation failure

The following are reasons for a complete activation failure.

Invalid datasource or datasource syntax errors

If SharePlex cannot find the source instance for the ORACLE_SID specified on the o.datasource line of the
configuration, activation fails. Make sure the correct ORACLE_SID is used, and spell it the way it appears in the
oratab file (Unix and Linux), the Registry (Windows), or V$PARAMETER table (both platforms). In a SharePlex
configuration, the ORACLE_SID is case sensitive. The spelling case (upper versus lower case or mixed case) for
the ORACLE_SID in datasource:o.SID must be identical to the spelling in those locations.

Oracle interaction problems

If you receive the following error when you attempt to activate a configuration: The Oracle sid
ora10 specified in the config file is invalid, and you know the SID is valid, it could be
one of two things:
l A database account does not exist for SharePlexon the source system.
Or...
l If this is a Unix or Linux system, the oratab file is not where SharePlex expects it to be.

To verify that there is a SharePlex database account

If a database account was not created for SharePlex, it means that the activation process cannot log into
Oracle. To determine whether or not database setup was performed, do either of the following:

SharePlex 8.6
Administrator Guide

236

l Query the database for tables beginning with "SHAREPLEX_." If they exist in the database, then a
SharePlex account exists. These tables are critical for activation and replication.
l Query the DBA_USERS view in the database to see if a SharePlex account was established for SharePlex.
If the SharePlex tables and account do not exist, shut down SharePlex and follow the instructions for
creating a SharePlex account in the SharePlex Installation Guide.

To verify the oratab file

SharePlex obtains its Oracle environment information from the oratab file on Unix and Linux systems.
SharePlex expects the oratab file to be in the /etc directory on HP-UX, IBM AIX systems, and in /var/opt/oracle
on Sun Solaris systems. If the oratab file is in a different location, or if it contains an invalid ORACLE_SID,
SharePlex generates an error during activation (The Oracle sid ora10 specified in the config
file is invalid).
On Sun systems, there sometimes are oratab files in the /etc directory as well as the /var/opt/oracle
directory. Rename or delete all other oratab files except for the one in /var/opt/oracle.

Oracle password problems

If there is an Oracle account and schema for SharePlex, but SharePlex is having trouble accessing Oracle, check
to see if someone changed the password for SharePlex. If that is true, the SharePlex parameter database must
be updated to reflect the new login information.
l To update the login information on a Unix or Linux system, see Change the SharePlex database account.
l To update the login on Windows systems, shut down the SharePlex service, run Ora-Setup, then start
SharePlex again.

Insufficient PROCESSES setting

If Oracle Error 20 (ORA-00020 maximum number of processes (string) exceeded) is the cause of an
activation failure, it is because Oracle ran out of resources on the source system to allow one or more threads
to log on. You can resolve the problem by increasing the PROCESSES parameter in Oracle or by decreasing the
number of activation threads you are using. The errors in the Event Log will look similar to the following:
Error 08-06-12 13:20:17.089485 2369 1 sp_tconf(rom) (for o.ora10 queue *) 1 Error logging onto database 20
Error 08-06-12 13:20:17.641582 2369 1 Config compilation completed: datasrc o.ora10; file - config_01192001
Error 08-06-12 13:20:17.641582 2369 1 Bad config file: file - config_01192001;
Error - Failed to build rowmap, sp_tconf exit.
Error 08-06-12 13:20:17.881325 2369 1 Process exited sp_tconf (for o.ora10 queue
*) [pid = 14083] - exit(1)

Inability to access the SYS tables

SharePlex must be able to access the Data Dictionary in order to activate a configuration. If the activation
process cannot access the SYS tables, you will see Event Log entries similar to the following, indicating Oracle
error 00942.
Error 08-06-12 13:20:17.089485 sp_tconf (for o.UALDEVA queue *)
GetObjectNumAndType failed. Owner SPADMIN name DEMO_SRC rc 942
Error 08-06-12 13:20:17.641582 sp_tconf (for o.UALDEVA queue *) FindObjNumAndType
failed on object SPADMIN.DEMO_SRC: ORA-00942: table or view does not exist.

SharePlex 8.6
Administrator Guide

237

Error 08-06-12 13:20:17.881325 Bad config file: file - demo.UALDEVA; Failed to

find object SPADMIN.DEMO_SRC due to ORA-00942: table or view does not exist. sp_
tconf exit.
Check the O7_DICTIONARY_ACCESSIBILITY Oracle init.ora parameter and make sure it is set to TRUE. (This is the
default.) The database must be restarted if the parameter is changed.

Deactivation followed too closely by activation

In rare cases, if you activate a configuration too soon after a deactivation, the activation fails. Before you
activate a new configuration, wait until you see the following message in the Event Log: Notice: sp_ordr
(for o.ora10 queue o.ora10) Deactivated.

Non alphanumeric characters in the routing map

Characters such as the dollar sign ($) can cause configuration activation to fail. Limit machine names and
ORACLE_SIDs to letters and numbers. A dot (.), plus sign (+), and asterisk (*) are valid syntax components in a
routing map when used to denote the target instance (o.), multiple target systems in a compound routing map
([email protected] + [email protected]), and named queues (sysA:QueueA*[email protected]).

Reasons individual objects fail to activate

The following are reasons why individual objects fail to activate.

Locks on source tables

If activation cannot lock the table, activation of that table will fail.

Invalid objects
Make sure you are attempting to replicate only objects supported by SharePlex. Supported and non-supported
objects are listed in the SharePlex Administrators Guide.

Invalid target systems

Verify that all target systems specified in the configuration are accessible through the replication network, and
that their names are spelled correctly.

Syntax errors and misspelled words

A misplaced space, a misspelled word, or a missing component causes activation of that table to fail. Examples
are a missing .o in the routing path, a missing or misspelled owner name, or the lack of double quote marks
around case-sensitive owners or table names. For help with configuration syntax, see Chapter 5 of the
SharePlex Administrators Guide.

Activation takes too long

The following can slow activation down significantly.

Locks on source tables

If source tables are being accessed by users during activation, SharePlex might have to wait to obtain the
locks it needs.

SharePlex 8.6
Administrator Guide

238

Use the show activate command to view the activation status of each table. If SharePlex is waiting for a lock on
a table, the command output displays a message alerting you. See Chapter 1 for more information about show
activate and other SharePlex commands.

Explanation of configuration command errors

The following are common error messages that you might encounter when executing configuration commands.
ACTIVATE CONFIG error messages

What to do

No datasource keyword at the beginning of Make sure datasource: and o. were typed
the configuration file.
directly preceding the source ORACLE_SID on the first
line, with no space between any of the items.
The data source name in the config file
must be preceded by o.

The datasource specification in the configuration file

must begin with o..

The Oracle sid SID specified in the

config file is invalid.

Check the oratab file (Unix and Linux), the Registry

(Windows), or V$PARAMETER table (both platforms) to
make sure you specified the correct ORACLE_SID for
the source instance. The SID is case-sensitive. If, for
example, it is in upper case in those locations, it
should be upper case in the configuration file.

Objectname may not be replicated because

it's neither a table or a sequence. Sp_
conf exit.

The object is probably one of the types of objects that

Share- Plex does not replicate. If that is not the
cause, make sure the object owners and names are
spelled correctly, including the spelling case if the
item is case-sensitive.

line n, source object name (T_HFL_1) not

of form OWNER.TABLE

See if the owner name is missing from one or more

objects. The correct form is ownername.objectname.

syntax error in line n.

Review the syntax, making sure each component is on

the correct line, and that no component is missing.
Remember to list both the source and target objects,
even if they have the same name. To enforce casesensitivity, enclose the owner or table name within
double quotes.

line n, bad routing spec (o.ora10)

Make sure the routing map is written correctly, for

example [email protected]. Note: SharePlex does
not support system names that contain nonalphanumeric characters, such as an underscore ( _ )
or a dot (.).

File does not exist.

Make sure you correctly entered the name of the

configuration you want to activate, including the case
of the spelling. Configuration names are casesensitive. To see a list of configurations on a system,
use the list config command

sp_conf: oracle configuration failed

Verify that all required components have been

specified correctly.

Attempt to run sp_conf when sp_conf is

already active

SharePlex is indicating that the configuration is

already in the process of being activated.

SharePlex 8.6
Administrator Guide

239

ACTIVATE CONFIG error messages

What to do

Login parameters not set...

This indicates that a SharePlex account snf internal

tables do not exist in the source instance. As part of
initial installation, an account was established for
SharePlex with the privileges needed to analyze
objects for activation and perform the replication
functions. For more information, see the SharePlex
Installation Guide .

Currently involved in transaction.

Verify that no other process has locked the configured

tables, such as users performing DML. SharePlex
needs to lock those tables during activation and
cannot do so when they are already locked.

WARNING, not all objects activated

successfully. Check activation log.

If an activation succeeds, but one or more tables fails,

Share- Plex displays this message. To view the objects
that failed to activate, look in the SID_oconf##.log log
file, which resides in the log sub-directory in the
SharePlex variable-data directory.

CREATE CONFIG error messages

What to do

The parameter for create config must be

a new file name. or... Destination file
exists - file must not exist prior to
operation.

The name you are giving this configuration already

exists for another file. Use a different name. To see a
list of configurations on a system, use the list config
command.

Couldnt fork editor. or Editor

execution failed.

SharePlex failed to open the default text editor.

Make sure the editor still exists on the system. The
default editor that Share- Plex uses is vi on Unix and
Linux systems and WordPad on Windows systems. To
change the default text editor, see the SharePlex
Administrators Guide.

COPY CONFIG error messages

What to do

Destination file exists - file must not

exist prior to operation.

The name you are giving this configuration already

exists for another file. Use a different name. To see a
list of configurations on a system, use the list config
command.

EDIT CONFIG error messages

What to do

Problems in reading or writing file used

in edit -- command aborted.

Review the syntax of the configuration being edited to

make sure it is correct; or check to see that the file is
not corrupted.

Edit config file is not allowed for an

active config file.

SharePlex does not allow editing of an active

configuration. To make changes to entries in an active
configuration, or to add objects, copy the
configuration using the copy config command in sp_
ctrl , then edit the copy using the edit config
command. Activate the new configuration when you
are ready. SharePlex only analyzes added and
changed objects.

RENAME CONFIG error messages

What to do

Destination file exists - file must not

The new name you are giving this configuration

SharePlex 8.6
Administrator Guide

240

ACTIVATE CONFIG error messages

What to do

exist prior to operation.

already exists for another file. Use a different name.

To see a list of configurations on a system, use the list
config command.

DEACTIVATE CONFIG error messages

What to do

Deactivate/flush a nonactive datasource

You are attempting to deactivate a configuration that

is not active. To see a list of configurations on a
system, and verify which ones are active, use the list
config command.

GENERAL configuration error messages

What to do

Invalid file name passed to command. or

File does not exist.

You could have misspelled the configuration name or

used the wrong case. Verify the name and spelling,
including the case, and enter it again. To see a list of
configurations on a system, use the list config
command.

File access denied - check file

permissions.

You are not authorized to issue the command. To view

a commands authorization level, see its alphabetical
listing in Chapter 1. To view your authorization level
(according to the SharePlex user group to which you
were assigned), use the authlevel command in sp_
ctrl .

Solve replication problems

This section reviews common problems that you could encounter while replication is underway. You should
issue the status, show statusdb and qstatus commands frequently to:
l Make sure all processes are running.
l To see if SharePlex has generated replication errors.
l To make certain the queues are not consuming too much disk space or that message accumulation is
causing data latency.
You can also use the show log command to view the Event Log. See Tools for preventing and solving problems
for more information about monitoring replication.

Replication is too slow

Many factors can cause replication to be slow. The following are common general and Post-related causes
and solutions.

General causes of slow replication

The following are general causes of slow replication. For Post-related causes, see Post-related causes of slow
replication.

SharePlex 8.6
Administrator Guide

241

Excessive chaining
Excessive chaining affects several aspects of replication for the following reasons:
l It reduces the performance of the source database because Oracle must read multiple blocks for a
single row.
l It reduces Post performance on the target system because block fragmentation in the database slows
the writing of Post's SQL statements.
Reorganizing chained tables to eliminate chaining makes replication faster.

Redo log configuration

Capture reads archive logs if the redo logs wrap before Capture is finished with them, but it slows down
replication and consumes significant disk space. Ideally, the redo logs should be configured so that SharePlex
can avoid using the archive logs.

To determine if Capture is reading the archive logs

1. Determine the log that SharePlex is processing by querying the SHAREPLEX_ACTID table.
SQL> select seqno from splex.shareplex_actid
2. Determine the log that Oracle is writing to by querying Oracle's V$LOG table.
SQL> select sequence# from v$log where status='CURRENT'
3. Subtract the seqno value from the sequence# value. This reveals how many logs Capture lags
behind Oracle.
4. Subtract the number of online redo logs from that value. If the number is negative, SharePlex is
processing archive logs. For example, if you have 10 redo logs and SharePlex is 11 logs behind, it is
processing archive logs.

To configure redo logs for replication

Ensure that the online redo logs are large and numerous enough to minimize processing from the archive logs.
At minimum, there should be enough redo log capacity to hold several hours worth of data without wrapping.
To calculate this value, use the following formula.
[number of online redo logs] - [number of switches in 2 hours] >/= 0
Oracle guidelines recommend allowing for 24 hours. The amount of disk space required to store 24 hours worth
of archive logs can give you a good estimate of the requirements for the redo logs. For further information about
redo log size and replicating from the archive logs, see the SharePlex Administrators Guide.

Tablespace in hot backup mode

Tablespaces in hot backup mode on the source system affect replication. User changes are written to both the
rollback segments and the redo logs, with the entire block containing the changes being written to the redo
log. If the database is built with 8k blocks, there is a high amount of redo activity for SharePlex to manage.

Process prioritization
If Capture, Read, or both slow down during hot backups or other Oracle-intensive operations, view the processpriority settings on the system to determine if SharePlex can be assigned more resources. Ideally, the
SharePlex priority should match Oracle's priority.

SharePlex 8.6
Administrator Guide

242

Latency
You can reduce the latency of data between the source and target systems by changing the setting of the SP_
ORD_DELAY_RECORDS parameter.

Veritas Quick I/O

Because of the way Veritas Quick I/O caches disk information, SharePlex cannot support replication if Quick I/O
is used for the redo and archive logs. SharePlex supports the use of Quick I/O for the datafiles.

Network issues
If data is not being transmitted to a target system, make sure that Export is running on the source system and
Import is running on the target system. It is possible that a user at one location stopped a process without the
knowledge of users in other locations.
If Export is slow to send data across a WAN to the target system, the reason is usually a network problem. Use a
network diagnostic tool to monitor the number of TCP/IP packet retransmissions. If that value is high, and you
can resolve the problem, Export's performance should improve.
There are two parameters for tuning SharePlex in a WAN environment:
SP_COP_SO_RCVBUF (set for the target machine)
SP_XPT_SO_SNDBUF (set for the source machine)
Those parameters dictate the size of the packet that is sent across the network. If Share- Plex is replicating
across a WAN, and the export queue is continually backlogged, try adjusting those parameters.
If transfer still is slow, try increasing the SP_IMP_WCMT_MSGCNT and SP_IMP_WCMT_TIMEOUT parameters on
the target system. Set SP_IMP_WCMT_MSGCNT to at least 10,000.
For more information about these parameters, see the parameter descriptions in this guide.

Parameter settings
Some SharePlex parameters, when changed from their default settings, can inhibit replication performance.
For example, SP_QUE_SYNC slows performance because it flushes all writes to the queues to disk at the time of
the write, and the SP_ORD_HP_IN_SYNC parameter causes SharePlex to use all columns as a key for tables
using horizontally partitioned replication. These parameters are necessary for certain situations, and their
value is weighed against performance issues.
To determine if any parameter settings are responsible for reduced performance, issue the list param
modified command and view parameters that have user-defined settings, then review their documentation.

Post-related causes of slow replication

There are a number of things that cause the Post process to slow down. SharePlex generates the sp_opst_mt
- operation taking too long message when it takes more than five seconds to apply a SQL statement to
the target instance. Often it only takes one table to cause a bottleneck. Use the show sql or show post
command to find out which table Post is processing, and then check for the following.

Full table scans

The lack of an index or unique key on a target table causes SharePlex to perform full table scans. This slows
the Post process significantly, especially if there are LONG columns. Add an index or key to such tables if
possible. To ensure that Oracle uses the correct index, you can use the hints file feature of SharePlex.

SharePlex 8.6
Administrator Guide

243

As an alternative to adding a key, you can specify a key definition based on one or more columns that ensure
uniqueness. For more information about creating a key definition, see Chapter 5 of the SharePlex
Administrators Guide.
If these suggestions are not practical in your environment, you can set the Oracle DB_FILE_MULTIBLOCK_READ_
COUNT parameter to the maximum number of blocks that can be read in one I/O request. This is defined by the
system setting MAX_IO_SIZE/DB_BLOCK_SIZE. You can increase the DB_BLOCK_BUFFERS parameter as well.

Bitmap indexes on target tables

If Post is slow, check to see if there are bitmap indexes on the target table(s) and, if so, what type of operations
are being performed. Bitmap indexes are beneficial for queries, but they slow down Post's DML operations.
When Oracle adds, updates or deletes a bitmap entry, it effectively locks all the rows associated with the
bitmap segment, which can contain references to hundreds of rows. Consequently, changes made by different
Post sessions (there is a Post session for every session on the source system) can block each other if rows they
are processing update bitmap entries in the same bitmap segment. To proceed, Post must detect and resolve
the blocking, which results in delays if the number of locks is high. In general, frequent inserts by multiple
concurrent sessions into a table with bitmap indexes will incur lock conflicts, but random update and delete
activity on such a table will not.

Disk I/O bottleneck

Disk I/O bottlenecks on the target system are the most common cause of slow Post performance. Post can
spend a high percentage of its time waiting for Oracle to commit data. The effect is worse when there is a
Capture process reading from the same log device in peer-to-peer replication.
Disk I/O is the nature of the database environment. You can reduce the bottleneck by locating the redo logs on
faster hard drives or on a solid-state drive. Oracle8 and later allow multiple I/O processes to write to the redo
log, and that can be enabled with certain I/O configurations to alleviate the problem.

High number of buffer gets

Review any table with SQL statements that cause a high number of buffer gets. There should only be two to
four buffer gets on an index, depending on size and whether or not it is a unique index. If there are more buffer
gets than that, the index probably needs to be rebuilt. You need not reactivate the configuration after you
rebuild an index.

Oracle write-rate bottlenecks

One buffer writer writes all dirty Oracle blocks to disk. Whenever that buffer writer process wakes up to write,
it locks portions of shared memory and, in effect, blocks the processes that are either modifying or reading data
blocks including the Post process.

Transaction size
Normally, Post performs an internal read/release after it receives each COMMIT, which means it purges that
data from the queue as part of the checkpoint recovery process. For smaller transactions, this can cause
excessive I/O on the target system and hinder the Post process. If most of your transactions are small, you can
set the SP_OPO_READRELEASE_INTERVAL parameter to tell Post to read/release only after a certain number of
messages have been processed, instead of after every COMMIT.

Sequence replication
Verify that replicating sequences are cached. If they are not, they can represent a large but unnecessary
portion of replication volume. If replicated sequences are part of a key, replicate the tables that contain those

SharePlex 8.6
Administrator Guide

244

keys, and remove the sequences from the replication configuration. You should see significant performance
improvement.

Low ulimit (Unix and Linux systems)

The following error in the Event Log means that the system file descriptors setting on the target system needs
to be increased:
Error 07-24-08 12:11:40.360226 8693 12345 Poster error: /var/quest/ vardir/log/event_log: Too many
open files (posting from ora102, queue prodsys, to ora10b)
To ensure fast, problem-free posting to the target database, SharePlex requires a hard limit system file
descriptors setting of 1024 or as close to that value as your system resources can accommodate.

Compare process locks

The repair command locks all rows needing repair, or the entire table if there are more than 1000 out-ofsync rows, throughout the repair process. This could block Post if Post tries to apply data to the table
being repaired.
If you do not want Post to wait for a repair process to finish, you can kill the compare process. For information
about how to kill a compare process, see Solving compare command errors. To avoid issues with locks caused
by repair processes, consider running the repairs during non-peak hours.

Difference in Capture and Post speed

SharePlex reads and processes records from the redo logs faster than it can post those operations to the target
database with standard SQL statements. See Chapters 4 and 6 in the SharePlex Administrators Guide for
information about optimizing Posts performance.

Full archived log directory

If Post appears stalled and will not shut down normally, but the only error in the Event Log is sp_opst_mt
- operation taking too long, it could be that the archived log directory on the target system is full.
If so, then Oracle cannot create new logs, and it suspends processing. Post stalls because it is waiting for
Oracle. To correct the problem, move some of the old archive logs to another device, or delete them to
make room for new ones.

Capture stopped
If Capture is stopped, issue the status command in sp_ctrl to verify whether or not it was stopped by a
SharePlex user. If it was, find out why and make certain that it is not stopped for too long.
If Capture was not stopped by a user, it could have stopped for any of the following reasons.

archive logs not available

When Capture detects a log wrap and the archive logs are not available, Capture stops and returns a Log
wrap detected error. It waits a certain amount of time and then starts again, continuing this process until
the logs are restored. To restore replication, uncompress (if applicable) and restore the archive logs. See
Missing archive logs for instructions for restoring archive logs. If the archive logs are unavailable, Capture
stays stopped, and you must resynchronize the data.

SharePlex 8.6
Administrator Guide

245

Compressed archive logs

Capture cannot read compressed archive logs. If Capture stopped because the log it needs is compressed,
uncompress it and restore the subsequent logs so that Capture can process them. To restore the archive logs,
see the instructions in Missing archive logs.
To prevent errors, do not compress the archive logs until SharePlex is finished processing them. To determine
the current log for SharePlex, issue the show capture command with the [detail] option in sp_ctrl on the
source system. You can compress any logs that were generated prior to the current one for SharePlex.

archive logs in unexpected location

Capture stops if it cannot locate the archive logs it needs. When the redo logs wrap, Capture looks for the
archives in Oracles archived-log list, but if the logs cannot be found, Capture looks in the directory or
directories specified by the SP_OCT_ARCH_LOC parameter. If you are storing the archive logs in a location other
than the normal Oracle location, make sure this parameter is set to the full path name of the directory
containing the archive logs.

No access to the redo logs

Capture stops when it cannot read or find the logs, then it tries to read the log again. If you know the archive
logs are available, find out if someone changed permissions denying SharePlex the ability to read the redo logs.

No access to the variable-data directory

Capture stops if it is unable to write to the SharePlex logs because of restrictive permissions on the state subdirectory in the variable-data directory, or if there are space restrictions in that directory. Verify the
permissions and space for the variable-data directory.

Corrupted archive logs

Capture stops due to the error a portion of redo logs could not be parsed.... This error occurs
because of corrupted archive logs.

Post stopped
If Post stops, issue the status command in sp_ctrl to find out why.
An idle status means there is no data in the post queue to post.
A stopped by user status means that a SharePlex user stopped the Post process. To find out which user is
responsible, view the user issued commands in the Event Log.
A stopped due to error status means a replication or Oracle error caused Post to stop.
The following are some potential causes for Post to stop without user intervention.

Oracle errors
Post stops for Oracle errors that can be corrected, enabling you to fix the problem so that the data in the
object remains synchronized. The errors and the faulty SQL statement are logged to the SID_errlog.sql file (SID
is the target ORACLE_SID) in the log sub-directory of the variable-data directory on the target system. Use this
file to help you correct the problem, then start Post again. Posting resumes from the point where it stopped.
For more information about the SID_errlog.sql file, see Manually patching out-of-sync tables.
Other errors, such as out-of-sync conditions, cannot be corrected. In that case, Share- Plex reports the error to
the Event Log, writes the error and SQL statement to the SID_errlog.sql file, and continues processing.

SharePlex 8.6
Administrator Guide

246

Sometimes, errors that cannot be corrected cause Post to stop. If you have accounted for those errors, you can
set the SP_OPO_CONT_ON_ERR parameter to tell SharePlex to ignore those errors and continue posting.

Locks on target tables

If a target table is locked, the Post process cannot apply a SQL statement and generates an error message:
Currently involved in a transaction. This message could mean that a user, application, or job is
accessing the table and might have caused an out-of-sync condition. Or, it could mean that a repair command
has locked the table.
To find out if the table is locked, check the V$LOCK system statistics table, and resolve the situation
accordingly. You might have to resynchronize the data if DML was performed on the table. See How to
resynchronize objects.

No more open cursors

If you see the following error, Post has exceeded the available open cursors.
Warning: sp_opst_mt (for o.oracle-o.oracle queue oracle) Post has opened number
cursors. No more available cursors! Exiting
Post requires a certain number of open cursors to the target database. To view the OPEN_CURSORS value,
query the database using the following SQL statement:
select value from V$PARAMETER where name = 'open_cursors' ;
To determine an adequate OPEN_CURSORS value for SharePlex, see the SharePlex Administrators Guide.

Oracle login terminates

If Post stops because of an error, or if it is purposely or inadvertently killed, its login to Oracle terminates. If
the login terminates in the middle of a transaction, Oracle rolls back that transaction because it did not
receive a COMMIT.
That is not a problem, because the post queue retains copies of all operations for a transaction until the
COMMIT has been applied to the target database. When you restart Post, it checks for the last committed
transaction and resumes applying everything after that point, including operations from the incomplete
transaction. If Post receives a ROLLBACK instead of a COMMIT, it rolls back all operations for that transaction.

Deactivating when there are named export queues

When you are using named export queues, and you deactivate the configuration, Post could stop with the
following error instead of posting the remaining data from the queues:
sp_opst_mt (for o.qa920-o.qa920 queue q5) 15007 - Can't open poster queue que_
NOEXIST: Queue does not exist.
To start Post and finish replication, shut down SharePlex, then start it again.

Queue name is too long

Post exits if a queue name is too long. If you are using named queues, make certain the name assigned in the
configuration file is no longer than 15 characters.

The post queue is not emptying

If it seems like the post queue is not emptying, issue the status command to make sure Post is running. If Post is
running, the delay in the queue could be caused by large operations for which there has not yet been a

SharePlex 8.6
Administrator Guide

247

COMMIT. To allow for rollbacks and data recovery, SharePlex retains data in the post queue until it receives
the COMMIT.
View the post queue with the qstatus command. If the value in the Backlog (messages) field remains constant
or is shrinking, while the value in the Number of messages field is increasing, Post is waiting for a COMMIT
before releasing the data.
Use the show post detail command to verify that Post is processing transactions normally. If possible, set the
COMMIT point for your application to 500 to generate smaller SQL statements for SharePlex to process. Also,
consider creating a configuration that uses named post queues which isolate tables known for long transactions.
See Chapter 5 of the SharePlex Administrators Guide for instructions on creating named post queues.
If the accumulation of messages in the Post queue is threatening to cause disk space issues, see SharePlex is
running out of disk space for help with controlling when SharePlex sends the messages to the queue.

There is a failure to write and open queue error

If there is a sequence of messages in the Event Log similar to the following, stop and start sp_cop.
1 08-06-12 13:20:17.089485 2384 1 sp_ordr(rim) (for o.user queue o.user) Error
opening output queue rv=9 que_open(-,writeuser+ X,0x0a02d364+PR+o.user+sp_
ordr+o.user)
Notice 08-06-12 13:20:17.089485 2384 1 sp_ordr (for o.user queue o.user) data
route to a02d364.48.7e failed err=100
Error 08-06-12 13:20:17.089485 2384 1 sp_ordr (for o.user queue o.user) 11004 sp_ordr failure writing to queue(s)
Notice 08-06-12 13:20:17.089485 2384 1 sp_ordr (for o.user queue o.user) Exit sp_
ordr to retry rim-write.
Info 08-06-12 13:20:17.089485 2384 1 Process exited sp_ordr (for o.user queue
o.user) [pid = 8183] - exit(1)

The queues are corrupted

If a system fails, one or more SharePlex queues can become corrupted, and there will be errors reading from
and writing to them. In that case, the purge config and abort config commands cannot be used, because they
rely on the queues to operate. Contact technical support to resolve this problem.
Note that queue corruption results in total data loss. You can contact Technical Support to discuss salvaging
the data if the data is important.

The post queue seems too large

If the size of the post queue seems too large relative to the number of messages it contains, that is not
unusual. The SharePlex post queue actually consists of a number of sub-queues, each approximately
corresponding to a user session on the source system. A sub-queue can have one or more files associated with
it, each with a default size of 8 MB. If the entire 8-MB of size is not used, the file remains on the system even
after the data has been posted and read-released.
The size for the post queue in a status display is the actual disk space used by all of the queue files. You can
eliminate obsolete files that have been read-released by using the trim command in the SharePlex qview
utility. The command preserves files containing data not yet posted and committed to the target database.
Instructions for running qview are in Chapter 12 of the SharePlex Administrators Guide.

SharePlex 8.6
Administrator Guide

248

You had to unexpectedly stop replication (Unix and Linux)

If an unforeseen condition such as database corruption or a system problem forced you to shut down SharePlex,
verify that the semaphores and shared memory that SharePlex was using have been released. The following
procedure shows you how.
1. Look for any SharePlex processes that did not shut down, and kill them.
$ ps -ef | grep sp_
$ kill -9 PID
2. Change directories to the rim sub-directory of the SharePlex variable-data directory, and issue the od x command for the shmaddr.loc and the shstinfo.ipc files.
# od -x shmaddr.loc
0000000 0000 00e1 ed40 0000 4400 9328 0080 0000
0000020 0002 0021
0000024
# od -x shstinfo.ipc
0000000 0000 00e0 ee90 0000 4100 9328 0010 0000
0000020 0002 0020
0000024
3. Make a note of the following values:
The first 32-bit word of each of the files above reveals the hexadecimal equivalent of the ID of the
shared memory segment. Convert this value to decimal. For example, in the shmaddr.loc file shown in
step 2, the first word is 0000 00e1, which equates to a decimal value of 225. In the shstinfo.ipc file, the
first word is 0000 00e0, which equates to a decimal value of 224.
The third word of the shmaddr.loc and the shstinfo.ipc files reveals the hexadecimal equivalent of the
KEY of the shared memory segment and the semaphore. (Each set has the same key value.) Do not
convert this value to decimal. For example, in the shmaddr.loc file, the third word is 4400 9328. In the
shstinfo.ipc file, the third word is 4100 9328.
The fifth word of each file is the SEMAPHORE ID. Convert this value to decimal. The semaphore IDs in
the examples are hex 0002 0021 and 0020 0020, which in decimal are 131105 and 131104, respectively.
4. Issue the ipcs -smaa command at the command prompt to view all of the shared memory segments and
semaphores. (Shared memory segments are listed first and are denoted with an m. Semaphores are

SharePlex 8.6
Administrator Guide

249

denoted with an s.) The display looks similar to the following, but will be more extensive.

5. Verify that the shared memory IDs from the shmaddr.loc and shstinfo.ipc are in the list and that the
keys match.
6. For each shared memory segment, verify that the value in the NATTCH column is 0. This ensures that
the SharePlex processes that you killed released their memory segments.
7. For the semaphores, verify that the semaphore IDs and keys match the file values.
8. As root, issue the ipcrm -m command for the ID values (224 and 225 in the examples) to remove the
memory segments.
# ipcrm -m 224
# ipcrm -m 225
9. As root, issue the ipcrm -s command for the key values (131104 and 131105 in the examples) to remove
the semaphores.
# ipcrm -s 131104
# ipcrm -s 131105

sp_cop is using too much CPU time

If you believe sp_cop is consuming too much CPU, you can increase its idle time with the SP_COP_IDLETIME
parameter.

SharePlex 8.6
Administrator Guide

250

A source table is corrupted

If a source table is corrupted or there is another reason that you do not want the replicated data to be posted
to the target database, you can prevent posting for that table without removing it from the active configuration
or affecting posting for other objects. To disable posting for a table, use the SP_OPO_DISABLE_OBJECT_NUM
parameter, which disables posting of both DML and DDL operations.
SP_OPO_DISABLE_OBJECT_NUM is disabled by default. To enable it, run sp_ctrl on the target system and
issue the set param command for it, using the source table's object ID as the value, as shown in the
following example.
sp_ctrl(sysB)> set param SP_OPO_DISABLE_OBJECT_NUM 12345
When you are ready to begin posting to the target table again, set SP_OPO_DISABLE_OBJECT_NUM to 0.

SharePlex is running out of disk space

Data accumulating in the queues can cause SharePlex to run out of disk space.

What to do
l Stopped replication processes cause data to accumulate in the queues. If a process was stopped by a
user, find out why and then start it as soon as possible so that SharePlex can process the accumulated
data. If a process stopped because of an error, view the Event log with the show log command to find
out what happened, then resolve the problem so that processing can continue and the queue backlog
can be reduced.
l If a stopped process is not the problem, find out if Capture is processing archive logs. The capture
queue consumes disk space while the archived records are being processed. If Capture's location in the
logs is far behind Oracle's, it might be more practical to run ora_cleansp, resynchronize the data, and
reactivate the configuration than to add disk space and continue replication. Data latency might be too
great for users to tolerate waiting for SharePlex to regain parity with Oracle.
If activation is an extreme option, contact Support for assistance with a procedure using SP_OCT_GEN_
STOP, cycling through the archive logs, and resynchronizing the target system without needing to
reactivate.
l If SharePlex continues to run out of disk space, adjust the redo logs to reduce replication's dependence
on the archive logs, and increase disk allocation for the variabledata directory. Technical Support can
help you tune Capture's performance when it is not keeping pace with Oracle. For more information
about how to configure the redo logs for replication, see Redo log configuration.
l If you experience an unplanned increase in activity on the source system that causes data to
accumulate in the post queue, you can prevent the queue from exceeding available disk space by
stopping the Import process. SharePlex captures and processes data much faster than it posts it with
SQL statements on the target system, so you probably have free space on the source system to queue
data. Let the data accumulate on the source system until Post has posted enough messages for you to
start Import again. You can continue stopping and starting Import for the duration of the peak activity.
When you implement this method, monitor the replication services and SharePlexs disk usage on the
source system. On Unix and Linux systems, you can use the sp_ps script to monitor processes and the
sp_qstatmon monitoring script to monitor the queues. On Windows systems, you can use the Sp_Nt_
Mon utility to monitor those components.
See Chapter 12 of the SharePlex Administrators Guide for information about these and the other

SharePlex 8.6
Administrator Guide

251

SharePlex monitoring utilities.

l If you do run out of disk space, see Lack of disk space for help

DDL is not replicating

If you are having problems with replication of supported DDL, make certain the following are true:
l Are the source and target databases identical? Components must exist in the target database in order
for the replicated DDL to succeed there. The SP_OPO_STOP_ON_DDL_ERR parameter is defaulted to
direct the Post process to stop if there is an error applying the DDL, to enable you to correct the
problem to keep the databases synchronized. This parameter should be set to 1 (on).
l Is the SP_OCT_REPLICATE_ALL_DDL parameter enabled? This parameter must be set to 1 for
SharePlex to replicate DDL other than truncate table or alter table on tables in replication.

Examples of error messages

If a user is not found on the target:
Skipping generic 9i DDL operation, schema (bob) could not be set.
If the DDL fails on the target:
FAILED DDL Replication for "create user bob."
TIP: For more information about DDL and other operations and objects supported by SharePlex, see the
SharePlex Administrators Guide. Chapter 4 of that guide also contains more information about configuring
SharePlex for supported Oracle DDL replication.

Replicated DDL is not completely displayed in the Event Log

SharePlex prints replicated DDL to the Event Log, but it truncates statements longer than 2,000 characters.
Only the first 2,000 characters are recorded in the log.

Post generates a shared memory error

Post sometimes generates a Cannot attach to second shared memory segment error. This error is
incorrect. To resume normal operations, stop and start the Post process.

Post generates a semaphore error

If Post returns an error message of "shs_SEMERR: an error occurred with the semaphore" on a
Windows system, SharePlex requires more semaphores than are available. This usually occurs when named
queues or horizontally partitioned replication are being used. You can increase the number of semaphores
through the MKS Toolkit.

To increase the number of semaphores

1. In the Windows Control Panel, open Configure PTC MKS Toolkit.
2. Select Runtime Settings.
3. From Category, select Semaphores.
4. Set the following semaphores:

SharePlex 8.6
Administrator Guide

252

Semaphore Parameter

Value

Max Number of Semaphore IDs

Max Number of Semaphores

512

Max Number of Semaphore Undo entries

SharePlex does not run on a Windows system

SharePlex uses the NuTCRACKER operating environment to run on Windows systems. NuTCRACKER is a thirdparty program developed by Mortice Kern Systems that enables SharePlex to be ported uniformly across all
platforms. NuTCRACKER runs as a service on Windows.
If the NuTCRACKER service is stopped or disabled, or if the NuTCRACKER files have been removed or relocated,
there will be errors when you try to run SharePlex. To troubleshoot the errors, do the following:
1. Run the Windows Task Manager, then click the Processes tab.
2. Check to see if the NuTCRACKER service is running. The process name is nutsrvx, where x is the version
of the NuTCRACKER software.
3. If the process does not appear in the processes list, it might have been stopped by someone. To start
the NuTCRACKER service, use the Administrative Tools Control Panel on Windows systems.
4. Do one of the following:
l If you do not see the NuTCRACKER service, re-install SharePlex from the CD and re-install
NuTCRACKER. See step 10 for instructions.
l If you were able to start the NuTCRACKER service and you still have problems with errors, check
to see if the NuTCRACKER files were relocated. To determine the correct installed location:
5. From the Start menu, select Run, then type regedit in the Run text box.
6. Expand HKEY_LOCAL_MACHINE, then expand SOFTWARE.
7. Expand the Data Focus entry, then highlight the Runtime entry. The InstallDir string in the right pane
shows the correct location for the files.
8. Close the Registry Editor.
9. Do one of the following:
l Locate the files and restore them to that directory. Search for the folder MKS Toolkit. If that
folder cannot be located, search for any of the files shown in the following illustration:

SharePlex 8.6
Administrator Guide

253

l If you cannot locate the files or cannot restore them to the original location, take the following
steps to remove the NuTCRACKER Registry entries and reinstall SharePlex and NuTCRACKER.
10. Stop the SharePlex and NuTCRACKER services, if running.
11. Run regedit to open the Registry Editor, and delete the Data Focus and Mortice Kern Systems entries.
12. Close the Registry Editor.
13. Restart the system.
14. Reinstall SharePlex, making sure to reinstall it in the current location, and making sure to install the
NuTCRACKER component when prompted.
15. Restart the system to make the new NuTCRACKER environment effective.

Explanation of common replication error messages

The following table explains many of the common error messages that you might experience during replication.

SharePlex 8.6
Administrator Guide

254

sp_cop error messages

What to do

sp_cop cannot setup; memory segment n in

use.

You can get this message when you try to start sp_
cop. It is generated if any processes that access the
queues were still running when you last shut down
sp_cop. Kill those processes. When all have been
killed, sp_cop should start.

Error: sp_cop can't setup shared memory

statistics capability - exiting Error: sp_
cop(shs) Cannot delete previous memory
segment 303. Please check to see if any
Shareplex processes are running (ps -ef |
grep sp_). If there are some processes
running then kill them and restart sp_cop.

This indicates that there are already one or more

SharePlex sp_cop processes pointing to the same
variable-data directory. To run multiple sessions of
SharePlex, you need to use separate variable-data
directories for each one. See Running multiple
instances of SharePlex in Chapter 3 of the
SharePlex Administrators Guide for instructions.

Capture error messages

What to do

Capture time limit (300 sec) exceeded.

This message alerts you when Capture is not

processing records, which could indicate a problem
with the redo log. If, after 300 seconds, Capture is
unable to process a record, this message appears
and the process stops and logs the record. If you
cannot determine the cause of the problem, call
Technical Support before a log wrap occurs.

Log wrap detected

This means that the redo logs have wrapped and

Capture cannot locate the archive logs. If archive
logs are not available, you need to resynchronize
the data because messages that SharePlex needed
were lost in the log wrap. If archive logs are
available, uncompress them (if applicable) and
restore them to the archived log directory. When
the redo logs wrap, SharePlex looks for the archive
logs in Oracles archived log list. If SharePlex
cannot find the archived log there, it looks in the
directory or directories specified by the SP_OCT_
ARCH_LOC parameter. This parameter should
always be set to the correct archived log directory.
If you use compression for the archive logs, do not
compress them until SharePlex is finished
processing them. To determine the current log for
SharePlex, issue the show capture command with
the [detail ] option in sp_ctrl on the source system.
You can compress any logs that were generated
previous the current one for SharePlex. Note that
this error also occurs when the archived log is
corrupted.

Post error messages

What to do

sp_opst_mt - operation taking too long.

This message appears when it takes more than five

seconds to apply a SQL statement to the target
instance.

Rowid not found

This means that SharePlex cannot locate the

correct row to update in the target database. The
row needed by the SQL statement probably already
was altered, either by a trigger or cascading delete

SharePlex 8.6
Administrator Guide

255

sp_cop error messages

What to do
firing or by direct DML access by a user.

Database not available.

This message alerts you when the Post process has

repeatedly attempted to log onto the target
database and failed. Verify that the database is
running, and see whether someone changed the
SharePlex Oracle users password or access
permission.

Oracle-related error messages

What to do

Warning: (sp_opst_mt for o.oracle-o.oracle

queue oracle)Oracle parameter 'OPEN_
CURSORS' is < 512. Check 'OPEN_CURSORS'
setting.

These messages all relate to Posts needing more

cursors than are available. If the value for the
Oracle parameter OPEN_CURSORS is less than 512,
Post sends a warning message. The Post process
requires a minimum of 512 total open cursors to
process SQL statements. For instructions on setting
the correct value for OPEN_CURSORS, see the
SharePlex Administrators Guide.

or...
Warning: sp_opst_mt (for o.oracle-o.oracle
queue oracle) Post has opened number
cursors. No more available cursors!
Exiting.
or...
ORA1000: maximum open cursors exceeded.
or... Notice: sp_opst_mt (for o.oracleo.oracle queue oracle) Post will not open
more than number cursors (OPEN_CURSORS
10).
Cant access OBJ$Table

This indicates that SharePlex is unable to access

the Data Dictionary, which it must be able to do in
order to replicate. Check the O7_DICTIONARY_
ACCESSIBILITY Oracle tuning parameter and make
sure it is set to TRUE (the default).

Forward and backward operation counts do

not match...

Find out if Oracle was shut down before SharePlex.

This can cause SharePlex to return errors, and in
rare cases, corrupt the queues. The proper
procedure is to shut down SharePlex and then shut
down Oracle. For help resolving this problem,
please contact Technical Support.

Error: sp_opst_mt (for o.blues920-o.ora9

queue bluesky) 15033 - Failed to execute
SQL on table: QA.T_DEST_1: ORA-00001:
unique constraint (.) violated.

If a user on the source system violates a unique

constraint, that change enters the redo log. Oracle
rejects that change and rolls it back, and the
rollback also enters the redo log. Therefore,
SharePlex replicates them, and because it finds
the constraint violation, it sends this message to
the Event Log on the target system. You can ignore
this message. The tables are still in synchronization
because Oracle rolled back the offending
operation. This is an unavoidable error because of
the way Oracle handles the violation.

SharePlex 8.6
Administrator Guide

256

sp_cop error messages

What to do

SQL Cache error messages

What to do

Warning: sp_opst_mt (for o.oracle-o.oracle

queue oracle) Too many concurrent
transactions. Will disable the SQL Cache
capability.

If the SQL Cache size has been reduced to 1, and

more cursors are still needed, SharePlex disables
the SQL Cache feature and generates a warning
message in the Event Log. For more information,
see Chapter 6 of the SharePlex Administrators
Guide.

Warning: sp_opst_mt (for o.oracle-o.oracle

queue oracle) Running out of cursors.
Number of cursors opened so far is number.
Will attempt to decrease SQL Cache size.

When SQL Cache is enabled, Post keeps track of the

number of cursors it has opened. If Post detects
that it will exceed its maximum number of cursors,
it issues this message in the Event Log and tries to
decrease the SQL Cache size. Do not do anything
unless the value gets to 1 and there are still not
enough cursors. For more information, see Chapter
6 of the SharePlex Administrators Guide.

or...
Notice: sp_opst_mt (for o.oracle-o.oracle
queue oracle) Shrinking SQL Cache size to
number per session.
SQL Cache disabled.

The SQL Cache feature has been disabled. For

information, see Chapter 6 of the SharePlex
Administrators Guide.

Hints file error messages

What to do

15050 hint file not found

SharePlex looks for the hints.SID file whether you

use it or not. The hints file is installed in the data
sub-directory of the SharePlex variable-data
directory. If this file has been removed or
relocated, you will get this message.
To resolve this issue, create a blank hints file using
the hints.SID naming format in the data subdirectory of the variable-data directory. On Unix
and Linux systems, anyone with root privileges can
issue a touch /variable_data_dir/data/hints.SID
command (substituting the full path name of the
SharePlex variable-data directory for variable_
data_dir, and substituting the ORACLE_SID of the
target instance for SID) to create a blank hints file
that will eliminate this message. For more
information about the hints file, see theSharePlex
Administration Guide.

15051 missing column in the hint file

(either table of index name)

The hints file has not been configured correctly.

One or more specifications has been omitted. For
instructions for creating a hints file, see Chapter 6
of the SharePlex Administrators Guide.

15052 syntax error for tablename

Check the hints file to make sure that the owner

and table name are specified in this format:
owner.tablename. For instructions for creating a
hints file, see Chapter 6 of the SharePlex
Administrators Guide.

SharePlex 8.6
Administrator Guide

257

sp_cop error messages

What to do

15053 syntax error for indexname

Check the hints file to make sure that the owner

and index name are specified in this format:
owner.indexname. For instructions for creating a
hints file, see Chapter 6 of the SharePlex
Administrators Guide.

15054 source tables object_id not found

in object cache

The hints file includes a source table that is not in

the active configuration. All tables in the hints file
must be listed in the active configuration. If this
table is in the configuration, make sure that the
owner name and table name are spelled in the
hints file the same way as they are in the
configuration. For instructions for creating a hints
file, see Chapter 6 of the SharePlex Administrators
Guide.

15055 more than n valid entries were

entered into the hints file

The hints file permits only as many table-index

combinations as the value set by the SP_OPO_
HINTS_LIMIT parameter.

15056 error allocation memory for hints

Generally, this indicates a system-level memory

problem; the hints file itself does not demand a
significant amount of memory. If you believe the
system memory is sufficient, stop the Post process
and start it again. If you are not using the hints file,
you can ignore this error.

17000 error opening hint file

SharePlex cannot open the hints file. Check to see

if it has been corrupted. If not, make sure there is
sufficient read permission. For instructions for
creating a hints file, see Chapter 6 of the SharePlex
Administrators Guide.

Environment-related error messages

What to do

sp_opst_mt: pid=num date/time src host/

sid=db01:N2PB /var/quest/vardir/log/
event_log: Too many open files

On Unix and Linux systems, SharePlex runs best

when the system file descriptors setting is 1024.
See the SharePlex Administrators Guide for
instructions for setting the system file descriptors.

06/29/00 08:05 System call error: sp_ocap

(que) (for o.QA11 queue o.QA11) No space
left on device devname 06/29/00 08:05
Internal error: sp_ocap (for o.QA11 queue
o.QA11) 10705 - writecommit failed que_
BUFWRTERR: Error writing buffer to file
06/29/00 08:05 Process exited sp_ocap (for
o.QA11 queue o.QA11) [pid = 8692] -exit
(1)

SharePlex ran out of space for the queues on the

disk. This caused the data to go out of
synchronization because there was no more room to
write the replicated data in the buffer to disk.

gethostbyname name failed - exiting

The SP_SYS_HOST_NAME parameter was probably

set incorrectly. This parameter is used in a cluster
configuration to provide a consistent host name for
SharePlex to use so that replication continues
seamlessly after failover.

SharePlex 8.6
Administrator Guide

258

sp_cop error messages

What to do
l If SP_SYS_HOST_NAME is set to an invalid
package name, SharePlex generates this
message and exits.
l If SP_SYS_HOST_NAME is set to the local host
name instead of the package name,
SharePlex generates this error message
after the standby node is activated and the
cluster manager tries to start SharePlex.
SharePlex cannot start because it has not
migrated with the rest of the package.
To resolve this problem, specify the global cluster
package name for SP_SYS_HOST_NAME. For
instructions on establishing SharePlex in a cluster
environment, see the SharePlex Installation and
Demonstration Guide.

Greater than maximum writers number

SharePlex maintains a shared-memory segment

that is separate from the shared memory segment
used by the queues. This segment allows SharePlex
to display status statistics through sp_ctrl . This
error message indicates that there is insufficient
locking protection for the statistics for the current
and subsequent processes.

Other error messages

What to do

Snapshot too old

This is when the read-consistent view required by

SharePlex is no longer available. To avoid this
message, increase the size of the rollback segment.

Parameter paramname does not exist in the

paramdefaults file. Using hard coded
default value. Please make sure that your
param-defaults file is the correct
version.

This indicates that SharePlex cannot find a

parameter that it needs to reference, and that it is
using a hard-coded default value. If you see this
message in the Event Log, it means you have an
older version of the param-defaults file than the
version of SharePlex that you are running.
Someone might have updated the SharePlex
binaries using a downloaded patch, and may not
have installed the latest param-default file.
Parameters are sometimes added or changed in a
SharePlex patch release, and you should always
check for an updated param-defaults file when you
manually update SharePlex.

Invalid DATE format detected in record

with rowid=rowid, on obj object_id. See
capture log for detail.

A user or application entered an invalid date value

into the Oracle database that bypassed the
databases validity check. SharePlex can correct
this problem if you specify the correct values using
the SP_OCT_DEF_ parameters.

shs_SHMERR: an error occurred with shared

memory.

This indicates that you tried to run the qview

utility without shutting down SharePlex (sp_cop).
Shut down SharePlex and re-run qview.

SharePlex 8.6
Administrator Guide

259

Solve Synchronization Problems

This section reviews the causes and solutions for common synchronization problems. If you try these solutions
and are still having problems, contact Technical Support.

How SharePlex reports out-of-sync conditions

For all objects except those involved in transformation, SharePlex verifies that the source and target data
are synchronized before posting the replicated data to the target instance. When SharePlex determines that
source and target data are different, it generates error conditions but continues to post the other data so
that synchronization can be maintained for all other rows and tables.
NOTE: Synchronization is not verified when transformation is in use because transformation changes the target
data, so the before and after images cannot be compared. Even if they could be compared, SharePlex could not
do it because the transformation routine posts the data, not SharePlex.
TIP: You can change Posts behavior to stop processing altogether when it detects an out-of-sync condition by
changing the SP_OPO_OUT_OF_SYNC_SUSPEND (Oracle) parameter.
When an out-of-sync condition occurs, the Post process logs a message in the Status Database (viewed with
the show statusdb or show sync command in sp_ctrl and also to the Event Log (viewed using the show log
command or by opening the file through the filesystem). Use these commands frequently to monitor for outof-sync errors.

The following is an example of how SharePlex reports an out-of-sync condition.

sp_ctrl (irvspxu14:8567)> show sync
Out Of Sync Status Database irvspxu14
Count Details
----- -------------------3 Table "SCOTT"."TG_TEST1" out of sync for queue irvspxu14 since 16-Jun08 17:06:33
3 Table "SCOTT"."TG_TEST2" out of sync for queue irvspxu14 since 17-Jun08 15:47:58
1 Table "SCOTT"."TG_TEST3" out of sync for queue irvspxu14 since 17-Jun08 15:52:03
When data goes out of synchronization, SharePlex logs the offending SQL statements (the ones that should have
been applied but failed) to the database_ID_errlog.sql file in the data sub-directory of the SharePlex variabledata directory.
IMPORTANT: If you see an out-of-sync message in the Status Database and in the Event Log, but there is no
record in the database_ID_errlog.sql file for the transaction, do not ignore those messages. They could be
associated with a ROLLBACK. Regardless of whether or not a transaction is rolled back, SharePlex still compares
the pre-images of the source and target rows. If they are different, that indicates that the data is out of
synchronization. Only when a transaction is committed on the source but fails on the target does Share- Plex
log it to the database_ID_errlog.sql file, to give you a record of the statement that should have been applied as
a tool for problem solving and for manually applying the statement if appropriate. Rolled back statements are
cancelled operations, and therefore not logged on the target.

SharePlex 8.6
Administrator Guide

260

Find and correct the problem before you resynchronize!

If data is out-of-synchronization, determine why it happened before you resynchronize the data. Otherwise,
the problem can repeat itself and result in more data going out of synchronization.
Stop the Post process to prevent further errors, but do not stop Post if it could cause a backlog in the post
queue with the potential to exceed free disk space. Even though the affected object(s) can become further
out-of-sync, there is a procedure in this guide for resynchronizing them. Meanwhile, SharePlex can continue to
keep the unaffected objects synchronized.
To determine the cause of the out-of-sync problem, view the Status Database and the Event Log. Once you
correct the problem, routinely monitor replication for anything unusual. This can help you prevent small
problems from becoming big ones.

How to detect and correct common out-of-sync conditions

The following are common ways in which data goes out of synchronization. In most cases, SharePlex detects outof-sync conditions and returns an error message, but there are some situations where an out-of-sync condition
is hidden, and SharePlex will not return an error.

Inadequate or non-existing conflict resolution routines

Conflict resolution procedures are required when users make DML changes to multiple databases that are
being replicated to each other. This is known as peer-to-peer replication. SharePlex uses the conflict
resolution procedures to determine which operation to post when the same data change is received from
different systems, for example an UPDATE to the same row.

Missing archive logs

If the redo logs wrap before Capture can process the data it needs, the data can go out of synchronization if
archived logging has been disabled or if the archive logs needed by Capture have been removed. (Normally,
Capture would access the archive logs and continue replicating.)
l If archiving is not enabled, there are no archive logs for SharePlex to read. Data lost after the log wrap
cannot be recovered. Enable archived logging, and resynchronize the data. Capture will not start until
you do so.
l If SharePlex is several hundred logs behind, consider resynchronizing the data instead of restoring the
logs. It might take less time than Capture would take to process the missing records from the archive
logs. In addition, it eliminates the possibility that the capture queue could exceed free disk space while
processing the archive logs. You can base your decision on the size of the redo logs and the number of
tables being replicated, both of which determine how much information Capture must process. Also
take into consideration how much latency the target data's users can tolerate.
l If archived logging is enabled (so that the required data is available) but the logs were removed, copy
the appropriate archive logs back to the archived-log directory on the source system, or use the SP_
OCT_ARCH_LOC parameter to point SharePlex to their location.

To restore the archive logs

If you decide to restore the archive logs to resume replication, use the following procedure to determine the
required archive logs.

SharePlex 8.6
Administrator Guide

261

1. Determine the sequence number that Capture needs to resume processing from. Capture stops when it
encounters a log wrap and prints a message to the Event Log (event_log) containing the redo log
sequence number it needs. You also can find out this number by querying the SHAREPLEX_ACTID table
and looking at the SEQNO column, as shown in the following example:
SQL> select * from splex.shareplex_actid;
ACTID

SEQNO

OFFSET

AB_
FLAG

QUE_SEQ_NO_1

QUE_SEQ_
NO_2

COMMAND

-----

------

--------

-------

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

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

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

114

9757200

672101000

2. Query the Oracle V$LOG_HISTORY table to find out when that sequence number was archived, then
copy the logs from that point forward to the source system.
SQL> select * from V$LOG_HISTORY;
RECID

STAMP

THREAD#

SEQUENCE#

FIRST_CHANGE#

FIRST_TIM NEXT_CHANGE#

-----

------

-------

--------

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

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

111

402941650

111

2729501

14-JUL-00 2729548

112

402941737

112

2729548

14-JUL-00 2729633

113

402941930

113

2729633

14-JUL-00 2781791

114

402942019

114

2781791

14-JUL-00 2836155

115

402942106

115

2836155

14-JUL-00 2890539

3. See Chapter 4 of the SharePlex Administrators Guide for instructions for increasing the size and
number of the redo logs to prevent this from happening again.

Triggers on target objects

If triggers fire on target objects, they cause the data to go out of synchronization. To determine if triggers are
enabled on the target system, query the database.
SQL> select * from user_triggers where table_owner=owner and table_name=name;
If triggers have fired on the target system, the objects changed by the triggers are out of synchronization and
must be resynchronized. See How to resynchronize objects for instructions.

To disable the effects of triggers

To disable the effects of triggers on target objects after the data is resynchronized, you can either:
l Run the sp_add_trigger.sql wrapper script, which directs triggers to ignore the SharePlex Oracle user.
Or...
l Disable the triggers if they are not needed.
See Chapter 4 of the SharePlex Administrators Guide for more information about configuring triggers for
replication.

SharePlex 8.6
Administrator Guide

262

Cascading deletes on target objects

If ONDELETECASCADE constraints are enabled on the target tables and SharePlex is not configured to handle
the effects of replicating the DML generated by these constraints, there will be out-of-sync errors on tables
where the contraints are enabled. This is caused by the replication of the child (cascaded) DELETE operations
that were triggered on the source, which are redundant to the cascaded deletes that are triggered on the
target when the replicated parent operation is applied. To configure SharePlex to handle ONDELETECASCADE
constraints, set the following parameters:
l SP_OPO_DEPENDENCY_CHECK parameter to 2
l SP_OCT_REDUCED_KEY parameter to 0
l SP_OPO_REDUCED_KEY parameter to 1 or 2 (recommended for optimal Post performance)

LONG columns
If a table has no primary or unique key, SharePlex builds a simulated key based on all of the columns except the
LONG and LOB columns. It uses the simulated key to locate the target row to change.
Synchronization problems occur when the LONG columns in the target rows contain unique values, but nonLONG columns in one row have the same values as those of another row. This results in multiple rows meeting
the criteria for the simulated key. SharePlex could apply the UPDATE or DELETE to the wrong row without the
error being detected, causing the table to go out of synchronization without an error message.
If you can create a key from columns that ensure uniqueness on the target table(s), you can avoid this kind of
out-of-sync condition. After you create the key, resynchronize and re-activate those objects so that SharePlex
can update its object cache.
If adding a primary or unique key is not possible (such as when packaged applications are in use), uniqueness of
rows on the target system cannot be ensured.

Changes to keys
If tables use sequences as keys, and a key value changed, check to see if it resulted in duplicity on the target
system. If the new value already existed as a key in another row on the target system, it probably caused
SharePlex to return a unique-key constraint violation and out-of-sync error. This can happen when you update
values using an x +n formula, where n is an incremental increase. It is possible that one of the x +n values will
equal an existing value. For more information about keys and replication, see Chapter 4 of the SharePlex
Administrators Guide.

DDL changes
SharePlex replicates some, but not all, DDL. For a list of supported DDL please refer to the Release Notes that
correspond to your version of SharePlex. Any of the following can cause replication to go out of
synchronization. For future DDL changes, see the procedures recommended in Chapter 11 of the SharePlex
Administrators Guide.

Configuration not reactivated after DDL changes

If non-replicated DDL changes were made to the source objects and their associated target objects, it requires
a configuration reactivation. SharePlex must re-analyze the objects to incorporate the changes. For example, if
you reorganize a table, the object ID changes, and SharePlex needs to know the new one.

SharePlex 8.6
Administrator Guide

263

To resolve the problem

1. Stop user access to the out-of-sync objects.
2. Resynchronize the affected objects.
3. Reactivate the configuration on the source system.
4. Allow users to access the objects again.

Supported DDL performed manually on the source and target systems

If DDL that SharePlex supports was performed on the source system, and those same changes were performed
on the target system, the tables are out-of-synchronization because SharePlex expects to perform the DDL.

To restore synchronization
1. Stop the Post process (it might already be stopped).
sp_ctrl(sysB)> stop post
2. Alter the target table to undo the DDL changes.
3. Start Post and let SharePlex post the replicated DDL (which is still in the post queue).
sp_ctrl(sysB)> start post

DDL performed only on the target system

If DDL was performed on the target system, but not on the source system, the source and target objects are
no longer identical, so the data is out of synchronization. If the DDL is of a type supported by SharePlex, do
the following:

To restore synchronization
1. Stop the Post process.
sp_ctrl(sysB)> stop post
2. Alter the target table to undo the DDL.
3. Apply the DDL on the source system.
4. Start Post and let SharePlex post the replicated DDL (which is still in the post queue).
sp_ctrl(sysB)> start post
If the DDL is of a type not supported by SharePlex, you need to resynchronize the objects. See How to
resynchronize objects.

Non-supported DDL performed only on the source system

If DDL that SharePlex does not support was performed on the source system, but not on the target system, the
data is out of synchronization, and a resynchronization of those objects is required after the DDL is applied to
the target objects. See How to resynchronize objects. For a current list of support and non-supported
operations please refer to the Release Notes that correspond to your version of SharePlex.

Changes to column conditions in horizontally partitioned replication

UPDATEs to columns in column conditions for horizontally partitioned replication can cause out-of-sync
conditions. This happens in the following cases.

SharePlex 8.6
Administrator Guide

264

Row no longer satisfies the column condition

If a column condition value is updated and the new value no longer satisfies the row selection criteria,
SharePlex performs the operation, but subsequent operations on that row are not replicated. The tables are
out of synchronization, but there are no errors from Post alerting you to it. For example:
Column condition is C1=A and C2=B.
1. INSERT a row into the database. C1 and C2 values satisfy the column condition, so the row is replicated
to the target system.
C1

2. UPDATE ...set C1=B WHERE C1=A and C2=B

3. The change is replicated. Now the row does not satisfy the column condition, and subsequent changes
to data in the row are not replicated.
C1

Row that did not satisfy column condition now does

If a row that does not satisfy the column condition is updated to satisfy the condition, subsequent operations on
that row return out-of-sync errors. The reason is that the row was not replicated to the target system when it
was inserted into the source database (it did not satisfy the column condition), but when it is updated to satisfy
the condition, SharePlex replicates it. However, since the row never existed in the target database, Post
cannot locate it, and it returns an error. For example:
Column condition is C1=A and C2=B.
1. INSERT a row into the database. C1 and C2 values do not satisfy the column condition, so the row is not
replicated to the target system.
C1

2. UPDATE ...set C1=A WHERE C1=B and C2=B

3. Now the row satisfies the column condition, so SharePlex replicates it, but Post cannot locate the
corresponding row on the target (it was never there) and returns an out-of-sync error.

Resolving the out-of-sync condition

Depending on the nature of the column conditions, you can use the compare command to resynchronize rows
that were affected by such changes. To avoid out-of-sync conditions when using horizontally partitioned
replication, the columns used for a column condition should contain values that will not change (such as
PRIMARY or UNIQUE key columns), since those values determine whether or not a row is replicated.
If there will be updates to values of columns in column conditions, you can set the SP_ORD_HP_IN_SYNC
parameter to detect the results of those updates and compensate for them.

SharePlex 8.6
Administrator Guide

265

Not re-activating after configuration changes

If a table was added to the configuration, but the configuration was not reactivated, operations on that table
are not being replicated. Resynchronize the affected tables, then reactivate the configuration so that
SharePlex can update its object cache.
For instructions on adding tables to active configurations, see Chapter 7 of the SharePlex
Administrators Guide.

Incorrect running of ora_cleansp

If ora_cleansp was run on some, but not all, systems associated with an active configuration, SharePlex
perceives an out-of-sync condition. To determine whether or not ora_cleansp was run on all systems, or to see
if the configuration was activated before ora_cleansp was completed on all systems, view the user issued
commands in the Event Log on each system.
The log tells you if and when ora_cleansp was run on each system. It also tells you if and when the
configuration was activated. You can compare the times for those events to determine what happened.
If ora_cleansp was not completed on all replication systems for this configuration, run it on all systems.
Because ora_cleansp removes replication queues and processes and deactivates the configuration, you must
perform initial synchronization again.
See Chapter 7 of the SharePlex Administrators Guide for instructions on synchronizing data.

Incorrect resynchronization procedure

If resynchronization was performed for any objects, make sure it was done properly. Resynchronizing is
different than initial synchronization if users were accessing the tables. Try resynchronizing according to the
directions in How to resynchronize objects.

Lack of disk space

Data goes out of synchronization if user transactions continue when SharePlex does not have enough room to
accommodate them in the queues. This can happen if:
l The network or target system was unavailable and too much data accumulated in the export queue.
l The target Oracle instance was unavailable and too much data accumulated in the Post queue.
l The redo logs wrapped and Capture lost pace with Oracle as it processed the archive logs, causing data
to accumulate in the capture queue.
l A SharePlex process was stopped, but not restarted.
l The flush command was issued, but Post was not started again.
If a queue disk runs out of disk space, you may see messages similar to this in the Event Log:
11/22/07 14:14 System call error: No space left on device bu_wt.write [sp_mport
(que)/1937472]
11/22/07 14:14 System call error: No space left on device bu_rls.bu_wt [sp_mport
(que)/1937472]
11/22/07 14:14 Error: que_BUFWRTERR: Error writing buffer to file que_writecommit
(irvspxuz+P+o.a920a64z-o.a102a64z) [sp_mport(rim)/1937472] 11/22/07 14:14 Error:
sp_mport: rim_writecommit failed 30 - exiting [sp_mport/ 1937472]

SharePlex 8.6
Administrator Guide

266

11/22/07 14:14 Process exited sp_mport (from irvspxuz.domain.com queue irvspxuz)

[pid = 1937472] - exit(1)
If a queue disk is almost out of free space, you might be able to add disk space without having to resynchronize
the data. Follow these steps:
1. Stop SharePlex on the affected system.
2. Add more disk space.
3. Start SharePlex.
4. View the Event Log and look for the messages queue recovery started and queue recovery complete.
l If both messages are there, SharePlex resumes processing where it stopped. If it does,
SharePlex has recovered. However, if your applications are generating high volumes of
transactions, there are probably numerous messages backlogged in the queues that must be
processed and posted using standard SQL. Depending on the nature of the transactions, how
well the target database and the Post process are tuned, and your tolerance for latency, it
might be more practical to resynchronize the data instead of waiting for replication to regain
parity with Oracle's processing.
l If one or more queues is corrupted, the Event Log records a message like this: Bad header
magic... or peekahead failure. Or, you will see the message queue recovery started,
but you will not see the queue recovery complete message that signifies successful queue
recovery. In this case, you must run ora_cleansp to restore replication to an initial state after
you add disk space, then resynchronize and reactivate. Use the following procedure.

To restore synchronization
1. Run ora_cleansp to restore the variable-data directory and SharePlex tables. See Chapter 12 of the
SharePlex Administrators Guide for instructions.
2. If necessary, refer to the guidelines in Disk space for queue files in the SharePlex Administrators
Guide for assistance with determining the space requirements for the queue files.
3. Synchronize the data using your method of choice and reactivate the configuration. See Chapter 7 of the
SharePlex Administrators Guide for instructions.
4. You can prevent this problem from re-occurring by using the SharePlex monitoring utilities to start
unattended monitoring of key replication events, including queue volume alerts. See Chapter 9 of the
SharePlex Administrators Guide for more information.

System crash
If the source or target system fails, SharePlex stores the data in the queues and resumes replication when the
system has been recovered. If either system panics, however, the SharePlex queues can be corrupted, and
data in them can be lost. This requires a resynchronization. To avoid queue corruption during system panic, you
can also use the parameter SP_QUE_SYNC. See SP_QUE_SYNC in the SharePlex Reference Guide for more
information.

How to resynchronize objects

The following instructions help you decide how to resynchronize out-of-sync objects.
l If only a few tables are out of synchronization, and they are not large, you can use the compare
command in sp_ctrl to see how many rows are out-of-sync in each one. If the number of out-of-sync rows

SharePlex 8.6
Administrator Guide

267

is small, you can run the repair command again to resynchronize them.
l As an alternative to the compare command, you can manually patch the tables after the cause of the
problem is corrected, using the SQL statement(s) logged in the SID_errlog.sql file. Instructions are in
the following section entitled Manually patching out-of-sync tables.
l If the number of out-of-sync objects is large, it might take less time to re-synchronize the databases
than it will to use the compare command or repair them manually. You can resynchronize by:
o Copying the tables.
o Using the transportable tablespace feature.
o Using an Oracle hot backup with the reconcile command.

Manually patching out-of-sync tables

It is sometimes possible to manually repair out-of-sync tables if the number of synchronization errors is
small. When the Post process detects that source and target tables are out-of-sync, it posts the
synchronized transactions normally, but it logs the SQL statement and data for the out-of-sync transactions
to an error file called SID_errlog.sql. (SID is the ORACLE_SID for the target instance.) The file entries look
similar to this example:
-- Host (irvlabua) Sid (al920u64)
-- session 2, 1 error ---- [1] Tue Dec 11 13:31:32 2007
-- redolog seq#/offset 26622/26980368
-- redolog timestamp 641050290 (12/11/07 13:31:30)
-- original rowid AAE0m8AAWAAAAFEAAA
-- -- NOT FOUND
delete from SP_5.QA_LOB_DISABLE_INROW t where rownum = 1 and KEY='01';
SharePlex creates this file in the log sub-directory of the variable-data directory on the target system when a
synchronization error occurs. Try manually applying those SQL statements to the target table. Since you are
bypassing Posts comparison process, the operations should succeed. Follow these steps:
1. Stop user access to the affected source table.
2. On the target system, open the SID_errlog.sql file.
3. Using SQL*Plus, manually apply the logged SQL statement(s) to the target table. The SQL statement
should succeed assuming the structure of the table has not changed.

Restoring synchronization by copying the source tables

This procedure restores synchronization to out-of-sync target objects by applying a copy of the source objects.
You only need to resynchronize the objects that are out of synchronization, so users can continue accessing all
other objects.
1. Make sure sp_cop is running on the source and target systems.
2. [IF NECESSARY] On the target system, issue the show sync command to identify the tables that are out
of synchronization. This tells you the name of the tables that are out of sync. sp_ctrl(sysB)> show sync
3. On the source system, stop activity for the out-of-sync tables.

SharePlex 8.6
Administrator Guide

268

4. On the source system, issue the flush command in sp_ctrl. For datasource, substitute o. followed by
the ORACLE_SID of the source instance.
sp_ctrl(sysB)> flush o.datasource
5. On the source system, copy the tables.
6. On the source system, allow users back onto the source tables.
7. On the target system, verify that the Post process has stopped. Keep issuing the command until it shows
that Post has stopped.
sp_ctrl(sysB)> status
8. On the target system, restore the tables.
9. On the target system, address all triggers, referential integrity constraints and check constraints
according to the requirements of your replication strategy. See Shared Semaphore Segment
Resources in the SharePlex Administrators Guide for more information.
10. On the target system, clear the out-of-sync messages from the Status Database.
1 Determine each messages status ID number by viewing the Status Database.
sp_ctrl(sysB)> show statusdb detail
2 Clear each message with the following command.
sp_ctrl(sysB)> clear status statusID
11. On the target system, start the Post process.
sp_ctrl(sysB)> start post [for datasource-datadest]

Resynchronizing using Oracles transportable tablespace feature

The transportable tablespace feature enables you to quickly resynchronize numerous out-of-sync objects with
minimal downtime. To use the transportable tablespace feature, follow the instructions in the Oracle
documentation for generating a tablespace set, moving the tablespace set to the target database, and plugging
the set into the database. The following instructions contain steps only for using this feature to resynchronize
data. It assumes familiarity with using the transportable tablespace feature.
1. On the source system, set the source tablespace to READ ONLY (alter tablespace TRANS read only;).
2. On the source system, issue the flush command in sp_ctrl. For datasource, substitute o. followed by the
ORACLE_SID of the source instance.
sp_ctrl(sysA)> flush o.datasource
3. Export the metadata to an export file according to Oracles instructions.
4. When the export is finished, copy the datafiles to a secondary location on the source system. This
minimizes the impact on the source database of copying the files to the target system.
5. On the source system, set the source tablespace(s) back to read/write mode (alter Tablespace TRANS
read write;)
6. On the target system, drop the existing datafiles and tablespaces from the target database so that the
copied files can be applied.
7. Copy the files from the secondary location on the source system to the target system.
8. On the target system, use the Oracle import utility to import the metadata and the tablespace
definitions.

SharePlex 8.6
Administrator Guide

269

9. On the target system, set the tablespace(s) to read/write mode.

NOTE: SharePlex must be the only user permitted to have write access to the target
tables, unless you are using peer-to-peer replication.
10. On the target system, start the Post process.
sp_ctrl(sysB)> start post

Resynchronization using an Oracle hot backup on an active database

When you use an Oracle hot backup, and the reconcile command to resynchronize a target instance, users can
continue to access the production data while the backup is made and applied.

Cautions
To resynchronize centralized reporting, such as a data warehouse, you cannot use a hot backup from all source
systems. One backup would override the data from the previous one. You can use a hot backup of one of the
source instances to establish the target instance, and then use another method such as export/import or
transportable tablespaces to copy the objects from the other instances.
To resynchronize peer-to-peer replication, you must quiet all of the secondary source systems for the duration
of this procedure. Move all users to the primary system, and then follow the procedure. After the procedure
has been performed on all of the secondary systems, users can resume activity on them.

To resynchronize with a hot backup

1. On the target system, stop the Post process. This allows the replicated data to accumulate in the post
queue until the target instance has been recovered and reconciled.
sp_ctrl(sysB)> stop post
2. Run the Oracle hot backup on the source system.
3. Change to the bin sub-directory of the SharePlex product directory, and start sp_ctrl on the source and
target systems.
4. Verify that sp_cop, sp_ctrl and all SharePlex processes (Capture, Read, Export, Import, Post) are
running on both the source and target systems.
sp_ctrl(sysA)> status
sp_ctrl(sysB)> status
5. Switch log files on the source system.
A To recover the database to a sequence number, make a note of the highest archive-log
sequence number.
svrmgrl> alter system switch logfile;
B To recover the database to a Oracle System Change Number (SCN), pick an SCN to recover to on the
target database.
6. Recover the target database from the hot backup:
A If recovering to a sequence number, recover the database from the hot backup using the UNTIL
CANCEL option in the RECOVER clause, and cancel the recovery after Oracle has fully applied the log
from step 5.

SharePlex 8.6
Administrator Guide

270

B. If recovering to a SCN, recover the database from the hot backup using the UNTIL CHANGE <SCN>
option in the RECOVER clause, and cancel the recovery after Oracle has applied the logs matching the
SCN from step 9.
7. Open the database with the RESETLOGS option.
8. On the target system, issue the reconcile command. If you are using named post queues, issue the
command for each one. Issue the qstatus command if you are unsure of the queue name.
A If recovering to a sequence number, substitute the sequence number of the log that you
noted in step 5.
sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest seq sequence_number
For example: if you are replicating from instance oraA on SysA to oraA on SysB, the syntax would be:
sp_ctrl(sysB)> reconcile queue SysA for o.oraA-o.oraA seq 1234
B If recovering to a SCN, substitute the SCN that you noted in step 5.
sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest scn scn_number
For example: if you are replicating from instance oraA on SysA to oraA on SysB, the syntax would be:
sp_ctrl(sysB)> reconcile queue SysA for o.oraA-o.oraA scn 0123456789
The reconcile process retains control of sp_ctrl until it is finished, and then the sp_ctrl prompt returns.
9. On the target system, log onto SQL*Plus as the Oracle user for SharePlex, and run the cleanup.sql script
located in the bin sub-directory of the SharePlex product directory. This script truncates and updates
the SharePlex tables, which are owned by the SharePlex user. If you are running multiple instances of
sp_cop with multiple variable-data directories, there is a SharePlex Oracle user for each one. Make
sure you run this script as the SharePlex user that owns the tables you want to restore. The script
prompts you for the SharePlex user name and password.
SQL> @/productdir/bin/cleanup.sql
10. Disable or modify the following on the target system according to your replication strategy:
l triggers
l foreign key constraints
l cascading delete constraints
l check constraints
l scheduled jobs that perform DML
11. Start the Post process on the target system. The two instances are now in synchronization, and
SharePlex will continue replicating.
sp_ctrl(sysB)> start post

Solve other replication problems

This section reviews solutions to other replication problems.

SharePlex 8.6
Administrator Guide

271

A configuration was accidentally deleted

You might be able to recover an accidentally deleted configuration if that configuration was previously active
and you did not run ora_cleansp since it was activated. To recover the configuration, view the Event Log to
determine the activation ID for that configuration file, then look in the save sub-directory of the SharePlex
variable-data directory for a .conf.actid file, where actid is the activation ID you got from the Event Log.

Conflict resolution generates compile errors

If you encounter compile problems with your conflict resolution routines, check to see if any tables have the
same names as their owners. A known issue in PL/SQL prevents the SharePlex conflict resolution logic from
compiling the PL/SQL for tables whose names are the same as their owners. Oracle has stated that the issue
will not be fixed. See Oracle TAR 2577886.996 for more information. This issue does not affect replication;
SharePlex replicates data for tables with identical owner and table names.

The reconcile command is slow to complete

If you issue the reconcile command when source database activity is low, the command process can, in some
circumstances, seem to stall. This happens because the reconcile command is dependent on data continuing
to arrive from the source system. If there is no replicated activity on the source system after the point of the
hot backup or copy, the reconcile process waits until source activity resumes. This is normal.

Machine names cannot be resolved

Sometimes, machine names cannot be resolved between Unix or Linux and Windows systems. To avoid this
problem, add the IP addresses and names of all servers (Unix, Linux, and Windows) in the replication network
to the /etc/hosts file on all Unix and Linux machines, and add the same information to the hosts file on all
Windows machines. For more information about this issue, see the Windows Preinstallation Checklist in the
SharePlex Installation and Demo Guide.

A Cant unlink file error occurs on Windows systems

A nuisance error similar to the ones below sometimes occur on Windows systems. The files eventually unlink.
Text file busy Unlinking file: 'r:\splex2102/rim/o.SERV+C+0.0000000
Or...
System call error: sp_ordr.exe(osp) (for o.SERV queue o.SERV) Text file busy
17003 - Can't unlink file R:\Splex2100/state/o.SERVlog_ sp_ordr.30

Solving connection errors

If you are having trouble starting sp_ctrl, or with forming a connection using the host, port or [on host]
commands in sp_ctrl, one of the following error messages might be displayed.

SharePlex 8.6
Administrator Guide

272

Explanation of connection error messages

Connection error messages

What to do

Host unknown: cannot form connection

This message appears when either the host command

or [on host] option is issued. Verify that the system to
which you want to connect is running and that you
are using the correct system name.

Network unreachable

The network is down. Check the network connections

to make sure that nothing became disconnected from
the machine. If it is truly a network outage, and it
affects a replication system, find out how long the
network administrator expects it to last. If the
downtime could cause the SharePlex queues to
exceed their disk space, take measures to avoid
having to resynchronize the data. (For more
information on sizing a disk for the SharePlex queues,
see the SharePlex Administrators Guide.)

User is not authorized as a SharePlex

user -- check /etc/group

You do not have user permissions to execute the

operation. SharePlex users must be entered in the
/etc/group file (Unix and Linux) or in the Users list
(Windows) under one of the SharePlex user groups:
SharePlex Admin group, spoper, spview.

Invalid password

You incorrectly entered your password, or it is not

valid on the system to which you want to connect.
Consult your Share- Plex or system administrator.

Invalid user name passed

You entered an incorrect user name. Re-enter it, and

if it is not accepted, consult your SharePlex or
systems administrator, or check the /etc/group file
(Unix and Linux) or Users list (Windows) to see if you
are part of a SharePlex group. You must be in the
SharePlex Admin group, spoper, or spview group to
issue commands for SharePlex.

Port number must be a positive number

You could have entered the port number incorrectly.

Try again.

unauthorized connection attempt from host

hostname. net

A connection from a remote machine has been

denied because its name is not listed in the auth_
hosts file. The systems name is shown in the error
message. To allow that system to connect to the sp_
cop on the local system, add its name to the auth_
hosts file. For more information on the auth_hosts
file, see Chapter 6 of the SharePlex Administrators
Guide.

Solving compare command errors

If you are having trouble with the compare or repair command, refer to the following for assistance.

SharePlex 8.6
Administrator Guide

273

Compare fails with Oracle error 904

The following error referring to Oracle error 904 in the sp_declt log indicates that a comparison failed because
the source and target tables being compared are structurally different.
Notice: Object ID of JULIA.T_HFL_101 is 3154
Error 904 calling oexec in de_select_prepare_to_fetch
SQL statement: select rowid, C1, C2, C3, AC1, AC2, AC3, MC1, MC2,
MC3 from JULIA.T_HFL_101 order by C1
Error 904 calling de_select_prepare_to_fetch in de_batch_setup
Error 1 calling de_batch_setup in de_compare_client
Error 1 calling de_compare_client in main ora10_declt-28852-01.log [Read only]
24 lines, 711 characters
Do a DESCRIBE on both tables. It probably will show that the tables do not have an equal number of columns or
the columns datatypes are different.
The compare and repair commands are designed to detect and repair only rows whose values do not match,
generally because of errant DML operations. They are not designed to detect and repair out-of-sync conditions
caused by unsynchronized DDL operations or tables that were not structurally identical to begin with. After you
correct the DDL problem, you can run a repair to resynchronize the values in the rows.

Compare fails with a Too many users error

A message similar to the following in the Event Log indicates that the maximum number of queue readers and
writers (processes reading from, and writing to, the SharePlex queues) has been exceeded, and that the
offending compare process failed.
Can not add DataEquator queue reader que_TOOMANYUSERS: User table is full
A maximum of 20 processes can read from, and write to, the post queue at the same time, including the
replication processes and the compare and repair processes. Thus, there is a limit to the number of
compare/repair processes that can run at one time. There is no workaround or way to adjust the limit, nor is
there a way to determine how many compare processes can run concurrently without exceeding the limit.
The compare process attempts to access the queue for five minutes before exiting. An error is most likely to
occur when a repair option is used, because a repair accesses the queue much longer than a compare process
without a repair.
TIP: To compare multiple tables at the same time, without being restricted by process limitations, use the
compare using command. To limit the tables being compared, create a new configuration containing only the
ones that you want to compare, and use it for the comparison. (Do not activate that configuration.) All of the
tables are compared with one compare using process.

A client process fails to die

When a sp_desvr server process dies, the associated sp_declt client process or processes usually die. If you
need to kill a sp_declt client process, and there are multiple compares running, you can determine which one
to kill in one of the following ways:
l By viewing the sp_declt log file In the file, look at the Session IDs of the sp_declt processes and find
the one that matches the PID of the sp_desvr process that died. That is the sp_declt process to kill. The
sp_declt Session ID is the same as the PID of the associated sp_desvr process.
l By viewing the Event Log The Event Log records the startup of each sp_declt client process and its

SharePlex 8.6
Administrator Guide

274

PID. A subsequent entry in the log records the compare log file to which the process is writing. Within
the compare log files name in that entry is the PID of the server process. For example, in the following
sample entry, the sp_declt process PID is 2450. The process writes to compare log ../o734v32a_declt1228-01.log. The 1228 is the PID of the server process.
05/04/01 17:01 Process launched: sp_declt (for o.o734v32a-o.o734v32a- 87056
queue all) [pid = 2450]
05/04/01 17:01 Notice: sp_declt(deq) (for o.o734v32a-o.o734v32a-87056 queue all)
Opened DataEquator session log file /u10/julia30014/var7/ log/o734v32a_declt1228-01.log
You can search the log file names for the server process that died, and look for the client process
associated with that log file to determine the correct PID to kill.
NOTE: On Windows systems, the logs also record the startup of the associated sp_cop process.

A server process fails to die

When you kill a sp_declt client process or it dies on its own or if the sp_desvr server process has not
communicated with the client the sp_desvr server process usually exits after a certain amount of time,
which is controlled by the SP_DEQ_TIMEOUT parameter. If you need to kill a sp_desvr server process when a
sp_declt client process dies, look in the Event Log to find out which log the sp_declt client process was
writing to. The Event Log records the startup of each client process and its PID. A subsequent entry in the log
records the compare log file to which the process is writing. Within the compare log files name in that entry
is the PID of the server process. For example, in the following sample entry, the sp_declt process PID is 2450.
The process writes to log ../o734v32a_declt-1228-01.log. The 1228 is the PID of the server process, and that is
the process to kill.
05/04/01 17:01 Process launched: sp_declt (for o.o734v32a-o.o734v32a- 87056 queue all)
[pid = 2450]
05/04/01 17:01 Notice: sp_declt(deq) (for o.o734v32a-o.o734v32a-87056 queue all)
Opened DataEquator session log file /u10/julia30014/var7/ log/o734v32a_declt-122801.log
NOTE: On Windows systems, the logs also record the startup of the associated sp_cop process.

Solving errors for other sp_ctrl commands

If you are receiving errors when using sp_ctrl commands, try these solutions.
CLEAR STATUS error messages

What to do

No such status db entry

Verify the ID number of the Status Database entry

that you want to clear, and retry the command.

Input id is of an entry which is not user-clearable.

The Status Database entry you selected is one of the

types of entries that SharePlex does not allow to be
cleared.

FLUSH error messages

What to do

Deactivate/flush a nonactive datasource

You are attempting to flush a configuration that is not

active.

Bad routing specification

Review the syntax of your command.

SharePlex 8.6
Administrator Guide

275

CLEAR STATUS error messages

What to do

LIST PARAM error messages

What to do

Module may be only one of the following:

You might have specified an unknown argument or

option for the command. For the correct syntax for
SharePlex commands, see their alphabetical listings.

or
Illegal module specified.
LSTATUS/STATUS/SHOW STATUSDB error messages

What to do

Status db file is corrupt.

The Status Database has been damaged. Shut down

SharePlex and remove the statusdb file, which
resides in the data subdirectory of the SharePlex
variable-data directory. SharePlex will create
another one when you start sp_cop again.

SETPARAM error messages

What to do

Parameter does not exist in database.

You either specified a non-existent or obsolete

parameter, or you misspelled the name. Use the list
param command to view the SharePlex parameters
for your version and to verify the spelling.
If you are confident that the parameter you are
setting is valid for your version of Share- Plex, and
that you used the correct parameter name and
command syntax, then you might have an older
version of the SharePlex parameter database.
Contact Technical Support to see if that is the
problem and to get an updated version.

Parameter type checking failed - look in

param - defaults file.

You might have entered the wrong data type for the
parameter. To determine the correct data type, view
the param defaults file in the data sub-directory of
the SharePlex product directory. Or, you can use the
list param command in sp_ctrl .

SHUTDOWN error messages

What to do

Warning: shutting down capture service

may cause out-of-sync state. Are you sure
you want to shutdown capturing? (N)

This is not an error; however, if you shut down sp_

cop, and users are still changing the data, an out-ofsync condition can occur if SharePlex is not started
again before the redo logs wrap and the archive logs
become unavailable. Make sure users are finished
working before you shut down SharePlex, or make
sure that you start sp_cop again as soon as possible.
SharePlex will resume processing where it stopped if
the redo logs and/or archive logs are available, but
long delays can result in error conditions (see the
SharePlex Administrators Guide) or unacceptable
latency between source and target data.

START/STOP/ABORT error messages

What to do

A service must be specified.

The command requires an additional argument for

the replication service to be affected. View the
correct syntax for that command by issuing the help

SharePlex 8.6
Administrator Guide

276

CLEAR STATUS error messages

What to do
command in sp_ctrl, and then issue the command
again. For example:
sp_ctrl(sysA)> help abort

Unknown service specified.

or...

You could have misspelled the process name when

you issued the command. Valid names are capture,
read, export, import, post.

No such module.
or...
Service may be only one of: post, read,
import, export, capture, all.
Command was ignored - process is already
in the requested state.

You or someone else already

stopped/aborted/started the process, or SharePlex
did so because of an error. Use the status or lstatus
command to find out what happened, or you can view
the user issued commands to find out is a user
stopped the process.

Warning: stopping/aborting capture log

may result in out-of-sync state.

This is just a warning reminding you that stopping

Capture stops replication, which can result in an outof-sync condition if the redo logs wrap and the
archive logs become unavailable. You can stop
Capture as long as you start it againpromptly.
Capture will resume processing where it stopped,
but if you wait too long, data latency might be so
great that you are better off resynchronizing the
data than waiting for replication to regain parity with
the source transactions. For more information about
this subject, see the SharePlex Administrators
Guide.

STARTUP error messages

What to do

Startup command ignored - system was

already started.

Someone already started sp_cop on this port number

and system.

sp_cop cannot setup; memory segment n in

use

When sp_cop was shut down, some processes did not

die and were not killed by the user.

Other command error messages

What to do

Command was called with an invalid argument.

You might have misspelled a command name,

argument or option, or specified an incorrect one. To
view the correct syntax for a SharePlex command,
issue the help command in sp_ctrl .

or
Unknown keyword used in command.
Permission denied for command - check
your authorization level.

You are not authorized to issue this command, or you

are not a member of one of the SharePlex user
groups. To check your authorization level, issue the
authlevel command in sp_ctrl .

Default host is not defined: use the

host command or [on host] option.

SharePlex is unable to determine which system you

want the command to affect. You can either establish
a default host with the host command or use the [on

SharePlex 8.6
Administrator Guide

277

CLEAR STATUS error messages

What to do
host] option with the command that you want to
issue.

The [on host] directive must be last all extra arguments are ignored.

Always use the [on host] option last in a command,

after all other required and optional arguments.

SharePlex 8.6
Administrator Guide

278

19
Repair out-of-sync Data

This chapter contains an overview of the SharePlex Compare and Repair feature. SharePlex provides this
feature as built-in support to help you maintain data that is synchronized between the source and
target systems.

Contents
Overview of Compare and Repair
Before you use Compare and Repair
How to use the repair and compare commands

Overview of Compare and Repair

When properly implemented from the start, replication processes keep doing their job seamlessly for long
stretches of time unless manually stopped or there is a failure of a system component. Even though you are
monitoring the activity, it is good practice to perform a comparison from time to time to ensure that all of the
data is still synchronized. The majority of time, the cause of out-of-sync data is DML applied on the target, an
incomplete backup restore, or some other hidden out-of-sync condition that can go undetected until Post
applies an operation that affects the out-of-sync row and an error is returned. The SharePlex Compare and
Repair feature enables you to restore synchronization to out-of-sync tables.
NOTE: To understand how hidden out-of-sync conditions can occur, see Understand the concept of
synchronization.
Compare and Repair functions are accessed by means of the following commands in sp_ctrl:
l compare: Compares an individual source table to its target table or compares a wildcarded set of tables
in the same schema.
l compare using: Takes input from a file to compare some or all of the tables in the active replication
configuration.
l repair: Repairs an individual target table or a wildcarded set of tables in the same schema.
l repair using: Takes input from a file to repair some or all of the tables in the active replication
configuration.

Overview of the server and client processes

The compare and repair commands are always issued on the source system. The command spawns a server
process on the source system and then sends a message through the SharePlex queues to spawn a client

SharePlex 8.6
Administrator Guide

279

process on the target system.

The server and client processes then begin communication with each other. Depending on the syntax
options included in the command, the processes may be multithreaded on the target. The two processes
compare the source and target tables and then write the results to a log file. They also write the SQL that
is needed to repair any out-of-sync rows to a SQL file in the same location as the log files. If only a compare
command is issued, SharePlex does not execute these SQL statements. If a repair command is issued, the
command works identically to the compare commands except that it executes the SQL statements to repair
the out-of-sync rows.

How locks are managed

During a comparison, SharePlex obtains a brief exclusive lock on the source table to get read consistency for its
row selection. On the target system, SharePlex obtains an exclusive lock on the target table and retains the
lock for the duration of the comparison of that table. This prevents the table from being modified while
SharePlex is processing it.
After locking the tables, the rows are read and sorted in identical fashion on both source and target. Next, a
batch of rows is read and a check sum is performed. If the check sums match, another batch of rows is
processed the same way. If any check sums do not match, the processes determine which rows are out-ofsynchronization and then they create the SQL statements to repair them. If a repair command is issued,
SharePlex repairs the rows.

Before you use Compare and Repair

Before running the compare or repair commands, review these guidelines.
l All of the SharePlex processes (Capture, Read, Export, Import, Post) must be running when you run a
comparison or repair, and they must remain running throughout the comparison.
l The tables that you want to compare or repair must be part of an active configuration file.
l Uncommitted transactions on a source table prevent the compare and repair processes from obtaining
the brief locks they need to obtain read consistency. Make certain that all transactions are committed
before you run a comparison or repair.
l If a table is large, it will probably need to be sorted in the TEMP tablespace. Before running the
compare or repair commands, the TEMP tablespace may need to be made larger. The size depends on
the setting of the SP_DEQ_THREADS parameter or the threads option within the command syntax, both
of which controls the number of processing threads used by SharePlex on the target. Each thread
processes a table. At the default of two threads, the size of the tablespace should be larger than the

SharePlex 8.6
Administrator Guide

280

sum of the sizes of the two largest tables. If you set the number of threads higher, then increase the
size of the tablespace to accommodate a proportionate number of the largest tables. However,
l The UNDO tablespace may also need to be increased. Based on transaction volume and the length of
time it takes to compare the largest table, increase the size of the UNDO tablespace and increase the
undo_retention database parameter to avoid an ORA-1555 Snapshot too old error. Tables with LOBs take
much longer to compare or repair than tables without them.
The following are commonly modified compare and repair parameters. Do not increase the values unless
necessary. For details about these parameters, see Compare/Repair Command Parameters.
Parameter

Description

SP_DEQ_
MALLOC

This parameter is used on the source side to control fetch batch size. The batch size controls
the number of rows that SharePlex selects at once for comparison. Larger batch sizes increase
processing speed but require more memory.

SP_DEQ_
PARRALLISM

This parameter manages the select statement Degree of Parallelism hint. The parallelism
option of the command overrides this setting.

SP_DEQ_
PART_
TABLE_
UPDATE

This parameter controls how the repair commands work on partitioned tables, depending on
whether row movement is possible.

SP_DEQ_
READ_
BUFFER_
SIZE

This parameter controls the size of the buffer that holds fetched LONG and LOB data and can
be adjusted based on available system memory.

SP_DEQ_
This parameter sets a threshold that controls whether SharePlex uses row-level or table-level
ROW_LOCK_ locking when a where option is used.
THRESHOLD
SP_DEQ_
SKIP_LOB

This parameter determines whether or not LOBs are included in the compare/repair
processing. If LOBs are not modified once inserted, you can speed up processing by setting this
parameter to 0 so that only non-LOB columns are included in the processing.

SP_DEQ_
TIMEOUT

This parameter sets a queue backlog threshold. High backlogs delay the establishment of a
connection between the source and target compare/repair processes. If the backlog meets or
exceeds this value, any compare or repair command that is issued on the source will exit and
return an error. If this happens, consider running the compare or repair when the system is
less busy.

How to use the repair and compare

commands
The recommended procedure for maintaining synchronized data through the comparison and repair commands
is to run the compare or compare using command first, then view the results with the repair status command.
This command shows any rows that are out-of-sync and the possible cause. Unless the cause of the out-of-sync
condition is corrected, replication will go out of synchronization again, even if you repair the rows this time.
After the problem is fixed, issue the repair or repair using command.

SharePlex 8.6
Administrator Guide

281

You can run the repair or repair using command without doing a preliminary comparison. The command
performs a comparison first, to identify the out-of-sync rows, and then it repairs those rows. However, the
underlying cause of the out-of-sync condition must be corrected to prevent future out-of-sync conditions.
See Solve Synchronization Problems for causes and solutions for out-of-sync conditions.
To view the status or results of a comparison, use the compare status command in sp_ctrl.
To view the status or results of a repair, use the repair status command in sp_ctrl.

When to run a repair

The best time to repair a target table depends on its size, the cause of the problem, the extent of out-of-sync
rows, and how long you are willing to tolerate users being locked out. Before you initiate a repair, consider the
following:
l Although the users of the tables are not usually affected by the brief locks that are applied when
tables are compared, they are locked out of the target table for the duration of the repair process. For
a small table, this might not be disruptive, but for a large table needing extensive repairs, the wait can
be significant.
l Locks on a target table can reduce posting performance if Post must wait for the repair to finish before
it can apply changes to that table and move on to other tables. This increases the latency of the target
data and causes operations to accumulate in the post queue. If the objects that Post needs to change
are different from those being repaired, the two processes run simultaneously.
l If you must repair a table immediately, but cannot tolerate locks or replication latency, you can use the
where option to limit the repair to certain rows. An alternative is to use the key option, but this option
may cause the repair to miss some out-of-sync rows.
l If the repair can wait, correct the cause of the problem immediately and then do the repair during nonpeak hours.
l Replication latency can slow down the compare and repair processing. The message sent from the
source to spawn the command processes on the target is sent through the queues along with regular
replicated data. Delays caused by a data backlog will delay the spawn message and cause the process
on the source to lose its read consistency, which results in errors. If possible, perform comparisons and
repairs during off-peak hours.

How to run the compare and repair commands

To get additional information and syntax for the compare and repair commands, see the following reference
documentation. Review all documentation before using these commands.
compare
compare using
repair
repair using

SharePlex 8.6
Administrator Guide

282

20
Procedures to Maintain Oracle High
Availability

This chapter contains instructions for recovering replication along with the database and applications during a
failover in a high-availability environment. To support these procedures, SharePlex must be properly
configured to support high availability. See Configure replication to maintain high availability.

Contents
Recover replication if the primary system fails
Recover replication if the secondary Oracle instance fails
Move replication during planned failover and failback

Recover replication if the primary system

fails
In an unplanned failure of the primary (source) machine, replicated data remaining in the SharePlex queues on
that system will be unrecoverable as a result of buffering and the likelihood that the queues are corrupted. In
a high-availability environment, you can move replication to the secondary (target) machine along with the
database users to maintain data availability. When the primary system is restored, you can move users and
replication back to that system with minimal downtime using a hot backup of the secondary instance.
For this procedure, you will activate a configuration file and then use the reconcile command to synchronize
the results of the backup with ongoing replicated user changes after the copied instance is recovered.

Supported databases
Oracle database on Unix or Linux

Requirements
l SharePlex must be configured correctly to support high availability. See Configure replication to
maintain high availability.
l You must have a backup of the SharePlex replication environment.
l You must know how to run SharePlex. See Run SharePlex.

SharePlex 8.6
Administrator Guide

283

l You must understand the activate config, reconcile, and delete queue commands. See the SharePlex
Reference Guide.

Procedure 1: Move replication to the secondary

system
This procedure moves replication to the secondary system after an unplanned failure of the primary system.
1. Verify that Export is stopped on the secondary system.
sp_ctrl> stop export
2. Use the qstatus command to view the post queue, and keep issuing this command until the number of
backlogged messages is 0. NOTE: Do not wait for the actual numberof messages to be 0. If the primary
system failed before the commit for some transactions were received, messages for these partial
transactions will remain in the queue until cleared later in this procedure.
sp_ctrl> qstatus
3. Run the script that grants INSERT, UPDATE and DELETE access to all users on the secondary system.
4. Run the script that enables triggers and constraints on the secondary system when users begin using
this system.
5. Implement the failover procedure for relocating users to the secondary system, including starting the
applications.
6. Move users to the secondary system and let them resume working, but do not start Export. Their
transactions will now be accumulating in the export queue awaiting restoration of the source
database. NOTE: If started, Export will repeatedly try to connect to the primary system, wasting
system resources.
7. Go to Procedure 2: Move replication to the restored primary system.

Procedure 2: Move replication to the restored

primary system
This procedure moves users back to the primary machine after it is recovered from an unplanned failure.
Follow each segment in the order presented.

Restore the replication environment on the primary system

1. On the primary system, recover the SharePlex directories, system files and Oracle files from the
backups and archives.
2. On the primary system, start sp_cop using the -s option to prevent the SharePlex processes (Capture,
Read, Export, Import, Post) from starting.
$ /productdir/bin/sp_cop -s &
3. On the primary system, start sp_ctrl.
4. On the primary system, deactivate the configuration file. When you copied the archived SharePlex
variable-data directory to the primary system, you copied the configuration that was active before the
system failed. This causes the Capture process to set the transaction number to 1 when replication

SharePlex 8.6
Administrator Guide

284

from the primary system resumes.

sp_ctrl> deactivate config filename

Purge the queues

1. Run sp_ctrl on the primary and secondary systems.
2. On the primary system, delete the capture queue.
sp_ctrl> delete queue datasource:C
Example: sp_ctrl> delete queue o.oraA:C
3. On the primary system, delete the export queue.
sp_ctrl> delete queue queuename:X
Example: sp_ctrl> delete queue sysA:X
4. On the secondary system, delete the post queue.
sp_ctrl> delete queue queuename:P for datasource-datadest
Example: sp_ctrl> delete queue sysA:P for o.oraA-o.oraB
NOTE:
l You are issuing the delete queue command on the primary system because you restored the old
capture and export queues when you restored the archived SharePlex directories.
l You are issuing the delete queue command on the secondary system because data remaining in
the post queue cannot be posted. The primary system failed before Post received a COMMIT for
remaining transactions. SharePlex will rebuild the queues when you reactivate the
configuration and the two systems are reconciled.

Start replication from secondary to primary system

1. On the primary system, verify that all SharePlex processes are stopped.
sp_ctrl> status
2. On the primary system, stop Post.
sp_ctrl> stop post
3. On the secondary system, start Export. This establishes communication between the primary and
secondary systems.:
sp_ctrl> start export

Synchronize the source and target data

1. On the secondary system, run an Oracle hot backup.
2. When the hot backup is finished, switch log files on the secondary system and make a note of the
highest archive-log sequence number.
3. On the primary system, recover the primary database from the backup by using the UNTIL CANCEL
option in the RECOVER clause, and cancel the recovery after the log with the number you recorded has
been fully applied.
4. Open the database with the RESETLOGS option.

SharePlex 8.6
Administrator Guide

285

NOTE: This resets the sequences on the primary system to the top of the cache upon startup.
5. On the primary system, issue the reconcile command using the sequence number of the log that you
noted previously. If you are using named post queues, issue the command for each one. If you do not
know the queue names, issue the qstatus command first.
sp_ctrl> qstatus
sp_ctrl> reconcile queue queuename for datasource-datadest seq sequence_number
Example: reconcile queue SysB for o.oraA-o.oraA seq 1234
6. On the primary system, disable triggers on the tables, or run the sp_add_trigger.sql utility script so
that the triggers ignore the SharePlex user.
7. On the primary system, disable check constraints and scheduled jobs that perform DML.
8. On the primary system, log onto SQL*Plus as the SharePlex Oracle user and run the cleanup.sql utility
from the bin sub-directory of the SharePlex product directory. This truncates the SharePlex tables and
updates the SHAREPLEX_ACTID table.
9. On the secondary system, truncate the SHAREPLEX_TRANS table. This table contains transaction
information that the Post process was using before the primary system failed, and therefore
that information is obsolete. Truncating the table restores transaction consistency between the
two systems.

Activate replication on the primary system

1. On the primary system, activate the configuration file.
sp_ctrl> activate config filename
2. On the primary system, start Post.
sp_ctrl> start post

Restore the object cache

1. On the primary system, view the status of the SharePlex processes.
sp_ctrl> status
NOTE: This command shows that Post stopped due to an error, which occurred because the object
cache is missing.
2. On the primary system, issue the show log command with the filter option, and filter on the keyword
"objcache."
sp_ctrl> show log filter=objcache
3. Look for a Post error message that refers to a file with a name similar to the following example:
0x0a0100c5+PP+sys4+sp_opst_mt+o.quest-o.ov-objcache_sp_opst_mt.18
You are looking for a string that contains the string objcache_sp_opst_mt, followed by a number. This
is the object-cache file that the Post process needs. If you are using named post queues, there will be
more than one error message, each referring to a different object-cache file but ending with the same
number, such as the number .18 in the example.
4. Make a note of the full pathname of the Post object-cache file(s) named in the error message. The path
will be the state directory in the SharePlex variable-data directory, for example:

SharePlex 8.6
Administrator Guide

286

splex_vardir/state/0x0a0100c5+PP+sys4+sp_opst_mt+o.quest-o.ov-objcache_sp_
opst_mt.18
5. On the secondary system, shut down SharePlex.
sp_ctrl > shutdown
6. On the secondary system, change directories to the state sub-directory of the SharePlex variable-data
directory and locate the Capture object-cache file. This file will have a name similar to the one in the
following example.
o.quest-objcache_sp_ocap.18
IMPORTANT! If there are more than one of these files, use the one with the most recent number at the
end of it this number should match the number at the end of the Post object-cache file, such as .18 in
the example.
7. Copy the Capture object-cache file to the primary system and rename it to the full pathname of the
Post object-cache file that you noted previously.
8. On the primary system, start Post.
sp_ctrl> start post

Switch users back to the primary system

1. On the secondary system, stop user access to the database.
2. On the primary system, view the post queue and continue to issue the command until the number of
messages is 0.
sp_ctrl> qstatus
3. On the secondary system, shut down the Oracle instance.
svrmgr1> shutdown
4. On the secondary system, start the Oracle instance.
svrmgr1> startup
NOTE: This resets the sequence on the secondary system to the top of the cache to synchronize with
the primary system.
5. On the primary system, enable database objects that were disabled.
6. On the secondary system, start SharePlex.
7. On the secondary system, stop Post.
sp_ctrl> stop post
8. Move users back to the primary system.
9. On the secondary system, disable triggers on the tables, or run the sp_add_trigger.sql utility script so
that the triggers ignore the SharePlex user.
10. On the secondary system, disable check constraints and scheduled jobs that perform DML.
11. On the secondary system, start Post.
sp_ctrl> start post
12. On the primary system, view the number of messages in the post queue, and keep checking until the
number of messages is 0.

SharePlex 8.6
Administrator Guide

287

sp_ctrl> qstatus
13. When the number of messages is 0, switch users back to the primary system.
14. On the primary system, stop Export to prevent accidental changes made on that system from being
replicated to the primary system.
sp_ctrl> stop export
NOTE: The secondary system is now in a failover-ready state again, with:
l no users
l an active configuration
l disabled or modified triggers, constraints, and scheduled jobs
l a stopped Export process
Delete this text and replace it with your own content.

Recover replication if the secondary

Oracle instance fails
In an unplanned failure of the secondary (target) Oracle instance, the replication environment from that
system to the primary system is corrupted. This procedure enables you to restore the replication configuration
without affecting the database users on the primary system, and without the need to reactivate the
configuration file on the primary system. Only the secondary configuration is affected.
This procedure cleans out the SharePlex queues and restores the target instance by means of a hot backup
from the source system. You will use the reconcile command to synchronize the results of the backup with
ongoing replicated user changes after the copied instance is recovered.

Supported databases
Oracle database on Unix or Linux

Requirements
l SharePlex must be configured correctly to support high availability. See Configure replication to
maintain high availability.
l You must know how to run SharePlex. See Run SharePlex.
l You must understand the activate config, reconcile, and delete queue commands. See the SharePlex
Reference Guide.
l This procedure assumes that the secondary system itself is operational so that you can interact with
SharePlex on the system.

Procedure
This procedure is divided into logical segments. Follow them in the order presented.

SharePlex 8.6
Administrator Guide

288

Purge the queues

1. On the secondary system, stop Post.
sp_ctrl> stop post
2. On the secondary system, deactivate the configuration file.
sp_ctrl> deactivate config filename
NOTE: The deactivation causes the error Error in sp_cnc. in the Event Log. You may ignore it and
continue with the procedure.
3. On the primary system, run sp_ctrl.
4. On the primary system, delete the post queue.
sp_ctrl> delete queue queuename:P for datasource-datadest
Example: sp_ctrl> delete queue sysB:P for o.oraA-o.oraB
NOTE: You are deleting the queues on the primary system because there could be messages remaining
from uncommitted transactions sent from the secondary instance before it failed.
5. On the primary system, truncate the SHAREPLEX_TRANS internal table in the SharePlex schema. This
table contains transaction information that the Post process on that system was using before the
secondary instance failed, and therefore the information is obsolete. Truncating the tables restores
transaction consistency.
6. On the secondary system, run sp_ctrl.
7. On the secondary system, delete the capture queue.
sp_ctrl> delete queue datasource:C
Example: sp_ctrl> delete queue o.oraB:C
8. On the secondary system, delete the export queue.
sp_ctrl> delete queue queuename:X
Example: sp_ctrl> delete queue sysB:X
NOTE: You are deleting the queues on the secondary system because the capture and export queues
on that system still retain a record of the transactions that have already been processed.

Synchronize the data

1. On the primary system, begin a hot backup of the primary Oracle instance.
2. On the primary system, switch log files.
svrmgr1> alter system switch logfile;
3. Make a note of the highest sequence number of the archive logs.
4. On the secondary system, recover the secondary database from the hot backup using the UNTIL CANCEL
option in the RECOVER clause. Cancel the recovery after Oracle has fully applied the log from the
previous step.
5. On the secondary system, open the secondary database with the RESETLOGS option. This resets the
sequence on the secondary system to the top of the cache upon startup
6. On the secondary system, run SQL*Plus as the SharePlex database user.
7. In SQL*Plus, run the cleanup.sql script from the bin subdirectory of the SharePlex product directory.

SharePlex 8.6
Administrator Guide

289

8. On the secondary system, issue the reconcile command using the sequence number of the log that you
noted previously. If you are using named post queues, issue the command for each one. If you do not
know the queue names, issue the qstatus command first.
sp_ctrl> qstatus
sp_ctrl> reconcile queue queuename for datasource-datadest seq sequence_number
Example: reconcile queue SysA for o.oraA-o.oraA seq 1234
9. On the secondary system, disable triggers on the tables, or run the sp_add_trigger.sql utility script so
that the triggers ignore the SharePlex user.
10. On the secondary system, disable check constraints and scheduled jobs that perform DML.
11. On the secondary system, after the sp_ctrl prompt returns, stop Export. This ensures that nothing
accidentally gets replicated to the primary system when you activate the configuration on the
secondary system.
sp_ctrl> stop export

Start replication on the secondary system

1. On the secondary system, activate the configuration file.
sp_ctrl> activate config filename
2. On the secondary system, start Post.
sp_ctrl> start post
3. Use the status command to determine if any other SharePlex processes have a status of Stopped due
to Error and start them.
sp_ctrl> status
sp_ctrl> start process
NOTE: The secondary system is now prepared for future failover.

Move replication during planned failover

and failback
In a planned failover of database activity to a secondary Oracle instance, you can quickly move SharePlex to the
secondary system. While users continue their transactions on that system, SharePlex captures their changes
and stores them until the primary system is back online and activity is moved back to that system.

Supported databases
Oracle database on Unix or Linux

SharePlex 8.6
Administrator Guide

290

Requirements
l SharePlex must be configured correctly to support high availability. See Configure replication to
maintain high availability.
l There must be enough disk space where the queues reside on the secondary system to contain the data
that accumulates while users are working on that system.
l You must know how to run SharePlex. See Run SharePlex.
l You must understand the SharePlex flush command. See the SharePlex Reference Guide.

Procedure
This procedure is divided into logical segments. Follow them in the order presented. Do not shut down the
primary instance until prompted in the procedure.

Switch users to the secondary system

1. On the primary system, stop user access to the primary instance.
2. On the primary system, flush the data in the queues to the secondary system. This command stops Post
on the secondary system and places a marker in the data stream to establish a synchronization point
between the primary and secondary data.
sp_ctrl> flush datasource
where: datasource is the datasource specification of the primary Oracle instance, for example o.OraA.
3. On the secondary system, verify that Post stopped. (Continue to issue this command until it shows that
Post stopped.)
sp_ctrl> status
4. On the primary system, verify that there are no messages in the capture and export queues. The
Number of Messages and the Backlog (messages) fields must be 0.
sp_ctrl> qstatus
5. On the secondary system, verify that there are no messages in the post queue. The Number of
Messages and the Backlog (messages) fields must be 0.
sp_ctrl> qstatus
6. On the primary system, shut down SharePlex.
7. On the primary system, shut down the Oracle instance with the abort option. Do not use the
immediate option.
svrmgr1> shutdown abort
NOTE: This resets the sequence on the primary system to the top of the cache when the
database starts.
8. On the secondary system, verify that Export is stopped. This prevents user changes from being
replicated to the primary system until it is back online and SharePlex is ready to receive them. Stop
Export if needed.
sp_ctrl> status
sp_ctrl> stop export

SharePlex 8.6
Administrator Guide

291

9. On the secondary system, run the script that grants INSERT, UPDATE and DELETE access to all users.
10. On the secondary system, run the script that enables triggers and constraints on the
secondary instance.
11. Run your failover procedure for relocating users to the secondary system, including starting the
applications and starting jobs that were running on the primary system.
12. Move the users to the secondary system to resume working, but do not start the Export process.

Switch users back to the primary system

1. On the primary system, open the Oracle instance. The sequence on this system should now be at the
top of the cache.
2. On the primary system, disable triggers on the tables, or run the sp_add_trigger.sql utility script so
that the triggers ignore the SharePlex user.
3. On the primary system, disable check constraints and scheduled jobs that perform DML.
4. On the primary system, start SharePlex.
5. On the secondary system, start Export so that SharePlex sends the accumulated replicated data to the
primary system.
sp_ctrl> start export
NOTE: SharePlex passes any sequence updates from the secondary system back to the primary system
when Export starts.
6. On the primary system, stop Export.
sp_ctrl> stop export
7. On the primary system, allow Post to process the message backlog that was sent from the
primary system.
8. On the secondary system, stop user access to the Oracle instance.
9. On the secondary system, flush the data in the queues to the primary system.
sp_ctrl> flush datasource
where: datasource is the datasource specification of the secondary Oracle instance, for example o.OraB.
10. On the primary system, verify that Post stopped. (Continue to issue this command until it shows that
Post stopped.)
sp_ctrl> status
11. On the secondary system, verify that there are no messages in the capture and export queues. The
Number of Messages and the Backlog (messages) fields must be 0.
sp_ctrl> qstatus
12. On the primary system, verify that there are no messages in the post queue. The Number of Messages
and the Backlog (messages) fields must be 0.
sp_ctrl> qstatus
13. On the secondary system, shut down SharePlex.
sp_ctrl > shutdown
14. On the secondary system, shut down the Oracle instance with the abort option. Do not use the

SharePlex 8.6
Administrator Guide

292

immediate option.
svrmgr1> shutdown abort
NOTE: This resets the sequence on the secondary system to the top of the cache when the
database starts.
15. On the secondary system, start the Oracle instance.
svrmgr1> startup
NOTE: The sequence on the secondary system is now at the top of the cache. When the next value is
selected on the primary system, a new cache is acquired and is replicated to the secondary system.
Now, the primary system is at the start of a cache, and the secondary system is at the top of a cache.
16. On the primary system, run the script that grants INSERT, UPDATE and DELETE access to all users.
17. On the primary system, run the script that enables triggers and constraints on the primary system when
users begin using this system.
18. Run your failover procedure for moving users back to the primary system, including starting the
applications and starting jobs that were running on the secondary system.
19. Switch the users to the primary system to resume working, but do not start the Export process. This
prevents replicated data from being sent to the secondary system until SharePlex is ready to
receive it there.

Resume replication to maintain the secondary instance

1. On the secondary system, disable triggers on the tables, or run the sp_add_trigger.sql utility script so
that the triggers ignore the SharePlex user.
2. On the secondary system, disable check constraints and scheduled jobs that perform DML.
3. On the secondary system, start SharePlex.
4. On the secondary system, stop Export. This prevents any accidental DML on that system from being
replicated to the primary system.
sp_ctrl> stop export
5. On the primary system, start export.
sp_ctrl> start export
6. On the secondary system, start Post.
sp_ctrl> start post
Replication from the primary instance to the secondary instance is now active to keep the two
databases synchronized and ready for future failover when needed.

SharePlex 8.6
Administrator Guide

293

21
Make changes to an active replication
environment

This chapter contains instructions for making datbase changes, or performing system and software
maintenance, on systems where SharePlex replication is active.

Contents
Change an active configuration file
Add or change table specifications in an active configuration
Change Partitioned Replication
Add Oracle sequences to an active replication configuration
Remove objects from replication
Make DDL changes in an active replication configuration
Make Oracle changes that affect replication
Change the SharePlex database account
Change the name or IP address of a replication host

Change an active configuration file

Many procedures that change an element of the replication environment will also involve changing the
SharePlex configuration file. SharePlex does not permit anyone to edit an active configuration file. You must
make a copy first. By copying the file first, you preserve the original file in case it is needed again or you
encounter a problem with the new file. By copying the file first, you also can control when to activate the new
configuration file.
Unless you are adding numerous objects to a configuration or adding tables with extensive chaining, activation
of an edited configuration is less time-consuming than the original activation if you do not deactivate the
original configuration. The activation of the new configuration automatically deactivates the original
configuration, and SharePlex only needs to analyze the new, changed, and removed objects. If you deactivate
the original configuration before you activate a new one, SharePlex re-analyzes all of the objects.

SharePlex 8.6
Administrator Guide

294

Add or change table specifications in an

active configuration
If you are using wildcards and an object that you are adding satisfies the wildcard specification, it is not
necessary to add the object to the configuration file. Any new objects that match the wildcard criteria are
automatically added into replication. Only add objects that must be explicitly stated by name.

Supported databases
Oracle

Procedure
IMPORTANT! Do not deactivate the original configuration.
1. If the new source and target tables are populated, synchronize them according to the directions in
Activate replication in an Oracle production environment.
2. In sp_ctrl, issue the copy config command to make a copy of the active configuration file.
sp_ctrl> copy config filename to newname
Where: filename is the name of the active file and newname is the name of the new one.
3. Issue the edit config command to open the new configuration file in the default text editor.
sp_ctrl> edit config newname
4. Add the entries for the new tables or change existing entries.
l To change the vertical partitioning of a table, make the required changes to the column
partition in the table specification. See Configure vertically partitioned replication for
assistance.
l To change the horizontal partitioning of a table, change the column conditions as needed in the
SHAREPLEX_PARTITION table, and change the partition scheme in the entry for that table in the
configuration file. If deleting a partition scheme, remove it from the configuration file and either
keep it in the SHAREPLEX_PARTITION table or remove it. See Configure horizontally partitioned
replication for assistance.
l To add a new target system to a partition scheme if that system is not already in a routing map
somewhere else in the configuration file, add a routing map for it in the configuration. Begin the
line with an exception marker (!) and one or more spaces, for example: ! [email protected]
5. Save the configuration file.
When you are ready to activate the new configuration file, do the following:
1. Stop user access to the tables you added.
2. Activate the new configuration. This deactivates the original configuration.
sp_ctrl> activate config newname
3. Allow users to access the tables.

SharePlex 8.6
Administrator Guide

295

Change Partitioned Replication

You can change a horizontally partitioned or vertically partitioned replication configuration while replication is
active. Both of these procedures require the reactivation of the active replication configuration, but SharePlex
only locks tables for which there are changes. To learn more about changing a configuration file, review Change
an active configuration file.
For more information about partitioned replication, see:
Configure horizontally partitioned replication
Configure vertically partitioned replication

To change horizontally partitioned replication

1. Run sp_ctrl.
2. Modify the SHAREPLEX_PARTITIONtable as needed.
3. If you dropped a partition scheme:
a. Copy (but do not deactivate) the active configuration file to a new file.
sp_ctrl> copy config filename to newname
b. Edit the copy to remove or change the routing map where the partition scheme was specified.
sp_ctrl> edit config filename
4. Activate the new configuration file.
sp_ctrl> activate config filename

To change vertically partitioned replication

1. Make a copy of (but do not deactivate) the active configuration file.
sp_ctrl> copy config filename to newname
2. Edit the copy to change the appropriate column partition.
sp_ctrl> edit config filename
3. Activate the new configuration file.
sp_ctrl> activate config filename

Add Oracle sequences to an active

replication configuration
The procedure to use to add a sequence to an active configuration file depends on whether or not you can stop
user access to the objects that use the sequence. If the sequences are used to populate a column in a table,
you may not be able to stop user access.
Add a sequence if the sequence does not populate a column
Add a sequence if the sequence populates a column

SharePlex 8.6
Administrator Guide

296

Supported databases
Oracle

Add a sequence if the sequence does not populate a column

1. Stop user activity to the objects on the source system.
2. In sp_ctrl, issue the copy config command to make a copy of the active configuration file.
sp_ctrl> copy config filename to newname
Where: filename is the name of the active file and newname is the name of the new one.
3. Issue the edit config command to open the new configuration file in the default text editor.
sp_ctrl> edit config newname
4. Add the new sequences to the configuration file.
5. Save and close the file.
6. Create the target sequence on the target system. To ensure uniqueness on the target system, the start
value of the target sequence must be larger than the start value of the source sequence. Use the
following formula to determine the target START_WITH value:
source_INCREMENT_BY_value = START_WITH_value
7. Activate the new configuration. This deactivates the original configuration.
sp_ctrl> activate config newname
8. Allow users to access the objects.

Add a sequence if the sequence populates a column

1. In sp_ctrl, issue the copy config command to make a copy of the active configuration file.
sp_ctrl> copy config filename to newname
Where: filename is the name of the active file and newname is the name of the new one.
2. Issue the edit config command to open the new configuration file in the default text editor.
sp_ctrl> edit config newname
3. Add the new sequences to the configuration file.
4. Save and close the file.
5. Activate the new configuration. This deactivates the original configuration.
sp_ctrl> activate config newname
6. On the source system, flush the data from source system to the target system. This command stops Post
and places a marker in the data stream that establishes a synchronization point between source and
target data.
7. flush datasource
where: datasource is o.ORACLE_SID of the source instance for example o.oraA.
8. After Post stops, issue the following Oracle command on the target system to find the last known value

SharePlex 8.6
Administrator Guide

297

of the sequence. Make a record of this value.

select max(column_name) = last known value
9. Determine the value of the following equation.
source_INCREMENT_BY_value x source_CACHE_value
For example, if the source sequence is incremented by 2 and the cache size is 10, the value
would be 20.
10. Starting with the value that you recorded for the select max (column_name) command, determine the
next highest multiple of (source_INCREMENT_BY_value x source_CACHE_value).
Example:
INCREMENT_BY = 2
CACHE = 10
select max(column_name) = 24
Next highest multiple of (2 x 10) after 24 = 40.
11. To the value obtained in the previous step, add another multiple of (source_INCREMENT_BY_value x
source_CACHE_value). The result determines the START WITH value of the target sequence. For
example, in the previous equation the START WITH value would be: 40 + (2 x 10) = 60.
12. Create the target sequence with the START WITH value that you calculated.
13. On the target, start Post.
sp_ctrl> start post
SharePlex will continue replicating the data, while keeping the target sequence at least one multiple
of (source_INCREMENT_BY_value x source_CACHE_value) ahead of the source sequence.
IMPORTANT!
Sequences continue to be incremented even when a transaction is rolled back. If numerous rollbacks are
issued for a source table that uses a replicated sequence, it causes the sequence values to increase without
actually being used in columns in the table. As a result, when Post applies the next valid operation, the
sequence value on the target system could be less than the value in the replicated row.
When there are numerous rollbacks, view the target table regularly to ensure that the current value of the
target sequence remains greater than the maximum value in the table. If the current value of the target
sequence is less than the maximum value in the table, repeat the preceding procedure to re-establish the
sequence relationships.

Remove objects from replication

Removing objects from an active replication configuration involves a similar procedure to adding objects. The
objects being removed are locked when the new configuration is activated, but only those objects are locked,
so the activation is less time-consuming that the original activation.
You can prevent posting to a table without removing it from the configuration file. You may need to do this if,
for example, there is data corruption and you do not want DML or DDL operations to be applied to that table. To
prevent posting to a table, use the SP_OPO_DISABLE_OBJECT_NUM parameter. For more information about this
parameter, see the SharePlex Reference Guide.

SharePlex 8.6
Administrator Guide

298

Supported databases
All databases supported by SharePlex

Procedure
1. In sp_ctrl, issue the copy config command to make a copy of the active configuration file.
sp_ctrl> copy config filename to newname
Where: filename is the name of the active file and newname is the name of the new one.
2. Issue the edit config command to open the new configuration file in the default text editor.
sp_ctrl> edit config newname
3. In the new configuration file, delete the entries for the objects that you want to remove from
replication. If the object that you want to remove from replication satisfies a wildcard, use the not
notation to exclude the object. See Use Wildcards to specify multiple objects for more information.
4. Save and close the file.
5. Activate the new configuration. This deactivates the original configuration.
sp_ctrl> activate config newname
6. Allow users to access the removed objects.

Make DDL changes in an active replication

configuration
This procedure applies to DDL changes that are not of a type that is supported by SharePlex. DDL that is
supported by SharePlex can be applied to the source database without reactivating the configuration file or
stopping user access to objects, assuming the applicable SharePlex parameters are set correctly. Supported
DDL is replicated by SharePlex to the target, where it is applied by Post. For a list of supported DDL operations
and required parameters, see the SharePlex Release Notes.
Use this procedure to apply DDL that is not of a type that is supported by SharePlex. The DDL must be applied
outside SharePlex on both the source and target systems. This procedure requires stopping access to the
objects in the configuration file and a reactivation of the configuration file to update the internal tables.
However, only the changed objects are analyzed, so the activation time will be shorter than the time required
for a full activation.

Supported databases
Oracle database

SharePlex 8.6
Administrator Guide

299

Requirements
l You must know how to run SharePlex. See Run SharePlex.
l You must understand how to activate a configuration file with the activate config command.
l You must understand the SharePlexflush command. See the SharePlex Reference Guide.

Procedure
1.

On the source system, stop access to the source objects (on all systems if using peer-to-peer
replication).

2. On the source system (trusted source in peer-to-peer), flush the data from the source system to the
target systems. This command stops the Post process and places a marker in the data stream that
establishes a synchronization point between the source and target data.
sp_ctrl> flush datasource
where: datasource is the database specification of the source instance, for example o.oraA.
3. On the target system (all secondary systems in peer-to-peer) verify that the number of messages in the
post queue is 0 on each system and that Post stopped.
sp_ctrl> lstatus
4. On the source system, make the DDL changes.
5. On the source system, reactivate the configuration file.
sp_ctrl> activate config filename
6. On the source system, allow user activity to resume. Their replicated changes will accumulate in the
post queue.
7. On the target system, make the corresponding DDL changes.
8. [High availability and peer-to-peer replication only] On the secondary systems, reactivate the
configuration file.
sp_ctrl> activate config filename
9. On the target systems, start Post.
sp_ctrl> start post
SharePlex resumes replication from the last stop point and the data remains synchronized.

Make Oracle changes that affect

replication
This topic helps you make common changes to the Oracle environment while replication is active.

SharePlex 8.6
Administrator Guide

300

Supported databases
Oracle on Linux and UNIX

Move the location of ORACLE_HOME

If you change the ORACLE_HOME, you need to relink SharePlex to the Oracle libraries.
1. Shut down SharePlex.
sp_ctrl > shutdown
2. Move the ORACLE_HOME.
3. Edit the oratab file to point to the new ORACLE_HOME.
4. Edit the defaults.yaml file to point to the new ORACLE_HOME. This file is in the data subdirectory of the
SharePlex product directory.
5. Start SharePlex.

Change the target ORACLE_SID

1. On the source system, run sp_ctrl.
2. On the source system, copy the active configuration file to a new name, but do not deactivate it.
sp_ctrl> copy config filename to newname
3. On the source system, open the new configuration file.
sp_ctrl> edit config filename
4. Change the ORACLE_SID to the new one in all of the routing maps that include this target database and
target system.
5. Save and close the configuration file, but do not activate it.
6. On the source system, stop user access to the objects involved in replication.
7. On the source system, flush the data in the queues to the target. This stops the Post process and
establishes a synchronization point between the source and target databases.
sp_ctrl> flush datasource
where: datasource is the database indicator of the source instance, for example o.oraA.
8. On the source system, activate the new configuration file. This will deactivate the original
configuration file.
sp_ctrl> activate config filename
NOTE:The activation will be brief because SharePlex does not need to analyze the tables.
9. On the source system, allow users to access the objects involved in replication.
10. On the target system, verify that Post stopped. If Post is not stopped, continue to issue the command
until it shows that Post stopped.
sp_ctrl> status
11. On the target system, shut down the database and then rename the ORACLE_SID.

SharePlex 8.6
Administrator Guide

301

12. On the target system, start Post.

sp_ctrl> start post

Change the SharePlex database account

You can change the user name (schema or database), the password, or both in the SharePlex database account.
The database account was established during the installation of SharePlex. These procedures guide you
through the process in the correct order to maintain an active replication configuration.

Supported databases
All SharePlex-supported databases

Procedure
This procedure changes the user account name and/or password of the SharePlex user account in a database.
This user account is the one that the SharePlex processes use to connect to the database when performing
replication tasks.
IMPORTANT! If using multiple variable-data directories, you must run this procedure for each one that you
want to change.
1. (Unix and Linux only) If you are using multiple variable-data directories, export the environment
variable that points to the variable-data directory for the SharePlex instance for which you are running
Oracle Setup.
ksh shell:
export SP_SYS_VARDIR=/full_path_of_variable-data_directory
csh shell:
setenv SP_SYS_VARDIR /full_path_of_variable-data_directory
2. Run sp_ctrl on the system where you are changing the password.
3. Stop the SharePlex processes on the system where you are changing the account information. For
example, if you are changing the SharePlex account in the source database, stop Capture and Read. If
you are changing the account in the target database, stop Post.
sp_ctrl> stop service
4. Verify that all SharePlex replication processes for this instance of SharePlex are stopped.
sp_ctrl> status
5. Log in to the database as a DBA user and change the SharePlex account name and/or password to the
new ones. Important! Do not delete the SharePlex objects!
6. If you changed the account name, copy all of the SharePlex database objects from the old account to
the new one.
NOTE:Keep the old account and SharePlex objects as backup until you are certain replication
resumes properly.

SharePlex 8.6
Administrator Guide

302

7. In sp_crtl, issue the following command to change the account name and/or password in the SharePlex
internal records.
To change the user account:
sp_ctrl> connection {o.SID | r.database} set user=username
To change the password:
sp_ctrl> connection {o.SID | r.database} set password=password
where:
l SID is the ORACLE_SID of the database, if the database is Oracle.
l database is the name (not the DSN) of the database, if the database is non-Oracle.
l username is the new account name.
l password is the new password.
8. Start the SharePlex processes.
sp_ctrl> start service

Change the name or IP address of a

replication host
Description
Use the provision utility to change a host name or IP address in the SharePlex configuration.
The SharePlex processes rely on the host names or IP addresses of the source and target machines to route
data properly. The provision utility enables you to update host names or IPaddresses within an active
SharePlex instance, without reactivating a new configuration.
NOTE: The provision utility does not change anything in the database. It only affects SharePlex
internal objects.

Supported databases
All databases supported by SharePlex on all supported platforms

Guidelines for using provision

l provision is only valid for SharePlex version 6.1.1 and above.
l (SharePlex 7.0.2 only) If provision is being used because the host name of a machine changed, contact
Dell Support to request a new license. Otherwise SharePlex will not start after the change.
l (SharePlex 7.0.2 only) Add the following parameter to the param-defaults file before you run provision:
SP_CFP_DEBUG I live int() 0x00000000

SharePlex 8.6
Administrator Guide

303

l If running SharePlex on an AIX machine, set EXTSHM before running provision.

export EXTSHM=ON
l Run provision on the machine for which the name or address changed. provision propagates the
changes to the SharePlex processes that are involved between that machine and the other machine in
the same routing map. Therefore, if you change the target machine, run provision from that machine. If
you change the source machine, run provision from that machine.

Run provision
1. Stop sp_cop. If sp_cop is running, provision will fail. NOTE: provision prevents sp_cop from being
started while it is running.
2. Using the command line of the operating system, run provision from the SharePlex variable-data
directory with the following syntax:
provision -f old_name[:old_ipaddress] -t new_name[:new_ipaddress] [-n]
Argument
-f hostname[:ipaddress]

Input
l -f is required and represents "from."
l old_name is the old (current) host name.
l old_ipaddress is the old IPaddress. Use if the IPaddress cannot be
obtained from the network.

-t hostname[:ipaddress]

l -t is required and represents "to."

l new_name is the new host name.
l new_ipaddress is the new IPaddress. Use if the IPaddress cannot
be obtained from the network.

-n

Runs provision without actually making any changes. Generates a report

on the changes that provision will make.
IMPORTANT! The best practice is to run provision with -n first, to make
certain you agree with the potential changes, then run it without -n to
make the changes.

Example:
provision -f oldname -t newname -n
3. View the event log to view every change that was made. If the provision run fails or you do not agree
with the changes that were made, you can undo them by running the undo_provision script. See Undo
changes made by provision

Undo changes made by provision

The provision utility creates an undo_provision script that can be used to restore the host names and
IPaddresses to their previous state. Run the undo_provision script from the util subdirectory of the SharePlex
product directory. There are no input arguments to this script.

SharePlex 8.6
Administrator Guide

304

Known issues
The following may occur but do not affect the integrity of the replication environment:
l The provision utility does not change the active configuration file.This means that the configuration file
no longer represents the current state of replication after provision is run. If you need to run the
compare config command, or if you decide to reactivate the configuration, update the host name or
IPaddress in the configuration file first.
l If an Export or Import error occurred when SharePlex connected to a machine before the name or
address was changed, the error status persists and cannot be cleared.
l If the new or changed machine is a source machine, provision generates new routing information, but
the Read process may still have the old routing in its cache. When you start sp_cop, Read might
generate a warning that the stored IP address does not match the one for the machine. You can ignore
this error.
l After provision is run for a source host, it might not update the "hostname" column in SHAREPLEX_ACTID
table with the new host name details. If that column is not correctly updated, you must update the
SHAREPLEX_ACTID table manually to specify the new host name. This is only required if the name
change affected a source machine.

SharePlex 8.6
Administrator Guide

305

22
Apply an Oracle application patch or
upgrade

This chapter contains procedures to follow when you need to apply an application patch or upgrade and there
is an active replication configuration. These procedures apply to Oracle databases.

Contents
Before you patch or upgrade an application
Apply patch/upgrade to source then copy it to target
Apply patch/upgrade to source and target
Apply patch to source and replicate it to the target

Before you patch or upgrade an application

Review the following topics before you patch or upgrade an application on a system where SharePlex
replication is active.

Which procedure to use?

There are different procedures for applying an application patch or upgrade to an Oracle database while
replication is in process. Which one to choose depends on what changes the patch or upgrade makes.
Changes made by the
patch/upgrade

What to do

Applies DDL that is not

supported by SharePlex.

Follow one of these procedures:

Before you patch or upgrade an application
Before you patch or upgrade an application

Adds new tables (including

temporary tables renamed to a
permanent table)

Follow one of these procedures:

Before you patch or upgrade an application
Before you patch or upgrade an application

Creates or modifies triggers or

constraints

Follow one of these procedures:

SharePlex 8.6
Administrator Guide

306

Changes made by the

patch/upgrade

What to do

Before you patch or upgrade an application

Before you patch or upgrade an application
Does any of the following:
l Adds indexes, stored
procedures and/or
packages to source
system

Follow Before you patch or upgrade an application

NOTE:Because this procedure assumes that SharePlex can replicate all of
the changes that the patch or upgrade applies, the patch/upgrade is not
applied to the target.

l Changes users and

security on source
system (other than
SharePlex)
l Performs DML changes.
l Performs DDL changes
that SharePlex
replicates.
And:
Does not make any of the
changes listed in the
previous rows of this
table.

The effect of patches and upgrades on partitioned

replication
A patch or upgrade can make changes that affect the column partitions or column conditions in your replication
configuration. Take the following into account when you perform this procedure.

How a patch or upgrade can affect vertically partitioned replication

See Configure vertically partitioned replication for more information.
If the patch or upgrade does this to a
table:

Do this:

Adds columns that do not satisfy the column

partition of the table

(Optional) Drop the columns from the target table after the
patch or upgrade is applied.

Adds columns that need to be in the column

partition of the table

Add those columns to the source and target column partition

lists in the configuration file.

Drops columns that are part of the column

partition of the table

Remove those columns from the source and target column

partition lists in the configuration file.

Changes the name of a column that is in the

column partition of a table

Change the column name in the source and target column

partition lists in the configuration file.

SharePlex 8.6
Administrator Guide

307

How a patch or upgrade can affect horizontally partitioned replication

See Configure horizontally partitioned replication for more information.
If the patch or upgrade does this
to a table:

Do this:

Adds rows that need to be in a

partition scheme

Add a column condition for the rows in the SHAREPLEX_PARTITION

table.

Deletes rows that are part of a

partition scheme

Remove the column condition from the partition scheme in the

SHAREPLEX_PARTITION table.

Naming conventions used

In these procedures, the "source" system is one of the following:
l The source system of a single-direction replication configuration, including cascading replication.
l All source systems of a consolidated replication configuration.
l The trusted source system in a peer-to-peer replication configuration.
these procedures, the "target" system is one of the following:
l The target system of a single-direction replication configuration, including cascading and consolidated
replication.
l The secondary systems in a peer-to-peer replication configuration.
In this procedure, the SharePlex commands in the procedure apply to all sp_cop instances that apply to the
replication strategy you are using (for example, all sp_cop processes on a target in consolidated replication).

Apply patch/upgrade to source then copy

it to target
Supported databases
Oracle on all supported platforms

When to use this procedure

If the patch or upgrade does any of the following:
l Makes DDL changes of a type not replicated by SharePlex.
l Used a temporary table that was renamed to a permanent table that must be included in replication
(for example, a reorganization.
l Added objects that must be replicated.

SharePlex 8.6
Administrator Guide

308

Overview of the procedure

Use this procedure to run an Oracle hot backup to copy patches or upgrades from the source system to the
target system, instead of applying the patch or upgrade directly on the target system. This is useful if the
patch or upgrade makes extensive changes that are of the type(s) not supported by SharePlex replication, or if
you are unsure of what it does.
With this procedure, you can keep the configuration file active on the source system. You use the reconcile
command to identify and eliminate the following:
l Duplicate DML and DDL from the patch or upgrade operations that were replicated but also applied by
the backup.
l Production transactions that were replicated but also applied by the backup.
NOTE: It could be less time-consuming to apply a patch or upgrade manually to the target system, instead of
using a hot backup. Examples of such situations are when the operation only adds an index or stored
procedures, or when it only changes security. See Apply patch/upgrade to source then copy it to target.

Apply the patch/upgrade

1. Stop user access to the instances involved in replication on the source and target systems, but do not
shut down SharePlex.
2. On the source system, run sp_ctrl.
3. On the source system, flush the data to the target system. This command stops Post and places a
marker in the data stream that establishes a synchronization point between source and target data.
sp_ctrl> flush datasource
where: datasource is the datasource of the source instance, for example o.oraA.
4. On the source system, apply the patch or upgrade.
5. On the source system, restore user access to the source instance.
6. [If the patch/upgrade adds objects that must be replicated] Edit the configuration file as follows (do not
deactivate it). The patch or upgrade may have affected column partitions or column conditions in
partitioned replication. See Apply patch/upgrade to source then copy it to target.
l Copy the configuration file.
sp_ctrl> copy config filename to newname
l Edit the copy.
sp_ctrl> edit config newname
Save the file.
7. Do one of the following:
l If you added objects in the previous step, activate the new configuration file.
sp_ctrl> activate config newname
l If you did not make any changes to the original configuration file, activate that one.
sp_ctrl> activate config filename
8. On the source, run the Oracle hot backup.

SharePlex 8.6
Administrator Guide

309

9. On the source, switch log files and make a note of the highest archive-log sequence number.
svrmgr1> alter system switch logfile;
10. On the target, recover the target database from the hot backup using the UNTIL CANCEL option in the
RECOVER clause, and cancel the recovery after Oracle fully applies the log that you recorded in the
previous step.
11. On the target system, open the database with the RESETLOGS option.
12. Run on the target instance, but do not create a new user. Choose the existing SharePlex user and
password (copied in the backup). See the SharePlex Reference Guide for Oracle Setup instructions.
13. On the target system, issue the reconcile command using the sequence number of the log that you
noted previously. If you are using named post queues, issue the command for each one. If you do not
know the queue names, issue the qstatus command first.
sp_ctrl> qstatus
sp_ctrl> reconcile queue queuename for datasource-datadest seq sequence_number
Example: reconcile queue SysA for o.oraA-o.oraA seq 1234
NOTE:The reconcile process retains control of sp_ctrl until it is finished.
14. On the target system, if the patch or upgrade installed triggers on the tables in replication, disable
them or run the sp_add_trigger.sql utility script so that the triggers ignore the SharePlex user.
15. On the target system, if the patch or upgrade added check constraints or scheduled jobs that perform
DML, disable them.
16. On the target system, perform any cleanup required by partitioned replication (see Apply
patch/upgrade to source then copy it to target).
17. On the target system, start Post.
sp_ctrl> start post
The two instances are now in synchronization, and SharePlex resumes replication.

Apply patch/upgrade to source and target

Supported databases
Oracle on all supported platforms

When to use this procedure

If the patch or upgrade does any of the following:
l Makes DDL changes of a type not replicated by SharePlex.
l Used a temporary table that was renamed to a permanent table (for example, a reorganization, which
changes the object ID)
l Added objects that must be replicated.

SharePlex 8.6
Administrator Guide

310

Overview of the procedure

Use this procedure to apply an application patch or upgrade if it includes changes to the database that are not
replicated by SharePlex and you can stop user access to the source database to deactivate and reactivate the
configuration file. It requires deactivation of the configuration file so that SharePlex can rebuild its object
information to incorporate the changes that the patch or upgrade applied. When you reactivate the
configuration, SharePlex will re-analyze all of the objects again. You can allow users to access the source data
while the patch or upgrade is applied to the target system.
NOTE: To avoid a deactivation, see Apply patch/upgrade to source and target.

Apply the patch/upgrade

1. Stop user access to the instances involved in replication on the source and target systems, but do not
shut down SharePlex.
2. On the source system, flush the data to the target system. This command stops Post and places a
marker in the data stream that establishes a synchronization point between source and target data.
sp_ctrl> flush datasource
where: datasource is the datasource of the source instance, for example o.oraA.
3. On the source system, deactivate the configuration.
sp_ctrl> deactivate config filename
4. On the source system, apply the patch or upgrade.
5. [If the patch/upgrade adds objects that must be replicated] On the source system, edit the
configuration file, including making any changes to column partitions or column conditions if using
partitioned replication. See Apply patch/upgrade to source and target.
sp_ctrl> edit config filename
6. On the source system, activate the configuration file.
sp_ctrl> activate config filename
7. On the source system, restore user access to the source instance.
8. On the target system, apply the patch or upgrade.
9. On the target system, if the patch or upgrade installed triggers on the tables in replication, disable
them or run the sp_add_trigger.sql utility script so that the triggers ignore the SharePlex user.
10. On the target system, if the patch or upgrade added check constraints or scheduled jobs that perform
DML, disable them.
11. On the target system, perform any cleanup required by partitioned replication (see Apply
patch/upgrade to source and target).
12. On the target system, start Post.
sp_ctrl> start post
The two instances are now in synchronization, and SharePlex resumes replication.

SharePlex 8.6
Administrator Guide

311

Apply patch to source and replicate it to

the target
Supported databases
Oracle on all supported platforms

When to use this procedure

If all of the operations applied by a patch or upgrade are supported by SharePlex and can be replicated to the
target. This includes DML changes and DDL that is supported by SharePlex. If you are not sure whether the
patch or upgrade performs operations that are not supported by SharePlex, use Apply patch to source and
replicate it to the target.
Note: For a list of operations that SharePlex supports, see the SharePlex Release Notes.

Apply the patch/upgrade

1. Stop user access to the Oracle instances on the source and target systems.
2. On the source system, flush the data to the target system. This command stops Post and places a
marker in the data stream that establishes a synchronization point between source and target data.
sp_ctrl> flush datasource
where: datasource is the datasource of the source instance, for example o.oraA.
3. On the source system, apply the patch or upgrade.
4. On the source system, restore user access to the source instance.
5. On the target system, if the patch or upgrade created or modified triggers, disable them or run the sp_
add_trigger.sql utility script so that the triggers ignore the SharePlex user.
6. On the target system, restore user access to the target instance.

SharePlex 8.6
Administrator Guide

312

23
Back up Oracle data on the source or
target

This topic contains procedures for making backups of source and target Oracle data while replication is active.

Contents
Perform a partial backup of the source system
Perform a full backup on the source system

Perform a partial backup of the source

system
To perform a partial back up of a source system (for example, to extract data or populate a data warehouse)
while data is being replicated, you can perform the partial backup on the target system instead and copy the
same data as you would on the source system.
This procedure does not interrupt user access to the source data and does not deactivate or reactivate the
configuration file.
1. On the source system, start sp_ctrl.
2. On the source system, flush the data to the target system. This command stops the Post process and
places a marker in the data stream that establishes a synchronization point between source and
target data.
sp_ctrl> flush datasource
where: datasource is the datasource specification of the source Oracle instance, for
example o.oraA.
3. On the target system, back up the data. NOTE:The data now matches the source data at the
flush marker.
4. On the target system, start the Post process.
sp_ctrl> start post

SharePlex 8.6
Administrator Guide

313

Perform a full backup on the source system

To back up the entire source system, including SharePlex, you must shut down SharePlex replication while the
backup is performed.
This procedure stops user access to the source data but does not deactivate or reactivate the configuration
file. Replication resumes when started after the backup.

Perform these steps on the source system:

1. Stop all system activity.
2. Start sp_ctrl.
3. Flush the data to the target system. This command stops the Post process and places a marker in the
data stream that establishes a synchronization point between source and target data.
sp_ctrl> flush datasource
where: datasource is the datasource specification of the source Oracle instance, for
example o.oraA.
4. Shut down SharePlex. This command shuts down SharePlex.
sp_ctrl > shutdown
5. Shut down the network and the Oracle instance.
6. Perform the backup.
7. Start the network and the Oracle instance.
8. Start sp_cop (Unix and Linux) or the SharePlex service (Windows).
9. Start sp_ctrl.
10. Allow users to access the source Oracle instance.
11. Verify that the SharePlex processes started.
sp_ctrl> status

Perform these steps on the target system:

1. Start Post.
sp_ctrl> start post
2. Verify that Post started.
sp_ctrl> status

SharePlex 8.6
Administrator Guide

314

24
Tune the Capture process for Oracle
sources

This chapter contains instructions for improving the performance of the Capture process to prevent Capture
from losing pace with the volume of redo that an Oracle source database generates.

Contents
Overview
Disable LOB Mapping
Tune Capture on Exadata
Support frequent log switches

Overview
This chapter contains instructions for improving the performance of the Capture process.

Disable LOB Mapping

If you have PK/UK logging enabled on the source database (recommended to support more SharePlex features
and faster processing), check the setting of the SP_OCT_ENABLE_LOBMAP parameter. This parameter controls
whether or not SharePlex uses a LOB map when replicating tables that contain out-of-row LOB columns. The
LOB map is used by the Capture process to map LOBIDs and rows when PK/UK logging is not enabled. LOB
mapping is enabled by default. The SHAREPLEX_LOBMAP table stores these mappings.Transactions with
numerous LOB operations can slow down Capture because it needs to maintain and refer to the mappings. If
PK/UK logging is enabled on the database, you can disable LOB mapping by setting this parameter to 0.

To disable LOBmapping during active replication

1. Run sp_ctrl on the source system.
2. Set SP_OCT_ENABLE_LOBMAP to 0.
sp_ctrl> set param SP_OCT_ENABLE_LOBMAP 0
3. Stop Capture.
sp_ctrl> stop capture
4. Truncate the SHAREPLEX_LOBMAP table.

SharePlex 8.6
Administrator Guide

315

5. Restart Capture.
sp_ctrl> start capture

Tune Capture on Exadata

Normally, SharePlex provides the least latency when reading from the online redo logs. On Exadata,
SharePlex can process higher volumes of data when reading from a multiplexed archive location outside of
the Exadata ASM file system. Should a backlog develop with high volumes of data on Exadata, you can
configure SharePlex as follows.
NOTE: Make certain to manage the secondary archive log destination directory. Ensure that enough space is
allocated to the archive log files and periodically remove files that Capture had already processed.

To configure SharePlex to read from a secondary redo log location:

1. Stop Capture.
2. Configure the multiplexing of the archive logs so that the secondary location is a non-ASM disk outside
the Exadata machine. See the Oracle documentation for instructions. For best performance, use a disk
that is local to the system where SharePlex is installed.
3. Set the SP_OCT_PREFER_ARCHIVE parameter to 1. This prevents Capture from using the online logs if an
archive is available at the secondary location.
4. Set the SP_OCT_ARCH_LOC parameter to point to the path of the secondary log location.
5. Set the SP_OCT_CK_LOC_FIRST parameter to 1. This directs Capture to look for the archive logs in the
secondary location.
6. Restart Capture.

Support frequent log switches

Capture checkpoints it state to disk on a regular basis to support recovery. This information includes the log
and location within that log of the most recently processes data. In a database environment where there are
frequent log switches, a switch can occur before SharePlex writes its checkpoint. You can use the SP_OCT_
CHECKPOINT_LOG parameter to ensure that Capture issues a checkpoint before a log switch.
The checkpoint is triggered when Capture lags a specified number of logs behind Oracle. For example, with the
default of 2, Capture does a checkpoint when it falls 2 or more logs behind Oracle.
The range of permissible values for this parameter is from 2 (the default) to a value equal to the number of logs
you are using. A value of 0 disables this feature.

SharePlex 8.6
Administrator Guide

316

25
Tune the Post process for Oracle
targets

This chapter contains instructions for improving the performance of the Post process when posting to an Oracle
target database. Because replicated data is applied through standard SQL mechanisms, the Post process
provides the most potential for performance tuning.

Contents
Use Oracle INDEX hints
Tune SQL Caching
Adjust open cursors
Skip large maintenance transactions
Make small transactions faster

Use Oracle INDEX hints

Valid for:Oracle targets

When SharePlex performs UPDATEs and DELETEs on a target table, Oracle sometimes does not pick the most
efficient index for SharePlex. Without the right index, the Post process slows down when multiple UPDATEs and
DELETEs are performed. SharePlex enables you to make use of Oracles INDEX hints to enforce the use of the
correct index on target objects.
To use INDEX hints, use the hints.SID file, where SID is the ORACLE_SID of the target instance. When Post
applies a SQL statement, it reads the hints file. If the file contains entries, Post reads the data into memory and
then checks each UPDATE and DELETE statement that it processes. If any of those operations involve tables
listed in the hints file, Post sends the hints to Oracle.
Use hints only for tables that need them. For example, if Post is doing full-table scans on tables where there
are defined indexes, use hints only for those tables. The use of hints causes Post to read the hints.SID file for
each operation on tables listed in the file. This can slow down processing if numerous tables are listed.
The default maximum number of hints (table/index pairs) is 100. You can adjust this value with the SP_OPO_
HINTS_LIMIT parameter. See the SharePlex Reference Guide for more information.
Make certain all indexes are valid. Although SharePlex will use an invalid index as a hint, Oracle ignores invalid
hints and returns no errors. SharePlex writes the following information to the event_Log if it detects abnormal
conditions relating to the specified hints.
15050 hint file not found

SharePlex 8.6
Administrator Guide

317

17000 error opening hint file

15051 missing column in the hint file (either table or index name)
15052 syntax error for tablename
15053 syntax error for indexname
15054 source tables object_id not found in object cache
15055 more than 20 valid entries were entered into the hints file

To use the hints file

There is a blank hints.SID file in the SharePlex variable-data directory on each system. Use the hints.SID file
that resides on the target system. If a hints file does not exist, create one in this directory and make certain to
use the hints.SID naming format.
1. Stop Post if it is running.
2. Open the file.
3. You can add comment lines anywhere in the file. Start a comment line with a pound symbol (#).
4. On a non-commented line, use the following template to specify a source table and the index that you
want to use for that table. Put at least one space between the table name and the index name. Place
each specification on a separate line.
src_owner.table

tgt_owner.index

Example
scott.emp

scott.emp_index

Tune SQL Caching

Valid for:Oracle targets

For Oracle targets, SharePlex caches frequently-used SQL statements for reuse so that they do not have to be
parsed and bound every time they recur. This is an adjustable feature of SharePlex that is named SQL Cache.
You can tune this feature to maximize its advantages based on the amount of repetitive statements your
application generates.
SQL Cache improves the performance of Post only if the same SQL statements are issued over and over again,
with no variation except the data values. If that is not true of your environment, then SQL Cache adds
unnecessary overhead to the Post process, and you should disable it.
The SQL Cache feature is controlled by the following SharePlex parameters:
l SP_OPO_SQL_CACHE_DISABLE: This parameter enables or disables the SQL Cache feature. By default,
SQL Cache is enabled, and this parameter is set to 0. A setting of 1 disables SQL caching. When you
disable SQL caching, SharePlex prints the following entry in the event_log: SQL Cache disabled.
l SP_OPO_MAX_CDA: This parameter determines the number of cursors to cache per session. To maintain
the cache, Post opens 50 cursors per session by default. You can increase or decrease this setting if
needed. See Adjust open cursors for additional important information.

SharePlex 8.6
Administrator Guide

318

To tune SQL Cache for best performance

1. Determine the hit ratio for cached statements by running sp_ctrl and issuing the show post
detail command.
2. Look for the SQL cache hit count field. It shows the ratio of the total number of messages that are
executed without parsing and binding divided by the total number of INSERT, UPDATE and
DELETEoperations. For example, a hit ratio of 36% indicates that Post is using cached statements 36
percent of the time.
3. View the hit ratio after several days of typical replication activity to gauge the ideal setting for SP_
OPO_MAX_CDA. If the hit ratio is under 50 percent, increase SP_OPO_MAX_CDA in a small increment of
about 5 cursors.
4. Monitor the hit ratio over the next few days. If the hit ratio increases, it means your applications are
using all of the available cursors. Continue to increase SP_OPO_MAX_CDA in small increments until the
hit ratio remains constant.

Adjust open cursors

Valid for:Oracle targets

The value of the Oracle parameter OPEN_CURSORS needs to be set high enough to support the level of
performance expected of the Post process. This parameter defines the maximum number of cursors that a
process (such as Post) can open.
Internally, Post establishes its maximum total number of open cursors from the value of OPEN_CURSORS, minus
the 10 required for routine calls. You view this value in the event_log. For the following example, OPEN_
CURSORS is set to 512.
Notice: sp_opst_mt (for o.oracle-o.oracle queue oracle) Post will not open more
than 502 cursors (OPEN_CURSORS 10).
Post maintains a record of the number of cursors it has open. If Post detects that it will exceed the maximum
number of cursors, it closes the least-recently used cursor in the least-recently used session.
To avoid running out of cursors, the Post process queries the OPEN_CURSORS value when it starts. If the value is
not high enough, Post writes the following warning to the event_log:
Warning: (sp_opst_mt for o.oracle-o.oracle queue oracle)Oracle parameter 'OPEN_
CURSORS' is < number. Check 'OPEN_CURSORS' setting.
The OPEN_CURSORS value can be modified or added if absent.
To view the OPEN_CURSORS value, query the database using the following SQL statement:
select value from v$parameter where name = 'open_cursors';

To estimate a value for OPEN_CURSORS that is high enough for the Post process
1. Estimate the peak number of concurrent transactions (sessions) that will be expected for the target
instance. Post opens a session on the target system for each one on the source system. You can get a
good estimate of the number of transactions by issuing the show post detail command in sp_ctrl when
production is at its maximum level. The Number of Open Transactions field in the display shows the
number of concurrent transactions.
2. Use the following formulas to determine the correct setting for OPEN_CURSORS to support SharePlex

SharePlex 8.6
Administrator Guide

319

(and other applications that may be accessing the target data).

SQL Cache enabled (default): By default, Post needs to reserve 10 cursors for routine calls that are
closed once they finish, plus a minimum of 7 cursors per transaction (the base minimum of 2 plus an
additional 5). The formula is:
10 + (peak number of concurrent transactions x 7) = minimum open cursors needed
SQL Cache disabled: The Post process needs to reserve 10 cursors for routine calls that are closed once
they finish, plus a minimum of 2 cursors per transaction. The formula is:
10 + (peak number of concurrent transactions x 2) = minimum open cursors needed

Skip large maintenance transactions

Valid for:Oracle targets

Large transactions that are applied by application patches or other internal Oracle operations can be omitted
from replication if they are not relevant to the data needed by user applications. These operations can
translate into thousands or millions of individual UPDATE or DELETE statements for SharePlex, all to be applied
by Post. Such transactions can adversely affect Post performance and increase the latency between the source
and target data that user applications need to perform their work. There may be reasons to prevent other DML
operations from being posted to a target database.
There are two ways you can handle such transactions:
l Assuming there are no referential relationships between those operations and the user data, configure
those operations to process through a dedicated named post queue. For more information, see
Configure named post queues.
l Configure Post to skip the operations, and then apply the SQL statement directly through Oracle. See
the following instructions.

To skip maintenance DML

1. In the source database, create a table with the following description. Name it dml_statement. Grant
SharePlex full DBA privileges to the table.
2. On the source system, run the create_ignore.sql script from the util sub-directory in the SharePlex
product directory. This script creates the SHAREPLEX_IGNORE_TRANS public procedure in the database.
When executed at the start of the transaction, the procedure directs the Capture process to ignore the
DML operations that occur until the transaction is committed or rolled back. Thus, the affected
operations are not replicated. For more information about the script, its limitations, and how to run it,
see create_ignore.sql in the SharePlex Reference Guide.
3. Edit your patch script to call SHAREPLEX_IGNORE_TRANS before UPDATEor DELETEoperations. This
allows SharePlex to ignore the transaction and not send it to the target. The script will also have to be
run on the target to bring the database back into sync.
NOTE: Only DML operations are affected by the SHAREPLEX_IGNORE_TRANS procedure. It does not cause
SharePlex to skip DDL operations, including TRUNCATE. DDL operations are implicitly committed by Oracle, so
they render the procedure invalid.

SharePlex 8.6
Administrator Guide

320

Make small transactions faster

Valid for:Oracle targets

Use the Post Enhanced Performance (PEP) feature to improve the speed of Post when it is processing mostly
small transactions, such as those most commonly found in OLTP.
This performance tool has two levels:
Increase the level of concurrency
Reduce the number of commits

Increase the level of concurrency

You can configure Post to apply transactions in parallel to increase overall throughput. The smaller the
transaction, the bigger the performance gain. To enable the concurrency feature, set the SP_OPO_
DEPENDENCY_CHECK parameter to 1.

Reduce the number of commits

You can configure Post to combine smaller transactions into larger ones. This reduces the number of commits
and acknowledgments that must be processed. The smaller the transaction, the bigger the performance gain.
Commit reduction is enabled by default when you enable the concurrency feature, and it cannot be enabled
without enabling concurrency. The SP_OPO_COMMIT_REDUCE_MSGS parameter controls the size of the
combined transaction. It sets the minimum number messages (operations) in the transaction. Post skips the
commits of small transactions whose boundaries are within the specified range, and instead applies all of the
operations in the combined transaction. The default combined transaction size is 100 messages. To disable
commit reduction, set this parameter to a value of 0.
The SP_OPO_COMMIT_REDUCE_MSGS setting is not an absolute threshold. SharePlex will not break up a
transaction across different combined transactions. Therefore, Post may need to exceed that threshold in
order to include all of the operations and the commit of the last transaction in the group.
With both concurrency and commit reduction enabled, testing has shown that performance can be increased
by as much as two or three times over conventional SharePlex posting speeds.
NOTE: The PEP feature may reduce or eliminate the need to run multiple Post processes, but you can still
benefit from the use of multiple Post processes because they eliminate a single point of failure. If a Post
process fails, the other Post processes will continue, resulting in less recovery time, after the problem is
resolved. This feature can be used in a multi-Post configuration, so long as the rules for using multiple
processes are followed (such as including all tables with referential integrity in the same process stream). See
Configure named post queues for more information about using multiple Post processes.

SharePlex 8.6
Administrator Guide

321

A
Appendix A: Peer-To-Peer Diagram

This diagram visually explains the concept of peer-to-peer replication. See Configure replication to maintain
multiple peer databases for more information.

SharePlex 8.6
Administrator Guide

322

B
Appendix B: SharePlex variables

SharePlex uses the following environment variables, which you may need to set in certain situations. Usually
you must perform additional steps before or after setting a variable, so refer to the recommended instructions
before setting a SharePlex variable.
Environment Variable

Description

EDITOR

Sets the default ASCII text editor for sp_ctrl commands that use one, for
example the create config command. See Set a default editor for sp_
ctrl .

HOST

Sets a host name for all locally run sessions of sp_ctrl . To set a persession host, see Execute commands in sp_ctrl .

SP_COP_TPORT

Sets a non-default port number for an instance of SharePlex. The

default port number is 2100. You may need to set a different port
number if you are setting up additional instances of sp_cop (see Run
multiple instances of SharePlex) or if a different port number than 2100
must be used (see Set the SharePlex port number).

SP_SYS_HOST_NAME

Sets the virtual IPaddress (also known as the global cluster package
name) on a clustered system, such as Oracle RAC. This variable must be
set on all cluster nodes. For more information, see Configure SharePlex
in a cluster.

SP_SYS_VARDIR

Sets the full path to the SharePlex variable-data directory so that sp_
cop can locate the configuration data, queues, logs and other
information. If there is only one instance of sp_cop on the local system,
this variable is set by default*. If there are multiple instances of sp_cop
on the local system, always set this variable to point to the correct
variable-data directory of an instance before setting any other
SharePlex variables for that instance. For more information, see Run
multiple instances of SharePlex.

*On Unix and Linux, the variable-data directory is set in the proddir/data/defaults.yaml file. On Windows, it is
set in the Windows Registry.

To set an environment variable in Unix or Linux

ksh shell:
export variable_name=value
csh shell:
setenv variable_name value

SharePlex 8.6
Administrator Guide

323

ksh shell:
export SP_SYS_VARDIR=full_path_of_variable-data_directory
csh shell:
setenv SP_SYS_VARDIR full_path_of_variable-data_directory

To set an environment variable on Windows

Set the environment variable by adding it to the SharePlex node of the Windows Registry.
IMPORTANT! Incorrect Registry settings can adversely affect the operation of SharePlex. Consult a System
Administrator if you need help with this procedure.
1. Shut down the SharePlex service.
2. Open the Run dialog. The location varies with the Windows version.
3. In the Run dialog, type regedit to run the Registry Editor.
4. Expand the SharePlex node:
\HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Software\SharePlex
5. Right click the port number of the SharePlex instance to which you want to add a variable, then select
New, then String Value.
6. Under the Name column, right click the new variable, then select Rename.
7. Type the correct name.
8. Double click the new variable.
9. Under Value Data, enter the string for the new variable and then click OK.
10. Exit the Registry.

SharePlex 8.6
Administrator Guide

324

1z0-071 Exam - Free Actual Q&As, Page 1 - ExamTopics
100% (1)
1z0-071 Exam - Free Actual Q&As, Page 1 - ExamTopics
120 pages
EDB Postgres Distributed (PGD)
No ratings yet
EDB Postgres Distributed (PGD)
307 pages
DB211 - Unit 7 Assignment A
0% (1)
DB211 - Unit 7 Assignment A
7 pages
Oracle Database 12c Backup and Recovery
No ratings yet
Oracle Database 12c Backup and Recovery
31 pages
LATCH - Enq TX - Index Contention
No ratings yet
LATCH - Enq TX - Index Contention
2 pages
Exam 1Z0-071
No ratings yet
Exam 1Z0-071
53 pages
Dell Shareplex Vs Oracle GoldenGate Competitive Differentiation
No ratings yet
Dell Shareplex Vs Oracle GoldenGate Competitive Differentiation
4 pages
Oracle Database Installation
No ratings yet
Oracle Database Installation
48 pages
Share Plex Bug
No ratings yet
Share Plex Bug
3 pages
How To Install Entrprisedb Server On Linux
No ratings yet
How To Install Entrprisedb Server On Linux
15 pages
Shareplex Presentation
No ratings yet
Shareplex Presentation
44 pages
GG Troubleshooting v104
No ratings yet
GG Troubleshooting v104
158 pages
Adm Ash Addm
No ratings yet
Adm Ash Addm
50 pages
Knowledge Transfer Data Redaction On EnterpriseDB
No ratings yet
Knowledge Transfer Data Redaction On EnterpriseDB
19 pages
Defining Multiple Replicats To Increase GoldenGate Performance
No ratings yet
Defining Multiple Replicats To Increase GoldenGate Performance
6 pages
Postgresql Dba: Learn Basic Rdbms Terms and Concepts
No ratings yet
Postgresql Dba: Learn Basic Rdbms Terms and Concepts
7 pages
SharePlex Oracle Migrations Webcast 1
No ratings yet
SharePlex Oracle Migrations Webcast 1
34 pages
E Book Simplify Your Database Migrations and Upgrades Ebook 22085 PDF
No ratings yet
E Book Simplify Your Database Migrations and Upgrades Ebook 22085 PDF
30 pages
CIS IBM DB2 9 Benchmark v2.0.0
No ratings yet
CIS IBM DB2 9 Benchmark v2.0.0
176 pages
Module 1 - Oracle Architecture
No ratings yet
Module 1 - Oracle Architecture
34 pages
ODA ODACLI and ODAADMCLI Command Line Reference (Doc ID 2411941.1)
No ratings yet
ODA ODACLI and ODAADMCLI Command Line Reference (Doc ID 2411941.1)
7 pages
Huge Page Caculator Tuning Red Hat Enterprise Linux For Oracle and Oracle RAC Performance - Red Hat Customer Portal
No ratings yet
Huge Page Caculator Tuning Red Hat Enterprise Linux For Oracle and Oracle RAC Performance - Red Hat Customer Portal
22 pages
Re-Imaging The Oracle Exadata Database Server
No ratings yet
Re-Imaging The Oracle Exadata Database Server
14 pages
Accessing SQL Server From Oracle With Database Gateway For ODBC (DG4ODBC)
No ratings yet
Accessing SQL Server From Oracle With Database Gateway For ODBC (DG4ODBC)
19 pages
MySQL To DB2 Redbook
No ratings yet
MySQL To DB2 Redbook
474 pages
Shutdown and Start RAC
No ratings yet
Shutdown and Start RAC
11 pages
D79794GC102 Ag
No ratings yet
D79794GC102 Ag
208 pages
Db2 Cert6112 PDF
100% (1)
Db2 Cert6112 PDF
47 pages
Oracle Automatic Storage Management: Notes
0% (1)
Oracle Automatic Storage Management: Notes
4 pages
db2 Backup Restore
No ratings yet
db2 Backup Restore
8 pages
Keeping Up With Oracle Database 12c Multitenant
No ratings yet
Keeping Up With Oracle Database 12c Multitenant
136 pages
PostgreSQL Cheat Sheet
No ratings yet
PostgreSQL Cheat Sheet
1 page
Opening Standby For Read - Write
No ratings yet
Opening Standby For Read - Write
7 pages
OPSS Configuration
No ratings yet
OPSS Configuration
18 pages
Top For Oracle 143
No ratings yet
Top For Oracle 143
10 pages
Database Vault
No ratings yet
Database Vault
18 pages
Oracle Golden Gate
No ratings yet
Oracle Golden Gate
8 pages
Oracle Upgrade 12c To 19c With Auto Upgrade Utility
No ratings yet
Oracle Upgrade 12c To 19c With Auto Upgrade Utility
2 pages
LogMiner by Example
No ratings yet
LogMiner by Example
35 pages
Post GR Esq L Notes For Professionals
No ratings yet
Post GR Esq L Notes For Professionals
74 pages
Performing Database Backups
No ratings yet
Performing Database Backups
20 pages
Securing Your Data in Motion With TLS
No ratings yet
Securing Your Data in Motion With TLS
38 pages
Data Guard PPT-oracle9i
No ratings yet
Data Guard PPT-oracle9i
54 pages
Oracledbafinal1
No ratings yet
Oracledbafinal1
197 pages
PostgreSQL Installation Guide
No ratings yet
PostgreSQL Installation Guide
55 pages
Multitenant Architecture 19c
No ratings yet
Multitenant Architecture 19c
10 pages
The Secrets of Materialized Views
100% (2)
The Secrets of Materialized Views
8 pages
ORACLE 11g SQL PL/SQL Performance Enhancements Developers
No ratings yet
ORACLE 11g SQL PL/SQL Performance Enhancements Developers
29 pages
Oracle To Microsoft SQL Server Migration - SQLines
No ratings yet
Oracle To Microsoft SQL Server Migration - SQLines
7 pages
Greenplum Database Overview
No ratings yet
Greenplum Database Overview
31 pages
CRSCTL Commands in Oracle RAC 1
No ratings yet
CRSCTL Commands in Oracle RAC 1
8 pages
Senior DBA Interview Questions
No ratings yet
Senior DBA Interview Questions
8 pages
Mystery of DBWR Tuning
No ratings yet
Mystery of DBWR Tuning
7 pages
How Does SQL Plan Management Match SQL Statements To SQL Plan Baselines
No ratings yet
How Does SQL Plan Management Match SQL Statements To SQL Plan Baselines
6 pages
Installing RAC On AIX
No ratings yet
Installing RAC On AIX
80 pages
ORACLE 12C Complete Self-Assessment Guide
From Everand
ORACLE 12C Complete Self-Assessment Guide
Gerardus Blokdyk
No ratings yet
Oracle Data Guard A Clear and Concise Reference
From Everand
Oracle Data Guard A Clear and Concise Reference
Gerardus Blokdyk
No ratings yet
Shareplex 8 6 5 Administrator Guide en
No ratings yet
Shareplex 8 6 5 Administrator Guide en
355 pages
Shareplex 8 6 1 Installationguide en
No ratings yet
Shareplex 8 6 1 Installationguide en
124 pages
Shareplex 9 0 2 Admin Guide
No ratings yet
Shareplex 9 0 2 Admin Guide
328 pages
SharePlex Original Admin Guide
No ratings yet
SharePlex Original Admin Guide
541 pages
SharePlex 80 Admin Guide
No ratings yet
SharePlex 80 Admin Guide
543 pages
SharePlex 7.6 Admin Guide
No ratings yet
SharePlex 7.6 Admin Guide
525 pages
DBMS (1 - 5 Units)
No ratings yet
DBMS (1 - 5 Units)
128 pages
Learning MySQL Language Structure
No ratings yet
Learning MySQL Language Structure
30 pages
SQL Programming
No ratings yet
SQL Programming
36 pages
DBMS Unit4
No ratings yet
DBMS Unit4
23 pages
Ip 2
No ratings yet
Ip 2
9 pages
Database System 3.19
No ratings yet
Database System 3.19
33 pages
Journal
No ratings yet
Journal
32 pages
DBMS Unit 2
No ratings yet
DBMS Unit 2
27 pages
SEMUA
No ratings yet
SEMUA
44 pages
Grade12 Practical Questions
No ratings yet
Grade12 Practical Questions
6 pages
Databse Chapter 5 - SQL-1
No ratings yet
Databse Chapter 5 - SQL-1
72 pages
Itd 256 01
No ratings yet
Itd 256 01
51 pages
Rules of Thumbs and Tips For Normalization
No ratings yet
Rules of Thumbs and Tips For Normalization
3 pages
2023efront Report User Guide v21 0
No ratings yet
2023efront Report User Guide v21 0
169 pages
ICT Worksheet STD X - Unit 8 - 1 - Spandanam
100% (1)
ICT Worksheet STD X - Unit 8 - 1 - Spandanam
1 page
A Framework For Building Financial Models: Yoder Email: Yoder@Cs - Uiuc.Edu
No ratings yet
A Framework For Building Financial Models: Yoder Email: Yoder@Cs - Uiuc.Edu
56 pages
Assignment# 2 of ICT
No ratings yet
Assignment# 2 of ICT
4 pages
Migrating Bde Applications To Dbexpress
No ratings yet
Migrating Bde Applications To Dbexpress
17 pages
Intro and Exercice Power Query
100% (1)
Intro and Exercice Power Query
30 pages
Hive Workshop Practical
No ratings yet
Hive Workshop Practical
29 pages
A Textbook On Computer Science-Grade 12: Asia's
No ratings yet
A Textbook On Computer Science-Grade 12: Asia's
312 pages
Database Practices Lab
No ratings yet
Database Practices Lab
2 pages
Learning Module
No ratings yet
Learning Module
6 pages
Examples
No ratings yet
Examples
11 pages
Albertsons PSQuery Basic
No ratings yet
Albertsons PSQuery Basic
58 pages
CST8276 Lab 2 - S2025
No ratings yet
CST8276 Lab 2 - S2025
8 pages
Introduction To Database Software
No ratings yet
Introduction To Database Software
26 pages

Shareplex 8 6 3 Administrator Guide en PDF

Uploaded by

Shareplex 8 6 3 Administrator Guide en PDF

Uploaded by

Dell SharePlex 8.

Copyright 2015 Dell Inc. All rights reserved.

Other SharePlex documentation

Conventions used in this guide

About Dell Software

Contacting Dell Software

Technical support resources

About source and target data

About the SharePlex architecture

How SharePlex replicates data

Understand the concept of synchronization

Characteristics of synchronized tables

Hidden out-of-sync conditions

Strategies for information availability

Broadcast and cascade

High availability and disaster recovery

Test before you deploy

Run SharePlex on Unix and Linux

Startup sequence on Unix and Linux

Start SharePlex on Unix and Linux

Identify SharePlex processes on Unix and Linux

Stop SharePlex on Unix and Linux

Shutdown Considerations on Unix and Linux

Run SharePlex on Windows

Startup Sequence on Windows

Start and stop SharePlex on Windows

Set SharePlex startup status on Windows

Set SharePlex process priority on Windows

Identify SharePlex processes on Windows

Shutdown Considerations on Windows

Run multiple instances of SharePlex

Run multiple instances of SharePlex from separate installations

Run multiple instances of SharePlex from one installation

How to run multiple sp_cop instances on Unix and Linux

How to run multiple sp_cop instances on Windows

Execute commands in sp_ctrl

How to run sp_ctrl

Define a default port for sp_ctrl

Define a default host for sp_ctrl

Prepare an Oracle environment for replication

Set up Oracle redo logging to support SharePlex

Set the appropriate logging level

Ensure that the correct key is logged

Configure the archive logs

Set up Oracle database objects for replication

Ensure row uniqueness

Prevent triggers from firing on the target

Configure integrity constraints

Foreign key constraints

Prevent access to target objects

Ensure compatible source-target mapping

Create objects and partitions

Set up an Oracle database to support SharePlex

Adjust OPEN_CURSORS to support Post cursors

Adjust the PROCESSES parameter to support connections

Adjust the log buffer size to improve posting

Adjust the SharePlex transaction table based on user volume

Control conversion of character sets

Set up SharePlex to support Oracle data

LOBs, LONGs, VARRAYs, and XML

Tune SharePlex based on Oracle data volume

Set system process priority

Enable Oracle direct path loads

Enable capture on Exadata machines

Set up TDE Support

Required privilege to capture TDE-protected data

Configure SharePlex to capture TDE-protected data

Create configuration files

How to create a configuration file

Create a configuration file

Structure of a configuration file

Additional configuration options

Database specifications in a configuration file

Target specifications in a configuration file

Routing specifications in a configuration file

Simple routing map