SharePlex Original Admin Guide

SharePlex
For Oracle
Administrators Guide
Version 8.0 (document revision 2)
2013 Quest Software, Inc. ALL RIGHTS RESERVED.
U.S. Patent Numbers: 7,065,538 and 7,461,103 Additional patents pending.
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 Quest Software, Inc.
The information in this document is provided in connection with Quest 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 Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND
CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST
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 QUEST 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 QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Quest 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.
Quest 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:
Quest Software World Headquarters
LEGAL Dept.
5 Polaris Way
Aliso Viejo, CA 92656
Email: legal@quest.com
Refer to our Web site (www.quest.com) for regional and international office information.
Trademarks
Quest, Quest Software, the Quest Software logo Simplicity at Work are trademarks and registered trademarks
of Quest Software, Inc. and its subsidiaries. For a complete list of Quest Softwares trademarks, please see
http://www.quest.com/legal/trademarks.aspx. Other trademarks are property of their respective owners.
Third Party Contributions
For a list of third party components and their applicable licensing please refer to Appendix A in the Shareplex
Administrators Guide.
SharePlex For Oracle

Administrators Guide
Version 8.0 Updated 8/19/13
Table of Contents
About this manual
Viewing this manual in PDF format ............................................................................................ xii

Conventions used in this manual ................................................................................................ xiii
About Quest Software.................................................................................................................. xv
Chapter 1: Whats New in 8.0

TDE Support .................................................................................................................................. 1
Target Configuration...................................................................................................................... 3
Change Tracking Enhancements ................................................................................................... 6
Open Target ................................................................................................................................... 9
Consolidated Target..................................................................................................................... 13
Process Tracing............................................................................................................................ 14
Transaction Modeling .................................................................................................................. 16
NLS Simplification ...................................................................................................................... 19
Compare Status Command .......................................................................................................... 20
Compare Sanity Check ................................................................................................................ 23
Deprecated Parameters ................................................................................................................ 24
General Changes .......................................................................................................................... 24
Chapter 2: How SharePlex Works

What is replication? ..................................................................................................................... 26
The roles of source and target data .............................................................................................. 27
The role of SharePlex configurations .......................................................................................... 28
SharePlex for Oracle architecture ................................................................................................ 29
The role of SharePlex queues ...................................................................................................... 30
The SharePlex replication processes............................................................................................ 32
How SharePlex replicates data .................................................................................................... 34
iv SHAREPLEX FOR ORACLE
Administrators Guide Version 8.0 Updated 8/19/13
How SharePlex uses the network................................................................................................. 35

How SharePlex reports errors ...................................................................................................... 35
The SharePlex internal tables....................................................................................................... 36
The SharePlex directories ............................................................................................................ 37
The Registry environment on Windows systems......................................................................... 41
The MKS Platform Components.................................................................................................. 42
Chapter 3: Running the SharePlex Programs

Part 1: Basic operation of SharePlex
Introduction to the SharePlex programs....................................................................................... 44

Process differences between UNIX and Windows systems......................................................... 46
System startup .............................................................................................................................. 47
Starting SharePlex........................................................................................................................ 48
Shutting down SharePlex ............................................................................................................. 52
Running sp_ctrl ............................................................................................................................ 54
Part 2: Alternative Operation of SharePlex
Starting SharePlex without starting replication processes ........................................................... 59

Running SharePlex for Oracle and SharePlex FS on the same UNIX system............................. 62
Starting sp_cop with the -u option on UNIX systems ................................................................. 63
Running multiple instances of SharePlex .................................................................................... 64
Running different versions of SharePlex concurrently ................................................................ 70
Chapter 4: Planning SharePlex Replication

Part 1: What you can replicate with SharePlex
What SharePlex replicates ........................................................................................................... 76

What SharePlex does not replicate............................................................................................... 76
SharePlex Best Practices.............................................................................................................. 77
Part 2: SharePlex replication strategies
Replication to maintain a reporting instance................................................................................ 81

Replication for high availability and data recovery ..................................................................... 83
Replication to distribute data ...................................................................................................... 84
Replication for distributed processing and load balancing .......................................................... 85
Replication using an intermediary system ................................................................................... 86
TABLE OF CONTENTS v
Replication for centralized reporting ...........................................................................................87

Peer-to-peer replication ................................................................................................................88
Part 3: Before you begin replication
Understanding synchronization ....................................................................................................90

Configuring system resources for replication...............................................................................92
Configuring the database for replication ......................................................................................95
Configuring the system for replication .......................................................................................122
Other implementation considerations .........................................................................................129
Chapter 5: Preparing for SharePlex Replication

Part 1: SharePlex configuration construction
Configuration options .................................................................................................................132

Configuration guidelines ............................................................................................................134
Components of a SharePlex configuration .................................................................................135
Routing maps in cluster environments .......................................................................................142
Routing limitations .....................................................................................................................142
Creating a basic configuration using sp_ctrl ..............................................................................145
Configuration for replicating to multiple target systems............................................................148
Configuration for isolating data using named export queues .....................................................150
Configuration for faster posting using named post queues ........................................................155
Configuration for horizontally partitioned replication ...............................................................160
Configuration for vertically partitioned replication....................................................................172
Scripting a configuration to replicate numerous tables in a schema ..........................................179
Scripting a configuration to replicate an entire database............................................................183
Part 2: Establishing replication
Establishing replication for reporting .........................................................................................186

Establishing replication for high availability and data recovery ................................................190
Establishing replication for data distribution or distributed processing .....................................194
Establishing replication through an intermediary system...........................................................197
Establishing combined cascading/broadcast replication ............................................................202
Establishing replication for centralized reporting (standard method) ........................................204
Establishing replication for centralized reporting using multiple sp_cop processes..................207
Establishing peer-to-peer replication .........................................................................................211
vi SHAREPLEX FOR ORACLE
Chapter 6: SharePlex Optional Setup

Part 1: Enhancing Post performance
Using INDEX hints for faster posting........................................................................................ 238

Caching SQL statements for faster posting................................................................................ 240
Part 2: Using transformation with SharePlex
Considerations for using transformation.................................................................................... 245

Creating transformation routines ............................................................................................... 249
Creating entries for the transformation.SID file ........................................................................ 255
Changing the transformation file ............................................................................................... 257
Part 3: Setting environment parameters
Setting the SP_SYS_VARDIR environment variable ............................................................... 258

Setting an alternative port for sp_cop ........................................................................................ 259
Setting a default port for sp_ctrl ................................................................................................ 265
Defining an alternative editor .................................................................................................... 266
Part 4: Using security with SharePlex
Enhancing security with host authorization ............................................................................... 268

Data encryption and SharePlex .................................................................................................. 270
Part 5: Turning on Change Tracking
Part 6: Other optional features
Configuring SharePlex startup status on Windows systems...................................................... 276

Setting SharePlex process priority on Windows systems .......................................................... 280
Changing SharePlex Registry entries on Windows systems...................................................... 282
Chapter 7: Starting SharePlex Replication

Part 1: Synchronizing data for the first time
Synchronizing data using an Oracle hot backup on an active database..................................... 289

Synchronizing data using an Oracle hot backup on a quiet database ........................................ 296
Synchronizing data with export/import or store/restore from tape ............................................ 299
Synchronizing data with FTP..................................................................................................... 302
Synchronizing data with transportable tablespaces ................................................................... 305
TABLE OF CONTENTS vii
Part 2: Activating and deactivating configurations
About configuration activation ...................................................................................................308

Before you activate a configuration............................................................................................310
Viewing activation status............................................................................................................311
Viewing configuration statistics .................................................................................................311
Deactivating a configuration ......................................................................................................311
Part 3: Changing Configurations
Adding objects to an active configuration ..................................................................................312

Adding sequences to an active configuration .............................................................................314
Removing objects from an active configuration.........................................................................318
Changing partitioned replication ................................................................................................319
Chapter 8: Using SharePlex in a High-Availability Environment

Failing over to a secondary system after an unplanned system failure ......................................322
Failing back to the primary system after an unplanned system failure ......................................324
Restoring replication when the secondary instance fails............................................................330
Planned failover and failback .....................................................................................................334
Chapter 9: Unattended SharePlex Monitoring

Part 1: Monitoring SharePlex on UNIX systems
Overview of the SharePlex Monitoring Utilities ........................................................................340

Requirements for using the monitoring utilities .........................................................................341
Upgrade instructions...................................................................................................................342
Monitoring the Event Log with sp_eventmon ............................................................................343
Monitoring the Capture process with sp_logmon.......................................................................347
Monitoring the SharePlex processes with sp_ps ........................................................................350
Monitoring the queues with sp_qstatmon...................................................................................353
Part 2: Monitoring SharePlex on Windows systems
Overview of Sp_Nt_Mon ...........................................................................................................356

Configuring Sp_Nt_Mon ............................................................................................................357
Running Sp_Nt_Mon..................................................................................................................360
viii SHAREPLEX FOR ORACLE
Part 3: Using SNMP with SharePlex
Overview of the SharePlex SNMP agent................................................................................... 361

Configuring SNMP monitoring ................................................................................................. 362
Chapter 10: Changing Oracle Characteristics Of Replicated Objects

Part 1: Performing DDL changes to replicating objects
CREATE TABLE ...................................................................................................................... 366

Making other non-replicated DDL changes............................................................................... 367
Part 2: Making other Oracle changes
Moving the location of ORACLE_HOME on UNIX systems .................................................. 369

Changing the target ORACLE_SID........................................................................................... 370
Chapter 11: Performing Administrative Operations

Part 1: Installing patches and upgrades
Installing application patches and upgrades on systems running SharePlex ............................. 380
Installing SharePlex upgrades.................................................................................................... 389
Installing SharePlex patches ...................................................................................................... 389
Downloading SharePlex .tpm files for installs, upgrades, and patches ..................................... 389
Installing OS and Oracle patches on systems running SharePlex.............................................. 389
Migrating your Oracle database................................................................................................. 390
Part 2: Administering the SharePlex Oracle account
Changing the SharePlex password on UNIX systems ............................................................... 402

Changing the SharePlex user (or user and password) on UNIX systems .................................. 406
Running ora_setup on UNIX systems........................................................................................ 407
Running OraSetup on Windows systems................................................................................... 410
Part 3: Performing other administrative operations
Performing system backups on systems running SharePlex...................................................... 412

Removing SharePlex from a UNIX system ............................................................................... 414
Removing SharePlex from a Windows system.......................................................................... 416
Chapter 12: SharePlex Utilities

Preventing DML transactions from replicating with create_ignore.sql..................................... 424
TABLE OF CONTENTS ix
Using the SharePlex trigger scripts ............................................................................................426

Viewing and manipulating queue files with qview ....................................................................428
Purging the variable-data directory with clean_vardir.sh...........................................................433
Truncating the SharePlex tables with cleanup.sql ......................................................................435
Debugging networking and/or firewall issues using the socket_test utility ...............................436
Restoring replication to an initial state with ora_cleansp...........................................................439
How ora_cleansp works..............................................................................................................439
Other alternatives to ora_cleansp ...............................................................................................439
Before running ora_cleansp........................................................................................................440
Running ora_cleansp on a UNIX system ...................................................................................441
Running OraCleanSp on a Windows system..............................................................................442
Using the SharePlex license key utilities....................................................................................444
Using the SpUtils utility .............................................................................................................451
Using the SpClient remote-access utility....................................................................................454
Glossary .......................................................................................................................................463
Index ..............................................................................................................................................483
x SHAREPLEX FOR ORACLE
ABOUT THIS MANUAL xi
About this manual
This manual provides instructions for:

Operating SharePlex.
Planning and implementing a replication strategy.
Failover/failback in a high-availability environment.
Performing administrative operations on replication systems.
Using the SharePlex utilities.
See the SharePlex Reference Manual for reference information that you will need from
time to time. It includes:
Descriptions and syntax for sp_ctrl commands that monitor and control replication.
Descriptions of SharePlex tuning parameters and how to set them.
Tools and tips for preventing and solving common replication problems.
For instructions on installing the SharePlex software, see the SharePlex Installation and
Demonstration Guide.
xii SHAREPLEX FOR ORACLE
Viewing this manual in PDF format

This manual is available in Adobe PDF format on a documentation CD provided with
the SharePlex software and from the Quest SupportLink web site at
http://support.quest.com.
The PDF document is viewable with Adobe Acrobat Reader Version 7 or 8 which is
free software that can be downloaded from the Adobe web site at
http://www.adobe.com if it is not installed on your system.
ABOUT THIS MANUAL xiii
Conventions used in this manual

The following typographic conventions are used in this guide.
Command-line syntax is expressed in Arial Narrow. The following explains the syn-
tax components.
Bold represents required components of a command or option that must be typed
as shown.
Italics represent variables defined, named or entered by the user.
Bold Italics represents required user defined variables in example command
strings.
{Braces} enclose available required arguments.
[Brackets] represent optional command components and may also be used in exam-
ple command strings to emphasize required user defined variables in long strings.
Example:
reconcile queue {queuename} for {datasource-datadest} [on host]
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.
Examples:
sp_ctrl(sysA)>
User is a viewer (level=3)
xiv SHAREPLEX FOR ORACLE
Windows menu items, dialog boxes, and options within dialog boxes are expressed in
Arial Bold.
Example:
From the File menu, select Print.
Text is set in Times New Roman, with italics and bold styles used either for emphasis or
warnings.
System names are expressed generically or fictitiously. When necessary, the source sys-
tem (or primary system) is referred to as SysA. Target systems (or secondary systems)
are referred to as SysB, SysC, SysD, and so forth.
The following icons are used to highlight important or helpful information:
This icon This icon This icon calls This icon refers
denotes addi- denotes advice attention to criti- you to related
tional informa- that can help cal issues that documentation
tion that you you save time or must not be for more infor-
should know. prevent prob- ignored. mation.
lems.
ABOUT THIS MANUAL xv
About Quest Software

Established in 1987, Quest Software (Nasdaq: QSFT) provides simple and innovative
IT management solutions that enable more than 100,000 global customers to save time
and money across physical and virtual environments. Quest products solve complex IT
challenges ranging from database management, data protection, identity and access
management, monitoring, user workspace management to Windows management. For
more information, visit www.quest.com.
Accessibility
Quest Software is committed to providing products and solutions that are accessible to
all people regardless of their capabilities. Section 508 compliance details are available
by product in the Voluntary Product Accessibility Templates (VPATs) published on our
web site at: http://www.quest.com/public-sector/vpat.aspx.
Contact Quest Software

Email: info@quest.com
Mail: Quest Software, Inc.
World Headquarters
5 Polaris Way
Aliso Viejo, CA 92656
USA
Web site: http://www.quest.com
Refer to our Web site for regional and international office information.
Contact Quest Support

Quest Support is available to customers who have a trial version of a Quest product or
who have purchased a Quest product and have a valid maintenance contract. Quest Sup-
port provides unlimited 24x7 access to our Support Portal at: http://quest.com/support.
From our Support Portal, you can do the following:
Retrieve thousands of solutions from our Knowledge Base
Download the latest releases and service packs
Create, update and review Support cases
xvi SHAREPLEX FOR ORACLE
View the Global Support Guide for a detailed explanation of support programs, online
services, contact information, and policies and procedures. The guide is available at:
http://quest.com/support.
1
Whats New in 8.0
This release of SharePlex includes the following new features:
TDE Support
In release 7.6.0 support encrypted column support was added to SharePlex. SharePlex
version 8.0 can support encrypted data whether the column, the table, or the tablespace
is encrypted. Limitations are:
Support limited to Oracle 11G
Cannot use the "copy" command for any table with encrypted data
Does not include support for encrypted SecureFile LOBs
To check whether the Oracle database is "encryption replication" ready do the follow-
ing:
Check to see that the kernel is ready by looking for the symbol 'kzekm_get_dek':
nm $ORACLE_HOME/bin/oracle | fgrep kzekm_get_dek
Check that the following file exists:
ls $ORACLE_HOME/rdbms/admin/prvtclkm.plb
If the above checks fail, download and apply Oracle Patch 10395645.
Setup
A separate key is used to provide SharePlex access to the encrypted data. The key is
defined in the wallet using the external utility "mkstore". Because the wallet is changed
outside of Oracle, the wallet must be closed and then reopened in order to make the key
visible to Oracle. Note that closing the wallet disables TDE within Oracle which might
require application downtime.
To define the key and initiate its use in Oracle:
2 SHAREPLEX FOR ORACLE
1 Create the wallet directory if necessary. For instance, $ORACLE_BASE/admin/

<instance-name>/wallet.
2 Create Shareplex's stored secret in the wallet. The mkstore utility will prompt for
the key:
mkstore -wrl <path for wallet> -createEntry ORACLE.SECURITY.CL.ENCRYPTION.SPLEX
3 If the wallet is open in the database, close it and re-open it using sqlplus:
alter system set encryption wallet close identified by "<password>";
alter system set encryption wallet open identified by "<password>";
4 Switch the log file:

alter system switch logfile;
If the database is RAC, and you are using copies of the wallet on each node, copy the
new wallet to each node and then perform steps 3 & 4 on each of the other nodes.
The next step is to run ora_setup. Note that In order for capture to decrypt the data the
SharePlex user must have sysdba privileges. Ora_setup will detect that the version is
"encryption replication" ready and will ask whether encryption replication is desired.
The SharePlex encryption key will be defined for Shareplex during this interchange:
Do you want to enable replication of tables with TDE? [y] :
If the answer is yes, ora_setup will prompt for the Shareplex encryption key:
Checking the TDE Support procedures...OK
The Shareplex TDE Shared Secret parameter has not been specified yet.
Enter the shared secret :
Please confirm the shared secret :
Again, if the database is RAC, and if SharePlex is installed on each instance, run
ora_setup in each instance to define the SharePlex key for each SharePlex instance
Upgrade
Upgrading from 7.6.x requires special care if the 7.6.x instance is using column encryp-
tion support as provided in the 7.6.0 release:
1 Verify that the source database is "encryption replication" ready as described above.
2 Create the SharePlex encryption key as described above (this may require down-
time).
CHAPTER 1 3
Whats New in 8.0
3 Quiesce the source TDE tables.
4 Upgrade to 8.0.1.
5 Run ora_setup, specify the SharePlex encryption key when prompted as described
above.
6 Bring up SharePlex and re-activate immediately.
7 The source activity can be restarted.
Target Configuration
Target configuration capability has been added to SharePlex to provide for configura-
tion that is more complex than was provided by the paramdb.
The following is the type of information configured using the target configuration:
List of metadata columns Post will update on the target table
The names of the metadata columns if not using the default names
Source id values for a consolidated post (Consolidated Target)
Long parameter values such as URI for JMS queue (Open Target)
The target configuration is identified by the name of the target sid. The command name
is target. To get basic help for the target command:
sp_ctrl > help target
Define target configuration.
target set - Set a value in the target's configuration.
target reset - Reset a value in the target's configuration.
target show - Display part, or all, of the target's configuration.
Type 'help target' and a command action for a full description and syntax
For help on setting a value in the target configuration:

sp_ctrl > help target set
Set a value in the target's configuration.
Usage: target {target} [queue {queuename}] set metadata {metadata list}
target {target} [queue {queuename}] set source {source id}
target {target} [queue {queuename}] set jms {keyword=value}
Types of configuration data
metadata - metadata to be updated on the target
source - value used for 'source' metadata
jms - parameters for jms target
Type 'help target' and the type of data to set for a full description
CHAPTER 1 5
Whats New in 8.0
The set metadata command defines which metadata columns Post will update for
either a change tracker target table or a replication target table. For detailed help on set-
ting metadata:
sp_ctrl > help target metadata
Configuration: metadata to be updated on the target
Usage: target {target} [queue {queuename}] set metadata {metadata list}
target {target} [queue {queuename}] reset metadata
target {target} [queue {queuename}] show metadata
When the target is a table in Oracle:

'metadata list' is: keyword[:custom column name], keyword[:custom
column name], . . .
and 'custom column name' is the user defined name of the column
in the target table
Keyword Column type Default column name Description

-------- ----------- ------------------------- -----------------------------
time TIMESTAMP SHAREPLEX_SOURCE_TIME Time operation applied on source
userid NUMBER SHAREPLEX_SOURCE_USERID User ID that performed operation
op VARCHAR2 SHAREPLEX_SOURCE_OPERATION Type of operation (INSERT, UPDATE,
DELETE, ...)
scn NUMBER SHAREPLEX_SOURCE_SCN Source SCN when operation was applied
rowid ROWID SHAREPLEX_SOURCE_ROWID ROWID of row that changed
trans VARCHAR2 SHAREPLEX_SOURCE_TRANS Transaction ID for the operation
seq NUMBER SHAREPLEX_OPERATION_SEQ Operation order within transaction
host VARCHAR2 SHAREPLEX_SOURCE_HOST Source host
queue VARCHAR2 SHAREPLEX_QUEUENAME Queue name
source VARCHAR2 SHAREPLEX_SOURCE_ID User defined source identifier
Example with default column names:

target o.orasid set metadata userid, op, scn, rowid
Example with user defined column name:
target o.ora112 queue prod1932 set metadata host:my_column_name
If you want Post to update the time, userid, op and scn metadata columns, and you want
to change the name of the op column to my_op, you would use the following command:
target o.orasid queue prod1932 set metadata time, userid, op:my_op, scn
You can issue the help target source command for help on setting the source which is
used for Consolidated Target.
You can also issue the help target JMS command for help on setting the target JMS
which is used for Open Target.
For help on how to display the existing configuration:
sp_ctrl > help target show
Display part, or all, of the target's configuration.
Usage: target {target} [queue {queuename}] show
target {target} [queue {queuename}] show metadata
target {target} [queue {queuename}] show source
target {target} [queue {queuename}] show jms
Types of configuration data
metadata - metadata to be updated on the target
source - value used for 'source' metadata
jms - parameters for jms target
Type 'help target' and the type of data to show for a full description
Note that the type of the "time" metadata column in the target table changed in 8.0.1
from VARCHAR2 to TIMESTAMP. For upgrades, the SHAREPLEX_SOURCE_TIME
column in existing target tables can be changed from VARCHAR2 to TIMESTAMP by
running the upgrade_cdc_timestamp_column script which can be found in the <optdir>/
util directory:
<optdir>/util/upgrade_cdc_timestamp_column.sql
The script will change the type of the SHAREPLEX_SOURCE_TIME column and con-
vert the column data.
If the name of the "time" metadata column in the target table is not
"SHAREPLEX_SOURCE_TIME", modify the upgrade_cdc_timestamp_column.sql
script to specify the column name being used.
Change Tracking Enhancements

In 8.0, several enhancements have been made to the Change Tracking functionality.
CHAPTER 1 7
Whats New in 8.0
Control changed from parameter to source configuration

Change tracking functionality was introduced in version 7.6.2. In that release, a Post
process could be designated for applying change information to the target table(s)
instead of performing replication. This was done via the parameter,
SP_OPO_TRACK_CHANGES, on the target. In 8.0, this designation is now done using
the configuration on the source rather than using this parameter on the target.
Note: Since it is no longer being used, SP_OPO_TRACK_CHANGES has been depre-

cated. For information on how deprecated parameters are handled after the 8.0 upgrade,
see Deprecated Parameters.
To configure a change tracker stream, use the following new control in the source dur-
ing setup:
owner.table !cdc:owner.table <target host>@c.<target sid>
There are two important features of a change tracker configuration entry:

1 The target table name is prefixed with the string "!cdc:" (case insensitive)
2 The target sid has a "c." in front of it instead of the "o."
For those upgrading from 7.6.2 or 7.6.3 to 8.0, the SP_OPO_TRACK_CHANGES

parameter will be in effect until the source configuration is changed and activated.
Note: If the source table is an IOT, the ROWID column will be set to
"AAAAAAAAAAAAAAAAAA".
Data type of SHAREPLEX_SOURCE_TIME column changed

When the change tracking functionality was introduced, the
SHAREPLEX_SOURCE_TIME column was a VARCHAR2 type column. In 8.0.1, it is
of type TIMESTAMP.
The add_change_tracking_columns.sql will add the column
SHAREPLEX_SOURCE_TIME column as TIMESTAMP.
For upgrades, the SHAREPLEX_SOURCE_TIME column in existing target tables can
be changed from VARCHAR2 to TIMESTAMP by running the
upgrade_cdc_timestamp_column script which can be found in the <optdir>/util direc-

tory:
<optdir>/util/upgrade_cdc_timestamp_column.sql
The script will change the type of the SHAREPLEX_SOURCE_TIME column and con-
vert the column data.
Note that the upgrade_cdc_timestamp_column.sql script will operate on a column
named "SHAREPLEX_SOURCE_TIME". If the name of the source time metadata col-
umn in the target table is not "SHAREPLEX_SOURCE_TIME", modify the script to
specify the column name being used.
New parameter to track pre-image

Change Tracker can now be configured to track the update pre-image as well as the
result of the update. If the new parameter, SP_OPO_TRACK_PREIMAGE, is set to 1,
the post process inserts two rows for every update: one with the key columns and the
before image of the updated columns ("UPDATE BEFORE") and the other with the key
columns and the after image of the updated columns ("UPDATE AFTER").
New parameter:
SP_OPO_TRACK_PREIMAGE I restart_process int(0:1) 0
Note: If the SP_OPO_TRACK_PREIMAGE parameter is set to 1, the "UPDATE

BEFORE" record may not include the before image of a changed non-key column.
Configure which metadata columns to update

A new target configuration mechanism in 8.0 provides the user with the means to cus-
tomize the metadata columns that are updated in the target table by change tracker post.
Users define which columns change tracker post will update and can also specify names
for the columns other than the ones defined in 7.6.2. There are more choices in columns
that the change tracker post can be configured to update.
If a post process is configured as a change tracker post (whether by parameter, or source
configuration), and there is no target configuration for that post process, the change
tracker post process will update the same seven metadata columns that were updated by
the 7.6.2 change tracker post:
CHAPTER 1 9
Whats New in 8.0
SHAREPLEX_SOURCE_TIME TIMESTAMP
SHAREPLEX_SOURCE_USERID NUMBER
SHAREPLEX_SOURCE_OPERATION VARCHAR2(20)
SHAREPLEX_SOURCE_SCN NUMBER
SHAREPLEX_SOURCE_ROWID ROWID
SHAREPLEX_SOURCE_TRANS VARCHAR2(60)
SHAREPLEX_OPERATION_SEQ NUMBER
For details on defining and using the target configuration, refer to the section Target
Configuration.
Open Target
In 8.0, SharePlex provides ability to post changes to a JMS queue. Currently the follow-
ing JMS providers are supported:
ActiveMQ
OpenMQ
Note: To support this functionality, PK/UK supplemental logging must be enabled on the
source table.
SharePlex requires an Oracle client even if the SharePlex install is on a machine that
will only write to JMS.
The post process will not write data changes in a transaction to the JMS until post has
received the commit for the transaction and has resolved all rollbacks.
Note: JMS broker should be configured to allow producer to automatically create queues
or the destination queue must be manually created prior to send messages. JMS broker
should be configured with proper authentication credentials for the producer user and
SharePlex should be similarly configured to use the same authentication credentials
SharePlex will need access to the provider JAR files. SharePlex installation will create
the following directory:
<opdir>/lib/providers
After installing SharePlex on the target machine, copy the JAR file, and any JAR file
dependencies it may have, to a directory created under the providers directory (best
practice is to use the provider name). For instance:
<opdir>/lib/providers/activemq/activemq-all.jar
<opdir>/lib/providers/activemq/slf4j.jar
Use the following syntax in the source configuration file to configure a stream replicat-
ing to JMS:
<source specification> !jms[:target table] <hostname[:queuename]>
The following configuration lines are valid:
PROD.TABLE !jms prodsys
PROD.TABLE !jms:LOCAL.TABLE prodsys
PROD.TABLE !jms prodsys:myjms
expand PROD.% !jms prodsys
Note that if the target table name is preceded by, or consists of, "!jms:", a target sid can-
not be specified. SharePlex will define the target as "x.jms".
CHAPTER 1 11
Whats New in 8.0
Use the target command (Target Configuration) to manage required and optional param-
eters for connecting to the JMS queue:
sp_ctrl (alvspxl11:8567)> help target jms
Configuration: parameters for jms target
Usage: target {target} [queue {queuename}] set jms {keyword=value}
target {target} [queue {queuename}] reset jms {key}
target {target} [queue {queuename}] show jms
'keyword' is one of:

Keyword Default value Description
------------- ------------------ --------------------------------------
* factory_class FQDN connection factory class name
(java.naming.factory.initial)
* lib_location Location of provider .jar files under
<optdir>/lib/providers
* provider_url Provider URL (java.naming.provider.url)
destination queue JMS destination type (queue or topic)
factory_name connectionFactory JNDI connection factory lookup names
(jndi.name) or (jndi.name1,jndi.name2,...
password Password of user attaching to JMS
persistent yes JMS delivery mode (yes or no)
queuename OpenTarget Name of JMS queue
session transacted no Local (session) transactions are enabled
user Username attaching to JMS
*-Required parameter
Example: target x.jms set jms user = jwalters

There are three required parameters: factory_class, provider_url and lib_location.
The factory class (java.naming.factory.initial) is the JNDI environment property speci-
fying the class name of the initial context factory for the provider (for more information
about this and the other JMS target parameters, see the section Target Configuration
Reference below). For example, to set the factory_class for any open target process to
org.apache.activemq.jndi.ActiveMQInitialContextFactory:
sp_ctrl> target x.jms set jms
factory_class = org.apache.activemq.jndi.ActiveMQInitialContextFactory
Note that if the parameter is being set for a specific open target process, use the queue
option. For example, if the queue name was jmsdata:
sp_ctrl> target x.jms queue jmsdata set jms
factory_class = org.apache.activemq.jndi.ActiveMQInitialContextFactory
The provider URL (java.naming.provider.url) is the JNDI environment property speci-

fying the location of the registry being used as the initial context. For example, to set the
provider URL to tcp://w2k3-64bit:61616:
sp_ctrl> target x.jms set jms provider_url=tcp://w2k3-64bit:61616
The lib_location should be set to the directory name under which the JAR files were
copied. For example, if the JAR files were copied into <optdir>/lib/providers/activemq,
enter the following command:
sp_ctrl> target x.jms set jms lib_location = activemq
The datatypes supported are:
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

CHAPTER 1 13
Whats New in 8.0
TIMESTAMP WITH LOCAL TIME dateTimeStamp

ZONE
Note: If the source table is an IOT, the ROWID column value will be
"AAAAAAAAAAAAAAAAAA".
Consolidated Target
In an environment where the data from multiple source databases is being replicated to
the same target database, new configuration parameters can be used to cause post to
update a column that will differentiate the data in the target database. These parameters
allow you to add a column to the target table that will be set to a different value by every
post process. This functionality is configured using the new Target Configuration.
For instance, if there are three post processes, each posting data from a different source
database, they might be configured as follows:
target cons11 queue prodsys718 set source eastern
target cons11 queue prodsys92 set source south
target cons11 queue prodsys101 set source 12345
The post process for queue prodsys718 will update column
SHAREPLEX_SOURCE_ID with the value eastern for every insert or update to a
table. In addition, the compare process will use the source id column and value to select
only the rows that are valid for that source.
The name of the column that is updated with the source id value can also be configured.
In the example above, the name of the source id column on all target tables is
SOURCE_NAME. The following configuration will satisfy this requirement. Any
target configuration entry that is entered without a queue name specification will be
applied to all queues:
target cons11 set metadata source:source_name
target cons11 queue prodsys718 set source eastern
target cons11 queue prodsys92 set source south
target cons11 queue prodsys101 set source 12345
Process Tracing
The trace command can be used to get performance and process activity about capture,
read and post. The new commands are:
trace capture [minutes] [for datasrc]
trace read [minutes] [for datasrc]
trace post [minutes] [for datasrc-datadst] [queue quename]
When the trace time is complete, the process writes out the trace data to a file in the var-
dir/log directory. The filename has the form:
<process_id>_trace_<time>
For example:
ora112_ocap_trace_Feb_5_17_24_2013
ora112_ord_trace_Feb_5_17_24_2013
ora112_spdl02_opo_trace_Feb_5_17_24_2013
The "trace capture" command outputs process utilization data. The following example
is for a capture trace where the source SID is a RAC database:
CAPTURE TRACE: Started: Sun Feb 3 15:51:55 2013
Completed: Sun Feb 3 15:52:56 2013
Time Elapsed #Operations Kbytes read Kbytes processed %Processed

1:01 0 215885 62 0%
Time breakdown: Idle Processing QWrite Other

0:47 0:04 0:00 0:10
77% 6% 0% 16%
Log reader threads: %Data read Time spent in thread

Instance 1 0% 50% - Opening/reopening file, 39% - Idle waiting
for data
Instance 2 99% 44% - Getting data, 24% - Waiting to send data to
next thread
RAC threads: Data read Time spent in thread

Instance 1 0% 91% - Idle waiting for data
CHAPTER 1 15
Whats New in 8.0
Instance 2 99% 85% - Idle waiting for data, 4% - Getting data
Sequencer thread: 95% - Idle waiting for data

The "trace read" command has been in the product since SharePlex version 6.0. It
writes out utilization information about time spent getting the Oracle key. In SharePlex
8.0, the trace output is written to a separate file instead of reader's process log. In addi-
tion, the following statistics have been added to the output:
============================ Statistics==================================
Total Time Total op Oracle time SharePlex time %Idle
1:02 1638 0:00 0:06 90%
The "post trace" command generates timing information for the different operations, as
well as breakdown of the most costly operations. Here is an example of the output:
POST TRACE: Started: Tue Dec 18 18:44:13 2012
Completed: Tue Dec 18 18:47:16 2012
Number Executions Cost

Operation Count Pct Seconds Pct
--------- ----- ---- ------- ----
Insert 716 0% 2 2%
Update 84 0% 0 0%
Delete 172687 58% 65 69%
Commit 24 0% 0 0%
Batch Delete 123706 41% 24 26%
Operation Table Avg(usec) Count Total(sec)

--------- ----- --------- ----- ----------
Insert "ELLIOT"."SRC_TEST6" 7409 123 0
Update "ELLIOT"."SRC_TEST4" 15986 23 0

Delete "ELLIOT"."SRC_TEST6" 7668 15 0

Commit 4078 24 0
Batch Delete "ELLIOT"."SRC_TEST3" 274 6199 1

Transaction Modeling
It can be helpful when setting up replication configuration to have information about the
activity of the tables that need replication. The SharePlex analyze feature has been intro-
duced to provide this information.
The following must be considered to analyze a datastream:
Run the analysis in a separate replication stream if SharePlex is already installed
as the analysis will behave the same as activation
Create a configuration file including all the tables that are being considered for
replication.
To analyze, start cop and then issue the following command. There cannot already be
an active configuration:
Usage: analyze config <filename>
[<number of hours>]
[<number> hours]
[<number> minutes]
CHAPTER 1 17
Whats New in 8.0
[<number> days]
[on {host}] | [on {host}:{port}] |
[on {login}/{password}@{host}] |
[on {login}/{password}@{host}:{port}]
For instance:
analyze config testconf 5 days
SharePlex will start a replication stream. Capture will be started and then the analysis
process which is the end of the stream:
sp_ctrl (alvspxl11:8567)> show
Process Source Target State PID
---------- ------------------------ ------------ -------------------- ------
Capture o.w111a64f Running 2968
Analyze o.w111a64f Running 2976
The analyze process can be stopped and started and the show command will display per-
tinent information:
sp_ctrl (alvspxl11:8567)> show analyze detail
Host: alvspxl11.quest.com
Operations
Source Status Processed Since Total Backlog
---------- --------------- ---------- ------------------ ---------- ----------
o.w111a64f Running 1497 17-Mar-12 10:41:54 1496 0
Last operation processed:

Redo log: 295 Log offset: 32327800
UPDATE of "TEST"."SRC_TEST3" at 03/17/12 10:59:17
Activation id : 1573
Operations processed : 1497
Transactions processed : 398
Analysis complete : 20-Mar-12 10:41:54
The analyze process will write out the analysis based upon the data gathered at the time
specified and then the replication stream will clean itself up. The analysis can be com-
pleted early by issuing the "abort config" or "deactivate config" commands or by modi-
fying the SP_ANL_RUN_TIME parameter.
The analysis will be written out in the vardir/log directory. The name of the file is:
o.<datasource>-analysis.<actid>
The analyze process maintains information about the activity for each object in replica-
tion as well as transaction information. The transaction information is used to identify
groups of tables that are inter-related in such a way that they should be replicated in the
same stream. The analysis will list out each group of related tables, the total number of
operations per table , and the total number of operations for the group. For example:
>cat o.w111a64f-analysis.1575
Activity Analysis
Group 1 of related tables: 1000 total operations in group

"TEST"."SS2_TEST1" 346
Group 2 of related tables: 1124 total operations in group

"TEST"."SRC_TEST1" 232
Tablename Inserts Updates Deletes Rollbacks Total

"TEST"."SS2_TEST2" 146 169 33 0 348
"TEST"."SS2_TEST1" 140 176 30 0 346
CHAPTER 1 19
Whats New in 8.0
"TEST"."SS2_TEST3" 116 158 32 0 306

"TEST"."SRC_TEST1" 75 114 29 14 232
"TEST"."SRC_TEST5" 61 94 22 11 188
"TEST"."SRC_TEST3" 69 73 28 8 178
"TEST"."SRC_TEST2" 69 77 21 10 177
"TEST"."SRC_TEST4" 54 89 19 13 175
"TEST"."SRC_TEST6" 61 79 25 9 174
NLS Simplification
A new parameter, SP_OPO_NLS_CONVERSION, determines whether or not the data
posted by SharePlex is converted from the source character set to the target character
set. The default behavior is to convert.
SP_OPO_NLS_CONVERSION int(0:1) 1 # Convert by default
Note that the various parameters pertaining to NLS language conversion in previous
versions have been deprecated as of 8.0 but will still work in an upgraded environment.
Deprecated parameters:
SP_ORD_NLS_LANG
SP_OPO_NLS_LANG
SP_OPO_CHARACTERSET
SP_OPO_NCHAR_CHARACTERSET
SP_DEQ_NLS_LANG
SP_DEQ_NLS_LANG_SELECTOR
SP_DEQ_CHARACTERSET
SP_DEQ_NCHAR_CHARACTERSET
Note: For information on how deprecated parameters are handled after the 8.0 upgrade,
see Deprecated Parameters.
Compare Status Command

In SharePlex version 7.6, the compare command interface was replaced with an inter-
face similar to the copy/append command.
In this release the show compare command has been replaced by the new status com-
mand output that is similar to the copy status output. To get status for the compare/
repair command use the new 'compare status' or 'repair status' command instead of
'show compare'.
Note: The execution of commands that have been de-supported in this release will
return the output from the closest corresponding new command.
The status command for jobs is now:

Usage: [job] status [all] | [{job_id}] | [{job_id}.{table_id}]
[full]
[detail]
["{status}"]
[for o.{source_sid}]
[on {host}] | [on {host}:{port}] |
[on {login}/{password}@{host}] |
[on {login}/{password}@{host}:{port}]
Note that the word "job" in the above command can be replaced by any of: compare,
repair, copy, append.
CHAPTER 1 21
Whats New in 8.0
The command will display the line items currently active, and those that are in a failed
state. For instance:
Job ID : 861
PID : 20571
Host : alvspxl11.quest.com
Started : 06-NOV-12 11:07:05
Job Type : Compare
Status : Processing - 3 objects completed
ID Tablename Status Time Total Rows %Comp Total Time

------ --------------------- ---------- ---------- ---------- ----- ---------
1 "SCOTT"."SRC_TEST1" Out Sync N/A 19 100 0:05
4 "SCOTT"."SRC_TEST4" WaitMarker 0:02 27392 0:04
5 "SCOTT"."SRC_TEST5" Init 0:01 27498 0:01
Note that 3 objects are complete, but one of those is not listed as it is in sync.
When done the job status indicates the job is complete and how many items compared:
Job ID : 861
PID : 20571
Started : 06-NOV-12 11:07:05
Job Type : Compare
Status : Processing - 6 objects completed

------ --------------------- ---------- ---------- ---------- ----- ---------
6 "SCOTT"."SRC_TEST6" Skipped
To display the status with all the items listed, use the full option:
sp_ctrl (alvspxl11:8567)> compare status full
Job ID : 861
PID : 20571
Started : 06-NOV-12 11:07:05
Job Type : Compare
Status : Done - 6 objects completed

------ --------------------- ---------- ---------- ---------- ----- ---------
2 "SCOTT"."SRC_TEST2" In Sync N/A 27297 100 0:08
6 "SCOTT"."SRC_TEST6" Skipped
CHAPTER 1 23
Whats New in 8.0
To display detail information about one line item:

sp_ctrl (alvspxl11:8567)> compare status 861.6
Job ID: 861

Table ID: 6
Compare "SCOTT"."SRC_TEST6"
From : alvspxl11.quest.com@o.w111a64f
To : "COPY"."SRC_TEST6"
alvspxl11.prod.quest.corp@o.w111a64f
Started : 06-NOV-12 11:07:18
Percent complete : N/A
Total Rows : 53741
Rows processed : N/A
Status : Skipped
Status Detail : The difference in size between source and target
is too large to process
: efficiently. Use copy command or re-issue with
'override' option.
Status Elapsed : N/A
Total Elapsed : 0:06
Compare Sanity Check

When a compare is run against a target table that is very different from the source table,
the process is inefficient. In this scenario, the copy command should be used as it is
much more efficient. To guard against the compare command being used in this case, a
sanity check has been added. It compares the number of rows in the source and target
tables. If the difference in the number of rows is large enough, the compare or repair
will not run.
Compare gets the source and target row count using the row count from the last analy-
sis. If they are not the same, and if either the source row count or the target row count is
greater than the number defined in the new parameter,
SP_DEQ_COPY_CHECK_ROWS, and if the difference between the two values is
greater than 1000000 rows or 20%, then the compare is not run.
The default value for SP_DEQ_COPY_CHECK_ROWS is 50,000.
SP_DEQ_COPY_CHECK_ROWS int(0: 2147483647) 50000
To override the sanity check, re-issue the compare command with the 'override' option.
Deprecated Parameters
New in 8.0, a parameter can be flagged as DEPRECATED. A parameter that had been
set in the paramdb in a prior release is still available and used by SharePlex in the
release where the parameter was flagged as deprecated. Deprecated parameters cannot
be set in 8.0. If you do not want SharePlex to use the deprecated parameter, you can
issue the reset command on it.
General Changes
Additional Data Type Support

SharePlex now supports Binary Float and Binary Double.
HCC Support
SharePlex now supports Oracles Hybrid Columnar Compression on Exadata. Share-
Plex supports the replication of tables where one of the following compression options
were specified on the table, or on the tablespace:
COMPRESS FOR QUERY [ HIGH | LOW ]
COMPRESS FOR ARCHIVE [ HIGH | LOW ]
Queue shared memory size for post queue

The queue shared memory size parameter, SP_QUE_POST_SHMSIZE, can be set for
individual post processes. Use the set param command with the queue ov for option. For
example:
set param SP_QUE_POST_SHMSIZE queue specialque 134217728
SharePlex cop must be restarted for the parameter to take effect.
2
How SharePlex Works
This chapter provides an overview of how SharePlex replication works. Read this chap-
ter before any others because it explains terms and processes that you need to know
before you establish and begin replication.
Contents
What is replication?
The roles of source and target data
The role of SharePlex configurations
SharePlex for Oracle architecture
The role of SharePlex queues
The SharePlex replication processes
How SharePlex replicates data
How SharePlex uses the network
How SharePlex reports errors
The SharePlex internal tables
The SharePlex directories
The Registry environment on Windows systems
The MKS Platform Components
What is replication?
Replication is the process of maintaining copies of production data that can be used as
alternate data sites on other systems. These copies are used if the production system
needs to be offline for backups or routine maintenance (high availability), or in an emer-
gency when the production system fails (disaster recovery).
Other replication options

A simple backup restored on an alternate system can be considered a form of replica-
tion, but with the same limitations as those associated with snapshots or export/import.
They are static copies of the production data at a specific point in time, getting stale as
time passes.
Other replication technologies can update a replicated copy of data, but only if no one is
accessing it. Although better than relying on simple backups, those solutions have sig-
nificant shortcomings because they require choosing between replication and access.
Data can be updated or available, but not both.
Other solutions are available, but they are equally insufficient because they negatively
affect production processing in order to maintain a copy.
SharePlex replication
SharePlex transcends the issues with other technologies in several ways:
SharePlex replicates only the changes that are made to the production data, without
interrupting production processing, so it is very fast and lightweight but also
accurate.
SharePlex replicates continuously as changes are made, so the alternate database is
an up-to-date representation of the original data.
Alternate databases maintained by SharePlex can be used in read-only mode to
offload query and report processing from the production system, greatly improving
the performance of online transaction processing (OLTP) on that system. The reports
provide the same results as if you had run them on the production system.
For more information about SharePlex benefits, see the Introduction in the SharePlex
Installation & Demonstration Guide.
CHAPTER 2 27
How SharePlex Works
The roles of source and target data

SharePlex replication uses the concepts of source and target. The source system is the
primary system that contains the original data to be replicated. This data is called the
source data.
The copy of the data is called the target data, and the machine it is copied to is the target
system. The object of replication is to keep the source and target data identical.
As changes are made to source data, SharePlex continuously replicates them to an Ora-
cle instance on the target system. When target data is identical to source data, taking into
account varying differences caused by delays in transport over a network, the two sets
of data are synchronized or in sync.
SharePlex replication is much more versatile than simply replicating data from one
machine to another. A source system can have many target systems. In addition, a
source system can simultaneously serve as a target system, receiving data from other
source systems.
Likewise, a target system can receive data from many source systems, and it can simul-
taneously serve as a source system, sending data to other target systems.
SharePlex can even be configured to replicate between tables on the same system, either
within the same database or in different databases.
FIGURE 1: Examples of source and target systems
For more information about the ways to establish replication for your database environ-
ment, see Chapter 4 and Chapter 5.
The role of SharePlex configurations

SharePlex gets its replication instructions from configurations, which are user-defined
specifications that tell SharePlex which objects to replicate and where to send the data.
When you activate a configuration, replication begins.
You create a configuration file in an ASCII text editor. Configurations reside in the con-
fig sub-directory on the source system and define the following:
The datasource the ORACLE_SID of the source Oracle instance that contains the
source data to be replicated. [o.oraA]
The source objects the names of the objects within the source database that con-
tain the source data to be replicated. You can replicate some or all of the tables and
sequences within a database. [jim.salary and jane.sales]
The target objects the names of the objects in the database on the target system
that will receive the replicated data. [jim.salary and jane.sales]
The routing map the route for transporting the data. A basic routing map includes
the target system(s), any intermediary systems or named queues, and the
ORACLE_SID of the target database. [sysB@o.oraB]
This is an example of a basic SharePlex configuration.
Datasource: o.oraA
#source objects target objects routing map
jim.salary jim.salary sysB@o.oraB
jane.sales jane.sales sysB@o.oraB
You can create as many configurations as you need for a source Oracle instance, but
only one of them can be active at a time. Multiple configurations, each replicating a dif-
ferent Oracle instance, can be active at the same time.
Important! Do not confuse datasource with source data. Datasource is a SharePlex term
for the Oracle instance containing the source data to be replicated. SharePlex does not
replicate the instance itself, but only the changes made to objects within it. Because
there can be several Oracle instances on a system, the datasource specification directs
SharePlex to the one containing the data specified in the configuration.
For more information about creating a configuration, see Chapter 5.

CHAPTER 2 29
How SharePlex Works
SharePlex for Oracle architecture
FIGURE 2: This illustration explains the basic SharePlex replication process. Depend-
ing on how you establish your replication configuration, there could be multiple Export
and Post processes and queues.
The role of SharePlex queues

Queues are interim data repositories that hold replicated data (target data) as it is trans-
ported from the source system to the target system. Queues function outside the Oracle
instance being replicated so that the I/O required to maintain them does not affect access
to the source data by the production applications.
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 gener-
ated. The replication process that sends data to a queue and the process that reads the
queue establish handshaking to acknowledge receipt of the data in the correct order. The
data is written to disk within a few seconds if the receiving process has not received it
and acknowledged its receipt.
Data is not read-released (deleted) from one queue until it is written to the next one. If a
system slows down or fails, or if connections fail or a replication process stops, data
accumulates in the queues. When the system or connection is restored, or when replica-
tion is started again, SharePlex continues replicating from the point where it stopped
and sends the accumulated data to the next process on its route.
SharePlex replication uses the following queues.
Capture Queue
The capture queue resides on the source system. It helps SharePlex obtain data from the
Oracle logs quickly, and it holds the data outside the Oracle instance for further process-
ing by SharePlex. There is one capture queue for each datasource being replicated in
other words, one capture queue for each Oracle instance. A capture queue is identified
by the datasource, for example o.oraA.
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. You can instruct SharePlex to create additional named export queues for more
complex replication strategies. A default export queue is identified by the name of the
source system on which it resides, for example, SysA.
Post Queue
The post queue resides on the target system. It holds data that is ready for writing to the
target database. On each target system, there is one post queue for the replication stream
between a source and target Oracle instance. For example, if OraA and OraB are both
CHAPTER 2 31
How SharePlex Works
replicating to OraC, there are two post queues. You can instruct SharePlex to create
additional named post queues for more complex replication strategies. A default post
queue is identified by the name of the source system and the source and target Oracle
instances, for example SysA (o.oraA-o.oraB).
Note: All SharePlex queue files are created and maintained in the rim sub-directory of
the SharePlex variable-data directory. Queue names are case-sensitive on all platforms.
The SharePlex replication processes

SharePlex replicates data using a series of replication processes, also commonly called
services. These processes start automatically as they are needed, but they can be con-
trolled with commands issued by a SharePlex user. For a visual representation of the
SharePlex sequence of events, see Figure 2 on page 29 in this chapter. The following
describes the SharePlex replication processes in their functional order.
1 The Capture Process: The Capture process reads the redo logs or archive logs
on the source system for changes to objects listed in the active configuration. Cap-
ture writes the data to the capture queue, where it accumulates until the next Share-
Plex process is ready for it. There is a separate Capture process for each datasource
being replicated, each functioning concurrently and independently. The Capture pro-
cess is named sp_ocap (Oracle Capture) and resides with the other SharePlex pro-
cesses in the bin sub-directory of the SharePlex product directory.
2 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 it sends it to the next queue. There is a separate Read process for each data-
source, each functioning concurrently and independently. By default, all Read pro-
cesses on a system share the same export queue. The Read process is named sp_ordr
(Oracle Reader) and resides with the other SharePlex processes in the bin sub-direc-
tory of the SharePlex product directory.
3 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. If there
are two target systems, there are two Export processes, and so forth. Each Export
process controls transmission of all data from all configurations that are replicating
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 net-
work. The Export process is named sp_xport and resides with the other SharePlex
processes in the bin sub-directory of the SharePlex product directory.
4 The Import Process: The Import process is the second half of the Export/
Import transport pair, operating on the target system to receive data and build a post
queue. If there are two source systems replicating to a target system, there are two
Import processes, and so forth. By default, Import builds one post queue on a target
system for each datasource being replicated from the source system. The Import pro-
cess is named sp_mport and resides with the other SharePlex processes in the bin
sub-directory of the SharePlex product directory.
CHAPTER 2 33
How SharePlex Works
Note: For replication between Oracle instances on the same system, Export and Import
processes are not created. The Read process places data directly into a post queue on
that system.
5 The Post Process: The Post process operates on the target system to read the
post queue, construct SQL statements for replicated operations, and apply them to
target objects. There is a Post process for each post queue on a target system, and
multiple Post processes can operate simultaneously on a system. The Post process is
sp_opst_mt, and it resides with the other SharePlex processes in the bin sub-direc-
tory of the SharePlex product directory.
Note: SharePlex binaries reside in the bin sub-directory of the SharePlex product direc-
tory.
How SharePlex replicates data

SharePlex reads the blocks of the redo logs for operations that need to be replicated.
SharePlex determines which operations to replicate based on the information provided
in the configuration file and in the object cache that is constructed when a configuration
is activated. SharePlex replicates only the changes made to the source data, providing a
fast and reliable replication solution.
From the information that it has about an operation, SharePlex creates one or more mes-
sages that are sent from Capture to the Read process, and from Read to all of the other
replication processes in sequence. A message can reflect a SQL operation or an internal
SharePlex operation, but most of the time it is an INSERT, UPDATE, DELETE, COM-
MIT, TRUNCATE or a supported DDL operation.
Large operations like those on LONG or LOB columns can require more than one mes-
sage 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 opera-
tions. 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 that you see in a process or queue status dis-
play approximately corresponds to the same number of SQL operations.
On the target system, the Post process receives the messages and constructs standard
SQL statements to post replicated changes to the target database.The following explains
how SharePlex builds its SQL statements on the target system.
If the change is an INSERT, SharePlex uses all of the columns in the row to build an
INSERT statement.
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 using the val-
ues in all of the columns, except LONG and LOB columns. (For more information
about keys, see Chapter 4.)
If the change is an UPDATE, SharePlex uses the key and 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 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 out-of-
sync error. In this way, SharePlex constantly validates the target data.
CHAPTER 2 35
How SharePlex Works
If the change is an UPDATE or DELETE statement that affects multiple rows on the
source machine, SharePlex will issue multiple statements on the target to complete
the task. For example, the UPDATE statement update tableA set name = Lisa where
rownum < 101 will actually send 100 UPDATE statements through the SharePlex
pipe even though only one statement was issued on the source.
How SharePlex uses the network

All communication and movement of data by SharePlex is handled by an internal mes-
saging and transport system, using an asynchronous stream protocol with TCP/IP con-
nections that is very efficient for large data transfers. This method delivers optimal
performance, reliability and restart capabilities, while conserving communication band-
width. SharePlex can replicate over any TCP/IP network, including WAN environ-
ments.
Because SharePlex replicates changes as they occur, rather than on a commit or refresh
schedule, it reduces the impact of replication on the network and does not cause spikes
in network performance. This design also minimizes latency between source and target
systems.
SharePlex recovers 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.
You can control when SharePlex uses the network. Ordinarily, data is transferred from
source to target continuously, but you can delay transmission by stopping the Export
process to send data when network connections cost less, for example. The data
remains safely in the export queue until you start Export again.
How SharePlex reports errors

SharePlex reports errors and other abnormal conditions in the following ways.
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 the replication process. It can be viewed directly from the UNIX com-
mand-line or through the sp_ctrl command-line interface.
The Status Database is generated when you issue the show statusdb command. 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 inter-
face. This information alerts you to potential problems and helps you resolve exist-
ing ones. The Status Database is viewed through the sp_ctrl command-line
interface.
When the Post process detects that source and target tables are out of synchroniza-
tion, it logs the first 100 SQL statements and data for the out-of-sync transactions to
an error file on the target system named SID_errlog.sql. (SID is the ORACLE_SID
for the target instance.) 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 con-
dition is not too severe, after first correcting the cause of the problem.
For more information about these and other tools for problem-solving, see Chapter 2 of
the SharePlex Reference Manual.
The SharePlex internal tables

Much of the replication process is controlled and tracked through a series of internal
tables that were installed when you ran ora_setup during the installation of SharePlex.
The tables reside in the SharePlex schema and belong to the SharePlex Oracle user
account. They are essential for SharePlex to operate, so do not alter them in any way.
TABLE NAME DESCRIPTION

SHAREPLEX_ACTID Each row in this table corresponds to a configura-
tion activation. It also contains the last checkpoint
from the redo log.
SHAREPLEX_COMMAND This table controls the flush, purge config, and
abort config commands.
SHAREPLEX_CONFIG A new row is inserted into this table whenever a
new configuration is activated.
SHAREPLEX_DATAEQUATOR This table maintains information when the com-
pare command has been issued.
SHAREPLEX_LOBMAP This table maintains information about LOBs
when they are being replicated.
SHAREPLEX_MARKER This table is updated whenever SharePlex gener-
ates a read-consistency marker, which is used for
key caching.
SHAREPLEX_OBJMAP This table contains the object ID records for each
configuration activation.
CHAPTER 2 37
How SharePlex Works
SHAREPLEX_PARTITION This table maintains information when partitioned

replication is used.
SHAREPLEX_TRANS This table is used by the Post process to keep track
of the state of the transactions it is processing.
DEMO_DEST This table is used as the source table for the Share-
Plex demonstrations.
DEMO_SRC This table is used as the target table for the Share-
Plex demonstrations.
The SharePlex directories

SharePlex uses two main directoriesthe product directory, where the SharePlex pro-
grams and libraries are stored, and the variable-data directory, where the queue files,
log files and other components that comprise the current replication environment are
stored. These directories are often referred to as productdir and vardir, respectively.
Do not remove, rename or edit any files or directories installed by SharePlex unless you
are directed to do so by Quest Technical Support, a Quest Systems Consultant, or a doc-
umented SharePlex procedure. 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 util sub-directory are for use only under supervision of Quest Techni-
cal Support or by Quest Systems Consultants in conjunction with a support call or via-
bility evaluation or installation. Utilities meant for general use in a production
environment are documented in the published SharePlex documentation. If you do not
find documentation for something in the util sub-directory or another SharePlex direc-
tory, do not attempt to run it.
The sub-directory structure within the two main directories differs slightly between the
UNIX and Windows platforms, and some files might exist in a Windows version but not
in a UNIX version (or vice versa). In addition, files and directories often vary from ver-
sion to version of SharePlex as features and functionality change, but the basic structure
appears as follows:
SharePlex product directory on UNIX systems:

bin contains executables for running SharePlex.
data contains default parameter settings.
install contains scripts relating to installation, licensing and upgrades.

lib contains SharePlex shared libraries.
util contains SharePlex utilities.
.app-modules is a hidden internal directory that contains raw executables which
cannot be launched directly as they require environment parameters.
.meta-inf is a hidden internal directory that contains meta information used during
the installation process.
Note: The .app-modules directory is a hidden directory and should not be used to
launch processes. SharePlex users will encounter errors if processes are launched from
this directory.
SharePlex variable-data directory on UNIX systems:

config contains configuration files for this installation of SharePlex.
data contains the Status Database, configuration activation information, user-
defined parameter settings, and other user-defined files that direct certain replica-
tion activities.
db contains a configuration database for each activation.
dump contains core files in the event of process failure.
log contains SharePlex log files.
rim contains the replication queue files.
save contains information about active and inactive configurations.
state contains information about the current state of SharePlex when a configura-
tion is active, such as the object and sequence caches.
temp is used by copy/append and other SharePlex sync related processes.
CHAPTER 2 39
How SharePlex Works
SharePlex product directory on Windows systems
bin contains executables for running SharePlex.

data contains default parameter settings.
util contains SharePlex utilities.
The product directory also contains installation-related programs and files, as well as
the variable-data directory.
Note: The directory structure in Windows differs from the directory structure in UNIX. On
Windows systems, the variable-data directory is installed inside the product directory,
while on UNIX systems, the variable-data directory and the product directories are sepa-
rate directories under splex.
SharePlex variable-data directory on Windows systems
config contains configuration files for this installation of SharePlex.

data contains the Status Database, configuration activation information, user-
defined parameter settings, and other user-defined files that direct certain replica-
tion activities.
db contains a configuration database for each activation.
dump contains core files in the event of process failure.
log contains SharePlex log files.
rim contains the replication queue files.
save contains information about active and inactive configurations.
state contains information about the current state of SharePlex when a configura-
tion is active, such as the object and sequence caches.
CHAPTER 2 41
How SharePlex Works
The Registry environment on Windows systems

SharePlex does not utilize a marker file on Windows systems as it does on UNIX sys-
tems. Instead, it refers to the Windows Registry for default directory locations and other
environment information.
The SharePlex Registry location is:

\HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Software\SharePlex
That is where any environment variables must be entered, such as SP_SYS_VARDIR as
shown in Figure 3. Each instance of SharePlex is defined in the Registry as a port num-
ber, and each has its own set of environment variables.
Warning! Do not add, change or remove Registry entries unless you are familiar with the
functionality of the Registry and the Windows platform. Errors when changing Registry
settings can adversely affect the operation of the software or the system itself. If you are
not familiar with the Registry, consult your Systems Administrator for assistance.
The MKS Platform Components

SharePlex on the Windows platform uses the MKS Toolkit operating environment
from Mortice Kern Systems (MKS). The MKS Toolkit runs as a service and enables
SharePlex to be ported to the UNIX and Windows platforms in a uniform manner.
SharePlex users have no interaction with the MKS Toolkit software, other than to ensure
that its service is running when the SharePlex service is running. The MKS Toolkit is
installed in automatic startup mode by default when it is installed during SharePlex
installation.
There is a Windows Registry entry for MKS Toolkit under the manufacturers name,
Mortice Kern Systems, and another under the name DataFocus. The default folder
for MKS Toolkit is C:\Program Files\MKS Toolkit, but a different folder might have
been selected during installation. The MKS Toolkit files must not be moved after
they are installed.
3
Running the SharePlex Programs
This chapter explains how to run the two main SharePlex programs, sp_cop and
sp_ctrl. You need to know how to run these two programs in order to establish replica-
tion, create configurations, control replication, and monitor replication status.
The chapter is divided into parts. The first part addresses basic operation of the Share-
Plex software, and the second part addresses advanced methods of operation.
Contents
Basic operation of SharePlex

Alternative Operation of SharePlex
Part 1: Basic operation of SharePlex
This section introduces you to the SharePlex programs and explains basic ways to run
them. It contains the following topics:
Introduction to the SharePlex programs
Process differences between UNIX and Windows systems
System startup
Starting SharePlex
Shutting down SharePlex
Running sp_ctrl
Introduction to the SharePlex programs

There are two programs with which users interact: sp_cop, the SharePlex control pro-
gram, and sp_ctrl, the command-line user interface.
sp_cop
The sp_cop program coordinates the main SharePlex processes (Capture, Read, Export,
Import, Post) and the SharePlex queues, and it initiates all of the other background pro-
cesses that perform specific tasks. It also maintains communication with other systems
in the replication network. There is an sp_cop process on each system involved in rep-
lication. 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.
sp_ctrl
There is an sp_ctrl command-line interface on each system involved in replication. You
will do most of your interacting with SharePlex through sp_ctrl by issuing commands
that start, stop, configure, direct and monitor SharePlex activities. The sp_ctrl program
interfaces with the sp_cnc (command and control) process, which is an sp_cop child
process that executes user commands. The sp_cnc process works in the background,
and users do not interact with it at all.
CHAPTER 3 45
FIGURE 4: The sp_cop and sp_ctrl processes

Process differences between UNIX and Windows systems

There are some differences in the way the SharePlex software runs on UNIX and Win-
dows systems.
How SharePlex runs on UNIX systems

On UNIX systems, you start SharePlex by running sp_cop. Once you start sp_cop and
sp_ctrl, sp_ctrl spawns the background processes such as sp_cnc. After you success-
fully activate a configuration, sp_cop, on source and target machines independently,
spawns the necessary child replication processes, such as Capture and Export. Each
instance of sp_cop that you start is a parent to its own set of child replication processes.
How SharePlex runs on Windows systems

On Windows, SharePlex, like Oracle, runs as a service. It appears as SharePlex [port#]
in the Services console panel. In the Task Manager it appears as Sp_Copsrv.exe. When
you start the SharePlex service, you start SharePlex. 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 would be the following processes:
On the source system
One parent Sp_Copsrv.exe process.
One Sp_Ocap (Capture) process plus one child Sp_Copsrv.exe process.
One Sp_Ordr (Read) process plus one child Sp_Copsrv.exe process.
One Sp_Xport (Export) process plus one child Sp_Copsrv.exe process.
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
One parent Sp_Copsrv.exe process.
One Sp_Mport (Import) process plus one child Sp_Copsrv.exe process.
One Sp_Opst_Mt (Post) process plus one child Sp_Copsrv.exe process.
CHAPTER 3 47
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 configurations, the SharePlex processes do not start, and just the
parent Sp_Copsrv.exe will be running.
Important! When SharePlex is running, the NuTCRACKER service must be running.

See The MKS Platform Components on page 42 for more information about the NuT-
CRACKER service.
How to identify Sp_Copsrv.exe processes on Windows systems

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.
System startup
When you start systems that are involved in replication, start the components in this
order:
1 Start the system.
2 Start the Oracle instance(s).
3 Start SharePlex (instructions follow).
4 Start sp_ctrl (instructions follow).
5 [OPTIONAL] Start the network, or start the network later to control user access.
6 Verify that the SharePlex processes are started by issuing the lstatus command.
sp_ctrl(sysA)> lstatus
7 Start the network if it was not started earlier.

8 Allow users on the system.
Starting SharePlex
This section shows you the basic method for starting a single instance of SharePlex.
Familiarize yourself with this procedure before using more advanced methods of run-
ning SharePlex.
Startup precautions
When starting replication, follow these guidelines:
Only a SharePlex Administrator (member of the SharePlex admin group) can start
sp_cop.
sp_cop must be running on all source and target systems involved in replication.
Start sp_cop as soon as (or before) users access the data on the source system, so
that all essential SharePlex processes are ready to start replicating transactions. That
way, Capture can keep pace with the changes.
If Capture loses pace with Oracles processing, the redo logs could wrap before Cap-
ture 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
accesses 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.
Starting SharePlex on UNIX systems

You can start sp_cop in one of two ways:
From the operating system command line
At system startup as part of the startup file
Run SharePlex from either the korn (ksh) or C shell (csh) shell. 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 Share-
Plex, then exit the shell and return to the Bourne shell.
CHAPTER 3 49
Warning for Exceed X users: When 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.
To start sp_cop at the UNIX command line

1 Log onto UNIX as a SharePlex Administrator using your UNIX password and user
name. Your user name must be assigned to the SharePlex Admin group in the /etc/
group file.
2 Start sp_cop either by typing its full directory path, or by changing directories to the
bin sub-directory of the SharePlex product directory, then running sp_cop. Use the
& to run it in the background.
Syntax
$ /productdir/bin/sp_cop &
Or...
$ cd /productdir/bin
$ ./sp_cop &
Every session of sp_cop has a process ID number. The system returns a process ID
number for this session of sp_cop, and then the UNIX prompt reappears. If a configura-
tion was activated during a former session of sp_cop, replication begins immediately.
Without an active configuration, sp_cop runs passively in the background.
To start sp_cop on a UNIX system at machine startup

You can add the sp_cop & command to your system's rc files so that replication begins
at system startup. Configure Oracle to start before SharePlex.
If, when the script runs, SharePlex returns an error similar to "System call error:
sp_cnc (connecting from cdrpx.mcit.med.umich.edu) Bad file number Can't dup2
stderr," try adding nohup to your startup script. The nohup command directs a com-
mand (in this case the startup of SharePlex) to continue in the background after the cur-
rent user (the script) logs out. The syntax is:
#!/bin/ksh
cd [product_dir]bin
nohup sp_cop &
Starting SharePlex on Windows systems

Because SharePlex runs as a service on the Windows platform, the only way to start
sp_cop is to start the SharePlex service. If the SharePlex service is not running, replica-
tion cannot take place. When you are directed in a documented SharePlex procedure to
start or stop sp_cop on the Windows platform, start or stop the SharePlex service.
SharePlex is installed in auto-startup mode, which starts the SharePlex service automat-
ically when the system starts so that replication begins as soon as possible. You can
change the startup option in the Computer Management Administrative Tool in Win-
dows.
To start the SharePlex service

1 Log onto Windows as a SharePlex Administrator using your system password and
user name. Your user name must be assigned to the SharePlex Admin group.
2 Double-click the SpUtils desktop shortcut.
Or...
Click the Start button on the Windows taskbar, then select Programs and navigate to
SpUtils in the SharePlex product group.
The SharePlex Utilities dialog box opens.
3 Click the SharePlex Services tab.
CHAPTER 3 51
4 In the Port list box, select the port number for the instance of SharePlex that you
want to start.
5 Under SharePlex Service Status, click Start.
6 When the Current State text box shows that the service has started, click Close to
close the dialog box.
Tip: You can control the SharePlex service from a remote system with the SpClient util-
ity. See page 454 for more information.
Important! When SharePlex starts, it checks for a license key. If it does not find a valid
license, it stops running. The license key is stored in the paramdb file, which is overwrit-
ten if you uninstall and then reinstall SharePlex. Always enter a license key when you
reinstall SharePlex after an uninstall. During upgrades, the paramdb file is retained and
the license remains intact.
Shutting down SharePlex

Normally, you should leave SharePlex running as long as you have data to replicate.
Shutting it down stops replication. Reasons to shut down SharePlex include, but are not
limited to:
to cease replication
to activate certain parameters
to run a SharePlex utility
when required by a documented SharePlex procedure or with direction from Quest
Technical Support.
You can safely shut down SharePlex while users are accessing the database and there is
an active replication configuration. SharePlex resumes replication at the point in the
redo log where it stopped, and it accesses the archive logs if the redo logs have wrapped
(if archive logging is enabled).
Warning! If you intend to shut down Oracle, do so after you shut down SharePlex.
Otherwise, SharePlex will interpret that the instance is failing and generate a warning
message. After you shut down Oracle, you can shut down the network and the system.
Cautions when stopping SharePlex

Use caution when stopping replication if users continue changing data and you want to
maintain data synchronization. If you delay starting SharePlex again, it can lose pace
with Oracles processing.
Your options in that case depend on your environment, including available disk space
for the queues and your tolerance for latency between source and target data. It might be
more practical to resynchronize the data than to wait for SharePlex to process back-
logged operations, especially if the Capture process must read the archive logs and
transaction volume is high. If the redo logs wrap and the archive logs are unavailable,
resynchronization is the only option.
You can stop individual SharePlex replication processes without shutting down Share-
Plex completely by using the stop command in sp_ctrl. See the SharePlex Reference
Manual for more information on this and other SharePlex commands.
CHAPTER 3 53
Shutting down through sp_ctrl (UNIX and Windows)

On UNIX and Windows systems, you can shut down SharePlex through sp_ctrl with
the shutdown command. This is a graceful shutdown that saves the state of each pro-
cess, performs a checkpoint to disk, read/releases buffered data, and removes child pro-
cesses. Data in the queues remains safely in place, ready for processing when sp_cop
starts again. Shutdown can take some time if SharePlex is processing large Oracle oper-
ations.
Syntax
sp_ctrl(sysA)> shutdown
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.
For more information about the shutdown command, see the SharePlex Reference
Manual.
Stopping the SharePlex service (Windows)

On Windows systems, you can shut down SharePlex by stopping the SharePlex service.
It is a graceful shutdown, similar to using the shutdown command in sp_ctrl.
Or...
SpUtils in the SharePlex product group.
want to shut down.
5 Under SharePlex Service Status, click Stop.
6 When the Current State text box shows that the service has stopped, click Close to
close the dialog box.
Tip: You can control the SharePlex service from a remote system with the SpClient util-
ity. See page 454 for more information.
Running sp_ctrl
The SharePlex sp_ctrl command-line interface program is where users do most of their
interacting with SharePlex. From sp_ctrl, you can issue all of the commands that start,
stop, configure, control, and monitor SharePlex activities. SharePlex 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.
CHAPTER 3 55
Any SharePlex user can run sp_ctrl, but in order to execute a command, a user must
have that commands authorization level or higher. The authorization level corresponds
to one of the SharePlex user groups: SharePlex Admin group (administrator), spopr
(operator), and spview (viewer).
You can run sp_ctrl from each machine where SharePlex is installed, or from just one
machine to control all other replication machines. The sp_ctrl program resides in the
bin sub-directory of the SharePlex product directory.
There are two ways to run sp_ctrl:
from the UNIX command line or the Windows Command Prompt console to issue a
single command.
through an interactive session during which you issue multiple commands, such as
checking replication status then stopping a SharePlex process.
Note: The sp_ctrl command line allows a total of 256 characters, including spaces.
To run sp_ctrl for one command

At the command-line prompt, enter the full path name of the sp_ctrl binary, followed by
the command name. Substitute the name of the command for commandname in the fol-
lowing syntax. Substitute the name of the system for hostname in the following syntax,
even if being run locally. The command executes then returns you to the command-line
prompt.
Syntax
On UNIX platforms:
$ /productdir/bin/sp_ctrl commandname on hostname
Or
$ ./sp_ctrl commandname on hostname
On Windows platforms:
C:\>drive:\productdir\bin\sp_ctrl commandname on hostname
Important! If the Windows path name contains spaces, the command may need to be
enclosed within double quotes, for example d:\Program Files\Quest Software\Share-
Plex\bin\sp_ctrl. Additionally, on Windows system, the command may be followed by a

prompt for the user name and password.
If the command you are issuing permits remote login, you can use one of its remote
login options to affect a different system or port number than the default, as shown in
the following example. The remote login options are explained in more detail in
Chapter 1 of the SharePlex Reference Guide.
$ /productdir/bin/sp_ctrl status on hostname:portnumber
To run sp_ctrl interactively for multiple commands

To start an interactive session of sp_ctrl on UNIX systems, enter the full path name of
the sp_ctrl binary from the command line, or change directories to the bin sub-directory
of the SharePlex product directory and run sp_ctrl from there.
Syntax
$ /productdir/bin/sp_ctrl
Or
$ ./sp_ctrl
To start a session of sp_ctrl on Windows systems, double-click the Sp_Ctrl desktop

shortcut or use any other Windows method for starting programs.
When the sp_ctrl prompt (sp_ctrl>) appears, the interactive session is ready for you to
enter one or more SharePlex commands. After sp_ctrl executes a command, it returns
you to the sp_ctrl prompt. The sp_ctrl prompt remains until you exit the interface with
the exit or quit command.
Tip (Windows): If your sp_ctrl window does not have a scroll bar and command output
cannot be displayed in its entirety, see Chapter 1 of the SharePlex Reference Guide for
instructions for displaying a scroll bar.
To connect to an alternate sp_cop port number

When you start sp_ctrl on UNIX systems, it reads the paramdb file for the port number
for sp_cop. If it cannot find the port there, it reads the param-defaults file and uses the
default port number of 2100. To run sp_ctrl for an instance of sp_cop other than one
CHAPTER 3 57
assigned a port number in either the paramdb or param-defaults file, start sp_ctrl and
use the port command to specify the alternative port number. Note that the alternative
port number is session-specific and thus is lost when you exit sp_ctrl.
On Windows systems, sp_ctrl reads the Registry for a default port number specified
with the DefaultPort entry in \HKEY_LOCAL_MACHINE\SOFT-
WARE\Wow6432node\Quest Software\SharePlex. If there is no value specified there,
sp_ctrl connects to port number 2100 by default or, if there are multiple instances of
SharePlex on the system, to the one with the lowest port number. To connect to a differ-
ent port number than the default, start sp_ctrl and use the port command to specify the
alternative port number.
To define a default system for sp_ctrl

To define a default machine where you want all commands to execute for an interactive
session of sp_ctrl, issue the host command. This enables you to enter a series of com-
mands without using the [on host] option for each command. Note that when you define
a different machine (other than port number 2100) as the default, the new setting is ses-
sion-specific and, therefore, is lost when you exit sp_ctrl.
Syntax
sp_ctrl> host hostname
The prompt now looks like this example:

sp_ctrl(sysA)>
To exit sp_ctrl
To exit the sp_ctrl command-line interface on a UNIX or Windows system, type either
the exit or quit command at the sp_ctrl prompt.
Syntax
sp_ctrl> exit
Or...
sp_ctrl> quit
As an alternative on Windows systems, you can close the sp_ctrl Command Prompt
window to exit sp_ctrl.
Exiting sp_ctrl does not shut down replication. All active configurations continue to
replicate data unless you shut down SharePlex or you stop the Capture process. The
shutdown command, which shuts down replication by shutting down sp_cop, also
shuts down sp_ctrl on UNIX and Windows systems upon completion of the SharePlex
shutdown procedures.
For more information about SharePlex commands and authorization levels, see the
SharePlex Reference Manual.
CHAPTER 3 59
Part 2: Alternative Operation of SharePlex
This section explains how to run SharePlex in special ways to meet specific replication
or operational requirements. It contains the following topics:
Starting SharePlex without starting replication processes
Running SharePlex for Oracle and SharePlex FS on the same UNIX system
Starting sp_cop with the -u option on UNIX systems
Running multiple instances of SharePlex
Running different versions of SharePlex concurrently
Starting SharePlex without starting replication processes
To start SharePlex without processes on UNIX systems

On UNIX systems, you can start sp_cop without automatically starting the Capture,
Read, Export, Import and Post processes by using the [-s] option. This starts SharePlex
with the processes in the idle state.
Syntax
$ /productdir/bin/sp_cop -s &
Or...
$ ./sp_cop -s &
To confirm idle status, issue the status command in sp_ctrl.

$ ./sp_ctrl
sp_ctrl> status
FIGURE 5: The status of SharePlex processes after starting sp_cop with the -s option.
To start processes after startup with [-s]

When you use the [-s] option to start sp_cop, you cannot start SharePlex processes indi-
vidually using the start command. For example, you cannot just start Capture. You first
must start the replication processes with the startup command, which starts them all at
once.
Syntax
sp_ctrl(sysA)> startup
After you issue the startup command, you can stop individual replication processes as
needed.
To start SharePlex without processes on Windows systems

Starting SharePlex without automatically starting individual replication processes (Cap-
ture, Read, Export, Import and Post) is not possible on the Windows platform. To start
the SharePlex service (sp_cop) without replication processes, stop the processes with
the stop command in sp_ctrl before shutting down SharePlex.
Syntax
sp_ctrl(sysA)> stop {capture | read | export | import | post}
The replication processes remain stopped when SharePlex starts until you issue the start
command for each process that you want to start.
CHAPTER 3 61
Syntax
sp_ctrl(sysA)> start {capture | read | export | import | post}
For more information about sp_ctrl commands, see the SharePlex Reference Manual.
Running SharePlex for Oracle and SharePlex FS on the

same UNIX system
SharePlex for Oracle and the filesystem replication application, SharePlex FS, both
from Quest Software, can run on the same system concurrently. The following Share-
Plex for Oracle and SharePlex FS processes have identical names:
SharePlex (sp_cop)
Command Line Interface or CLI (sp_ctrl)
Command and Control (sp_cnc)
Export (sp_xport)
Import (sp_mport)
To enable users to differentiate between the processes for the two programs while they
are running, use the -u option when starting each sp_cop (see Starting sp_cop with the
-u option on UNIX systems following this section).
CHAPTER 3 63
Starting sp_cop with the -u option on UNIX systems

You can use the -u option on UNIX systems to start sp_cop with a unique identifier.
Use this method when there are multiple instances of sp_cop running on a system, such
as when you are using consolidated replication with different variable-data directories,
and if you are running SharePlex FS filesystem replication, which uses its own version
of sp_cop. For example:
root 22362 24638 0 13:15:02 pts/3 0:00 sp_cop -umike8570
root 22375 22362 0 13:15:34 pts/3 0:00 /splexdata/mike/src/opt8/bin/
sp_cnc+PN+*+sp_cnc+0xa0101cf R -umike8570
root 22375 22362 0 13:15:34 pts/3 0:00 /splexdata/mike/src/opt8/bin/
sp_opst_mt -umike8570
root 22375 22362 0 13:15:34 pts/3 0:00 /splexdata/mike/src/opt8/bin/sp_mport -
umike8570
Some suggestions for -u naming are:
the SharePlex port number (-u2100)
the ORACLE_SID of the instance for which replication is running (-uora10a)
the SharePlex Administrators name (-ujad)
an identifier for the SharePlex for Oracle sp_cop (-usp_orcl)
Syntax
$ /productdir/bin/sp_cop -uname &
Or...
$ ./sp_cop -uname &
Running multiple instances of SharePlex

You can run multiple instances of the same version of SharePlex on a UNIX or Win-
dows system. For example, when replication is configured from multiple source sys-
tems to a central target system, you can run multiple instances of sp_cop to isolate the
replication streams.
The following instructions are for installing and running the same version of SharePlex
on multiple ports. Before you begin replication, ensure that you follow all recommenda-
tions in this manual for establishing your replication strategy.
Running multiple SharePlex instances on a UNIX system

Running multiple instances of sp_cop on a UNIX system requires the following:
Assigning unique port numbers and variable-data directories for each sp_cop pro-
cess. This separates the queues (and their data) for each sp_cop instance.
Creating an Oracle user account for each variable-data directory.
Using the SP_SYS_VARDIR environment variable and the -u option to start each
instance of sp_cop.
The following steps guide you through this process.
To establish the variable-data directories

1 Install SharePlex in the normal manner according to the instructions in the SharePlex
Installation and Demonstration Guide. SharePlex uses the default port of 2100.
These instructions assume, as an example, that the SharePlex product directory (con-
taining the binaries) is installed in a directory named /splex/proddir, and that the
SharePlex variable-data directory is installed in a directory named /splex/vardir.
Important! The steps that follow must be performed by a user with root privileges.
Do not start SharePlex until directed to do so. The following steps create a vari-
able-data directory for each sp_cop. In this example, two directories are created, one
using port 2101 and one using port 2200. The default port of 2100 is used for the
original SharePlex installation.
CHAPTER 3 65
2 Tar the original /splex/vardir and its subdirectories. The following commands put
the resulting tar file in /splex (one directory up). Pay close attention to the dots in the
tar command.
$ cd /splex/vardir
$ tar cvf ../splex.tar .
3 Make new variable-data directories, each named for the port number (or another
unique identifier) to be used by the associated sp_cop instance.
$ mkdir /splex/vardir/splex2101 (for the first instance of sp_cop)
$ mkdir /splex/vardir/splex2200 (for the second instance of sp_cop)
4 Change directories to the variable-data directory made for port number 2101.
$ cd /splex/vardir/splex2101
5 Enter the original variable-data directory structure into this directory.

$ tar xvf /splex/splex.tar
6 Repeat steps 4 and 5 for each additional variable-data directory. (In the example,
there is only one additional directory.)
$ cd /splex/vardir/splex2200
$ tar xvf /splex/splex.tar
7 Set the port number for each variable-data directory that you created by setting the
TCP and UDP port parameters in the SharePlex paramdb. There is a paramdb file in
each of the variable-data directories you created. See page 259 for instructions on
setting the port numbers.
8 [PERFORM THIS STEP ONLY IF THERE IS AN ACTIVE CONFIGURATION.] Log on as a SharePlex

Administrator and run the clean_vardir.sh script for each variable-data directory
that you created. The script removes duplicated replication queues and restores each
one to a fresh state. Instructions for running clean_vardir.sh are on page 433.
9 In the rim sub-directory of each variable-data directory, delete the shstinfo.ipc and
shmaddr.loc files.
Note: The shstinfo.ipc and shmaddr.loc files may not exist if sp_cop has never been
started against this variable-data directory.
To establish the Oracle users

Create an Oracle user account for each variable-data directory for which there will be an
instance of sp_cop. The account enables the Post process to log into Oracle and post
data. To create the accounts, run the SharePlex ora_setup program for each sp_cop
instance. To identify an account, use its port number, for example splex2101. See
page 407 for instructions on running ora_setup.
To start and control the sp_cop instances

To run multiple sp_cop sessions, start a session of sp_cop and sp_ctrl for each vari-
able-data directory. Follow these steps.
1 Export the SP_SYS_VARDIR environment variable to point to the first variable-data
directory.
$ export SP_SYS_VARDIR=/splex/vardir/splex2101 (ksh shell)
Or...
$ setenv SP_SYS_VARDIR /splex/vardir/splex2101 (csh shell)
2 Start sp_cop by typing the absolute path name and the uportnumber argument,
where portnumber is the port number assigned to the first variable-data directorys
sp_cop instance. This points SharePlex to the correct port and allows you to see that
sp_cop instance when you use the ps -ef | grep sp_ command. Use the & argument
to run sp_cop in the background.
$ /splex/proddir/bin/sp_cop -u2101 &
3 To run sp_ctrl for that instance of sp_cop, start sp_ctrl, then issue the port com-
mand.
$ ./sp_ctrl
sp_ctrl(sysA)> port 2101
4 Repeat the preceding steps for each variable-data directory.
Example syntax for a second variable-data directory

$ export SP_SYS_VARDIR=/splex/vardir/splex2200 (ksh shell)
Or...
$ setenv SP_SYS_VARDIR /splex/vardir/splex2200 (csh shell)
CHAPTER 3 67
$ /splex/proddir/bin/sp_cop -u2200 &
$ ./sp_ctrl
sp_ctrl(sysA)> port 2200
Note: If you receive an error message similar to this:
Error cleaning up previous shared memory segment ###.

Cannot delete because there are users attached.
Check if SharePlex processes are running and kill them if necessary.
Find out if someone else started a session of sp_cop using the same port number and
variable-data directory. Kill the processes associated with that session, then start
sp_cop again.
Running multiple SharePlex instances on a Windows system

Running multiple instances of SharePlex on the same Windows machine requires the
following:
Installing the SharePlex service multiple times using a different port number and
variable-data directory for each installation.
Starting each instance of the SharePlex service.
To install SharePlex
1 Install SharePlex on the source and target systems according to the directions in the
SharePlex Installation and Demonstration Guide, including running OraSetup and
assigning SharePlex users. You only need to assign SharePlex users once on each
system.
2 Repeat the installation procedure for each SharePlex instance that you want to create,
using the same product directory as before but with the following differences:
A Use a different variable-data directory and a different port number (2101, for
example) for each SharePlex instance you are creating. The installation program
locates available ports, which you can override if necessary.
B When you are prompted for a license key, select the port number for the installa-
tion from the drop-down list, then enter the license key. Use the same license key
for all instances that you install.
C When you run OraSetup, use the port number for the installation, and specify
the ORACLE_SID for which you are creating the SharePlex instance. Use a dif-
ferent name for each SharePlex user.
To start and control the sp_cop instances

To run multiple SharePlex instances, start a session of SharePlex and sp_ctrl for each
variable-data directory. All instances are controlled through one SharePlex Services
dialog box of the SpUtils utility. Follow these steps.
1 Log onto Windows as a SharePlex Administrator.
2 Double-click the SpUtils desktop shortcut to open the SharePlex Utilities dialog
box.

CHAPTER 3 69
want to start.
5 Under SharePlex Service Status, click Start.
6 When the Current State text box shows that the service has started, you can start
another instance of SharePlex.
7 Click Close to close the dialog box.
8 Run an Sp_Ctrl session for each SharePlex instance by double-clicking the Sp_Ctrl
desktop shortcut or browsing to its location in the SharePlex product directory.
9 In Sp_Ctrl, use the port command to specify the port number of the SharePlex ser-
vice you want to affect.
sp_ctrl> port 2101
Running different versions of SharePlex concurrently

You can run different versions of SharePlex on the same system to:
replicate the same source database to the same target database with both versions.
replicate different source databases (same or different Oracle version) to different
target databases.
test new versions of SharePlex.
replicate to target systems running different versions of SharePlex.
This procedure creates autonomous replication instances. You start, control and main-
tain each one separately, and there is no interaction between them.
SharePlex 5.0 supports replication from a source system running SharePlex Versions 4.0
or 4.5 to a target system running Version 5.0. The target system where you install Ver-
sion 5.0 must be used exclusively as a target system, meaning that it does not concur-
rently serve as a source system for another configuration. Replication from SharePlex
Version 5.0 to Versions 4.0 and 4.5 is not supported.
For other versions of SharePlex, the source and target versions must be the same.
Running different SharePlex versions on a UNIX system

Note: These instructions use Version A and Version B as examples. You can apply this
procedure to any two versions of SharePlex that you want to run concurrently.
Installing concurrent versions of SharePlex

1 Review all pre-installation requirements in the SharePlex Installation and Demon-
stration Guide for each version. When you are prompted to choose SharePlex prod-
uct and variable-data directories, choose a pair for Version A and a different pair for
Version B. For example, a logical naming convention would be:
Version A Version B
/splex/VerA/prod_dirA /splex/VerB/prod_dirB
/splex/VerA/var_dirA /splex/VerB/var_dirB
CHAPTER 3 71
2 Install Version A according the instructions in the SharePlex Installation and Dem-
onstration Guide, using the product and variable-data directories you specified for
this version. Do not run ora_setup yet.
3 Install Version B, using the product and variable-data directories you specified for
this version. Do not run ora_setup yet.
4 Export the Version A variable-data directory for SP_SYS_VARDIR. Navigate to the

bin directory for Version A and run ora_setup according to the instructions in the
SharePlex Installation and Demonstration Guide. When prompted by the ora_setup
script, do the following:
Enter the SID for the database associated with Version A.
Enter the password for the SYSTEM account.
Enter the SharePlex user for this instance of SharePlex, for example, splexA.
Enter the tablespace for SharePlex, the temporary tablespace, and the index
tablespace.
5 Export the Version B variable-data directory for SP_SYS_VARDIR. Navigate to the

bin directory for Version B and run ora_setup according to the instructions in the
SharePlex Installation and Demonstration Guide. When prompted by the ora_setup
script, do the following:
Enter the SID for the database associated with Version B.
Enter the password for the SYSTEM account.
Enter the SharePlex user for this instance of SharePlex, for example, splexB.
Enter the tablespace for SharePlex, the temporary tablespace, and the index
tablespace.
6 If you have not done so already, assign the users who will be operating and viewing
SharePlex according to the instructions in the SharePlex Installation and Demon-
stration Guide.
Setting ports for concurrent versions of SharePlex

Each version of SharePlex that you are running must be assigned a port number. This
number is stored with other SharePlex parameters in the paramdb in the variable-data
directory.
1 Export the following SharePlex system environment variables for the Version A
installation.
ksh shell:
export SP_COP_TPORT=port number for Version A
export SP_COP_UPORT=same port number as SP_COP_TPORT
export SP_SYS_VARDIR=full path name of Version A variable-data directory
csh shell:
setenv SP_COP_TPORT port number for Version A
setenv SP_COP_UPORT same port number as SP_COP_TPORT
setenv SP_SYS_VARDIR full path name of Version A variable-data directory
2 Start sp_cop for Version A from the bin sub-directory of the product directory you
created for Version A. Use the -uname option to differentiate this sp_cop from the
one you will start for Version B of SharePlex.
$ /splex/VerA/prod_dirA/bin/sp_cop -uVerA &
Tip: For the name variable, use something unique to this instance of sp_cop, such as
the version number (-uVerA) or port number (-u2100).
3 Run sp_ctrl for Version A.

$ /splex/VerA/prod_dirA/bin/sp_ctrl
4 Issue the set param command for the following SharePlex parameters.
sp_ctrl(sysA)> set param SP_COP_TPORT port number for Version A
sp_ctrl(sysA)> set param SP_COP_UPORT port number for Version A
5 Shut down and then restart sp_cop for the parameter changes to take effect.
6 Repeat steps 1 through 5 for Version B, using different variables.
Running concurrent versions of SharePlex

When you installed SharePlex, it created a defaults.yaml file in the /proddir/data/
directory. Normally, when sp_cop starts, SharePlex references this file to obtain envi-
ronment information, including the location of the variable-data directory. When you
CHAPTER 3 73
run multiple versions of SharePlex, the marker file cannot be used, because it contains
information only about one version of SharePlex the last version installed. Instead,
the SP_SYS_VARDIR environment variable must be exported for each sp_cop
instance.
1 Export the SP_SYS_VARDIR environment variable for Version A.
ksh shell:
export SP_SYS_VARDIR=full path name of Version A variable-data directory
csh shell:
setenv SP_SYS_VARDIR full path name of Version A variable-data directory
2 Start sp_cop for Version A from the bin sub-directory of the product directory you
created for Version A. Use the -uname option to differentiate this sp_cop from the
one you will start for Version B. This enables you to differentiate between them
when you issue the ps -ef | grep sp_ command or you need to kill a process.
3 Repeat steps 1 and 2 for Version B.
Important information about running two versions of SharePlex!

Do not issue Version A commands for the Version B instance of SharePlex. Likewise,
do not issue Version B commands for the Version A instance of SharePlex. Each
instance must be started and controlled separately.
Maintain and upgrade each installation of SharePlex separately.
Running different SharePlex versions on a Windows system

To run concurrent versions of SharePlex on a Windows system, install the two different
versions in different folders (directories) and on different port numbers, as though you
were installing two different software programs. This creates two separate SharePlex
services and two separate Registry entries. You can run these services independently at
the same time, if desired.
The Task Manager in the SpClient utility can help you differentiate among the Share-
Plex processes when you are running replication on multiple ports. For more informa-
tion about this utility, see Using the SpClient remote-access utility on page 454. For
more information about identifying SharePlex processes on the Windows platform, see
Process differences between UNIX and Windows systems on page 46.
4
Planning SharePlex Replication
Although SharePlex for Oracle replication requires little user intervention, its imple-
mentation requires careful planning and preparation. Subsequent chapters guide you
through this process. Read them in sequence to establish replication properly, beginning
with this chapter.
This chapter is divided into parts to make the information easier to find and understand.
The first two parts provide an introduction to the operations and replication strategies
supported by SharePlex, and the last part addresses important pre-implementation sys-
tem and data issues.
The chapters after this one help you establish and begin replication.
Contents
What you can replicate with SharePlex

SharePlex Best Practices
SharePlex replication strategies
Replication to maintain a reporting instance
Replication for high availability and data recovery
Replication to distribute data
Replication for distributed processing and load balancing
Replication using an intermediary system
Replication for centralized reporting
Peer-to-peer replication
Before you begin replication
Configuring the system for replication
Part 1: What you can replicate with SharePlex
This section will help you decide which objects to include in your replication configura-
tion and which objects to exclude.
What SharePlex replicates

In general, SharePlex replicates changes to objects listed in the configuration file. The
changes can be made with any Oracle application.
The most current list the Oracle components that SharePlex replicates can be found in
the Supported and Non-supported Operations section of Release Notes. Unless a com-
ponent is listed in the Release Notes for the version of SharePlex that you are running,
assume that SharePlex does not replicate it.
Important! Component support is added as SharePlex is upgraded and patched. See

the latest Release Notes for your version of SharePlex for supported and non-supported
components that supersede the following lists. You also can contact your Quest repre-
sentative or visit the Quest Support website a http://support.quest.com.
What SharePlex does not replicate

The most current list the Oracle components that SharePlex does not replicate can be
found in the Supported and Non-supported Operations section of Release Notes. Unless
a component is listed in the Release Notes for the version of SharePlex that you are run-
ning,, assume that SharePlex does not replicate it. Because both Oracle and SharePlex
continually change and improve, this list of exclusions cannot be considered complete.
Important! Component support is added as SharePlex is upgraded and patched. See

the latest Release Notes for your version of SharePlex for supported and non-supported
components that supersede the following lists. You also can contact your Quest repre-
sentative or visit the Quest Support website at http://support.quest.com.
CHAPTER 4 77
SharePlex Best Practices

The following recommendations are for your consideration while you are replicating
data.
Replicating LOBs, VARRAYs, and XML
If you are replicating LOBs and the Post process receives an ORA-00060 error, look
at the trace log from Oracle. If you see the following,
Deadlock graph:
---------Blocker(s)-------- ---------Waiter(s)---------
Resource Name process session holds waits process session holds waits
TX-0008002e-00002d1e 18 18 X 18 18 S
session 18: DID 0001-0012-00000002session 18: DID 0001-0012-00000002
Rows waited on:
Session 18: no row
Information on the OTHER waiting sessions:
End of information on OTHER waiting sessions.
then you have encountered an Oracle issue. The known workaround is to issue an
ALTER TABLE command with any option on this table and restart the Post process.
The TAR number is 3661187.994.
To avoid an out-of-sync condition on range-partitioned tables with LOB columns,
create a unique index on both the source and target tables, which includes the range
column in the index key columns.
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.
Changing supplemental logging
Do not turn off supplemental logging while you are in the process of replication.
Doing so can cause errors and possibly table corruption.
Performance considerations
When bitmap indices are used on the target system, the Post performance is
adversely affected. For performance purposes, it is recommended that bitmap indices
not to be used while the Post process is applying the data.
While we support LinuxThreads and Native POSIX Threading Library (NPTL) on
Linux, we recommend using NPTL for SharePlex. LinuxThreads can be enabled per
process using the LD_ASSUME_KERNEL environment variable, but setting this
has a performance impact and shows individual threads as processes within the pro-
cess list. NPTL is faster and behaves more like other UNIX OS's. If
LD_ASSUME_KERNEL is employed we suggest a setting of 2.4.21.
Replicating partitioned and sub-partitioned tables
To avoid an out-of-sync condition on range-partitioned tables with LOB columns,
create a unique index on both the source and target tables that includes the range col-
umn in the index key column.
Replicating DDLs
Using ALTER TABLE when replicating from an intermediary system to target sys-
tems in a cascading configuration is not recommended.
Using the ALTER TABLE operation to add a column with a primary key or unique
constraint is not recommended, unless you reactivate the configuration.
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 does not support ALTER TABLE commands that change the size of fixed-
length columns such as from char (2) to char (5) when there is data in the col-
umn. In such circumstances, Oracle first issues an UPDATE on each row that adds
spaces to the column to make sure there is sufficient space to complete the ALTER
TABLE command for example, UPDATE tableA set value (col1 = 'ro ') where
col1 = 'ro' ...; SharePlex replicates the UPDATE. Next, Oracle issues the ALTER
TABLE command to change the column size, and SharePlex replicates it. When Post
receives the UPDATE message, it has not yet received the ALTER TABLE message.
Therefore, the target column is not sized correctly to accommodate the added spaces
from the UPDATE. This causes Post to stop posting and print an error to the Event
Log (ORA-01401: inserted value too large for column).
When performing an ALTER TABLE to set a default value for a column when the
table has data in it, SharePlex sends one message for each record in the table to the
target machine. For a very large table, this can cause replication to fall significantly
behind Oracle as a result of the large number of UPDATEs that Oracle places into
the redo logs as part of the DDL transaction.
Replicating direct-path loads
Use direct-path loads (SQL*Loader) when there is only one load per table (PARAL-
LEL=FALSE). Simultaneous loads on different tables are supported if the database
is in archive mode.
Replicating NCHAR and NVARCHAR2 datatypes
Replication of NCHAR and NVARCHAR2 datatypes with the AL16TUF16 charac-
ter set for Linux and Windows.
CHAPTER 4 79
Replication with data updates greater than 2000 bytes to an NCHAR column must
take into account multi-byte character sets. For example, a table with NCHAR(2000)
and a two byte characterset requires 4000 bytes and exceeds the 2000 byte column
limit.
Replicating character sets
SharePlex supports replication between Oracle compatible charactersets.
Other considerations
When updating the columns in the column conditions which may cause data to
switch from one horizontal partition to another you need to set
SP_ORD_HP_IN_SYNC to 1 and SP_ORD_FIRST_FIND to 0. Information for
these individual parameters is located in the SharePlex for Oracle Reference Guide.
If constraints are DEFERRED on the target tables and the transaction goes out-of-
sync, the Post process can fail on the constraint validation. To work around this prob-
lem, enable the SP_OPO_DISABLE_OBJNUM parameter, thus allowing the trans-
action to process without the Post process failing. Note that the underlying target
table still remains out-of-sync until it is resynchronized.
SharePlex replicates all of the storage parameters for a source 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 source tables parameters
or, if the DDL is not supported by Oracle, an Oracle error will be generated.
For example, consider a source table with MAXEXTENTS 525 and MINEXTENTS
20, and a target table with MAXEXTENTS 505 and MINEXTENTS 4. If the MAX-
EXTENTS 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.
During the installation process the user must specify the ORACLE_HOME. Share-
Plex uses the ORACLE_HOME to locate the Oracle shared libraries. SharePlex must
link to the binaries and libraries of the lower minor/patch release version of Oracle if
more than one Oracle minor/patch release version is installed on the same server.
Part 2: SharePlex replication strategies
Before you create configurations and begin replication, determine how you will be
using SharePlex for Oracle. SharePlex offers great flexibility for reporting, high avail-
ability, data distribution, and disaster recovery. It enables you to replicate an entire data-
base of data for the purpose of high availability, or you can replicate subsets of a
database selected tables or selected columns and rows, for example which typi-
cally is all you need for reporting or data distribution.
This section highlights the following SharePlex replication strategies to help you deter-
mine which one (or combination) is right for your business environment. Then, see
Chapter 5 for details on how to establish your environment for your chosen strategy.
SharePlex replication strategies at a glance

CHAPTER 4 81
scott.emp bill.emp
From one system to another

The most common replication strategy is uni-directional replication to replicate from a
source machine to a target machine to offload report and query processing. This enables
you to maintain an up-to-date, accessible secondary instance that does not interfere with
your on-line transaction processing. The secondary instance can be optimized to meet
its users own set of needs, leaving the production database optimized for online pro-
cessing.
In a reporting environment, the owners and names of corresponding source and target
tables need not match. A reporting instance can contain all of the tables in the produc-
tion database or just a subset of the production tables. You can replicate all of the
changes to a table or just the changes made to selected columns or rows, disseminating
only the data required for reporting.
For multiple reporting sites, you have the additional option to route changes made to a
record exclusively to the locations which use that record. This eliminates the necessity
for all locations to maintain data that is either irrelevant or inappropriate for all users.
On the same system (UNIX only)

On UNIX systems, you can replicate data to alternate locations
on the same system by specifying the local system as the desti- jim.emp
nation system in the configuration file. With this strategy, there
are no Export and Import processes, because the network is not
being used. The Read process puts data directly into a post jim.salary
queue on that system.
Within one Oracle instance, you can replicate to different tables within the same schema
or the same table in different schemas. Or, you can replicate to a different instance on
the system that users can access for reports without using the I/O resources of the pri-
mary instance. Source and target owners and table names need not match for reporting.
On the Windows platform, SharePlex does not support replication between databases
that reside on the same system. The databases must be on separate systems with differ-
ent Oracle versions.
CHAPTER 4 83
scott.emp scott.emp
You can configure SharePlex to replicate over LAN and WAN connections to keep a
second Oracle instance constantly updated and ready to take over for the production
instance when the source system is scheduled for maintenance or a disaster strikes. Peri-
odic physical refreshes are used to update changes to the database structure, while
SharePlex replicates the changes to the data.
In this strategy, the alternate instance is a mirror image of the production environment,
which means that all objects exist in their entirety on both systems. To optimize the
effectiveness of this strategy, all of the secondary objects must have the same owners
and names as their source objects on the primary system.
A high-availability strategy uses bi-directional replication. SharePlex replicates to the
secondary system during normal operations, but when the primary system is offline and
users are transferred to the secondary system, SharePlex captures their changes and
queues the data on the secondary system. When the primary system is restored, Share-
Plex updates it with those changes.
You might be able to use a high-availability instance for reporting if the source and tar-
get instances are identical. This is not possible with some ERP applications, because
there can be conflict between the H/A tables and the reporting tables.
scott.prod
scott.cust
scott.prod scott.prod
scott.cust scott.cust
scott.prod
scott.cust
SharePlex can help you overcome accessibility problems when many remote users need
to use a central database. Rather than the remote users logging onto the production sys-
tem to perform queries, which burdens the system and slows online processing, they
have access to a constantly updated duplicate database against which they can run their
queries locally. They gain access faster, and the users of the main database can perform
their work more efficiently.
In this strategy, source and target objects can have the same owners and names or differ-
ent ones. The illustration above shows data distribution using broadcast replication.
CHAPTER 4 85
scott.emp
scott.prod
scott.cust
jane.emp
jane.prod
joe.cust jane.cust
mary.emp
Because SharePlex can simultaneously replicate to numerous target systems, you can
use it to optimize productivity by offloading non-critical processing to up-to-date sec-
ondary systems. This strategy, which uses broadcast replication, can be used to send the
same data to each system, such as when you want to send data to several remote loca-
tions for reports or further processing. Or, you can send different data to each system,
the goal being to balance the data load by splitting the replication to several machines.
SharePlex provides different levels of control over how much data is distributed,
enabling you to replicate all of the changes to a table or just the changes to specific col-
umns. In addition, you can control which rows are replicated to which targets, so that
each one reflects only the data that its users need, but none that is irrelevant or inappro-
priate.
In these scenarios, source and target objects can have the same owners and names or dif-
ferent ones.
hq.price reg.price loc.price
loc.price
Multi-tiered, or cascading, replication minimizes the network costs and other logistical
issues associated with replicating data to numerous target systems. It is useful when:
one or more target systems have no direct connection to the source system.
you want to limit network activity or expense affecting the source system.
Instead of broadcasting directly to multiple target systems, replicated data is routed

through an intermediary system (or pass-through system) to one or more target systems.
Replicated data can be posted to a database on the intermediary system, or it can be
transferred directly to the target systems. An example of this strategy is replication from
New York (the source system) to London (intermediary system), and then from London
to offices in Paris and Rome (target systems).
Cascading replication supports different types of replication. For example, you can
combine data distribution (see page 84 and page 85) with high availability (see
page 83), using some target systems for reporting and others for high availability. DDL
replication is not supported from an intermediary system to target systems. It is sup-
ported only from the source system to the intermediary system.
CHAPTER 4 87
sales.dat mfg.dat
sales.dat
cust.dat
mfg.dat
emp.dat
cust.dat emp.dat
SharePlex can be configured to replicate different data from different systems to a single
system to provide a centralized reporting base. This strategy, known as consolidated
replication, is ideal for data warehousing or data mart environments.
In a consolidated replication configuration, corresponding source and target objects can
have the same owners and names or different ones.You can replicate any or all tables
from a source system to the central target system. When needed, you can confine repli-
cation to selected columns and/or rows of a table to control the information that is avail-
able in the central data site. Transformation options provide additional versatility by
enabling you to manipulate replicated data to conform to the structure and design of the
central database and its applications.
With these options, you can blend data from different sources, such as human resources
and operations, into central tables that are designed for reporting. SharePlex keeps the
central instance up to date and accessible enterprise-wide for reports and queries.
sales.dat
cust.dat
mfg.dat
emp.dat
sales.dat sales.dat
cust.dat cust.dat
mfg.dat mfg.dat
emp.dat emp.dat
Peer-to-peer replication allows users on multiple databases to make changes concur-

rently to the same data in other active databases, all databases acting as peers. SharePlex
configurations on each system replicate local changes to all other systems, keeping all
of the databases synchronized.
Peer-to-peer replication with SharePlex can be used to maintain the availability of a
mission-critical database should any of the database sites become unavailable due to
database, system or network failures. A peer-to-peer replication strategy also is useful
for online transaction processing applications (OLTP) that require multiple points of
access to database information for the purpose of distributing a heavy application load,
ensuring continuous availability, or providing more localized data access. In all of these
circumstances, the databases are usually mirror images of each other, with all objects
existing in their entirety on all systems.
An example of peer-to-peer replication is an e-commerce company with three different
databases that replicate among themselves. When users access the application using 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 the
next 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 in the
replication scheme. Should the company need to produce business reports, user access
to one of the databases can be stopped temporarily, either by disabling the database
CHAPTER 4 89
name in the listener or by reconfiguring the web server. That database then can be used
to run the reports. When the reports are done, user access can be re-established.
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 appli-
cations are in use. In addition, conflict resolution routines are required to prioritize
which transactions SharePlex will accept for posting to the target database when more
than one user changes the same data at or near the same time.
Part 3: Before you begin replication
SharePlex works best when your system, instance and data are optimized and properly
prepared. This section helps you review the issues that affect replication. Once replica-
tion is underway, you might want to make additional adjustments to the database and
environment by reviewing the suggestions in this manual and in the troubleshooting
chapter of the SharePlex Reference Manual.
Understanding synchronization
It is important to configure your databases and systems to ensure that source and target
data remain synchronized. Resolving out-of-sync conditions can be time-consuming
and disruptive to user activity. To establish and maintain a synchronized replication
environment, you need a basic understanding of how SharePlex replicates and how it
determines an out-of-sync condition.
The basic characteristics of synchronized source and target objects are as follows
(unless the transformation feature is used, as described on page 245).
Corresponding columns have the same attributes and datatypes.
Data values in corresponding rows are identical.
If a row exists in the source database, it exists in the target database, unless selective
row replication is being used (see Replication options on page 96).
Before SharePlex posts replicated data to the target system, it verifies that the data is
being applied to a synchronized environment. Ensuring data integrity is the responsibil-
ity of the Post process. If the following events occur during the Post process, SharePlex
returns out-of-sync errors:
An out-of-sync condition occurs when an INSERT is performed on the source
system, but the row already exists in the target database when SharePlex
attempts to post it.
When SharePlex constructs its INSERT statement to add a replicated row to the tar-
get database, it uses all of the columns in the row. If SharePlex attempts to insert a
row that already exists in the target table, it causes an Oracle unique-key violation
error. The INSERT fails, and SharePlex returns an out-of-sync error.
CHAPTER 4 91
An out-of-sync condition occurs when an UPDATE is performed on the source

system, but the image of the row on the source system before the change was
made does not match that of the target row.
When SharePlex constructs its UPDATE statement to be applied to the target data-
base, it uses the SharePlex key to locate the row. The SharePlex key can be a
--primary key - One or more fields (columns) whose value or values uniquely iden-
tify each row in a table. A primary key cannot allow NULL values.
--unique key - Is used to uniquely identify each row in an Oracle table. There can be
one and only one row with each unique key value.
--user-defined key
As an additional measure to verify synchronization, SharePlex constructs a WHERE
clause consisting of the pre-image (or before values) of the updated columns the
values before the UPDATE. If the pre-images and the keys match in the source and
target rows, SharePlex posts the operation. If the pre-images do not match, or if
SharePlex cannot locate the row using the key, the SQL statement fails and Share-
Plex returns an out-of-sync error.
Example of SharePlex UPDATE statement on the target:
SQL> UPDATE scott.employee_source
SET Salary = 32000
WHERE EmpNo = 3
AND Salary = 30000; (this is the amount before the salary
value was updated to 32000.)
An out-of-sync condition occurs when a DELETE is performed on the source
system, but SharePlex cannot locate the row to be deleted on the target system.
When SharePlex constructs its DELETE statement to remove a row from the target
database, it uses only the key value in the WHERE clause. If the key is unavailable
on the target system, either because the row already was deleted or the key column(s)
changed, SharePlex cannot locate the row. The DELETE statement fails on the target
database, and SharePlex returns an out-of-sync error.
When SharePlex returns an out-of-sync error, then at that moment, that row is deter-
mined by SharePlex to be out of synchronization. This is not an indication of how many
other rows in this or other tables are out of synchronization in the target database. Share-
Plex does not check row-by-row for out-of-sync conditions, because that would slow
posting to unacceptable levels. SharePlex only compares rows being changed by its
SQL statements, and that design makes it important for all of the requirements in this
chapter to be satisfied.
Tip: After you begin replication, you can use the compare command to compare source
and target tables to verify synchronization. For more information, see Chapter 1 of the
SharePlex Reference Guide.
Configuring system resources for replication

During your planning process, consider the demand that will be put on your system
resources during the replication process.
Configuring UNIX resources for SharePlex

SharePlex uses interprocess communication tools provided by most UNIX-based oper-
ating systems to maximize cohesion of the SharePlex services while allowing the ser-
vices to perform their functions independently. SharePlex uses the "SystemV" style
semaphore and shared memory tools, which are available on most systems. SharePlex
does not use BSD or POSIX-style shared memory or semaphores. SharePlex uses its
own queue module; therefore, it does not use System V message queues, POSIX mes-
sage tools, or named pipes.
Before beginning SharePlex replication, you must calculate the kernel resources your
SharePlex implementation requires and change those resource parameters. To configure
your UNIX system to support SharePlex software, you must
1 Calculate your system resources.
2 Edit the kernel's configuration to change those resources.
3 Rebuild the kernel, if necessary.
4 Restart the system.
Note: Whenever you change any system parameters in the kernel configuration file, you
might need to modify the kernel and restart your system to ensure those modifications
take effect.
Shared memory segment resources

Shared memory segments are used by the queue and statistic modules to allow all pro-
cesses to see data written by other processes.
CHAPTER 4 93
The queue module uses shared memory for all of its transfers from and to user applica-
tions and from and to disk data files. The data is written to disk at checkpoint. When
data is read from the disk, it is transferred to shared memory before it is processed.
Number of shared memory segments

At startup, SharePlex creates a minimum of two shared memory segments - the queue
global area and the SHS segment. One additional shared memory segment is created for
each queue. The creation of the per-queue shared memory segment happens dynami-
cally when SharePlex is restarted or when activating a configuration.
You need to specify the maximum number of shared memory identifiers available to
support your system configuration. Shared memory identifiers are set using the system
configuration parameter SHMMNI. The minimum setting recommended for SHMMNI
is 100.
Size of shared memory segments

The system configuration parameter SHMMAX is the maximum size permitted for a
shared-memory segment. The value for SHMMAX must be large enough for the largest
SharePlex shared-memory segment, which, in most cases, is the queue information seg-
ment. Queue performance is related to the shared memory size that is allocated to two
queue parameters, SP_QUE_POST_SHMMAX and SP_QUE_Q_SHMMAX. The sys-
tem configuration parameter SHMMAX must be greater than the larger of these two
queue parameters. The minimum setting recommended for SHMMAX is 60 MB.
Location of shared memory segments

SharePlex maps shared memory by using the system default mapping. This means the
system selects the address at which the shared memory will be mapped. Programs that
dynamically expand their private data space can encounter problems if the default map-
ping location is not set sufficiently high.
Use the system configuration parameter SHMBRK to set the distance between private
and shared data space. For most systems, setting the parameter to 4 MB is adequate.
Note that on systems where SHMBRK is expressed in pages, you can divide the number
of bytes by the page size to get the parameter value.
Table of Shared Memory Parameters
Parameter Name Definition
SHMMNI Number of shared memory identifiers
SHMMAX The maximum size of shared-memory segments
SHMBRK Sets the distance between private and shared data space
Shared Semaphore Segment Resources

SharePlex requires two shared semaphore segments at startup. Refer to the Installation
and Demonstration Guide for the recommended settings for your system.
Number of shared semaphore segments

The configuration parameter SEMMNI is the number of semaphore set identifiers in the
system. The value of SEMMNI equals the number of semaphores required for your sys-
tem plus double the number of SharePlex instances.
Number of semaphores per SharePlex instance

The configuration parameter SEMMNS is the number of individual semaphores in the
system. The number of semaphores required for a SharePlex instance is the number of
semaphores required by the SHS module plus three (3) semaphores for general use. By
default the number of queues is set to 25, which implies that you will have 28 sema-
phores per SharePlex instance.
Number of semaphores per process

The configuration parameter SEMMSL is the maximum number of System V sema-
phores that can be in one (1) semaphore set. The recommended setting for SharePlex is
128.
Number of UNDOs per SharePlex instance

The configuration parameter SEMMNU is the maximum number of processes that can
have UNDO operations pending on any given IPC semaphore on the system. The
UNDO is used by SharePlex to prevent a semaphore deadlock if a process that is wait-
CHAPTER 4 95
ing for the semaphore exists due to a signal or other reason. SharePlex uses one UNDO
in every semaphore operation. The default setting for SEMMNU is 64.
Number of UNDOs per process

The configuration parameter SEMUME is the maximum number of IPC semaphores
that a given process can have UNDO operations pending on at any given time. The
default setting is 64.
Table of Shared Semaphore Parameters
Parameter Name Definition
The number of semaphore set identifiers required in the sys-

SEMMNI
tem
SEMMNS The number of individual semaphores in the system
The maximum number of processes that can have UNDO

SEMMNU operations pending on any given IPC semaphore on the sys-
tem.
The maximum number of System V semaphores that can be

SEMMSL
in one semaphore set
The number of IPC sempahores that a given process can

SEMUME
have UNDO operations pending on at any given time
Configuring the database for replication
Oracle supplemental logging

With Oracle 9i, the database can be instructed to write data that aids replication to the
redo logs. Commands can be issued at the database level that result in the logging of
rowid information, as well as key column information in the redo log.
SharePlex requires that minimal supplemental logging be set. This ensures that the
rowid information is logged in the redo log, eliminating the need for SharePlex to main-
tain this information.
SharePlex recommends that both primary key and unique key supplemental logging be
set, or that a supplemental log group be defined for every table in replication. SharePlex
can take advantage of the key information logged in the redo log when posting the mod-
ifications on the target. If the key column values for a row update are not in the redo log,
SharePlex has to retrieve this information from the database. On a busy system and
when data has accumulated, this can add additional processing that adversely impacts
the performance of the read process.
When primary and unique key supplemental logging is enabled, and a table does not
have a primary key, Oracle has to decide what key to log. If the table has multiple
unique keys, Oracle will determine the key that is best and log the values of those col-
umns for every update. If the table does not have a key Oracle will log all columns that
are not a LONG or a LOB.
SharePlex also has to identify a key to use to replicate data. Like Oracle, SharePlex will
use the primary key if there is one, determine the best (or only) unique key if there is
one, otherwise SharePlex will use all the key columns for the key. If a table being rep-
licated by SharePlex does not have a primary key, but has multiple unique keys, then it
is possible that the key columns that Oracle logs are not those that SharePlex requires.
Note: If you have questions concerning SharePlex keys vs. Oracle keys logged, please
contact Quest using SupportLink at: http://support.quest.com.
Replication options
When planning your replication strategy, take into consideration how much source data
you want to be replicated. SharePlex offers several options.
SharePlex can replicate all of the columns and rows of a table. This is known as full-
table replication. Or, SharePlex can replicate selected rows, selected columns, or both
from one table to another, even when the target schema is not identical to the source
schema. This is called partitioned replication, also known as selective replication.
You can use vertically partitioned replication (also known as selective column repli-
cation) to distribute selected information, such as employee names and locations,
while protecting other data, such as sensitive personal information or salaries, with-
out separating the data sets into different objects.
You can use horizontally partitioned replication (also known as selective row repli-
cation) to distribute different segments of data to different target systems, such as
sending sales and customer data to the individual stores responsible for it.
CHAPTER 4 97
Partitioned replication is not appropriate for high-availability environments where you

need full replicas for failover. For reporting, load balancing, data marts or other environ-
ments where replicas of the production data are not necessary, partitioned replication
could be appropriate for some or all tables, and it can provide more control over infor-
mation dissemination and network load. For example, if there are public and private
components of a table, you could replicate the public elements beyond a firewall so that
sensitive information remains protected by the firewall, rather than just by a limited
view.
For more information about configuring SharePlex for partitioned replication, see
SharePlex configuration construction on page 132.
Table structure
SharePlex supports replication between identical and non-identical target schemas,
depending on how replication is configured.
Replicating entire tables

When you are using full-table replication (replicating all of the data in a source table),
the following rules apply to the target table.
The names of the target columns must be identical to the names of the source col-
umns. You can avoid this limitation by using vertically partitioned replication (see
Using vertically partitioned replication following this topic).
The number of target columns must be identical to the number of source columns in
order to be able to use SharePlex data synchronization procedures.
-or-
A target table can have more columns than the source table, but SharePlex will
ignore the extra columns in the target table. An INSERT will insert values into target
columns for which there are corresponding columns in the source table, but it will
not insert values for the extra columns. If the extra columns have NOT NULL con-
straints but do not have default values, there will be Oracle errors. Default values are
recommended for extra columns in target tables. An UPDATE will update the values
in the target columns for which there are corresponding columns in the source table,
but the values in the extra columns will remain unaffected. A DELETE is not
affected by extra columns in the target table because SharePlex selects rows based on
the key or on column data in the matching columns.
When a target table has more columns than the source table, you can use the com-
pare command to verify synchronization and repair out-of-sync rows, or you can
develop your own set of synchronization procedures. For more information about the
compare command, see the SharePlex Reference Manual.
A target table cannot have fewer columns than the number of columns in the source
table.
Corresponding source and target columns must contain the same datatypes (same
type, size, precision).
Corresponding source and target rows must contain the same values.
Using vertically partitioned replication

When using vertically partitioned replication, the following rules apply to a target table.
The target table can contain all of the same columns as the source table, or just the
columns being replicated from the source table. For example, the source table might
have 20 columns, but if you are only replicating data from eight of them, then only
those eight columns need to exist in the target table.
The names of corresponding columns need not be identical. You can specify column
names when you create the configuration file.
Corresponding columns must contain the same datatypes (same type, size, preci-
sion).
Corresponding rows must have the same values.
Table names
For most replication strategies, the name and/or owner of a source object can be differ-
ent from those of its target object. SharePlex replicates to the correct object because you
specify it by owner and table name within the configuration file. For high-availability
configurations, the owner and name of a source table and those of its target object must
be the same.
Tables that should not be replicated

Some applications use temporary tables. Because they are not critical database compo-
nents, such tables should be excluded from the replication configuration. Work tables
and any tables that are instance-specific also should be excluded.
CHAPTER 4 99
Target table access

In all scenarios except peer-to-peer replication, the SharePlex Oracle user created dur-
ing ora_setup must be the only user allowed to perform DML or supported DDL on the
target objects. If DML or DDL changes are made to target objects by other individuals,
jobs or applications, the data will go out of synchronization. The following examples
illustrate detectable and undetectable out-of-sync conditions that can occur when target
objects are changed by a user other than SharePlex. The example assumes that source
and target tables (with columns COLOR, SIZE, WEIGHT) start out synchronized.
Detectable out-of-sync condition

A user directly updates the COLOR column in the target table from blue to red in
Row1. Now, someone makes the same change to the source table, and SharePlex repli-
cates it to the target. Post uses a WHERE clause to verify synchronization (see Under-
standing synchronization on page 90), so it expects the pre-image for the target table to
be blue, but it is notit is red. Post generates an out-of-sync error alerting you to
the out-of-sync condition.
Hidden out-of-sync condition

A user directly updates the COLOR column in the target table from blue to red in
Row2, but the change is not made to the source table, therefore not replicated. The two
tables now are out-of-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 rep-
licated, Post compares the pre-images, and only then is there an error message.
Tip: After you begin replication, you can use the compare command to compare source
and target tables to verify synchronization. For more information, see Chapter 1 of the
SharePlex Reference Guide.
Requirements for target table access

For reporting and other uni-direction replication: All tables on the target system
that are outside the replication configuration can be accessed (and changed, if appli-
cable) as usual without affecting replication. Any target table within the replication
configuration can be accessed for queries and reports while replication is underway,
but do not allow DML or DDL of any kind to be performed on them. DML or DDL
changes to the target objects must be performed according to the procedures in

Chapter 11.
For high availability: Some ERP applications do not permit using the target data-
base for queries or reporting, since there can be conflict between the H/A tables and
reporting tables. If the source and target databases are identical, reports and queries
might be permissible. When using SharePlex replication for high availability, you
can prepare the target system to grant INSERT, UPDATE and DELETE privileges,
but do not implement them except when that system is used as a failover machine.
For more information, see Establishing replication for high availability and data
recovery on page 190.
For peer-to-peer replication: Peer-to-peer replication, where DML is replicated
among peer production instances, requires two-way replication with the proper data-
base preparation and conflict resolution routines. For more information, see Estab-
lishing peer-to-peer replication on page 211.
SharePlex keys
Understanding the role of keys in the SQL statement constructed by SharePlex is critical
to helping you understand and maintain data synchronization. SharePlex uses the key in
its SQL statements to locate the correct row in the target table for UPDATEs and
DELETEs, and to ensure that a row being inserted is not already there. Row IDs cannot
be used to locate rows on the target system because row IDs are different on the source
and target systems, and the target row ID is not in the redo log.
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 choos-
ing a key to use, SharePlex uses the best available key column in the following order of
priority.
Primary key
Unique key with the fewest columns, where at least one of the columns is NOT
NULL
Unique key with the fewest columns. If a key permits NULLs, SharePlex cannot
ensure the rows uniqueness 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
Chapter 2 of the SharePlex Reference Guide for more information about this param-
eter.
If SharePlex cannot determine 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
CHAPTER 4 101
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 more information, see Long columns on
page 110.
User-defined key. You need to create a non-unique index on the target system and
add the index to the SharePlex hints file, which allows the Post process to use the
index upon posting data to that table.
Effects on the source system: If a table does not have a unique key and SharePlex has
to build its simulated all-column key for UPDATEs, this procedure can be very time-
consuming for tables with numerous columns.
Effects on the target system: Without the help of a primary or unique key on the target
table, Post (relying on its constructed all-column key) must compare the entire table row
by row. This causes transaction data to accumulate in the queues, increasing the latency
between source and target instances to unacceptable levels.
Recommendation: If adding a primary key is not possible (such as when packaged
applications are in use), you can create a user-defined key by creating a key definition.
To create a key definition, you use special syntax in the configuration file to list one or
more columns that ensure row uniqueness. SharePlex will use those columns as a
unique key in its WHERE clause to locate target rows for posting. This key overrides
any other key created for the table. See Components of a SharePlex configuration on
page 135 for more information about constructing a key definition.
An alternative to a key definition is to create or use a unique index based on one or more
columns that establish uniqueness. See Indices on page 102 for more information.
Keys in peer-to-peer replication: Primary keys are essential in peer-to-peer replica-
tion, and they must be unique among all of the databases that will be involved in repli-
cation. For more information about keys in peer-to-peer replication, see page 216.
Changing key values

If sequences are used for keys, and if there is a possibility that key values will be
updated, create the sequences so that the updates cannot result in duplication of keys on
the target system. Otherwise, if a new value already exists as a key in another row on the
target system, there can be conflict and SharePlex will return unique-key constraint vio-
lations and out-of-sync errors.
That 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. For example, assume that the values in the following sample key column are
increased by 1:
Key_Col
1
4
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 that update using the following individual steps, in the order that
the operations enter the redo log:
update x set a=2 where a=1; (This will be successful.)
update x set a=5 where a=4; (This will fail because 5 already exists.)
The Post process, which is responsible for ensuring data integrity, processes a pre-image
value for the target sequence that 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 will be running peer-to-peer replication, there are additional key
requirements. Consult the instructions for establishing peer-to-peer replication on
page 211 when you are done reviewing the rest of the requirements in this chapter.
Indices
When replicating a source table with a unique index, the target table also should have a
unique index. An index maintains the integrity of the target data and prevents users from
entering duplicate data. All large tables should have at least a unique index on the target
CHAPTER 4 103
system. If there is no unique index, Oracle scans the entire table in order to locate the
rows to be changed by Post.
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 valuessuch as a persons
name and employee identification number. If no unique index exists for a table, it is rec-
ommended that you create one or use a user-defined key, if possible.
Once you have identified or created a unique index, you can ensure that Oracle uses it
by employing the hints feature of SharePlex. See Using INDEX hints for faster post-
ing on page 238 for more information.
Other planning tips:
Keep your indices up-to-date, or it can slow the Post process. Rebuild the ones that
are fragmented.
Try to use just a few indices for applications that do mainly INSERT statements, to
limit their maintenance.
For UPDATE statements, try to an index on the column that doesnt change after an
INSERT statement.
For DELETE statements, remove as many indices as you can.
When you run large batch jobs that do millions of SQL operations on tables with
numerous indices, remove unnecessary indices before the batch job, then rebuild
them at the end. This makes SharePlex run faster, and you will have more organized
indices afterward.
If tables use referential integrity (foreign keys), make sure the appropriate columns
are indexed so that modifications to the foreign keys do not cause full table scans.
When using bitmap indices on target tables, weigh their benefit for queries against
the following impact on Posts SQL transactions. When Oracle adds, updates or
deletes a bitmap entry, it effectively locks all the rows associated with the bitmap
segment. 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 rows they are processing update bitmap
entries in the same bitmap segment. To proceed, Post must detect and resolve the
blocking, which delays posting significantly if the number of locks is high. In gen-
eral, frequent inserts by multiple concurrent sessions into a table with bitmap indices
will incur lock conflicts, but random update and delete activity on such a table will
not. Note: SharePlex follows the Oracle recommendation to have a bitmap index
on a more static table.
Note that replicating bitmap indices is not recommended because 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.
Tip: If there are too many indices on a target table, Oracle must update them all as rows
are added and deleted. This slows the entire system, including replication. Consider lim-
iting the number of indices to the ones that have the most utility.
Index-organized tables
If you will be replicating index-organized tables that are in locally-managed
tablespaces, make certain that the iot_setup.sh script was run after ora_setup. This
script creates the SYS.QSA_KTFBUE view exposing SYS.X$KTFBUE and grants
select privilege on this view to the SharePlex Oracle user. Verify that the view and priv-
ilege exist, and if they do not exist, run the script as an Oracle user with SYSDBA role.
Integrity constraints
The following topics address the effects that integrity constraints have on replication.
Referential integrity
Tables with referential integrity to one another must all be included in the configuration
file for accurate replication, and therefore all must exist in the target database. If you
leave one or more out, the referential integrity could become corrupted.
If you are using named export or post queues, all tables with referential integrity to one
another must be in the same queue. See Chapter 5 for more information about named
queues.
Foreign key constraints/cascading DELETEs

Special measures are required on the target system for applications using ON DELETE
CASCADE constraints. When these constraints fire during the original transaction,
SharePlex replicates both the primary (original) DELETE and the dependent (cascaded)
DELETE operations to the target system because they all enter the redo logs. SharePlex
expects to post replicated operations in the order that they are received. If the primary
DELETE activates foreign-key constraints on the target table that delete dependent
rows, those rows will not be there when SharePlex expects to perform the replicated
cascaded DELETEs. This causes SharePlex to return out-of-sync errors.
CHAPTER 4 105
Recommendation: Disable ON DELETE CASCADE constraints on the target system.

You can use the following script to disable them.
SELECT 'ALTER TABLE ' ||
owner ||
'.' ||
table_name ||
' DISABLE CONSTRAINT ' ||
constraint_name ||
';'
FROM dba_constraints
WHERE constraint_type = 'R'
And delete rule=CASCADE
AND owner NOT IN
('SYSTEM', 'SYS')
/
If cascading DELETE functionality must be available on the target system for peer-to-
peer replication or in preparation for failover, incorporate the required DELETE func-
tions into triggers, instead of using constraints. In this way, you can maintain referential
integrity.
After you convert the constraints to triggers, run the sp_add_trigger.sql script to direct
the triggers to ignore the SharePlex user. A trigger fires for a source transaction to delete
the dependent rows in the source database, but when SharePlex posts the replicated pri-
mary DELETE to the target database, the trigger does not fire. No dependent rows are
deleted until the replicated dependent DELETE operations arrive from the source.
For more information about sp_add_trigger.sql and the other SharePlex trigger scripts,
see page 426.
Check constraints
For improved performance, disable check constraints on the target system. Such checks
are redundant, because they are satisfied on the source system and will only increase
overhead on the target. For high-availability purposes, you can build a script that re-
enables the constraints as part of the failover procedure.
Triggers
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. Conse-
quently, 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 violationthe row already exists because the trigger fired for TableA.
Recommendation: Either disable triggers on target tables within the replication config-
uration, or use the sp_add_trigger.sql script to instruct them to ignore the SharePlex
user, depending on your replication strategy.
High availability and peer-to-peer replication: On all systems in a high-availabil-
ity or peer-to-peer replication configuration, triggers must be enabled for users other
than SharePlex, either in preparation for failover or because transactions are per-
formed on multiple source systems. To disable triggers for the SharePlex user, run
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.
For more information about this script, see page 426.
Reporting: For reporting and other non-data recovery purposes, you can either dis-
able triggers entirely on the target system or run the sp_add_trigger.sql script.
Triggers and patches: After applying an Oracle patch (which sometimes creates or
modifies triggers), re-run sp_add_trigger.sql on the target system if triggers are not
disabled.
Note: The SharePlex trigger scripts support row-level triggers only. Statement-level trig-
gers must be disabled/enabled for the SharePlex user separately.
Triggers that modify data in tables NOT being replicated: Triggers that modify data
in objects not in the replication scheme can fire on the target system, if needed.
Sequences
SharePlex replicates changes to sequences that are made during transactions and with
the ALTER SEQUENCE command. To replicate sequences, specify them in the config-
CHAPTER 4 107
uration by owner and name, as you would a table. SharePlex updates target sequences
with the ALTER SEQUENCE command in the following way:
1 Changes the increment value to {source_INCREMENT_BY_value} x
{source_CACHE_value} and sets no caching.
2 UPDATES the sequence(s).
3 ALTERS the sequence(s) again by setting the following values:
Increment value = source_INCREMENT_BY_value

Cache value = source_CACHE_value
When working with sequences, keep the following points in mind.

SharePlex treats ALTER SEQUENCE operations like a simple SELECT (UPDATE)
to a sequence because it cannot tell the difference between the two operations in the
redo log.
To ensure the uniqueness of sequences on the target system, the start value of the tar-
get sequence must be larger than the start value of the source sequence. Use the fol-
lowing 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.
If sequences are unnecessary on the target system, do not replicate them. It can slow
down replication. For example, 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.
If you replicate sequences, 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.
Sequences in high availability: Replicate sequences for high availability. The way that
SharePlex replicates sequences allows users to begin using the failover database imme-
diately without worrying about incrementing the sequences or reusing one.
Sequences in reporting: Sequences usually are not replicated for reporting instances.
Sequences in peer-to-peer replication: SharePlex does not support peer-to-peer repli-

cation of identical sequences. See Establishing peer-to-peer replication on page 211
for important instructions concerning sequences in peer-to-peer replication.
Object-relational structures
SharePlex supports abstract datatypes (also known as user-defined types, or UDTs) and
varying array collectors (VARRAYs), with the following exceptions:
Replication of nested tables.
Record abstract datatypes containing record abstract datatypes that include a VAR-
RAY column.
VARRAY column containing abstract datatypes, or UDTs.
Abstract datatypes for which the SQL statements use the system-defined name
instead of the user-defined name.
Operations to add a VARRAY column or abstract-datatype column if an ALTER
TABLE to drop a column or set a column unused is issued soon thereafter.
Replication of UDTs and VARRAYs is not supported when the source and target
schemas have different names. When the UDT or VARRAY belongs to different
schemas on the source and target, even though the source and target tables are in the
same named schemas, the Post process will fail with an error.
LOB datatypes
Considerations for LOB replication
Use a tuning tool such as Spotlight on Oracle from Quest to remove any I/O conten-
tion affecting the redo logs.
Use one or more named export queues for tables containing LOBs. This automati-
cally creates separate Export processes and named post queues with their own Post
processes. Separating the processing of LOB datatypes should improve the overall
speed of replication. For instructions on creating named export queues, see
Chapter 5.
If tables containing LOBs have referential integrity among one another, replicate
them all using the same named queue.
Replication of large LOBs has an effect on the SharePlex post queue. A SharePlex
post queue actually consists of multiple subqueue files, each with a size of 8 MB.
Subqueue files are added dynamically as needed. LOB activity can cause an unusu-
CHAPTER 4 109
ally high number of subqueue files, which require additional shared memory. 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 Share-
Plex generates shared memory segment errors such as Error: sp_cop process
sp_mport/sp_opst_mt killed due to SIGSEGV, increase the setting. For instructions on
setting SP_QUE_POST_SHMSIZE, see Chapter 4 of the SharePlex Reference
Guide.
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.
A table with LOBs cannot be configured for horizontally-partitioned replication.

Peer-to-peer replication does not support replication of LOBs. If you enable LOB
replication, they will be bypassed by conflict resolution, causing the potential for
data to be out of synchronization.
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 fre-
quently and must be analyzed frequently so that its indices remain efficient.
TIMESTAMP datatypes
The TIMESTAMP, TIMESTAMP WITH TIMEZONE, and TIMESTAMP WITH
LOCAL TIMEZONE datatypes are supported for Oracle versions 9i and higher. Note
the following:
For TIMESTAMP WITH TIME ZONE, the time zone is not changed by replication
from a source machine in one time zone to a target machine in a different time zone.
What this means is if, for example, the source machine is in the Pacific time zone
and the target machine was in the Eastern time zone, the timestamp of the replicated
data does not change from the timestamp of the source data.
For the TIMESTAMP WITH LOCAL TIMEZONE datatype, Oracle stores this data
relative to the DB_TIME_ZONE. SharePlex adjusts the timestamp according to any
difference in the DB_TIME_ZONE between the source and target machines. Users
selecting data with identical session time zones fetch identical data from both the
source and target.
Long columns
If tables do not have primary or unique keys, SharePlex must build a simulated key
internally by using all of the columns except the LONG column in its WHERE clause.
Uniqueness cannot be guaranteed if there is a possibility that non-LONG columns in
different rows could contain identical values, but the LONG columns could have differ-
ent values. If this occurs, the table can go 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)

10 20 100
10 20 200
10 20 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 con-
structs 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.
Recommendation: If possible, add keys, then resynchronize and reactivate those
objects so that SharePlex can update its object cache.
DDL Replication
By default SharePlex replicates TRUNCATE TABLE and ALTER TABLE DDL issued
against any table that is in replication. This functionality is controlled via that parame-
ter SP_OCT_REPLICATE_DDL. In addition, SharePlex will replicate any CREATE
INDEX DDL that creates an index on a table in replication. This functionality is con-
trolled via the SP_OCT_AUTOADD_ENABLE parameter.
SharePlex also supports the replication of all other DDL. This functionality is con-
trolled via the parameter SP_OCT_REPLICATE_ALL_DDL. If this parameter is set,
any DDL that any user issues against the source database is written to the database redo
logs. The Capture process picks up the DDL and replicates it to the target database.
Capture then reads in the DDL statement in the redo log and passes it to the Read pro-
CHAPTER 4 111
cess, which routes the DDL to the target machines, and the Post process applies the
DDL to the target database(s).
Setting the SP_OCT_REPLICATE_ALL_DDL requires identical source and target
databases in order for the replicated DDL to execute successfully on the target system.
Since this DDL is broadcast by the Read process to all target machines, all target sys-
tems must be identical. SharePlex replicates supported DDL for all schema objects and
accounts, so those components must exist in the target database for the operations to
succeed.
DDL will be replicated only if the DDL operations are performed on objects owned by a
user other than the SharePlex user, a SYS user, or a SYSTEM user, or a SYSMAN user.
Essentially, DDL against objects owned by the SharePlex user, a SYS user, or a SYS-
TEM user, or a SYSMAN user do not get replicated.
Renaming tables
You can use the ALTER TABLE RENAME command to rename a table. If the table is
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. If the target table
name is the same as the source table name, the new configuration line will reflect the
name change on both the source and target. Otherwise, the target name will not change.
For example, the source table, scott.table1, is replicating to scott.table1 on the target.
scott.table1 ====> scott.table1
If you rename the source table to scott.table2, the target table name will also change to
scott.table2.
scott.table2 ====> scott.table2
Capture will comment out the old entry in the configuration file by putting a pound sign
(#) in the first byte of the line, which might overwrite part of the name.
#scott.table1 scott.table1 sysA@o.ora555
Then a new entry is added to the end of the configuration file as follows:
# Table scott.table1 renamed to scott.table2 August 5, 2003 10:14
scott.table2 scott.table2 sysA@o.ora555
Renaming the source table can cause an error on the target if scott.table1 does not exist
on the target. Whether the Post process stops or not depends on the setting of the
SP_OPO_STOP_ON_DDL_ERR parameter. Refer to Chapter 2 in the SharePlex Refer-
ence Guide for more information about this parameter.
DDL Logging
SharePlex has separate DDL logs on the source and target machines. All of the DDL
that Capture retrieves from the redo log, and all of the DDL that Post processes is
logged.
The Capture process logs the SQL for all of the DDL found in the redo log, the date and
time that the DDL was processed by Capture, and the date and time that the DDL was
issued against the database. In addition, if Capture replicates the DDL, this information
is added to the log. The Capture log is designated as follows:
ORACLE_SID_ocap_ddl_[log file number].log
For example,
o.ora10_ocap_ddl_01.log
The Post process logs all the DDL that it applies to the target database, the date and time
that the DDL was processed by Post, and the date and time that the DDL was issued
against the source database. In addition, if the SQL fails, Post will log that it failed
along with the Oracle error. This second message describes the DDL only by the com-
mand and the object, and not the entire SQL. The Post log is designated as follows:
ORACLE_SID_[machine name]_opo_ddl_[log file number].log
For example,
0.ora10a_irvspxub_opo_ddl_01.log
Error handling for Oracle DDL replication

By default, the Post process stops if there is an error applying replicated DDL. 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, implying that subsequent DML
changes also will fail. Stopping Post prevents the DML failures and enables you to cor-
rect the problem to keep the databases synchronized. You can change this behavior with
the SP_OPO_STOP_ON_DDL_ERR parameter. For more information about this
parameter, see the SharePlex Reference Manual.
Note: SharePlex prints replicated DDL to the Event Log, but statements longer than
2000 characters will be truncated, and only the first 60 characters will be recorded in the
log. The complete DDL is printed in the DDL log for the Post process.
CHAPTER 4 113
Cascading replication and replication of DDL

DDL replication is supported only from the source system to the intermediary system;
not from an intermediary system to target systems.
For cascading replication, ALTER TABLE commands are replicated when
SP_OCT_REPLICATE_DDL is enabled. TRUNCATES do not get replicated. To stop
replication of DDL in cascading replication, disable the SP_OCT_REPLICATE_DDL
and SP_OCT_REPLICATE_ALL_DDL parameters.
Direct-path loads
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 (PARAL-
LEL=FALSE), although there can be simultaneous loads on different tables. The data-
base 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 the applica-
tion users changes entering the redo logs, thus causing latency between source and tar-
get systems.
If you elect not to replicate a direct-path load and instead repeat the load on the target
system, and if this requires enabling referential and check constraints on those tables
after the load, remember to disable the constraints again once they are satisfied.
The SP_OCT_REPLICATE_DLOAD parameter controls whether or not direct-path
loads are replicated. The default setting of 1 enables direct-path load replication. To dis-
able replication of direct-path loads, change this parameter to 0. For instructions on
changing SP_OCT_REPLICATE_DLOAD, see Chapter 4 of the SharePlex Reference
Guide.
Redo and archive logs

SharePlex captures data from the online redo logs that Oracle creates as backup for
recovery purposes. Oracle writes changes to the redo logs until they are full. Then the
logs wrap, which means that Oracle starts writing to the first log again, overwriting the
existing data. This design has an important impact on replication for which you should
be prepared. The following topics address the requirements for preparing the redo and
archive logs for SharePlex replication.
ASM support
ASM, Automatic Storage Management, is an Oracle feature introduced in Oracle 10g.
For a list of currently supported platforms please refer to the Supported and Non-sup-
ported Operations section of the latest Release Notes/Patch Notes.
Redo log and datafile locations

SharePlex supports replication when the Oracle redo logs and datafiles reside on raw
devices, on filesystem devices, or both.
Redo log size

If the Capture process stops (or is stopped by a user) while users are making changes to
objects being replicated, 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 the delay before Capture starts again is long, Capture loses pace with Oracles pro-
cessing, and it could be more practical to resynchronize the data instead of waiting for
SharePlex to restore parity by replicating from the archive logs. It depends on your envi-
ronment and tolerance for latency between source and target data.
Reading the logs involves processing data through the capture queue, so it is possible to
run out of disk space on the source system while Capture processes the operations that it
missed. There also is the potential for SharePlex to lose information needed to construct
SQL statements for posting on the target system. At this point, there is no alternative but
to resynchronize the data. Therefore, avoid stopping the Capture process for long peri-
ods.
Archive logs
The archive logs allow replication to continue when the online redo logs wrap before
Capture is finished reading them. The following guidelines help you configure archive
logging to ensure successful replication.
Archive logs on the source system
Enable archive logging on the source system. If the archive logs are not available, you
will need to resynchronize the data if the redo logs wrap and Capture is not finished pro-
cessing the data.
If you compress your archive logs, do not compress them until SharePlex is finished
processing them. Otherwise, SharePlex returns a Log wrap detected error and will not be
able to process the data. To determine the current log for SharePlex, issue the show
CHAPTER 4 115
capture command with the [detail] option in sp_ctrl on the source system. You can
compress any logs that were generated previous to the current one.
When using compressed archive logs, set the SP_OCT_ARCH_LOC parameter to the
full path name of the directory where the archive logs are located. When the redo logs
wrap, SharePlex looks for the archive logs in Oracles archive log list. If SharePlex can-
not find the archive log there, it looks in the directory or directories specified by the
SP_OCT_ARCH_LOC parameter. For more information about this parameter, see the
Archive logs on the target system
Disable archive logging on the target system to eliminate unnecessary Oracle activity on
that system. If you must retain archive logging on the target system, such as for high
availability or peer-to-peer replication, maintain enough space in the archive log direc-
tory for Oracle to continue creating archive logs. If Oracle cannot create the logs, Post
will be unable to post changes until the problem is resolved.
Archive volume
For optimum performance when transaction volume is either very high or very low, cer-
tain parameter changes are recommended before replication commences. To determine
the correct values, refer to one of the following tables that corresponds to your source
databases daily archive log volume. Change the parameters using the set param com-
mand in sp_ctrl. If you have any questions or concerns about changing these parame-
ters, contact Quest Technical Support.
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.
Daily log volume less than 5 GB per day

RECOMMENDED WHERE TO MAKE THE
PARAMETER NAME
SETTING CHANGE
SP_OCT_CHECKPOINT_FREQ 500 source system
SP_ORD_CDA_LIMIT 5 source system
SP_ORD_DELAY_RECORDS 50 source system
SP_ORD_LDA_ARRAY_SIZE 5 source system
SP_ORD_RMSG_LIMIT 20 source system
SP_IMP_WCMT_MSGCNT 100 target system
SP_COP_IDLETIME 120 source and target systems
Daily log volume greater than 15 GB per day

RECOMMENDED WHERE TO MAKE THE
PARAMETER NAME
SETTING CHANGE
SP_OCT_CHECKPOINT_FREQ 5000 source system
SP_ORD_CDA_LIMIT 20 source system
SP_ORD_DELAY_RECORDS 500 source system
SP_ORD_LDA_ARRAY_SIZE 10 source system
SP_ORD_RMSG_LIMIT 2000 source system
SP_IMP_WCMT_MSGCNT 2500 target system
SP_COP_IDLETIME 600 source and target systems
For more information about SharePlex parameters and the set param command, see the
Operations that bypass the redo logs

SharePlex replicates only changes that are written to the redo logs. Changes that bypass
the redo logs are not replicated. The exception is SQL*Loader direct-load operations.
SharePlex replicates direct loads when there is one load per table (PARAL-
LEL=FALSE). The database must be in archive mode, and table logging must be
enabled.
DML (data) locks

SharePlex locks the tables specified in a configuration when that configuration is acti-
vated for the first time. In addition, it locks tables that are added to the configuration
when the configuration is re-activated (just the added tables, and only for that activa-
tion). To ensure that SharePlex does not run out of locks, set the DML_LOCKS param-
eter in the init.ora file to at least the current value plus the number of tables in the
configuration, or higher if you think you will be adding more tables to the configuration.
CHAPTER 4 117
OPEN_CURSORS parameter
SharePlex requires the value of the Oracle OPEN_CURSORS parameter to be set cor-
rectly. 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 needs to reserve 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 follow-
ing, depending on whether or not you are using SQL Cache.
With SQL Cache enabled: SQL Cache is on by default. 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 disabled. See page 241 for more information about setting
OPEN_CURSORS for SQL Cache.
With SQL Cache disabled: Estimate the peak number of concurrent updating trans-
actions (sessions) 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. It is suggested that
users consult the appropriate Oracle documentation prior to making changes to Oracle
parameters.
PROCESSES parameter
The PROCESSES parameter in the init.ora file must be set to accommodate connec-
tions created by SharePlex and the database users. Its value depends on whether a sys-
tem is a source system, a target system, or a system that serves as both a source and
target system.
Source system only

If a system serves only as a source system, the following formula takes into account log-
ins made by the Read process.
(peak number of source database sessions) + (background Oracle processes) +
(value of SP_ORD_LDA_ARRAY_SIZE parameter +3) = PROCESSES value
Target system only

Although the Post process is one Oracle user, it creates as many connections on the tar-
get 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 Posts connections, plus the background Oracle processes those con-
nections generate, plus 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) = PROCESSES value
Combination source and target system

If a system serves as both a source system and a target system, the following formula
takes into account logins made by the Read process as well as Posts connections, back-
ground Oracle processes, and 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) = PROCESSES value
LOG_PARALLELISM parameter
The LOG_PARALLELISM parameter in Oracle 9i is found in the init.ora file. This
parameter sets the maximum number of latches that can be obtained at one time for
writing to the redo logs. The default value for this parameter is 1. Users typically set the
value for this parameter higher than one when they are experiencing long log waits due
to heavy activity because the LOG_PARALLELISM parameter helps alleviate conges-
tion by allowing redo logs to be written non-serially.
However, SharePlex assumes that the transactions within a redo log are written serially.
If the LOG_PARALLELISM parameter is set to a value greater than 1, SharePlex will
detect it and fail.
To prevent this problem, check the value for the LOG_PARALLELISM parameter in
the init.ora file before installing SharePlex. If the value is greater than 1, reset it to 1,
and restart the Oracle instance for the new value to take effect.
For Oracle versions 10g and higher, the LOG_PARALLELISM setting has been depre-
cated and now is enabled by default. SharePlex supports writing redo logs non-serially,
for Oracle versions 10g and higher, which means that SharePlex will not fail if the value
of the parameter is greater than 1. Note that the Oracle RECOVERY_PARALLELISM
parameter, if set to values greater than 1, is not supported by SharePlex.
CHAPTER 4 119
Log buffer size

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. Gener-
ally, more than 1 MB is too big unless you are rebuilding an index; in that case, you
need large chunks to be written at once. Try decreasing the size of the log buffer to 1024
KB, or even 512 KB if possible.
Transaction size
Normally, Post performs an internal read/release after it receives each COMMIT, which
means it purges that transactions data from the queue as part of the checkpoint recovery
process. For small transactions, this can cause excessive I/O on the target system and
slow the Post process. If most of your transactions are small, you can increase the
SP_OPO_READRELEASE_INTERVAL parameter default value to 100, thus directing
Post to read/release only after a certain number of messages have been processed. For
more information about this parameter, see Chapter 4 of the SharePlex Reference Guide.
For more information about messages, see page 34.
Character sets
The following character sets are tested and supported for SharePlex:
US7ASCII
UTF8
WE8ISO8859P1
AL16UTF16
AL32UTF8
KO16KSC5601
Note that Shareplex supports replication between a subset of a character set and a super-
set of that character set and not between two different character sets.
Character set conversion

SharePlex reliably replicates all characters within the character set you are using if you
are replicating between identical character sets.
If, however, you are replicating between non-identical character sets, then some charac-
ter set conversion might be required. SharePlex does not perform character set conver-
sion; instead Oracle performs the conversion. As SharePlex posts data, Oracle is
notified about the character set encoding of the data. If the data is encoded in a different
character set than the character set of the target database, Oracle will perform character
set conversion.
Depending on the character sets involved, the Oracle conversion might lead to data loss.
For example, consider the Japanese character for "rice" in the JA16SJIS character set.
There is no corresponding symbol in the US7ASCII character set. If you attempt to rep-
licate this symbol into a US7ASCII database, Oracle will convert this to a '?' character
since there is no such symbol in US7ASCII.
Oracle character set conversion can cause unexpected results. For example, according to
Oracle, the WE8ISO8859P1 character set is a superset of the US7ASCII character set.
Hence, you might expect 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 that 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.
Replicating between non-identical character sets

If you are replicating between non-identical character sets you should choose to either
use the Oracle character set conversion
or . . .
bypass the Oracle character set conversion
The default behavior for SharePlex is to accept the Oracle character set conversion. You
do not need to set any parameters to achieve this behavior.
CHAPTER 4 121
The parameter, SP_OPO_NLS_CONVERSION, determines whether or not the data

posted by SharePlex is converted from the source characterset to the target characterset.
The default behavior is to convert.
SP_OPO_NLS_CONVERSION int(0:1) 1 # Convert by default
To change this behavior, set the parameter to 0.
Note that the following parameters pertaining to NLS language conversion in previous
versions have been deprecated as of 8.0 but will still work in an upgraded environment.
Deprecated parameters:
SP_ORD_NLS_LANG
SP_OPO_NLS_LANG
SP_OPO_CHARACTERSET
SP_OPO_NCHAR_CHARACTERSET
SP_DEQ_NLS_LANG
SP_DEQ_NLS_LANG_SELECTOR
SP_DEQ_CHARACTERSET
SP_DEQ_NCHAR_CHARACTERSET
Note: New in 8.0, a parameter can be flagged as DEPRECATED. A parameter that had
been set in the paramdb in a prior release is still available and used by SharePlex in the
release where the parameter was flagged as deprecated. Deprecated parameters can-
not be set in 8.0. If you do not want SharePlex to use the deprecated parameter, you can
issue the reset command on it.
Note: SharePlex will always convert NVARCHAR and NCLOB data if the source data-
bases NLS_NCHAR_CHARACTERSET is not the same as the target databases
NLS_NCHAR_CHARACTERSET.
For more information about this parameter, refer to the SharePlex Reference Guide.
Dates
Oracle JDBC driver classes below version 8.0.5 can allow the input of improper date
formats. Make certain your applications use JDBC driver classes 8.0.5 or above.
initrans setting for SHAREPLEX_TRANS table

SharePlex updates the SHAREPLEX_TRANS table to maintain read consistency for
the target database. Because the Post process reconstructs transactions made to the pro-
duction instance, the initrans setting might need to be increased to improve perfor-
mance and reduce contention on that table.
If the production database has between 500 and 1,000 concurrent users, rebuild the
SHAREPLEX_TRANS table to have an initrans of 30.
If the production database has more than 1,000 concurrent users, rebuild the
SHAREPLEX_TRANS table to have an initrans value of 40.
Oracle Label Security (OLS)

When Oracle Label Security (row-level security) is enabled for tables in replication,
SharePlex cannot process the rows that are protected. By default, users granted DBA
privileges (such as SharePlex) do not have enough privileges to see those rows without
granting a special role from the OLSSYS user.
SharePlex was tested under the following OLS configuration:
The SPLEX_USER was granted FULL privilege to the objects in replication. Test tables
with OLS security were created. The OLS policy data label column was not hidden.
Data was replicated using insert/update/delete/rollback/truncate, and alter table to add
and drop columns.
If the OLS policy data label column is defined as hidden the data in that column can not
be replicated by SharePlex to the target system.
Configuring the system for replication

SharePlex requires no changes to the operating system, but some system-level adjust-
ments are needed to ensure successful replication.
Host names
SharePlex supports host names that contain letters or numbers only. If a host name con-
tains a dot or any other non-alphanumeric character (such as . or _), create an alias
in the local /etc/hosts file that contains only alphanumeric characters. Also create the
alias on the NIS server and the DNS server, if used.
CHAPTER 4 123
Geography
Review the disk drives on which the elements of the Oracle database are distributed, and
compare them to the location of the SharePlex processes. Generally, the following I/O-
intensive processes should be on separate drives from each other, preferably with sepa-
rate processors:
The redo logs preferably without any
striping and preferably on solid-state The redo logs and the rollback
drives. segments are the two most
write-intensive processes, and
The rollback segments preferably on the ones with the most sequen-
solid-state drives tial access. They should be sep-
The SYSTEM tablespaces arated from the other, more
The indices mixed or read-intensive pro-
cesses that have more of a ran-
The datafiles dom-access nature.
The SharePlex processes (the binaries in
the SharePlex product directory)
The SharePlex queues (the files that are created in the rim sub-directory of the Share-
Plex variable-data directory)
If the SharePlex processes and queues cannot be on their own disk drives, combine the
SharePlex queues with the datafiles, and combine the SharePlex processes with the
SYSTEM tablespace.
Important! If you move just the rim sub-directory to a separate drive, link it to the Share-
Plex variable-data directory.
Raw devices
SharePlex binaries and queue files cannot reside on raw devices. If the SharePlex soft-
ware was installed on a raw device, move all of the files to a filesystem disk that is dif-
ferent from the production filesystem, or remove SharePlex and reinstall it on a
filesystem disk. Redo logs and Oracle datafiles can reside on raw devices in a replica-
tion environment.
CPU considerations
In a typical business application with a mix of 80 percent queries and 20 percent
changes, SharePlex adds a load of between two and five percent to the resources con-
sumed by Oracle. Additional I/O load is minimal, assuming that the network can keep
up with the amount of data being transferred.
On systems that are DML intensive, SharePlex adds about 15 percent to the amount of
resources consumed by Oracle. For example, if it takes 100 seconds for Oracle to insert
50,000 rows of data, SharePlex will generate an additional 15 seconds of CPU to repli-
cate those rows. These are guidelines only, and your results can vary depending on your
transaction mix.
Disk space for queue files

Queue File Size
The main SharePlex consumers of disk space are the queues (capture, export, post),
which are periodically written from memory to disk in the rim sub-directory of the
SharePlex variable-data directory. To accommodate data in a queue, SharePlex builds
data files for each queue on demand. All queue data files are 8 MB.
Since the queues are dynamic, the number of data files can grow considerably during
peak activity, and more so when replication is stopped by a user or because of a net-
work, instance or system failure.
When Read stops, data accumulates in the capture queue on the source system.
When the network or target system is unavailable, or when Export or Import is
stopped, data accumulates in the export queue on the source system.
When the target Oracle instance is unavailable, or when Post is stopped, data accu-
mulates in the post queue on the target system.
There must be enough disk space on both systems to hold that queued data for as long as
the peak processing or downtime persists. If a system runs out of disk space, replication
stops, and you will need to resynchronize the data.
To determine the amount of queue space on each system
1 Use a worst-case scenario and estimate the length of downtime to be tolerated.
2 Determine how much data is replicated in that time, using the following formula as a
guide. This formula multiplies the redo log value by one-third because only about
one-third of the redo log is actually data that is replicated. The rest is data used by
Oracle to maintain and operate the instance itself.
[size of a redo log] x [number of log switches in 1 hour] x 1/3 x [number of hours
downtime] = amount of disk space needed for the queues on each system
CHAPTER 4 125
Example:
Suppose you expect to recover from 8 hours of downtime and your redo logs are 60
MB. They switch five times an hour. According to the formula, you need 800 MB of
space on the source machine and on the target machine for the SharePlex queues.
[60 MB redo log] x [5 switches/hour] x [1/3] x [8 hours] = 800 MB disk space
Tip: Always monitor disk usage when there is an active configuration, especially when
there are unexpected peaks in user activity. SharePlex provides monitoring utilities for
UNIX and Windows platforms that monitor queue volume. See Chapter 9 for more infor-
mation.
Queue File Location

Because the SharePlex queues consume disk space as data accumulates, put them on a
separate file system from the production files, including the Oracle datafiles, binaries,
and logs. The queues reside in the rim sub-directory of the SharePlex variable-data
directory. By isolating the queues, you can continue production activity even if replica-
tion runs out of space.
Establish the queues on a non-striped device. Because reads of the queues are sequen-
tial, the queues will not benefit from striping or RAID 5. A device with a large disk
cache works best.
You can put the queues on NAS (Network Attached Storage) or SAN (Storage Area
Network) devices, but do not put them on traditional NFS (Network File System)
devices, because NFS devices cannot meet the performance demands of SharePlex rep-
lication.
Warning! SharePlex queue files must not be located on a raw device.
Tip: Putting the rim sub-directory on solid-state drives can improve performance by as
much as 50 percent. If you move the rim sub-directory to a separate drive, link it to the
SharePlex variable-data directory.
Memory (UNIX systems)

SharePlex requires a per-process memory allocation of greater than, or equal to, 256
MB. Typically, per-process memory usage for SharePlex processes is just a fraction of
that amount. Under some conditions, however, the Post and Read processes dynami-
cally allocate larger sets of memory. To prevent process failure, the per-process memory
must be large enough to allow SharePlex processes to function.
System file descriptors (UNIX systems)

To ensure fast, problem-free posting to the target database, SharePlex requires a system
file descriptors setting of 1024 or as close to that value as your system resources can
accommodate. The system file descriptors setting (nofiles) determines the number of
files that a process can have open at one time. This parameter can be set either as a sys-
tem hard limit or a session-based soft limit.
On most production systems, the hard limit usually is set high enough for SharePlex, but
it should be verified. The following command displays the hard limit (and other ulimit
settings) on Sun Solaris and IBM AIX systems. On HP-UX systems, the command
works in the Bourne shell (sh).
$ ulimit -aH
time(seconds) unlimited
file(blocks) unlimited
data(kbytes) unlimited
stack(kbytes) unlimited
coredump(blocks) unlimited
nofiles(descriptors) 1024
vmemory(kbytes) unlimited
The nofiles(descriptors) value is the one to verify and change if necessary. Changing
the system file descriptors value requires root privileges (usually the System Adminis-
trator), and the system must be rebooted after you make the change. Consult your Sys-
tem Administrator for assistance.
Instead of changing the hard limit, you can set a soft limit for this parameter, but the soft
limit only stays in effect for the duration of the sp_cop session for which it was set.
When you shut down sp_cop and start it again, the soft limit reverts back to its default
value, which could be lower than the hard limit.
The soft limit can be set as high as the hard limit, but not higher. It does not require a
root user to change it. On Solaris, IBM AIX, and HP-UX (Bourne shell) platforms, the
following command displays the soft limit for file descriptors.
$ ulimit -aS
CHAPTER 4 127
The following command sets the soft limit for system file descriptors.
$ ulimit -n value
Because of the session-based limitations of the soft limit, Quest recommends that you
use the hard limit setting for SharePlex (sp_cop) to ensure that the system file descrip-
tors setting remains at a sufficient value. If you increase the hard limit to satisfy Share-
Plex, you can use the soft limit to restrict other applications to lower levels.
If you see the following error in the event_log, it indicates that the system file descrip-
tors setting 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)
Core File Management

Many platforms support system-wide, user, or process-specific placement of application
core files, and customizable naming conventions for core files.
For core file location, SharePlex supports only the dump subdirectory of the SharePlex
variable data directory. This is the "current working directory" for sp_cop and the pro-
cesses started by sp_cop.
For naming conventions, SharePlex supports "core" and "core.<pid>". SharePlex will
rename files named "core" to "core.<pid>" unless the core file is from sp_cop. In that
case, the core file will not be renamed. If the OS naming convention is set to
"core.<pid>", all core files will have that name format.
If the SharePlex core file policy is not met, the SharePlex event log might report that a
core file was not generated. The core file generating process might exit even if a core
file was actually created.
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. The SharePlex process priority should be matched to Oracles priority.
Otherwise, Capture, Read, or both could lose pace with Oracle during hot backups or
other Oracle-intensive operations. SharePlex only uses about three to eight percent of
overhead, so the possibility of overwhelming the system is low.
To change process priority

On UNIX systems, use the nice command.
On Windows systems, the NuTCRACKER operating environment controls the
SharePlex processes, so you must run the Windows Task Manager with special priv-
ileges to set process priority for SharePlex. Do not use the standard Windows Task
Manager. The SpUtils and SpClient utilities both have options for running the Task
Manager with the correct privileges. You also can use the DTaskmgr program in the
bin sub-directory of the SharePlex product directory. For more information about
setting process priority for SharePlex on Windows systems, see page 280.
Network requirements
Bandwidth
SharePlex replicates over any TCP/IP network connection. The bandwidth required by
SharePlex to transfer data varies, depending on the volatility of the database and the
transaction mix of queries and changes. Typically, if all of the tables in a database are
being replicated, SharePlex replicates about 33 percent of the redo log volume, the
remainder being mostly maintenance data used by the Oracle software. The following is
a formula for determining bandwidth.
[size of a redo log] x [number of log switches in 1 hour] x 1/3 = volume of data per
hour
For example, if the redo logs are 20 MB in size, and they switch six times an hour,
SharePlex will replicate approximately 40 MB each hour:
[20] x [6] x [1/3] = 40 MB/hour
Security
SharePlex can be configured to work with SSH software. For instructions for using
SharePlex with SSH, see Chapter 6. Also in that chapter are instructions for using the
host-authorization feature of SharePlex, which authorizes connection attempts made by
other systems.
Veritas Quick I/O

Because of the way Quick I/O caches disk information, Capture cannot access the
cache, so it interprets that it already processed the data and waits for more to process.
While it waits, it loses pace with Oracle, which continues generating redo data not
CHAPTER 4 129
accessible to Capture. The eventual result is a log wrap and the necessity to access the
archive logs. When Capture processes what it missed and returns the redo logs, the same
thing happens again because of the Quick I/O cache. The only workaround is to remove
Quick I/O from the redo and archive logs, but you can use it for the datafiles.
Other implementation considerations
Regular SharePlex backups

After replication commences, back up the SharePlex environment on all source and tar-
get systems and then repeat the backup whenever there is a change in the replication
environment. Such changes include:
modification, activation, reactivation, or deactivation of a configuration
parameter changes that you want to keep
SharePlex patches that were applied
Backups are essential when users need the ability to fail over to a secondary system and
back for high availability.
The following are the items to back up:
All platforms
the entire SharePlex product and variable-data directories
UNIX platforms
the oratab file
the /etc/services file (for file descriptor settings)
the /etc/system file (for semaphore information in case of system loss)
the /etc/group file for user information
the .profile file if SharePlex is installed on a cluster
Windows platforms
the Windows Registry files (to save the SharePlex environment)
the files containing the user and group information
When you have an archive of the current directories, and the filesystem(s) or machine
containing SharePlex components is unrecoverable, you can recover the state of the
queue files in the rim sub-directory. You also can recover the object cache information
in the state sub-directory, enabling you to restore the replication environment without
recreating and reactivating configurations, resynchronizing data, re-establishing direc-
tory paths, or resetting parameters. You also can restore the SharePlex logs, Status Data-
base, license key, and other critical files.
5
Preparing for SharePlex
Replication
Because the previous chapter provided an overview of replication options with Share-
Plex and the basic requirements for successful implementation, you now should know
your replication strategy and addressed any system issues associated with Shareplex
replication. The chapters that follow help you implement your replication strategy, so
read them in sequence for the best results.
Contents
SharePlex configuration construction

Configuration for replicating to multiple target systems
Configuration for isolating data using named export queues
Configuration for faster posting using named post queues
Configuration for horizontally partitioned replication
Configuration for vertically partitioned replication
Scripting a configuration to replicate numerous tables in a schema
Scripting a configuration to replicate an entire database
Establishing replication
Establishing replication for reporting
Establishing replication for high availability and data recovery
Establishing replication for data distribution or distributed processing
Establishing replication through an intermediary system
Establishing combined cascading/broadcast replication
Establishing replication for centralized reporting (standard method)
Establishing replication for centralized reporting using multiple sp_cop processes
Establishing peer-to-peer replication
Part 1: SharePlex configuration

construction
After you configure your data and systems, the next step is to create a configuration file
that defines the data to be replicated. This part of the chapter explains the different ways
to create configurations, so that you can create one that is most suitable for your replica-
tion strategy.
The configuration is an ASCII text file that tells SharePlex which data to replicate and
where the data needs to go. Configurations reside on the source systemthe system
hosting the database containing the objects whose data will be replicated. If you are a
SharePlex Administrator or operator, you have the authority to create a configuration.
Configuration options
Before you begin creating configurations, review the following to familiarize yourself
with the options available to you.
Full-table and selective replication

SharePlex offers several configuration options:
The most basic configuration replicates all rows and columns from one table to
another. This is full-table replication.
You can replicate selected rows or columns, or both, from one table to another. This
is partitioned replication, also known as selective replication.
To replicate selected rows, you use horizontally partitioned replication, also known
as selective row replication. See Configuration for horizontally partitioned replica-
tion on page 160 for more information.
To replicate selected columns, you use vertically partitioned replication, also known
as selective column replication. See Configuration for vertically partitioned replica-
tion on page 172 for more information.
You can combine horizontally and vertically partitioned replication to control which
information is distributed and where it is sent. For example, partitioned replication can
CHAPTER 5 133
Preparing for SharePlex Replication
be used by a business that has a central location, such as corporate headquarters, and a
number of remote locations, such as regional divisions or retail locations. The central
location maintains the corporate database, and the remote locations maintain different
reporting databases, with little or no data in common between them.
The headquarters replicates many of its tables in their entirety to all regions. But for
other tables, the company uses vertically partitioned replication to replicate data from
some of the columns, but not others. The non-replicated data either is not useful to the
regions, or it is sensitive information that cannot be shared.
For the vertically partitioned tables, the company also can use horizontally partitioned
replication to direct each data change to the region that needs it, excluding regions that
have no use for it. Horizontally partitioned replication also can be used when you are
replicating all of the columns of a table.
Replicating to multiple target systems

When all target tables for a source table have the same owners and names, you can use
compound routing syntax to configure one routing map for all targets. See page 148 for
instructions.
Replicating numerous objects

SharePlex provides options for speeding the creation of configurations.
For high-availability or reporting strategies where the corresponding source and tar-
get table names are identical, you can use the build_config.sql script to configure all
tables in a schema. See page 179 for instructions.
For high-availability strategies, you can configure all tables and sequences in the
database with the config.sql script. See page 183 for instructions.
To replicate numerous objects, especially if there is extensive row chaining, you can
use progressive configuration activation to make the process faster. It might be help-
ful to review those instructions before you decide how to build your configuration(s).
See page 311 for instructions.
For ease of use SharePlex supports the use of wildcards in the configuration file.
This allows you to specify a group of tables in a specific schema using a single line
in the configuration file. You may also specify a specific set of tables not to be
included in replication. Using wildcards also allows for the automatic addition of
any new tables to replication without having to reactivate the configuration. See
page 137 for instructions.
Defining a unique key

You can specify a key definition in the configuration file if a table was not created with a
PRIMARY or UNIQUE key. SharePlex uses the specified columns as a unique key in its
WHERE clause to locate target rows for posting. An explanation of how a key is
defined follows in Components of a SharePlex configuration on page 135.
Separating replication datastreams

For replication from two different Oracle instances, or for replication to multiple target
systems, you can use named export queues to separate the replication streams. For more
information, see page 150.
To improve Post performance when tables have different transaction types or large
datatypes, you can use named post queues to separate the replication streams among two
or more Post processes. For more information, see page 155.
Configuration guidelines
When creating SharePlex configurations, follow these rules:
Review the commands for creating, viewing, activating and modifying configura-
tions. See Chapter 1 of the SharePlex Reference Guide for more information about
SharePlex commands.
Create configurations on the source systemthe system containing the data to be
replicated. SharePlex automatically sends configuration information to the target
system. (Certain replication strategies necessitate configurations on two or more sys-
tems.)
You can create as many configurations for the same Oracle instance as you wantto
replicate different tables at different times for examplebut only one can be active
at a time. Configurations for different Oracle instances on a system can be active at
the same time.
To activate multiple configurations for different datasources on the same system,
activate the first one and 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.
Objects listed in the configuration must be part of the Oracle instance specified in the
configuration and must contain datatypes that SharePlex supports. A list of sup-
ported items is on page 76.
CHAPTER 5 135
Correct syntax is essential. If an entry in the configuration contains misspellings or is

missing a required component, activation of that object will fail. Configurations con-
taining duplicate entries will fail to activate.
Each line in the configuration can contain only one entry (source object, target
object, routing). Lines can wrap on-screen. To end a line and start a new one, press
Enter.
Do not activate a configuration until you configure your data and systems properly
for the type of replication that you are doing.
All configurations must reside in the config sub-directory of the SharePlex variable-
data directory. Configuration files outside this directory cannot be activated. Share-
Plex places configurations in this directory by default when you create them through
the sp_ctrl interface.
Components of a SharePlex configuration

The following are the components of a configuration and the rules for specifying them.
Configuration name
The configuration name is not a functioning component within the configuration itself,
although you can add it to the file as a comment line. You assign a name to a configura-
tion when you create the configuration using the create config command in sp_ctrl.
Because the number of configurations that you write probably will increase over time,
consider developing consistent and meaningful naming conventions.
SharePlex configuration names are case-sensitive. CONFIG1 is not the same as config1.
Datasource
Datasource is a SharePlex term for the ORACLE_SID of the Oracle instance containing
the data to be replicated. The ORACLE_SID is the most accurate way for SharePlex to
locate the data. There can be only one datasource per configuration.
Methods for determining the ORACLE_SID

You can view the ORACLE_SID in a few different ways.
On UNIX and Windows systems, you can query the V$PARAMETER table through
SQL*Plus.
SQL> select name, value from V$parameter
where name = db_name;
On a UNIX system, you can view the oratab file.

On Windows systems, you can view the Windows Registry under
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE.
Syntax for the datasource

The syntax for a SharePlex for Oracle datasource is:
o.SID
... where o is the lower-case letter o and SID is the ORACLE_SID of the source Oracle
instance for example o.ora10. The o. identifies the datasource as an Oracle database
and differentiates it from UNIX datasources, which are replicated by SharePlex FS soft-
ware.
ORACLE_SIDs are case-sensitive. ORA10 is not the same as ora10. The
ORACLE_SID must appear in the configuration the same way it appears in the oratab
file, Windows Registry or V$PARAMETER table.
In the configuration file, the word Datasource and a colon (:) precede the datasource,
for example:
Datasource:o.ora10
A space is permitted between the Datasource: and o.SID components, but nowhere else
in the syntax. The word Datasource is not case-sensitive. The datasource component
must be the first non-commented line in the configuration file.
HP-UX and IBM AIX systems
$ cd /etc
$ more oratab
You will see a display similar to this:

ora10:/qa/oracle/ora10/product
In this example, ora10 is the ORACLE_SID and
/qa/oracle/ora10/product is the ORACLE_HOME directory.
CHAPTER 5 137
Sun Solaris systems

On the Solaris platform, the oratab file is typically located in the var/opt/oracle direc-
tory. Sometimes there is an oratab file in the /etc directory as well. If there is an oratab
file in the /etc directory, remove, rename or relocate it to prevent problems for Share-
Plex.
Important! Limit machine names and ORACLE_SIDs to letters and numbers. Other
characters, such as the dollar sign ($) can cause configuration activation to fail. A dot (.),
plus sign (+) and asterisk (*) are valid syntax components in a routing map when used to
denote the target instance (o.SID), multiple target systems in a compound routing map
(sysB@o.oraB + sysC@o.oraC), and named queues (sysA:QueueA*sysB@o.oraB).
Source objects and owners

The source objects are the tables and sequences to be replicated. Each source object can
be listed separately, identified by the fully qualified name of the object. Alternatively, a
set of source tables (not sequences) can be specified using a wildcard sequence.
Specifying source tables using wildcards

A set of tables may be specified using wildcards. To specify a set of tables using wild-
cards:
Wildcard expansion must be indicated by using the expand keyword. Wildcard char-
acters are also valid object name characters so it is necessary to inform SharePlex
that you are employing wildcards.
Valid wildcards are the same as for Oracle and follow Oracles rules of usage.
Wildcards cannot be used to define the owner (or schema) name. If wildcards are
used in the owner (or schema) name, SharePlex will assume that these are part of the
owner (or schema) name.
An exclusion list may be included to further refine the set of tables. The exclusion
list follows the table specification and is indicated by the keyword not.
The name of the object on the source must be the same as the name of the object on
the target; however, the tables may belong to different owners (or reside in different
schemas).
If SharePlex sees the expand keyword in a configuration line, SharePlex will query
Oracle for all objects that match the criteria in the wildcard specification. For instance
the following sample configuration entry:
expand scott.prod% not (%temp%) hal.% sysa@o.sidb
will cause SharePlex to activate all tables owned by SCOTT, where the table_name is
like PROD% and the table_name is not like %TEMP%. All the tables that match
this description will be replicated to the same table_name on the target, owned by
HAL.
The syntax for a wildcard specification in the configuration file is as follows:
expand schema.{wildcarded name} [not ({list of exclusions})]
An example of not notation can be found in the last two lines of the example below.
The following are valid config file specifications:
expand scott.% scott.% sysa@o.ora920
expand scott.%test% scott.% sysa@o.ora920
expand scott.%t__t% fred.% sysa@o.ora920
expand scott.% not (spo%, gen%, prodct) scott.% sysa@o.ora920
expand scott.%test% not (spo%, gen%, prodct) scott.% sysa@o.ora920
The following config file specifications are NOT valid:
expand rob%.%test% scott.% sysa@o.ora920
expand scott.%test% scott.%obj% sysa@o.ora920
Note: The target object name must be specified in the form of: schema.%. It must be the
object owner (or schema) name followed by a period and the percent sign.
If you are unsure if the wildcard specification will produce the specific list of tables you
want to replicate, you can first issue the verify config command in sp_ctrl. This will
give you a list of all the objects for the specified schema as well as any problems
encountered. For more information on the verify config command, please see the Refer-
ence Guide.
During activation, if no tables are found that meet the wildcard criteria, activation will
continue without error.
Using wildcards also allows for the automatic addition of any new tables to replication
without having to reactivate the configuration. If you do not want new tables to be auto-
matically added into replication, this feature can be turned off using the
SP_OCT_AUTOADD_ENABLE parameter. Please see the Reference Guide for
details on this parameter.
CHAPTER 5 139
Limitations of wildcard support

The use of vertical partitioning, user key specification, or target column name specifica-
tions is not supported in a configuration specification using wildcards. These tables will
need to be added to the configuration file separately using the components described in
the following sections. Compound routing maps and named queues are explained later
in this chapter.
Source objects and owners

These optional components can be used for any tables that the wildcard specification
does not cover. The syntax for specifying source objects is:
owner.object
... where owner is the objects owner (or schema) and object is the objects name. Sepa-
rate the items with a dot (.) but no spaces for example scott.table1 and
scott.sequence1. Owner (or schema) names are used so that if a database has multiple
objects with the same name, SharePlex can differentiate among them.
The following are examples of strings that are not permissible because they contain
spaces:
scott.emp seq
scott . emp
scot. emp
scott smith.emp seq
Underscores are permissible, such as scott.emp_seq.
SharePlex recognizes case-sensitivity for an owner or object name when it is enclosed
within double quote marks. Otherwise, owner and object names are converted to upper
case.
Non-case sensitive example:
Scott.emp is the same as scott.emp or SCOTT.EMP. SharePlex converts them all to
upper case.
Case-sensitive examples:
case-sensitive table name: scott."Emp"
case-sensitive owner name: "Scott".emp
case-sensitive owner and table name: "Scott"."emp"
Key definition
A key definition is an optional component of a source object that lets you specify one or
more columns as a unique key if a table was not created with a PRIMARY or UNIQUE
key. Without some form of 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.
SharePlex uses the columns defined in the key definition as a key in its WHERE clause
to locate target rows for posting. The columns must meet the following criteria:
They cannot be LONG or LOB columns.
They must be able to uniquely identify a row. Otherwise, replication could return
out-of-sync errors or post to incorrect target rows.
They must be part of the column partition if vertically partitioned replication is being
used.
Important! When using exclude column notation in vertical partitioning excluded col-
umns cannot be used in the key definition.
Important! When a key definition is specified for a table that has a PRIMARY or
UNIQUE key, the key definition overrides the Oracle key.
To create a key definition, type a space after the source object and use the following
syntax, including the parentheses. Spaces between column names within the parenthe-
ses are optional. The !key component must precede the column names.
!key (col_name, col_name)
Example:
!key (Name, Emp_ID)
Example of wildcard and key specification:
expand scott.% scott.% .....
scott.tabnokey !key(c1,c2) scott.tabnokey .....
Target objects and owners

The target objects are the tables or sequences on the target system to which data will be
replicated. Specify them the same way as source objectsby owner and namefollow-
ing the same syntax rules.
CHAPTER 5 141
owner.object
Depending on the replication strategy, target object and owner names can be different
than, or the same as, corresponding source object and owner names. Refer to the appro-
priate guidelines for your replication strategy in the procedures beginning with Estab-
lishing replication on page 185.
Routing map
The routing map directs SharePlex where to send the replicated data.
For non-partitioned replication (full-table replication) and vertically partitioned rep-
lication (replication of selected columns) the routing map is the last component of a
tables configuration entry.
For horizontally partitioned replication (replication of selected rows) the routing
map is listed in a partition scheme, and the partition schemes name is the last com-
ponent of the tables configuration entry.
The syntax for a routing map is:
targetsystem@o.targetSID
...where targetsystem is the name of the target system and targetSID is the
ORACLE_SID of the target database for example sysB@o.ora10. There can be no
spaces between any characters in the routing map. The o. identifies the instance as an
Oracle database and differentiates it from other types of data.
The following are examples of strings that are not permissible because they contain
spaces:
sys B@ o.ora10
sysB @ o.ora10
sysB@o.ora 10
sysB@o. ora10
Target system names

The target systems name is not case-sensitive in a configuration.
SharePlex supports system names that contain letters or numbers only. If a system
name contains a dot (.) or any other non-alphanumeric character, such as an under-
score ( _ ), create an alias for that system in the local /etc/hosts file that contains
only alphanumeric characters. Also create the alias on the NIS server and the DNS
server, if used.
The source system must be able to resolve the names of all target systems listed in
the routing map. All target systems in the routing map must be accessible by the
source system through the replication network or through an intermediary system
that is accessible.
Target ORACLE_SID
The target ORACLE_SID is case-sensitive and must appear exactly as it appears in the
oratab file, V$PARAMETER table, or Windows Registry.
Routing maps in cluster environments

For a target system that is part of a cluster, the global cluster package name must be
used instead of the local systems name in the routing map, following the format Clus-
terPackageName@o.SID.
Example:
oracluster@o.ora10
The global cluster package name must match the string specified with the
SP_SYS_HOST_NAME system environment variable. SP_SYS_HOST_NAME must
be set to the same value on all systems in the cluster. The package name cannot contain
underscores ( _ ), dots (.) or any other non-alphanumeric characters. For more informa-
tion about configuring SharePlex on clustered systems, see the SharePlex Installation
and Demonstration Guide.
Routing limitations
Although few SharePlex users encounter routing limitations, they do exist, and they can
have an important effect on the way you build your configuration if you are replicating
data to numerous target systems and Oracle instances. Review the following routing
limitations before you build a configuration.
Using a default export queue, you can replicate to a maximum of 19 direct target sys-
tems from one source system. The reason is that SharePlex limits the number of pro-
cesses that can simultaneously read a queue to a maximum of 19, in addition to the
sp_cop process. Because SharePlex creates one export queue for all target systems,
CHAPTER 5 143
but creates an Export process for each target (which reads the queue), there can be a
maximum of 19 target systems.
You can compensate for the preceding limitation by using named export queues (see
page 179). This method permits a maximum of 25 queues per sp_cop instance,
which includes one capture queue, any named post queues (see page 155) and named
export queues that are used by that instance of sp_cop.
Note: By default, there is a maximum of 25 queues. However, this amount can be

changed using the parameter, SP_QUE_MAX_QUEUES, from 9 to 254. This change
only takes effect when cop is restarted.
The number of named queues is limited by the maximum number of routes. Each
instance of sp_cop on a system permits a maximum of 1024 different routing maps.
Each combination of targetsys@o.SID, including routing maps with named queues,
constitutes a different routing map. For example, in Figure 6 on page 144, there are
four routes.
If your replication objectives require exceeding these limitations, consider using one
or more intermediary systems to route replicated data to its final destination. See
page 86 for a description and page 197 for information about establishing this strat-
egy.
There is a limit of nine queues for AIX systems.
FIGURE 6: Routing example: In this illustration, there are four routes. SharePlex is repli-
cating all four tables to SysB and SysC. Each system has named post queues. This sepa-
rates the two datastreams into four, for a total of four routes.
CHAPTER 5 145
Creating a basic configuration using sp_ctrl

These instructions show you how to create a configuration for replication of entire
tables (non-partitioned replication). To replicate selected rows and/or columns from a
table, follow the instructions in Configuration for horizontally partitioned replication
on page 160 or Configuration for vertically partitioned replication on page 172.
These instructions create the most basic SharePlex configuration: a uni-directional con-
figuration replicating from one Oracle instance to another. Refer to the following tem-
plate as you follow the instructions.
Template 1: Basic SharePlex for Oracle configuration

Datasource:o.source-
SID
source_owner.table target_owner.table targetsystem@o.targetSID
source_owner.sequence target_owner.sequence targetsystem@o.targetSID
To create a basic configuration

To create a basic configuration, use the create config command in sp_ctrl. When you
issue this command, it invokes either the vi editor, which is the default text editor for
SharePlex on UNIX systems, or WordPad, which is the default editor on Windows sys-
tems. To change this default, see page 266.
1 From the bin sub-directory of the SharePlex product directory on the source system,
start sp_ctrl.
2 At the sp_ctrl prompt, issue the create config command. In the syntax below, sub-
stitute the name of your configuration for filename. This command opens the text
editor.
sp_ctrl(sysA)> create config filename
3 [OPTIONAL] You can enter comment lines to identify the configuration or convey
other information. Precede each comment line with a pound (#) symbol to indicate
that it is non-functioning, and end each one by pressing Enter.
4 On the first non-comment line, type the word Datasource, followed by a colon (:),
then the letter o, then a dot (.) followed by the source instance ORACLE_SID.
Leave no space between any of the items. The word Datasource is not case sensi-
tive. The ORACLE_SID is case-sensitive.
Datasource:o.SID
5 Press Enter to start a new line.

6 On the next line, type the owner and name of the first source object, separating them
with a dot (.). Leave no space between any of the items. Enclose case-sensitive items
within double quotes, for example "scott"."emp"; otherwise, SharePlex does not
recognize case-sensitivity. Do not press Enter after you type the source object infor-
mation.
source_owner.object
7 [OPTIONAL] If the table has no primary or unique key, you can specify a key definition
if one or more columns ensure row uniqueness. A key improves replication perfor-
mance, particularly if there are numerous columns.
To define a key, type at least one space after the source object, then use the following
syntax. Do not press Enter.
8 Type at least one space or tab, then type the owner and name of the corresponding
target object in the same manner as you did for the source object. Do not press
Enter.
target_owner.object
9 Type at least one space or tab, then type the name of the target system*, followed by
the @ symbol, then o. followed by the target database ORACLE_SID. Leave no
space between any of these entries. This creates the routing map.
targetsystem@o.targetSID
11 Repeat steps 6 through 9 for the following:
each additional target system to which you want to replicate the same object.
each additional object that you want to replicate with this configuration.
Tip: When target objects for a source object have identical owners and names on two or
more target systems, you can use a compound routing map to reduce the amount of typ-
ing for those entries. See page 148 for more information.
* SharePlex does not support system names that contain non-alphanumeric characters, for example an
underscore (_) or a dot (.). For more information, see Target system names on page 141.
CHAPTER 5 147
Your configuration should look similar to the following:
Datasource: o.fin
jim.salary
jim.salary sysB@o.oraB
jim.salary
jane.emp sysC@o.oraC
jane.sales !key
jane.sales sysB@o.oraB
(emp_no,emp_name)
12 When you are finished entering objects to be replicated, save the file with the :wq
command in vi or by selecting Save from the File menu in WordPad, and exit the
editor. You are returned to the sp_ctrl prompt. SharePlex automatically saves config-
uration files in the config sub-directory of the SharePlex variable-data directory.
Configuration for replicating to multiple target

systems
When target objects for a source object have identical owners and names on two or
more target systems, you can use a compound routing map in the configuration entry for
those objects. You start with a basic configuration line, but instead of using a separate
line for each target system, you specify them all in one routing map.
The additional syntax is shown in italics in the template below. See Routing limita-
tions on page 142 for the maximum number of target systems.
Template 2: Configuration for replication to multiple target systems

Datasource:o.sourceSID
targ_own.tabl
srce_own.table targsysB@o.targSID + targsysC@o.targSID
e
To create a configuration for multiple target systems

Start with the first object to be replicated and follow the instructions for creating a basic
configuration on page 145. Type the routing for the first target system* (for example
sysB@o.oraB), but do not press Enter to start a new line. Instead, type the routing for
the second target system in the following manner, in sequence, without starting a new
line (it can wrap to the next line).
a space
a plus sign (+)
another space
the routing map for the second target system, for example systemC@o.oraC.
Add each additional target system to the routing map in the same way. Press Enter at the
end of the line. Start a new line for each source table, as shown in the example. You
need not send each set of objects to all of the target systems.
Example configuration on source system sysA:

Data-
source:o.oraA
CHAPTER 5 149
Example configuration on source system sysA:

sysB@o.oraB + sysC@o.oraC +
scott.emp scott.emp
sysD@o.oraD
scott.ord scott.ord
sysB@o.oraB + sysC@o.oraC
scott.cust scott.cust
sysB@o.oraB
If any target objects have different owners or names than the source object, use a sepa-
rate line for each set that is different, as shown in the following example. Press Enter
after each line.
Datasource:o.oraA
scott.emp scott.emp sysB@o.oraB + sysE@o.oraE
scott.emp mary.emp sysC@o.oraC
scott.emp mary.cust sysD@o.oraD
Configuration for isolating data using named export

queues
Named export queues enable you to isolate replication of individual configurations or
selected database objects into their own export queues, each one generating its own
Export process.
FIGURE 7: SharePlex replication using named export queues
Named export queues are essential for separating the data streams of different replicat-
ing Oracle instances. The default architecture of SharePlex sends data from all active
configurations through one export queue and one Export process for each target system.
Consequently, if you issue a purge config or abort config command for one configura-
tion, you are affecting the queues for all other active configurations as well. And, should
CHAPTER 5 151
you need to stop Export or Import for one datasource, you are stopping those processes
for all others as well.
Named export queues eliminate those concerns. You can purge or abort one configura-
tion without affecting the others, and you can stop Export or Import for one datasource
while allowing other Export and Import processes to continue.
Named export queues can be used to separate data destined for different target systems.
You can create a named export queue for each target so that you can stop Export for
each one separately.
Because each Export process creates an Import process on the target system, named post
queues with their own Post processes are generated. This is effective for isolating tables
with large operations or LOB datatypes. For more information about named post
queues, see page 155.
You can set SharePlex parameters for processes associated with named queues on an
individual basis, enabling you to tune performance based on the objects replicating
through each one. For more information about setting process-specific parameters, see
the SharePlex Reference Guide.
Number of queues on a system

You can name several export queues within a configuration. The queue names for one
configuration must be different than those for any other active configuration.
You can combine named export queues with default export queues. Tables in the config-
uration with a standard routing map (targetsys@o.targetSID) will be replicated through
a default export queue.
Each sp_cop instance allows a total of 25 queues on a system. There will always be
one capture queue, so you can have as many as 24 named export queues. If this system
is also a target system, then it also has to have post queues. The maximum number of
export queues on a system is reduced by the number of post queues, including named
post queues. See Routing limitations on page 142 for additional information before
you build your configuration.

To create a named export queue

Creating a configuration that uses named export queues is similar to creating a basic
configuration. The difference is that you add the named-queue information at the begin-
ning of an objects routing map.
In Template 3, the named queue specification is highlighted in italics to show how cre-
ating a configuration with named export queues differs from a basic configuration.
Template 3: Configuration for creating named export queues

sourcesys:queue_name*targetsys@o.target-
source_owner.table target_owner.table
SID
start sp_ctrl.
2 At the sp_ctrl prompt, issue the create config command. Substitute the name of
your configuration for filename. This command opens the text editor.
Leave no space between any of the items. Datasource is not case-sensitive. The SID
is case sensitive.
Datasource:o.SID
with a dot (.). Enclose case-sensitive items within double quotes, for example
"scott"."emp"; otherwise, SharePlex does not recognize case-sensitivity. Leave no
space between any of the items. Do not press Enter.
source_owner.object
CHAPTER 5 153
8 Type at least a space or tab, then type the owner and name of the corresponding tar-
get object in the same manner as you did for the source object. Do not press Enter.
target_owner.object
9 Type at least a space or tab, then type the following information on the same line, in
sequence, with no spaces between them.
the name of the source system* (required part of the queue name)
a colon (:)
the name you are giving the export queue (maximum 15 characters). Queue names
are case-sensitive on all platforms. Underscores are permissible.
an asterisk (*)
the name of the target system
the @ symbol
the o.
the target database ORACLE_SID (This is case-sensitive.)
source_sys:queue_name*targetsys@o.targetSID
10 Start a new line and repeat steps 6 through 9 for each table or sequence being repli-
cated through this named queue.
11 To create additional named queues for other objects, repeat steps 6 through 9 using a
different queue name.
12 When you finish, save the file with the :wq command if using vi or with Save on the
File menu if using WordPad, then exit the text editor. You are returned to the sp_ctrl
prompt. Your configuration should look something like the following example:
Example configuration for instance oraA on source system sysA

Datasource:o.oraA
scott.emp !key
scott.dest_emp sysA:QueueA*sysB@o.oraB
(name,ID)
scott.dest_sales sysA:QueueA*sysC@o.oraC
scott.sales
Example configuration for instance oraA2 on source system sysA

Datasource:o.oraA2
jane.cust !key
jane.dest_cust sysA:QueueA2*sysB@o.oraB
(name,ID)
jane.dest_ord sysA:QueueA2*sysC@o.oraC
jane.ord
The preceding configurations create the following export queues on source sys-
tem SysA:
QueueA containing transactions for scott.emp destined for sysB and scott.sales
destined for sysC.
QueueA2 containing transactions for jane.cust destined for sysB and jane.ord
destined for sysC.
Tip: You can view the named export queues with the qstatus command, and you can
view them with their associated Export processes and other replication processes with
the show command. See Chapter 1 of the SharePlex Reference Guide for more informa-
tion about these commands.
CHAPTER 5 155
Configuration for faster posting using named post

queues
The Post process is only as fast as the time it takes to apply the changes to the target
database using standard SQL. There is a noticeable effect on performance when some
transactions are extremely large, which delays processing of other transactions in the
post queue. Using named post queues can improve Posts performance.
With named post queues, you can isolate data into separate post queues, each queue
generating its own Post process. The concurrent Post processes facilitate smaller, more
efficient operations to be posted separately, while devoting one or more separate Post
processes to larger operations.
If you are using named export queues (see page 179), named post queues are created by
default. If you are not using named export queues, you can create named post queues by
specifying them in the configuration file.
You can create one or more named post queues for the following:
objects in the configuration that have LOB columns (recommended).
objects that involve large transactions.
any objects whose operations you want to isolate.
Then, create one or more named post queues for the rest of the objects in the configura-
tion, or use default post queues.
You can combine named post queues with default post queues. Tables in the configura-
tion with a standard routing map (targetsys@o.targetSID) are replicated through a
default post queue.
You can set SharePlex parameters for processes associated with named queues on an
individual basis, enabling you to tune performance based on the objects replicating
through each one. For more information about setting process-specific parameters, see
the SharePlex Reference Guide.
Number of post queues on a system

Each sp_cop instance allows a total of 25 queues on a system. If this system is only
being used as a target system, all of those queues can be named post queues. If this sys-
tem is also a source system, then it also has to have one capture queue and one or more
export queues. The maximum number of post queues on a system is reduced by the cap-
ture queue and the number of export queues. See Routing limitations on page 142 for
additional information before you build your configuration.

FIGURE 8: SharePlex replication using named post queues
Considerations when using named post queues

Under normal replication circumstances, SharePlex captures data in the order in which
it was generated. On the target side, it maintains that sequence of events by using one
Post process and one default post queue per sourceSID-targetSID datastream. With
named post queues, the following conditions apply:
CHAPTER 5 157
The target objects, and the rows within them, might not be changed in the same order
that the corresponding source objects were, possibly causing the target database to be
inconsistent with the source database.
If replicating tables have referential constraints, the unpredictability of the posting
order can result in the rejection of a child record if the parent record is not applied to
the target instance first. To avoid this, replicate all related objects in the same queue,
or disable referential constraints on the objects involved in replication on the target
system. This is acceptable (and recommended for most replication strategies)
because the constraints are satisfied on the source system and replicated to the target
instance by SharePlex.
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.
To create a named post queue

Creating a configuration with named post queues is similar to creating a basic configu-
ration. The difference is that you add the named-queue information in the middle of an
objects routing map. In Template 4, the named queue specification is highlighted in
italics to show how a configuration with named post queues differs from a basic config-
uration.
Template 4: Configuration for creating named post queues
source_owner.table target_owner.table targetsys:queue_name@o.targetSID
start sp_ctrl.
Leave no space between any of these items. Datasource is not case-sensitive. The
SID is case-sensitive.
Datasource:o.SID
with a dot (.). Enclose case-sensitive items within double quotes, for example
"scott"."emp"; otherwise, SharePlex does not recognize case-sensitivity. Leave no
space between any of the items. Do not press Enter.
source_owner.object
8 Type at least a space or tab, then type the owner and name of the corresponding tar-
get object in the same manner as you did for the source object. Do not press Enter.
target_owner.object
9 Type at least a space or tab, then type the following information on the same line, in
sequence, with no spaces between them.
the name of the target system*
a colon (:)
the name you are giving the post queue (maximum 15 characters). Queue names
are case-sensitive on all platforms. Underscores are permissible.
the @ symbol
the o.
the target database ORACLE_SID (This is case-sensitive.)
targetsys:queue_name@o.targetSID
10 Repeat steps 6 through 9 for each table or sequence being replicated through the first
post queue.
CHAPTER 5 159
11 To create additional named post queues for other objects, repeat steps 5 through 9
using a new queue name.
12 When you finish, save the file with the :wq command if using vi or with Save on the
File menu if using WordPad, then exit the text editor. You are returned to the sp_ctrl
prompt. Your configuration should look something like the following example:
Example named post queue configuration for instance oraA on source system sysA
Datasource:o.oraA
scott.emp !key
scott.dest_emp sysB:Queue1@o.oraB
(name,ID)
scott.dest_cust sysB:Queue2@o.oraB
scott.cust
The preceding configuration will create the following post queues on target sys-
tem SysB:
Queue1 containing data from the table scott.emp (with long transactions) des-
tined for target instance oraB.
Queue2 containing transactions from scott.cust destined for instance oraB.
How named post queues are listed in status displays

A named post queue is identified by the datasource and either the name of an associated
named export queue (if named export queues are being used on the source system) or
the user-assigned post-queue name if a default export queue was used on the source sys-
tem. Queue names are case-sensitive on all platforms.
Tip: You can view the named post queues with the qstatus command, and you can view
them with their associated Post processes and other replication processes with the
show command. See Chapter 1 of the SharePlex Reference Guide for more information
about these commands.
Configuration for horizontally partitioned

replication
These instructions show you how to configure SharePlex for horizontally partitioned
replication, where different rows of a table are replicated to different target systems.
You can replicate all rows of a table in this fashion, or you can be more selective by
excluding some rows from replication altogether.
FIGURE 9: Horizontally
partitioned replication: In
this illustration, data in rows
where C1 = 2, 4 and 6 is rep-
licated to instance oraB.
Data in rows where C1 = 1, 3
and 5 is replicated to
instance oraC.
Horizontally partitioned replication can be combined with vertically partitioned replica-

tion. For example, a companys headquarters could use vertically partitioned replication
to replicate data from a subset of a tables columns to a reporting instance in each of its
regions. It can use horizontally partitioned replication to route the appropriate records to
each of those instances. For more information about vertically partitioned replication,
see page 172.
Horizontally partitioned replication can be used in conjunction with full-table replica-
tion for the same table, for example to route groups of rows to different reporting sys-
tems and all rows to a failover system. SharePlex does not support that combination
when vertically partitioned replication is also used for the same table.
Restrictions for using horizontally partitioned replication

Horizontally partitioned replication does not support the following:
UPDATEs or INSERTs on LONG columns larger than 100k.
Tables with LOB columns.
Replication of sequences.
TRUNCATEs of an Oracle partition.
Referencing other tables in a column condition.
Column conditions that include VARRAYs or abstract datatypes.
CHAPTER 5 161
Oracle TO_DATE function
Important! Using horizontally partitioned replication reduces replication performance.

The amount of reduction depends on the number of tables involved and their size.
Components of horizontally partitioned replication

To implement horizontally partitioned replication, you create the following components.
Partition schemes
Column conditions
Configuration entries
As you follow the instructions for creating these components, refer to the sample table
in Figure 10. It is the central table at a corporate headquarters. Different groups of rows
are replicated to target tables on systems in four regional headquarters.
FIGURE 10: Sample table

scott.employee_HQ
EmpNo number(4) not null
SocSec number(11) not null
EmpName char(30)
Job char(10)
Salary number(7,2)
Region char(20)
unique index employee_Idx on
employee_HQ(EmpNo)
Creating partition schemes and column conditions

You create one or more partition schemes for each table being configured for horizon-
tally partitioned replication. The partition scheme is a logical container for column con-
ditions.
A column condition defines a group of rows to be replicated. You can specify as many
column conditions as needed to route rows of a source table to different destinations.
You need not replicate all rows in a table.
For example, a simple partition scheme for the sample table in Figure 10 could have
four column conditions for replication:
Region = West
Region = South
Region = Midwest
Region = East
There could be a fifth value for the Region column, such as HQ, for which rows are not
replicated because the data is used locally, although those rows could be replicated with
the entire table to a backup system.
Planning for multiple partition schemes

There are almost limitless ways you can divide rows for replication.
You can create any number of partition schemes for a table.
Partition schemes can have different or overlapping column conditions.
All partition schemes for a table can be active at the same time (they are active if
they are listed in the configuration file and inactive if they are not).
If you plan to use numerous partition schemes, decide ahead of time their names and
which column conditions you want to create for each one.
Choosing columns for column conditions

When defining a column condition, use columns whose values will not change (such as
PRIMARY or UNIQUE key columns). Those values determine whether or not a row is
replicated. The following problems can occur when there are changes to columns in col-
umn conditions.
If a column condition value is updated and the new value no longer meets the col-
umn condition, SharePlex performs the operation, but future operations on that row
are not replicated. The tables become out of synchronization, but there are no errors
from Post to notify you of the situation.
If a row that does not meet a column condition is updated to meet the condition, the
next operation on that row returns out-of-sync errors. This happens because the row
was not replicated when it was inserted into the source database (it did not meet the
column condition). When the row is updated to meet the condition, SharePlex repli-
cates the update, but Post cannot locate the row because it never existed in the target
database. The operation fails and causes an error.
CHAPTER 5 163
If you expect values for columns in column conditions to change, you have the follow-
ing options for repairing rows for which updates to columns defined in a column condi-
tion cause out-of-sync conditions:
Set the SP_ORD_HP_IN_SYNC parameter so that SharePlex automatically detects
and corrects the out-of-sync condition. Enabling SP_ORD_HP_IN_SYNC causes
some performance degradation, depending on how many tables are configured for
horizontally partitioned replication. For more information about this parameter, see
the SharePlex Parameters chapter of the SharePlex Reference Guide.
Use the compare command. For more information about this command, see
Chapter 1 of the SharePlex Reference Guide.
Planning for column conditions that are not mutually exclusive

SharePlex maintains a cache of the column conditions for each partition scheme. It
reads through that cache whenever it receives a row change for a table which uses that
partition scheme. By default, SharePlex assumes that column conditions within a parti-
tion scheme are mutually exclusive, so it stops searching when it locates the first column
condition that the row satisfies and uses that conditions routing. No other conditions are
checked for that row change.
If you are using column conditions that are not mutually exclusive (such as when a
change to a record must be routed to different target tables), you can set the
SP_ORD_FIRST_FIND parameter to 0 so that SharePlex checks all of the column con-
ditions each time it receives a row change for a partition scheme.
Controlling the processing order of column conditions

You can control the order in which SharePlex checks the column conditions in a cache.
Referring to the sample table in Figure 10, for example, if you know that most of the
changes will be made to the Eastern regions data, you can direct SharePlex to check the
East column condition first, which improves overall replication performance because
the other conditions are not checked (unless SP_ORD_FIRST_FIND is set to 0).
You also can use the ordering option when column conditions in a partition scheme are
not mutually exclusive, directing SharePlex to process one before the other if it is more
important.
To create partition schemes and column conditions

For each group of rows to be replicated (each column condition), you define:
the partition scheme to which those rows belong
the conditional syntax that selects them

their routing
the order in which this condition is checked
Use standard INSERT statements to enter this information into the

SHAREPLEX_PARTITION table, which was installed unpopulated in the SharePlex
schema when you ran ora_setup. During configuration activation, SharePlex uses the
SHAREPLEX_PARTITION table to build a routing cache for each group of rows (as
defined by column conditions) in each partition scheme.
Use one SHAREPLEX_PARTITION table for all configurations that replicate data
from the same Oracle instance.
You can, but are not required to, use all of your partition schemes in a configuration
file. Only those that are listed in an active configuration file are active.
Issue the INSERT statement for the SHAREPLEX_PARTITION table on the source
system (the system on which you are activating the replication configuration). The fol-
lowing are the columns of the SHAREPLEX_PARTITION table, their datatypes, and
their size.
SHAREPLEX_PARTITION table
PARTITION_SCHEME VARCHAR2(30)
DESCRIPTION VARCHAR2(61)
TARGET_TABLE_OWNER VARCHAR2(30)
TARGET_TABLE_NAME VARCHAR2(30)
ROUTE VARCHAR2(1024)
PRIORITY NUMBER
ORDER NUMBER
OPTIONS VARCHAR2(32)
COL_CONDITIONS VARCHAR2(1024)
Note: When a column condition has multiple targets and not all target owners or table
names are the same, you need to issue an additional INSERT statement for each target
owner or name that is different. The SHAREPLEX_PARTITION table provides a column
for this. The most common owner and name should be listed as the target object on the
configuration line.
1 In the PARTITION_SCHEME column, enter the name of the partition scheme for
which you are creating a column condition. For example, the name of a scheme for
CHAPTER 5 165
the sample table in Figure 10 on page 161 could be EMP_SCHEME.
2 In the DESCRIPTION column, enter a description of the column condition. You can
enter a NULL value, but if you are creating numerous column conditions, it helps to
identify or describe each one. For example, the description of a column condition for
the sample table in Figure 10 on page 161 could be West Coast employees for
rows that are replicated to the companys Western region.
3 In the TARGET_OWNER column, enter one of the following for the target tables
owner:
a NULL value if the owner is the same as the owner that you are listing in the con-
figuration file. (Typically, all corresponding target table owners are the same.)
Or...
the target owner name if it is different from the one in the configuration file. This
value overrides the value in the configuration file for this route only. To enforce
case-sensitivity, enclose the string within double quotes, for example Jane.
4 In the TARGET_TABLE_NAME column, enter one of the following:

a NULL value if the table name is the same as the one that you are listing in the
configuration file. (Typically, all corresponding target table names are the same.)
Or...
the target tables name if it is different from the one in the configuration file. This
value overrides the value in the configuration file for this route only. To enforce
case-sensitivity, enclose the string within double quotes, for example
employee_West2.
5 In the ROUTE column, enter the SharePlex routing map* for this column condition.
FIGURE 11: Routing formats

Basic routing map targetsys@o.targetSID
Compound targetsys1@o.target_SID1 + targetsys2@o.target_SID2
routing map
Routing map with source_sys:queue_name*targetsys@o.targetSID

named export queue

Routing map with targetsys:queue_name@o.targetSID
named post queue
If you are routing the rows to one target system, use a basic routing map.
If you are routing the rows to more than one target system, you can use a com-
pound routing map if all of the corresponding target owners and names are identi-
cal on those systems.
If you are using named queues, use the appropriate syntax as shown in Figure 11.
You can use a compound routing map if all of the corresponding target owners and
names are identical.
6 In the PRIORITY column, enter a NULL value. This column is for use by SharePlex.
7 In the ORDER column, either enter a NULL value, or enter any positive number to
specify the order for checking this column condition. Column conditions are checked
starting with the one that has the lowest value in the ORDER column.
8 In the OPTIONS column, enter a NULL value. This field is used internally by Share-
Plex.
9 In the COL_CONDITIONS column, enter the conditional syntax for the columns
and values that define the rows to be replicated to the target table specified in step 4.
Do not include references to other tables in the column condition. SharePlex sup-
ports the following datatypes and conditional syntax, which can be combined into
nested expressions with parentheses and the AND, OR, and NOT logical connec-
tives.
Supported datatypes
CHAR
DATE
NUMBER
LONG VARCHAR
VARCHAR
VARCHAR2
Note: For the DATE datatype, SharePlex uses the nls_date_format, with the syntax
specified as MMDDSYYYYHH24MISS in the COL_CONDITIONS column. In the follow-
CHAPTER 5 167
ing example, hiredate is in the COL_CONDITIONS column with the DATE syntax spec-
ified as 1111 2011000000
hiredate<1111 2011000000
Note that the Oracle TO_DATE function is not supported in the configuration file.
Supported conditional syntax

In the following syntax, the variable 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).
NULLs are replicated by SharePlex in cases such as this one: not (department_id =
90). If department_id is NULL, then it is replicated. To avoid replicating records
with NULLs in a column condition, include the column is not null syntax as part of
the condition, for example: not (department_id = 90) and department_id is not
null.
column = value
not (column = value)
column > value
value > column
column < value
column >= value
column <= value
column <> value
column != value
column like value
column between value1 and value2
not (column between value1 and value2)
column is null
column is not null
Example column conditions:
not (col1 = 5)
(col2 = 5) and not (col3 = 6)
((col1 is not null) and (col2 = 5))
When 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.
Note: During configuration activation, SharePlex verifies the syntax in the column condi-
tion. If any syntax is incorrect, configuration activation fails. SharePlex prints an error to
the Event Log that indicates where the error was made.
10 Repeat these steps for each combination of partition scheme, column condition and
target object.
11 COMMIT the data to the database.
Creating configuration entries for horizontally partitioned

replication
Follow these instructions to create configuration entries for tables using horizontally
partitioned replication. Use one configuration file for all of the tables that you are repli-
cating, whether or not they are using partitioned replication. To create configuration
entries for tables not using partitioned replication, see page 145. To create configuration
entries for tables using vertically partitioned replication, see page 172.
Template 5: Configuration for horizontally partitioned replication

targ_own.tabl
srce_own.table !partition_scheme
e
! sysD@o.oraD
Note: The entry on the second line is needed only if a route in a partition scheme does
not exist on a configuration line.
start sp_ctrl.
2 At the sp_ctrl prompt, issue the create config command. In the syntax below, sub-
stitute the name of your configuration for filename. This command opens the text
editor.
CHAPTER 5 169
tive. The SID is case-sensitive.
Datasource:o.SID
6 On the next line, type the owner and name of the first source table to use horizon-
tally partitioned replication, separating them with a dot (.). Leave no space between
any of the items. Enclose case-sensitive items within double quotes, for example
"scott"."emp"; otherwise, SharePlex does not recognize case-sensitivity. Do not
press Enter after you type the source table information.
source_owner.object
8 Type at least one space or tab, then type the owner and name of the target table that is
common to most of the column conditions for the partition scheme to which the col-
umn condition you are defining belongs. Target tables with different owners or
names are specified by entering override values in the TARGET_TABLE_NAME
and TARGET_TABLE_OWNER columns of the SHAREPLEX_PARTITION table.
Do not press Enter.
target_owner.object
9 Type at least one space or tab, then type an exception marker (!) immediately fol-
lowed by the name of the partition scheme. Type the partition scheme name using the
same case and spelling as in the SHAREPLEX_PARTITION table.
!partition_scheme
Important! There is no compound routing capability for listing multiple partition schemes
for the same source table, for example !schemeA + schemeB. Each partition scheme
must be listed on a separate configuration line with a source and target table owner and
name.
10 Start a new configuration line and repeat steps 5 through 9 for each partition scheme.
11 Enter placeholder routing maps as needed. See To enter placeholder routing maps
following these steps before you close the configuration file to determine whether or
not you need to enter placeholder routing maps.
12 Save the file with the :wq command in vi or with Save on the File menu in WordPad,
and exit the editor.
To enter placeholder routing maps

All routing maps in a partition scheme must also be listed on a line somewhere in the
configuration file itself, in order for SharePlex to build its routing list. The requirement
usually is satisfied because partitioned replication generally is combined with full-table
replication. When using a route in a partition scheme but not in a regular (non-parti-
tioned) configuration entry, you must provide a placeholder routing map for that route
on a configuration line so that it is incorporated into the routing list.
If all routes used in your partition schemes exist on a line somewhere in the configura-
tion file, placeholders are not required, and you can close and save the configuration
file. Otherwise, do the following:
1 Press Enter to start a new configuration line.
2 Type an exception marker (!).
3 Type at least a few spaces or, if you are using tabs to maintain columns, tab to the
second or third column.
4 Type the routing map* using one of the following methods.

routing map
CHAPTER 5 171

named export queue

named post queue
If you are using default (not named) queues, use a basic routing map or a com-
pound routing map, depending on how many target systems you are listing.
Or...
If you are using named queues, use the appropriate syntax as shown in Figure 12.
5 Press Enter at the end of the line.
Repeat these steps for each placeholder that is needed.
Viewing and changing partition schemes

Because partition schemes are stored in an Oracle table, you can use a graphical data-
base tool such as Toad for Oracle to view them, or you can view them using regular
SQL statements. You can add, delete, or modify partition schemes while the replication
configuration is active. To perform any of these procedures, make the necessary
changes to the SHAREPLEX_PARTITION table and configuration file, then reactivate
the configuration. See Changing partitioned replication on page 319 for instructions.
Configuration for vertically partitioned replication

These instructions show you how to configure SharePlex for vertically partitioned repli-
cation, where a subset of the columns of a table are replicated to one or more target sys-
tems. The names of the target columns can be the same as, or different from, the names
of the source columns.
FIGURE 13: Vertically par-

titioned replication: In this
illustration, the data in col-
umns C1, C2, C3 and C4 is
replicated to instance oraB.
The data in columns C5 and
C6 is not replicated.
Vertically partitioned replication can be combined with horizontally partitioned replica-

tion. For example, a companys headquarters could use vertically partitioned replication
to replicate data from a subset of a source tables columns to a target table in a reporting
instance in each of its regions. The company can use horizontally partitioned replication
to route relevant records to those instances. For more information about horizontally
partitioned replication, see page 160.
Vertically partitioned replication is appropriate for reporting and other information dis-
tribution scenarios where replicating all of the columns of a table is not desirable. It is
not appropriate for high availability environments. Once you configure a table for verti-
cally partitioned replication, SharePlex does not recognize the other columns in its
object cache, and data in those columns is not replicated.
Restrictions for using vertically partitioned replication

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).
CHAPTER 5 173
There can be only one column partition per source table.

A target table can, but does not have to, contain all of the same columns as its source
table.
Source and target columns must have identical definitions, but their names can be
different. You specify column names in the configuration file.
Corresponding columns must contain the same datatypes (same type, size, preci-
sion).
Columns in the target table that are not part of the column partition and are NOT
NULL must have a default insert value; otherwise Posts INSERT statement will fail.
This is a normal Oracle requirement.
If a table is using horizontally and vertically partitioned replication together, all col-
umns used as column conditions in the partition scheme must be included in the col-
umn partition.
ALTER TABLE to add a column to a table configured for vertically partitioned repli-
cation is not supported.
Replication to multiple target systems

A vertically partitioned source table cannot be listed more than once in a configuration.
Therefore, replication of a vertically partitioned table to multiple target systems requires
a compound routing map. To use a compound routing map, all of a source tables target
tables must have the same owners and names.
Permissible:
scott.emp (c1,c2) scott.sal (c1,c2) targsysB@o.targSID + targsysC@o.targSID
Not permissible:
scott.emp (c1,c2) scott.sal (c1,c2) targsysB@o.targSID
scott.emp (c1,c2) scott.sales (c1,c2) targsysC@o.targSID
For more information about using a compound routing map, see Configuration for rep-
licating to multiple target systems on page 148. You can work around this limitation by
using horizontally partitioned replication. For more information, see page 160.
To create configuration entries for vertically partitioned

replication
To implement vertically partitioned replication, you specify a column partition or
excluded column partition in the configuration file. These define the columns for which
data is replicated.
Use one configuration file for all of the tables that you are replicating, whether or not
they are using partitioned replication. To create configuration entries for replication of
entire tables, see page 145. To create configuration entries for horizontally partitioned
replication, see page 160.
Template 6: Configuration for vertically partitioned replication

srce_own.table !key targ_own.table targsysB@o.targ-
(c1,c2) (c1) (c1,c2) SID
Note: The !key (c1) component is an optional key definition (see step 8).
start sp_ctrl.
tive. The SID is case-sensitive.
Datasource:o.SID
6 On the next line, type the owner and name of the first source table to use vertically
partitioned replication, separating them with a dot (.). Enclose case-sensitive items
within double quotes, for example "scott"."emp"; otherwise, SharePlex does not
CHAPTER 5 175
recognize case-sensitivity. Leave no space between any of the items. Do not press
Enter after you type the source table information.
source_owner.object
7 Type at least one space or tab after the source object. Proceed using on the following
two options:
A List the names of the source columns whose data will be replicated. This creates
the column partition. Use the following format.
Enclose the string of column names within parentheses.
Separate each column name with a comma (,). A space after the comma is
optional.
List any number of columns. The columns need not be contiguous in the
source table. For example, you can replicate the first, third and seventh col-
umns of a table. You need not replicate key columns, but it might help to
define one or more columns as a key. See step 8 for more information.
Allow long strings to wrap to the next line, if necessary but do not press
Enter within the string of column names, and do not press Enter when you
are done listing the columns.
(src_col_name1, src_col_name3, src_col_name7)
B List the names of the source columns whose data will NOT be replicated. This is
exclude column notation. This creates the excluded column partition. Use the
following format.
Use an exclamation point ! to indicate that the columns that follow, in the
parentheses, are excluded columns.
Enclose the string of excluded column names within parentheses.
Separate each excluded column name with a comma (,). A space after the
comma is optional.
List any number of excluded columns. The excluded columns need not be
contiguous in the source table. For example, you can exclude the second,
fourth, and eighth columns of a table. You need not replicate key columns, but
it might help to define one or more columns as a key. Excluded columns can-
not be used in the key definition. See step 8 for more information.
Allow long strings to wrap to the next line, if necessary but do not press
Enter within the string of column names, and do not press Enter when you
are done listing the columns.
not (src_col_name2, src_col_name4, src_col_name8)
Important: When using exclude column notation with vertically partitioned tables, the
corresponding source and target column names must be identical.
8 [OPTIONAL] If the table meets any of the following conditions, you can specify a key
definition:
the tables primary or unique key is not part of the column partition.
the table has no key.
the column partition has numerous columns.
A key improves replication performance. Without a key, SharePlex uses all of the
columns in the column partition as a key. The key column(s) that you define will be
replicated as part of the column partition.
To define a key, type a space after the column partition, then use the following syn-
tax, leaving a space between the !key component and the list of columns. Do not
press Enter.
Important! When using exclude column notation in vertical partitioning excluded col-
umns cannot be used in the key definition.
9 Type at least one space or tab on the configuration line, then type the owner and
name of the corresponding target table in the same manner as you did for the source
table. Do not press Enter.
target_owner.object
10 Do one of the following, depending on whether or not the names of the correspond-
ing source and target columns are identical.
If the source and target column names are identical, skip to step 11.
Or...
If the source and target column names are different, type a space after the target
tables name and list the target columns using the same syntax that you used to list
the source columns. List the target columns in the same logical order as their cor-
responding source columns so that SharePlex builds the correct correlations in the
object cache. For example, a change to the first column in the source list is repli-
cated to the first column in the target list. A change to the second source column is
CHAPTER 5 177
replicated to the second column in the target list, and so forth. Use this format
regardless of the actual order of the target columns in the table.
(targ_col_name1, targ_col_name2, targ_col_name3)
scott.employee_HQ mary.sales_W
EmpNo number(4) not null, RepName char(30) not null,
SocSec number(11) not null, SalesID number(4) not null,
EmpName char(30), CustCount number(7,2),
Job char(10), SalesVol number(7,2),
Salary number(7,2), Commis number(7,2),
Region char(20) Region char(20)
FIGURE 14: Source and target tables with dissimilar column names: To replicate data
from EmpNo to SalesID and from EmpName to RepName, you would list them on the con-
figuration line as follows: scott.employee (EmpNo, EmpName) mary.sales_W (SalesID,
RepName)
Do not press Enter after you are finished creating the target column component.
11 Type at least a space or tab on the configuration line, and then specify the routing in
one of two ways.
If you are using horizontally partitioned replication for the source table, type an
exception marker (!) and the name of the partition scheme using the same case and
spelling as in the SHAREPLEX_PARTITION table.
!partition_scheme
Or...
If you are not using horizontally partitioned replication for the source table, type
the routing map using one of the following methods.

routing map

named export queue

named post queue
--
--If the columns are replicated to one target system*, create a basic routing map.
--If the columns are replicated to more than one target system, use a compound rout-
ing map, because a vertically partitioned table cannot be listed more than once in
the configuration. The corresponding target owners and table names must be iden-
tical on all target systems.
--If you are using a named export queue, use the appropriate syntax as shown in
Figure 15.
13 Repeat steps 6 through 11 for each table that will use vertically partitioned replica-
tion.
CHAPTER 5 179
Scripting a configuration to replicate numerous

tables in a schema
The build_config.sql script enables you to build a configuration containing 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 each objects information and routing
individually, you can use a wildcard to select certain tables at once or with one key-
stroke, you can select all of the tables in the schema.
Conditions for using build_config.sql

Source and target table names must be the same.
The script does not support sequences. Before you activate the configuration, you
can use the edit config command in sp_ctrl to add entries for sequences.
The script does not support partitioned replication. You can use the copy config
command to copy the configuration, then use the edit config command to add
entries for tables that use partitioned replication. Activate the new configuration.
The script does not configure objects in the SharePlex, SYS and SYSTEM schemas.
These schemas cannot be replicated since they are system and/or instance-specific.
You can use the edit config command to make any other changes as needed after the
configuration is built. See Chapter 1 of the SharePlex Reference Guide for more
information about SharePlex commands.
Replicating multiple schemas

You can run build_config.sql for different schemas, then combine the resultant config-
urations into one configuration using a text editor. Make certain to eliminate all but one
Datasource:o.SID line, which must be the first non-commented line of the file. Do not
move the file out of the config sub-directory. For more information about configuration
construction, see Components of a SharePlex configuration on page 135.
To create a configuration using build_config.sql

1 Change directories to the config (configurations) sub-directory within the SharePlex
variable-data directory. The build_config.sql script puts configurations in the cur-
rent working directory, and SharePlex configurations must reside in the config sub-
directory for SharePlex to find and activate them.
$ cd /variabledata_dir/config
2 Log onto SQL*Plus as SYSTEM.

$ sqlplus SYSTEM/MANAGER
3 Run the script. Enter the full path name of the script, which resides in the util (utili-
ties) sub-directory within the SharePlex product directory.
SQL> @ /product_dir/util/build_config.sql
4 The script displays a series of prompts, beginning with a request for the target
machine. Refer to the following table for the prompts and what to enter.
CHAPTER 5 181
Prompt What you should enter
Target machine Enter the name of the target machine, for example SystemA, then
press Enter. A target systems name cannot include an underscore
(_), a dot (. ) or other non-alphanumeric character.
Source database SID Enter the ORACLE_SID of the source (primary) Oracle instance, for
example oraA, then press Enter. You need not enter o. before the
SID as when building a configuration in sp_ctrl. The ORACLE_SID
is case-sensitive.
Target database SID Enter the ORACLE_SID of the target (destination) Oracle instance,
for example oraB, then press Enter. You need not enter o. before the
SID. The ORACLE_SID is case-sensitive.
Owner of the source Enter the owner of the tables to be replicated, for example Scott, then
database tables press Enter.
Owner of the target Enter the owner of the target tables, for example Mary, then press
database tables Enter.
Table name to include At this prompt, do one of the following.

(blank for all) Enter nothing and press Enter if you want the script to select all
tables belonging to the source owner you specified.
Or
Enter the wildcard (%) character and a string if you want to
select certain tables, for example % e_slry&, then press Enter.
Or
Enter an individual table name, then press Enter. The script will
create a configuration for just one table even though it is
intended for configuring multiple tables.
The script configures source and target table names.
Name of the output file Enter a name for the configuration, then press Enter. The script gives
to create the file a .lst suffix, for example Scott_config.lst.
5 If any tables or owners are case-sensitive, open the configuration with the edit con-
fig command in sp_ctrl, and 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(sysA)> edit config filename
6 Save and close the file using the text editors standard save command.
7 To ensure that the configuration is in the correct location, issue the list config com-
mand. You should see its name in the display. See Chapter 1 of the SharePlex Refer-
ence Guide for more information about this command.
sp_ctrl(sysA)> list config
CHAPTER 5 183
Scripting a configuration to replicate an entire

database
The config.sql script enables you to automate construction of a configuration that lists
all of the tables and, optionally, all sequences in all of the schemas of a database. This
script saves time when establishing a high-availability replication strategy or other sce-
nario where you want the entire database to be replicated.
Conditions for using config.sql

The script does not configure objects in the SharePlex, SYS and SYSTEM schemas.
These schemas cannot be replicated since they are system and/or instance-specific.
The script does not support partitioned replication. You can use the copy config
command to copy the configuration, then use the edit config command to add
entries for tables that use partitioned replication. Activate the new configuration.
You can use the edit config command to make any other changes as needed after the
configuration is built. See Chapter 1 of the SharePlex Reference Guide for more
information about SharePlex commands.
To create a configuration using config.sql

1 Change directories to the config (configurations) sub-directory within 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-direc-
tory for SharePlex to find and activate them.
$ cd /variabledata_dir/config
2 Log onto SQL*Plus as SYSTEM.

$ sqlplus SYSTEM/MANAGER
3 Run the script. Enter the full path name of the script, which resides in the util (utili-
ties) sub-directory within the SharePlex product directory.
SQL> @ /product_dir/util/config.sql
4 The script displays a short series of prompts, beginning with a request for the target
machine. Refer to the following table for the prompts and what to enter.
Prompt What you should enter
Name of the Target Enter the name of the target machine, for example SystemA, then press
machine Enter. A target systems name cannot include an underscore (_), a dot (.)
or other non-alphanumeric character.
Source Database SID Enter the ORACLE_SID of the source (primary) Oracle instance, for
example oraA, then press Enter. You need not enter o. before the SID as
when building a configuration in sp_ctrl. The ORACLE_SID is case-
sensitive.
Target Database SID Enter the ORACLE_SID of the target (destination) Oracle instance, for
example oraB, then press Enter. You need not enter o. before the SID.
The ORACLE_SID is case-sensitive.
Replicate Sequences Enter either y or n, depending on whether or not you are replicating
(y/n) sequences, then press Enter. Generally, sequences are replicated for
high-availability replication, but not for reporting or peer-to-peer replica-
tion. For more information about sequences and replication, see
page 106.
Shareplex oracle Enter the name of the SharePlex Oracle user, then press Enter. This pre-
username vents 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 this
script again to create another configuration, it overwrites the first file. To preserve the
original file, rename it before you create the second one.
5 If any tables or owners are case-sensitive, open the configuration with the edit con-
fig command in sp_ctrl, and 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 for case-sensitivity.
sp_ctrl(sysA)> edit config filename
6 To make certain the configuration is in the correct location, issue the list config
command. You should see its name in the display. See Chapter 1 of the SharePlex
Reference Guide for more information about this command.
sp_ctrl(sysA)> list config
7 Save and close the file using the text editors standard save command.
CHAPTER 5 185
Part 2: Establishing replication
Your replication strategy (as defined in Chapter 4) determines how to configure Share-
Plex and prepare the Oracle instance and the servers for replication. The instructions in
this part of the chapter address unique requirements for each replication strategy. If you
have not done so already, review the basic data and system requirements in
Chapter 4.
Configuration templates, examples and instructions are provided for:
Establishing replication for high availability and data recovery
Establishing replication for data distribution or distributed processing
Establishing replication through an intermediary system
Establishing combined cascading/broadcast replication
Establishing replication for centralized reporting (standard method)
Establishing replication for centralized reporting using multiple sp_cop processes
A template for creating the appropriate configuration(s) for each strategy is provided.
Conventions used in the examples

The examples in these instructions use system names such as sysA, sysB, and sysC, and
Oracle instances with SIDs such as oraA and oraB.
For simplicity, the word table is used, but the same procedures generally apply to
sequences, except where noted.
This configuration from one Oracle instance to another is the most simple. It is a uni-
directional configuration replicating either to another system or to other tables on the
same system. The following examples show you the different ways to establish a report-
ing instance. Template 7 applies to all variations of a reporting instance.
Template 7: Configuration to replicate for reporting

To establish reporting from one system to another

If replication is used only for reporting, without the intention of data recovery, the
ORACLE_SIDs can different on the source and target systems. A target tables owner
and name can be the same as those of the source table, or one or both can be different.
Example configuration on source system sysA

Datasource:o.oraA
scott.emp bill.emp2 sysB@o.oraB

Install SharePlex and run ora_setup in the normal manner. See page 407 for instruc-
tions.
Referring to Template 7, create a configuration. If you are using vertically parti-
tioned replication for a table, include the column partition or excluded column par-
tition (see page 174). If you are using horizontally partitioned replication for a
table, create partition schemes and use them in the routing map (see page 160). Rep-
licating sequences for reporting is not necessary, so do not include them in this con-
figuration. If all of the source tables are in the same schema and the source and target
table names are the same, you can use the build_config.sql script (see page 179).
CHAPTER 5 187

Create the target instance, unless you will be using an Oracle hot backup to synchro-
nize the data. If you are using an Oracle hot backup or DBCopy, you will create the
target instance when you follow the synchronization procedure.
tions. Do not run ora_setup if you are establishing the target instance with a hot
backup or DBCopy. You will be instructed to do so by the synchronization procedure
after the target instance is established.
On both systems
Before you synchronize data to begin replication, ensure that all data and system
issues have been addressed according to the guidelines in Chapter 4.
Perform initial synchronization by making a copy of the source data, applying it to
the target instance, and activating the configuration. Use any of the procedures in
Chapter 7 for the correct sequence of events to follow.
To establish reporting from one instance to another on the

same system (UNIX only)
This configuration is only possible on UNIX systems. Source tables are replicated to a
different instance on the same system (from oraA to oraB in this example). In this con-
figuration, a target tables owner and name can be the same as those of the source table,
or one or both can be different.
Example configuration on sysA

Datasource:o.oraA
scott.emp scott.emp sysA@o.oraB
Install SharePlex in the normal manner. See the SharePlex Installation and Demon-
stration Guide for instructions.
Create the target instance, if necessary.
Run ora_setup for each instance. See page 407 for instructions.
issues have been addressed according to the guidelines in Chapter 4 for the tables
required for reports and queries.
Referring to Template 7 on page 186, create a configuration with the source

instances ORACLE_SID as the datasource. If you are using vertically partitioned
replication for a table, include the column partition or excluded column partition
(see page 174). If you are using horizontally partitioned replication for a table,
create partition schemes and use them in the routing map (see page 160). Specify the
local machines name and the target instances ORACLE_SID in the routing map.
Replicating sequences for reporting instances is not necessary, so do not include
them in this configuration. If all of the source tables are in the same schema and the
names of corresponding source and target tables are identical, you can use the
build_config.sql script as instructed (see page 179).

the target instance, and activating the configuration. See Chapter 7 for an appropriate
procedure to follow.
To establish replication between tables in the same instance

(UNIX systems)
This configuration is only possible on UNIX systems. Source tables are replicated to
different tables within the same Oracle instance. A target tables name can be the same
as that of the source table, but their owners must be different in order for this configura-
tion to succeed.
Example configuration on sysA

Datasource:o.oraA
scott.emp mary.emp sysA@o.oraA
Install SharePlex in the normal manner. See the SharePlex Installation and Demon-
stration Guide for instructions.
Run ora_setup for this instance. See page 407 for instructions.
Referring to Template 7 on page 186, create a configuration using this instances
ORACLE_SID as the datasource and as the target instance in the routing map. If you
are using vertically partitioned replication for a table, include the column partition
or excluded column partition (see page 174). If you are using horizontally parti-
tioned replication for a table, create partition schemes and use them in the routing
map (see page 160). Specify the local systems name in the routing map.
CHAPTER 5 189
Replicating sequences for reporting is not necessary, so do not include them in this
configuration.
the target tables, and activating the configuration. See Chapter 7 for an appropriate
procedure to follow.
To establish reporting in combination with data recovery

and
high availability from one system to another
Depending on the environment, you can use a reporting instance as a backup for failover
from the primary instance if the source and target instances are identical, including cor-
responding source and target tables owners and names. Using the target instance for
high availability is not appropriate with ERP applications, because there can be conflict
between the H/A tables and the reporting tables.
If your environment permits this configuration, follow the instructions in "Establishing
replication for high availability and data recovery," on page 190.
Establishing replication for high availability and

data recovery
The goal for data recovery and high availability is to have a duplicate of the primary
instance ready on the secondary system for immediate failover. The same objects exist
in both databases, and the owners and names of corresponding source (primary) and tar-
get (secondary) objects are identical. Partitioned replication is not appropriate for this
configuration. This strategy uses bi-directional replication with two configurations that
are the reverse of each other. The configuration on the secondary (standby) machine
CHAPTER 5 191
remains in an activated state with the Export process on that system stopped in readiness
for failover.
Template 8: High availability configuration on the primary system

Important! For high availability, the owner and table names of the primary objects must
be identical to those of their corresponding secondary objects.
Datasource:o.primarySID
primary_owner.tab secondary_owner.tab secondarysystem@o.secondary-
le le SID
Example configuration on primary system sysA

Datasource:o.oraA
scott.emp scott.emp sysB@o.oraA2
Template 9: High availability configuration on the secondary system

Datasource:o.secondarySID
primary_owner.tabl
secondary_owner.table primarysystem@o.primarySID
e
This is intentionally the reverse of the configuration on the primary system.
Example reverse configuration on secondary system sysB

Datasource:o.oraA2
scott.emp scott.emp sysA@o.oraA
On the primary system
tions.
Referring to Template 8 on page 191, create a configuration on the primary system
that replicates to the secondary system. Include sequences in the configuration. To
replicate all of the tables and sequences in the database, use the config.sql script to
simplify the configuration process (see page 183).
On the secondary system

For high availability, you can use an Oracle hot backup or DBCopy to synchronize
the data, and this will create the secondary instance but if you are not using one of
those methods, create the secondary instance now.
tions. Do not run ora_setup if you are establishing the secondary instance with a hot
backup or DBCopy; you will be instructed by the synchronization procedure to do
this after the secondary instance is established.
Stop the Export process on the secondary system so that nothing accidentally hap-
pening on the secondary system (such as a scheduled job changing data) gets repli-
cated back to the primary system.
Note: During replication, you can verify whether or not there were changes made to the
secondary instance. View the status of the export queue on the secondary system using
the qstatus command in sp_ctrl. It 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, unless the
SP_OCT_REPLICATE_POSTER parameter has been enabled. See the SharePlex
Parameters chapter of the SharePlex Reference Guide for more information about
SharePlex commands and parameters.
Referring to Template 9 on page 191, create a reverse configuration on the secondary

system to replicate the same tables from the secondary system to the primary system.
Specify the secondary instance as the datasource, and specify the primary instance
and system in the routing map. After the data is synchronized, activate this configu-
ration so that it is ready to replicate when users fail over to this system. Export must
remain stopped.
Create a script that denies INSERT, UPDATE and DELETE operations to all users
except SharePlex.
For failover
Make the applications used on the primary system available on the secondary sys-
tem.
Copy non-replicated database objects and critical files outside the instance to the
secondary system.
Create a script that grants INSERT, UPDATE and DELETE privileges to all users
that can be run during a failover procedure.
Create a script that enables constraints on the secondary system to be used during a
failover procedure. (You will disable the constraints during the synchronization pro-
cess.)
Develop a failover procedure for relocating users to the secondary system.
If you used an Oracle hot backup procedure to create the secondary instance, keep
the script that you ran. It can be modified to re-create the primary instance.
CHAPTER 5 193
Maintain backups of replication files as recommended in Regular SharePlex back-

ups on page 129.
See Using SharePlex in a High-Availability Environment on page 321 to familiar-
ize yourself with failover and failback procedures on machines running SharePlex.
On both systems
Perform initial synchronization by making a copy of the primary data, applying it to
the secondary instance, and activating the configuration. Use any of the procedures
in Chapter 7 for the correct sequence of events to follow. You can use an Oracle hot
backup (see page 289) so that users can continue accessing the primary database.
Maintain backups of replication files as recommended in Regular SharePlex back-
ups on page 129.
Establishing replication for data distribution or

distributed processing
Data distribution and distributed processing employ broadcast replication through a

direct network connection to each target system.
Data distribution typically replicates all tables in the configuration to all of the target
systems in the configuration.
Distributed processing replicates different sets or subsets of tables to different target
systems to split up processing. Distributed processing assumes that the processing on
the target systems is for queries, output and reporting only. If your intention is for users
to make DML transactions on the target data, see page 211 to establish a peer-to-peer
replication environment.
In both strategies, the owner and name of a target table can be the same as those of the
source table, or one or both can be different. For data distribution, all of a source tables
target tables can have the same owners and names or different ones.
Template 10: Configuration to distribute data when target table owners

and names are the same
If the owners and names of all corresponding target tables are the same on all target sys-
tems, you can use a compound routing map. For assistance with creating a compound
routing map, see page 148.
srce_own.table targ_own.table targsysB@o.targSID + targsysC@o.targSID

Datasource:o.oraA
scott.prod scott.prod sysB@o.oraB + sysC@o.oraC + sysD@o.oraD
CHAPTER 5 195
Template 11: Configuration to distribute data when target table owners

and names are different
If the owners and/or names of corresponding target tables are different on any target
systems, use this configuration. This configuration can be combined with the configura-
tion in Template 10.
source_owner.table target_owner.tabl
1 e1 targetsysB@o.targetSID
source_owner.table target_owner.tabl targetsysC@o.targetSID
1 e2

Datasource:o.oraA
scott.emp jane.emp sysB@o.oraB
scott.emp joe.prod sysC@o.oraC
scott.emp mary.cust sysD@o.oraD
Template 12: Configuration for distributed processing

In this configuration, the owners and names of target tables can be the same as, or differ-
ent than, those of the source tables.
target_owner.tabl
source_owner.table1 e1 targetsysB@o.targetSID
source_owner.table2 target_owner.tabl targetsysC@o.targetSID
e2

Datasource:o.oraA
scott.emp scott.emp sysB@o.oraB
scott.sales scott.sales sysC@o.oraC
scott.prod jane.prod sysD@o.oraD

tions.
Create a configuration, referring to Template 10, Template 11 or Template 12. If you
are using vertically partitioned replication for a table, include the column partition
or excluded column partition (see page 174). If you are using horizontally parti-
tioned replication for a table, create partition schemes and use them in the routing
map (see page 160). To replicate sequences for distributed processing, include them
in this configuration. As an alternative, give each system its own unique range of
sequences. Another option is for all systems to access the same sequences using
database links.
On the target systems

Create the target instance unless you will be using an Oracle hot backup or DBCopy
to synchronize the data. If you are using an Oracle hot backup or DBCopy, you will
create the target instance when you follow the synchronization procedure.
On both systems
the target instance, and activating the configuration. Use any of the procedures in
Chapter 7 for the correct sequence of events to follow.
CHAPTER 5 197
Establishing replication through an intermediary

system
Cascading replication replicates data from the source system to an intermediary system,
and then from the intermediary system to one or more remote target systems that do not
have direct network connections to the source system. The owners and names of corre-
sponding source and target tables can be the same or different on any of the systems in
the replication route. To use a cascading strategy, the source machine must be able to
resolve the target machine name(s), but the target machines need not be reachable from
the source machine.
There are two possible ways to configure this strategy.
Scenario A: Replication to intermediary and target
instances. You can replicate and post to an Oracle
instance on the intermediary system, and then have the
Capture process on that system replicate those changes
to Oracle databases on one or more remote (target) sys-
tems.
Scenario B: Replication through the intermediary
system to the target instance. You can use the inter-
mediary system to pass the replicated data to the
remote (target) systems without posting it to a database
on the intermediary system. In that case, Oracle must
be installed and an ORACLE_SID must exist in the
oratab file (UNIX systems) or the Windows Registry,
but the database need not be populated.
Warning! DDL replication is not supported from an intermediary system to target sys-
tems. It is supported only from the source system to the intermediary system.
To replicate to instances on the intermediary and target

system
Use these templates to post replicated changes to an Oracle instance on the intermedi-
ary system and also to forward them to the target system for posting to an Oracle
instance there (Scenario A).
Template 13: Cascading replication configuration on the source system

source_own.table intermed_own.table intermedsystemB@o.intermedSID

Datasource:o.oraA
HQ.price Reg.price sysB@o.oraB
Template 14: Cascading replication configuration on the intermediary

system*
Datasource:o.intermedSID
intermed_own.tabl target_own.tabl targsysC@o.targSID + targsysD@o.targ-
e e SID
*Note: To list multiple target systems in one routing map, all corresponding target tables
must have identical owners and names on all target systems. Otherwise use a separate
line for each set of source-target tables where owners and/or names are different. See
page page 148 for more information.
Example configuration on intermediary system sysB

Datasource:o.oraB
Reg.price Loc.price sysC@o.oraC + sysD@o.oraD
CHAPTER 5 199
To replicate through the intermediary system to the target

instance only
Use this template to use the intermediary system only as a pass-through system, with-
out posting to an Oracle database there (Scenario B). In this scenario, a configuration is
unnecessary on the intermediary system. You can replicate to multiple targets through
the intermediary system as shown in the template.
Template 15: Cascading replication configuration on the source system*

intermedsystemB*targsysC@o.targSID
source_own.table target_own.table
+
intermedsystemB*targsysD@o.targSID
*Note: To list multiple target systems in one routing map, all corresponding target
tables must have identical owners and names on all target systems. Otherwise use a
separate line for each set of source-target tables where owners and/or names are differ-
ent. See page page 148 for more information.

Datasource:o.oraA
HQ.price Reg.price sysB*sysC@o.oraC + sysB*sysD@o.oraD
Establishing cascading replication for both methods

tions.
Do one of the following:
For Scenario A: Referring to Template 13 on page 198, create a uni-directional con-
figuration replicating to the database on the intermediary system. If you are using
vertically partitioned replication for a table, include the column partition or
excluded column partition (see page 174). If you are using horizontally partitioned
replication for a table, create partition schemes and use them in the routing map (see
page 160).
If there are numerous source tables with the same names as their target tables, and if
all source tables are in the same schema, you can use the build_config.sql script to
build the configuration (see page 179). Or, use the config.sql script to configure the
entire database (see page 183).

For Scenario B: Referring to Template 15 on page 199, create a uni-directional con-
figuration that replicates to the target system using the intermediary system as a pass-
through only (no active configuration). If you are using vertically partitioned repli-
cation for a table, include the column partition or excluded column partition (see
page 174). If you are using horizontally partitioned replication for a table, create
partition schemes and use them in the routing map (see page 160).
On the intermediary system

Establish an Oracle instance in one of the following ways:
For Scenario A: Create the intermediary instance, unless you will be using an Oracle
hot backup or DBCopy to synchronize the data. If you are using an Oracle hot
backup or DBCopy, you will create the intermediary instance when you follow the
synchronization procedure.
For Scenario B: You need not create a full Oracle database. Only an Oracle installa-
tion (with libraries) and a valid ORACLE_SID in the oratab file (UNIX) or Registry
(Windows) are required.
Install SharePlex in one of the following ways:
For Scenario A: Install in the normal manner following the instructions in the Share-
Plex Installation and Demonstration Guide. Because SharePlex will be replicating to
an Oracle instance on this machine, run ora_setup for that instance in the normal
manner. Do not run ora_setup if you are establishing the intermediary instance with
a hot backup or DBCopy; you will be instructed to do so by the synchronization pro-
cedure after the instance is established.
For Scenario B: Install SharePlex in the normal manner following the instructions in
the SharePlex Installation and Demonstration Guide. It is not necessary to run
ora_setup on this system.
(Scenario A only) Referring to Template 14 on page 198, create a basic or multi-tar-

get configuration that replicates to the target system or systems. If you are using ver-
tically partitioned replication for a table, include the column partition or excluded
column partition (see page 174). If you are using horizontally partitioned replica-
tion for a table, create partition schemes and use them in the routing map (see
page 160).
(Scenario A only) 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, mean-
ing that Capture ignores Post activity on the same system.)
CHAPTER 5 201
To change the setting of SP_OCT_REPLICATE_POSTER

1 Start SharePlex and sp_ctrl, and issue the following command in sp_ctrl. The
change takes effect the next time Capture starts.
sp_ctrl(sysB)> set param SP_OCT_REPLICATE_POSTER 1
2 You can either exit sp_ctrl and shut down SharePlex or leave them both running,
depending on what is required by the synchronization procedure you are follow-
ing.

Create the target instance, unless you will be using an Oracle hot backup or DBCopy
to synchronize the data. If you are using an Oracle hot backup or DBCopy, you will
create the intermediary instance when you follow the synchronization procedure.
On all systems
Perform initial synchronization by:
--making a copy of the source data.
--applying the copy to the intermediary system (Scenario A only) and to the target
systems (both scenarios).
--activating the configuration on the intermediary and/or source system.
Choose an appropriate synchronization procedure from the ones in Chapter 7.
Establishing combined cascading/broadcast

replication
You can combine broadcast replication with pass-through cascading replication within
the same configuration, as shown in the illustration. A target table can have the same
owner and name as its source table, or one or both can be different.
If the owner and name is the same on all target systems, use Template 16.
If any owner or name is different, create a separate line for that set of source-target
objects. See page 148 for instructions
If you are using vertically partitioned replication for a table, include the column parti-
tion or excluded column partition (see page 174). If you are using horizontally parti-
tioned replication for a table, create partition schemes and use them in the routing map
(see page 160).
Template 16: Configuration combining broadcast and cascading

replication
target_own.tab
source_own.table intermedsystemB*targsysC@o.targSID +
le
targsysD@o.targSID

Datasource:o.oraA
HQ.price Reg.price sysB*sysC@o.oraC + sysD@o.oraD
In the example, the source table is being replicated from SysA through SysB to target
system SysC, and it is being replicated through a direct network connection to SysD.
CHAPTER 5 203
To establish replication, follow the instructions in Establishing replication for data dis-
tribution or distributed processing on page 194 and Establishing replication through
an intermediary system on page 197.
Establishing replication for centralized reporting

(standard method)
Centralized reporting uses consoli-

dated replication, in which multi-
ple source systems replicate
different tables to the same Oracle
instance on one target system.
Replicating the same tables from
different source systems (where
users perform DML) to a central
database is not consolidated repli-
cation; it is peer-to-peer replica-
tion. To establish peer-to-peer
replication, see page 211.
Considerations for
centralized reporting
When you start replication, Share-
Plex creates an Import process for
each source system on the central
target system. That, in turn, creates
post queues and Post processes for
each replication stream, all con-
trolled by one sp_cop process.
These post queues share the same
SharePlex variable-data directory FIGURE 16: Centralized reporting using a sin-
gle instance of sp_cop.
on the central target system.
CHAPTER 5 205
Depending on the systems resources, this might cause contention for the same queue
resources and semaphores. To avoid contention, you can establish separate variable-data
directories on the central target system, one for each source system. This involves run-
ning multiple instances of sp_cop, which enable you to isolate the replication stream
for each source system so that events affecting one do not affect the others. To establish
consolidated replication using separate sp_cop processes, see page 207.
The following instructions are for consolidated replication using a single instance of
sp_cop.
Template 17: Configuration for centralized reporting with one sp_cop

instance
Create this configuration on each source system. Each configuration replicates a differ-
ent set of tables. A target table can have the same owner and name as its source table,
or one or both can be different.
The following configuration examples show two source systems, sysA and sysB, both
replicating to target system sysC.

Datasource:o.oraA
sales.dat sales.dat sysC@o.oraC
Example configuration on source system sysB

Datasource:o.oraB
cust.dat cust.dat sysC@o.oraC
On the source systems

Install SharePlex on each source system (sysA and sysB) in the normal manner and
run ora_setup for the source instance. See page 407 for instructions.
Referring to Template 17, create configurations on each source system that replicate
to the central target system (sysC). If you are using vertically partitioned replica-
tion for a table, include the column partition or excluded column partition (see
page 174). If you are using horizontally partitioned replication for a table, create
partition schemes and use them in the routing map (see page 160). Sequences need
not be replicated for reporting or archiving, so do not include them in the configura-
tions.
Important! Each configuration must replicate a different set of objects.
On the central target system

Create the target instance so that all tables from all of the source systems exist in that
database. If you want to use a hot copy as part of this process, combine it with cold-
copy methods as instructed in the synchronization procedure.
Install SharePlex and run ora_setup for the target instance in the normal manner.
See page 407 for instructions.
On all systems
Perform initial synchronization by making a copy of the source data on each source
system, applying it to the target instance, and activating the configurations. You can
do this one source system at a time, or you can copy and apply the data from all sys-
tems at once. A hot-copy method (Oracle hot backup or DBCopy hot copy) can be
combined with cold-copy methods for this, but the hot copy only can be used to copy
the data for one source system. A hot copy overwrites existing data, so you must use
a cold-copy method such as import/export for the other source systems, or use the
transportable tablespace feature. See Chapter 7 for the appropriate procedures to fol-
low.
CHAPTER 5 207
Establishing replication for centralized reporting

using multiple sp_cop processes
Use this configuration for central reporting to isolate the replication stream from each
source system. This method establishes separate variable-data directories on the central
target system. Each variable-data directory is controlled by a separate instance of
sp_cop, each running on a different port number.
Running multiple instances of sp_cop avoids contention for queue resources and sema-
phores. In addition, it gives you the option to locate the variable-data directories on sep-
arate disks to ensure that events affecting one replication stream do not affect the others.
FIGURE 17: Centralized report-

ing using separate variable-data
directories and multiple instances
of sp_cop.
Replication for centralized reporting through separate variable-data directories is imple-

mented in several steps, as summarized below. Detailed instructions follow.
Install SharePlex on each source system.
Create a configuration on each source system that replicates to the central reporting
instance on the target system. Replicate different source tables to the target system.
To replicate the same tables from different systems to the target system is peer-to-
peer replication. To establish peer-to-peer replication, see page 211.
Create multiple variable-data directories on the target system, one for each source
system, which isolate each source systems replication streams.
Establish unique port numbers for each variable-data directory, which will enable
simultaneous sp_cop instances to run on the target systemone for each source sys-
tem.
Create separate Oracle user accounts for each sp_cop instance
Template 18: Configuration for centralized reporting using separate

sp_cop instances
Create this configuration on each source system. Each configuration replicates a dif-
ferent set of tables. A target table can have the same owner and name as its source
table, or one or both can be different.
The following configuration examples show two source systems, sysA and sysB, both
replicating to target system sysC.

Datasource:o.oraA
sales.dat sales.dat sysC@o.oraC
Example configuration on source system sysB

Datasource:o.oraB
cust.dat cust.dat sysC@o.oraC
On the central target system

Create the target instance so that all tables from all of the source systems exist in that
database. If you want to use a hot copy as part of this process, combine it with cold-
copy methods as instructed in the synchronization procedure.
CHAPTER 5 209
Install SharePlex in the normal manner on the target system, but do not run
ora_setup yet.
Follow the instructions in Running multiple instances of SharePlex on page 64 to
create one new SharePlex variable-data directory on the target system for each
source system. For example, if you are replicating from sysA and sysB to target
sysC, create one variable-data directory for sysA and one for sysB on sysC.
Those instructions also show you how to create an Oracle user account for each of
the variable-data directories, how to set a port number for each one, and how to start
the associated instances of sp_cop and sp_ctrl. Make sure the system has enough
disk space to accommodate the data received from all of the source systems.
On the source systems

Install SharePlex on each source system in the normal manner and run ora_setup for
the source instance. See page 407 for instructions.
--For each Windows source system, install on the port number that corresponds to its
variable-data directory on the target system.
--For each UNIX source system, change the SharePlex port number after installation
to the port that corresponds to its variable-data directory on the target system. That
way, you avoid having to export the SharePlex environment variables every time
you start sp_cop. See Setting an alternative port for sp_cop on page 259.
Referring to Template 18 on page 208, create a configuration on each source system
that replicates to the central target system. If you are using vertically partitioned
replication for a table, include the column partition or excluded column partition
(see page 174). If you are using horizontally partitioned replication for a table,
create partition schemes and use them in the routing map (see page 160). Sequences
need not be replicated for reporting or archiving, so do not include them in the con-
figurations.
Important! Each configuration must replicate a different set of objects.

On all systems
Perform initial synchronization by making a copy of the source data on each source
system, applying it to the target instance, and activating the configurations. You can
do this one source system at a time, or you can copy and apply the data from all sys-
tems at once. A hot-copy method (Oracle hot backup or DBCopy hot copy) can be
combined with cold-copy methods for this, but the hot copy only can be used to copy
the data for one source system. A hot copy overwrites existing data, so you must use
a cold-copy method such as import/export for the other source systems, or use the
transportable tablespace feature. See Chapter 7 for the appropriate procedures to fol-
low.
CHAPTER 5 211
Peer-to-peer replication allows users on multiple databases to make changes concur-

rently to the same data, while SharePlex replication keeps all of the databases synchro-
nized. 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 pack-
aged applications are in use. It also requires PL/SQL conflict resolution routines that
control which transactions to accept for posting to the target database when more than
one user changes the same record at, or near, the same time.
Challenges in peer-to-peer replication

Peer-to-peer replication presents unique challenges not found in single-direction repli-
cation situations like replicating from a production server to a secondary system for
reporting purposes. In those configurations, there is never DML access to the secondary
system. In peer-to-peer replication, however, different users all make DML changes to
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.
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:
Conflict occurs when an INSERT is performed on the source system, but the
row already exists in the target database when SharePlex attempts to post it.
To construct the INSERT statement, SharePlex uses all of the columns. If SharePlex
attempts to insert a row containing a key that already exists in the target table, an out-
of-sync error results because Oracle generates a unique-key violation error.
SharePlex statement:
SQL> INSERT into scott.employee_source values (emp_seq.nextval, Mary
Smith, Manager, 50000, 1);
Conflict occurs when an UPDATE is performed on the source system, but the
image of the row on the source system before the change was made does not
match the existing values in the target row.
This implies that another user already either changed the target row or deleted it. In
constructing an UPDATE statement to be applied to the target database, SharePlex
uses the primary key to locate the row. In addition, SharePlex constructs a WHERE
clause consisting of the pre-image of the updated columns the values before the
change. If the pre-images and the keys match in the source and target rows, Share-
Plex posts the operation. If the pre-images do not match, or if SharePlex cannot
locate the row using the key, the SQL statement fails and SharePlex returns an out-
of-sync error.
User statement on the source: SharePlex statement on the target:

SQL> UPDATE SQL> UPDATE
scott.employee_src scott.employee_source
SET Salary = 32000 SET Salary = 32000
WHERE EmpNo = 3 WHERE EmpNo = 3
AND Salary = 30000;
(30000 is the amount before the salary
value was updated to 32000.)
Conflict occurs when a DELETE is performed on the source system, but Share-
Plex cannot locate the row to be deleted on the target system.
To construct a DELETE statement to remove a row from the target database, Share-
Plex uses only the key value in the WHERE clause. If the key is unavailable on the
target system, either because the row already was deleted or the key column(s)
changed, SharePlex cannot locate the row and returns an out-of-sync error.
SharePlex statement:
SQL> DELETE from scott.employee_source
WHERE EmpNo = 3;
Examples of conflict situations

To understand how SharePlex determines a conflict, refer to the following examples of
normal and conflict situations. For the sake of simplicity, three systems (SysA, SysB
CHAPTER 5 213
and SysC) are used, but there could be more systems replicating among one another.
The following table is used in the example.
FIGURE 18: Sample Table for peer-to-peer replication

PRIMARY TABLE (owned by scott) SECONDARY TABLE (owned by jane)
Employee_source Employee_backup
EmpNo number(4) not null, EmpNo number(4) not null,
SocSec number(11) not null, SocSec number(11) not null,
EmpName char(30), EmpName char(30),
Job char(10), Job char(10),
Salary number(7,2), Salary number(7,2),
Dept number(2) Dept number(2)
unique index employee_Idx on unique index employee_bk on
employee_source(EmpNo) employee_backup(EmpNo)
Values for both tables
EmpN SocSec EmpName Job Salary Dept

o 111-22-3333 Mary Smith Manager 50000 1
1 111-33-4444 John Doe Data Entry 20000 2
2 000-11-2222 Mike Jones Secretary 30000 3
3 000-44-7777 Dave Brown Manager 45000 3
4
Example of peer-to-peer replication without a conflict

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 data-
bases remain synchronized.
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:
FIGURE 19: Updated Dept column for Emp No 1
EmpNo SocSec EmpName Job Salary Dept
1 111-22-3333 Mary Smith Manager 50000 3
Example of peer-to-peer replication with an UPDATE conflict

This example is illustrated in Figure 20 on page 215.
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. Replicated changes queue on all systems.
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. Replica-
tion data transmission resumes.
When SharePlex attempts to post UserAs change to the database on SysB, it expects the
value in the Dept column to be 3 (the pre-image, as shown in Figure 19), but it is not
it is 2 because of UserBs change. The pre-images do not match, so SharePlex deter-
mines that the row is out of synchronization and it generates an error.
When SharePlex attempts to post UserBs change on SysA, it expects the value of the
column to be 3, but it is 1 because of UserAs change. SharePlex generates an out-of-
sync error.
When SharePlex attempts to post the changes made by UserA and User B to the data-
base on SysC, both of those statements fail because the pre-images do not match. Again,
SharePlex generates an out-of-sync error.
Note: The SharePlex design prevents the data in peer-to-peer replication from looping
back from one machine to another. By default, SharePlex transactions performed on the
local system by the SharePlex Oracle user (by way of the Post process) are ignored, so
the Capture process does not replicate those transactions back to their source.
CHAPTER 5 215
FIGURE 20: Conflicts caused by UPDATE statements

Considerations for peer-to-peer replication

To successfully deploy SharePlex in a peer-to-peer configuration, you must be able to:
isolate keys
prevent changes to keys
control sequence generation
control trigger usage
eliminate cascading deletes
designate a trusted host
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-to-peer deployment because they were not cre-
ated within those guidelines.
Following are more detailed explanations of each of the requirements.
Can you isolate the keys?

Understanding the role of keys in the SQL statement constructed by SharePlex is critical
to understanding synchronization issues and minimizing conflicts in a peer-to-peer envi-
ronment. SharePlex depends on unique, not-NULL keys in the SQL statement in order
to locate the correct row in the target table for UPDATE and DELETE statements, and
to ensure that a row being inserted is not already there.
SharePlex normally uses a unique key in the absence of a primary key, or it will build a
simulated key internally using all columns except LONGs, but this is not acceptable in
peer-to-peer replication. The only acceptable key is a primary key.
If a table has no primary key but does have 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 replica-
tion network, meaning
it must use the same column(s) in each corresponding table in all databases.
key columns for corresponding rows must have the same values.
CHAPTER 5 217
The primary key must be created to contain enough information about a row so there
can be no question about that rows uniqueness and location. This ensures that Share-
Plex cannot possibly post data to the wrong row and that conflict resolution succeeds.
Using just a sequence as the primary key probably will not suffice for peer-to-peer rep-
lication. The following example explains why.
Suppose the sample table in Figure 18 on page 213 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.
Because the sequence numbers would be different on each system (and sequences gen-
erate the key), there are no unique key violations when those INSERTs are replicated
between systems. Even so, data integrity is compromised: There are now two entries for
Jane Wilson in the databases causing problems for future UPDATE operations.
The solution is to include other unique columns in the key. For the sample table, the key
could also include the SocSec column (U.S.A government-assigned Social Security
Number, a unique number) and the EmpName column (as added verification with the
EmpNo and SocSec columns). This is enough information to ensure uniqueness of each
row among all databases. When there is duplicate user activity on a row, it ensures a
conflict, resulting in the correct application of a conflict resolution routine.
The concept of ensuring key uniqueness among all databases is defined as key isolation.
When you isolate keys, SharePlex can locate and change the correct row in all data-
bases, and it can apply a conflict resolution routine for the correct row, if needed.
Warning! Because SharePlex locates rows on the target system by using the key, it can-
not provide conflict resolution when one or more columns of a key are changed. Peer-to-
peer replication would not be practical in environments where key values are changed.
How does the application use sequences?

Sequences would help ensure uniqueness of a primary key, but SharePlex does not sup-
port peer-to-peer replication of sequences. If you are using 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, but that might be impractical over WAN and Internet
connections. As an alternative, you can maintain sequences separately on each server,
making sure you partition a unique range to each one. For example, if you have two
servers, you can assign even values to one, and odd values to the other. You need to
anticipate the growth of the number of servers and the number of rows requiring
sequences on each system. Quest 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 sys-
tem name to the sequence value in the primary key to enforce uniqueness.
Does the application use triggers?

DML changes resulting from triggers firing on the source system enter the redo log, so
they are replicated and posted to the target database by SharePlex. If the same triggers
fire on the target system, they return out-of-sync errors.
If triggers must be available to fire when activated by operations from users other than
SharePlex, they must be directed to ignore the SharePlex user by wrapping them with
the sp_add_trigger.sql script on all instances in the peer-to-peer configuration. This
puts a WHEN clause into each triggers procedural statement that tells it to ignore the
Post process. For more information about this script, see page 426.
Does your application use cascading deletes?

ON DELETE CASCADE constraints require special attention. When these constraints
fire during the original transaction, SharePlex replicates both the primary (original)
DELETE and the dependent (cascaded) DELETE operations to the target system
because they all enter the redo logs. SharePlex expects to post replicated operations in
the order they are received. If the primary DELETE activates foreign-key constraints on
the target table that delete the dependent rows, those rows will not be there when Share-
Plex expects to perform the replicated cascaded DELETEs. This causes SharePlex to
return out-of-sync errors.
ON DELETE CASCADE constraints must be disabled. Instead of using ON DELETE
CASCADE constraints, you can incorporate the required DELETE functions into trig-
gers, then run the sp_add_trigger.sql script to direct the triggers to ignore the Share-
Plex user.
This enables you to maintain referential integrity. The trigger fires for a source transac-
tion to delete the dependent rows in the source database, but when SharePlex posts the
replicated primary DELETE to the target database, the trigger does not fire. No depen-
dent rows are deleted until the replicated dependent DELETE operations arrive from the
source.
CHAPTER 5 219
Does the application maintain inventory quantities or

account balances?
Applications that use UPDATE statements to record changes in quantity, such as inven-
tory or account balances, pose a challenge for peer-to-peer replication. The following
example of an online bookseller explains the reason why. The following table describes
the booksellers Inventory table.
Book_ID (primary key)
Quantity
Suppose 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).
But 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.
When the Post process attempts to post the first transaction, it discerns 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 maintain-
ing account or inventory balances using UPDATEs. Following are some alternate solu-
tions.
Possible solutions for maintaining quantities and balances

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 book-
seller 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 resolu-
tion 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 finan-
cial record:
account_number (primary key)
balance
Suppose a row (an account) in the example table has a balance of $1500 on SysA. Cus-
tomerA makes a deposit of $500 on that system. The application uses an UPDATE state-
ment 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).
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;
CHAPTER 5 221
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.
How will you assign 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 sys-
tem 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:
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.
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. How-
ever, 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. 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).
Configuring peer-to-peer replication

Peer-to-peer replication consists of the following configurational steps:
1 Create a replication configuration on each system that replicates to all other systems
in the peer-to-peer environment.
2 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.
3 List the conflict resolution routines in a special conflict_resolution.SID file. Share-

Plex refers to this file to determine the correct procedure to use when a conflict
occurs.
Important! Business rules vary widely from company to company, so create conflict res-
olution rules and syntax that are appropriate for your business. This documentation pro-
vides guidelines, examples and templates to assist you, but do not use them as your own
routines. In addition, Quest periodically updates 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.
Template 19: Peer-to-peer configuration on each system

Source is the database/schema/table/system where a transaction originates. Target is
the database/schema/table/system that receives the replicated operations for the trans-
action.
Example configuration
Datasource:o.oraA
sales.dat1 sales.dat2 sysB@o.oraB
CHAPTER 5 223
Steps to take on the trusted source system

To maintain a peer-to-peer replication strategy, you must establish a trusted source data-
base and system the primary database and system from which all other systems are
initially synchronized and re-synchronized when necessary. Perform the following steps
on the trusted source system first.
Install SharePlex in the normal manner and run ora_setup. See page 407 for instruc-
tions.
Referring to Template 19 on page 222, create a configuration that replicates to the
other replication system(s). You might be able to automate this task using either the
build_config.sql script (see page 179) or the config.sql script (see page 183).
Do not include sequences in the configuration. To accommodate the use of
sequences, see How does the application use sequences? on page 217.
On all other systems

Create the Oracle instances on these systems. If you intend to use an Oracle hot
backup or a DBCopy hot copy for this, do not create the instances. You will create
them with the copy during the synchronization procedure. Important: To use a hot-
copy method, be prepared to quiet all of the secondary source systems for the dura-
tion of the procedure.
tions. Important: Do not run ora_setup if you are using an Oracle hot backup or
DBCopy hot copy. You will be instructed to do so in the synchronization procedure
after the instance is established.
Referring to Template 19 on page 222, create a configuration on each system that
replicates to all other systems. Owner and table names can be different than their
counterparts on other systems if the table structure is identical. Specify the local
instance as the datasource, and specify the remote instances and systems in the rout-
ing map. You might be able to automate this task using either the build_config.sql
script (see page 179) or the config.sql script (see page 183).
Do not include sequences in the configuration. To accommodate the use of
sequences, see How does the application use sequences? on page 217.
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 com-
mand to change the date format in SQL*Plus.
SQL> ALTER SESSION SET nls_date_format = 'MMDDYYYYHH24MISS'
On all systems, including the trusted source

If the systems are in different time zones, establish timestamps using offsets to
Greenwich Mean Time.
Create conflict resolution routines by creating stored PL/SQL conflict resolution
procedures that direct the action of SharePlex when a conflict occurs. SharePlex sup-
ports the following forms of conflict resolution:
Generic conflict resolution uses dynamic PL/SQL that enables one conflict resolu-
tion routine to be used for multiple tables. Instructions are in Using generic conflict
resolution on page 224.
After you create conflict resolution routines, complete the SharePlex conflict resolu-
tion file on each system by listing the conflict resolution procedures you developed.
Instructions for completing a conflict resolution file follow the instructions for creat-
ing the conflict resolution procedures.
Before you synchronize data to begin replication, ensure that all replication consider-
ations have been addressed according to the guidelines in Chapter 4 and in Consid-
erations for peer-to-peer replication on page 216.
Perform initial synchronization by copying the database from the trusted source sys-
tem to the other systems and activating the configurations on each system. Choose a
procedure from the ones in Chapter 7.
Changing the conflict resolution file

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 so that it updates the resolution cache.
Using generic conflict resolution

Generic conflict resolution enables you to use dynamic SQL to write one or more con-
flict resolution routines for use with multiple tables. SharePlex provides some prepared
conflict resolution routines, but you probably need to write your own procedures instead
of, or in conjunction with, those routines to satisfy your business rules. See page 235 for
more information about the prepared routines.
Conflict resolution for DELETE statements could be as simple as writing a routine that
directs SharePlex to ignore out-of-sync errors for DELETEs and discard duplicate trans-
actions for UPDATES performed after a DELETE, assuming keys are isolated and the
CHAPTER 5 225
database is configured properly. INSERT and UPDATE statements change data values
and can be complex, so procedures for ensuring data integrity can be equally complex.
It is good practice to write more than one procedure, such as making site or system pri-
ority the primary routine and timestamp a secondary routine. SharePlex invokes one
routine after another until one succeeds or there are no more procedures available.
You can write a generic conflict resolution procedure for a specific table and for a spe-
cific operation, such as for INSERTs, and use it in combination with one or more multi-
table procedures.
Warning! Test your conflict resolution routines before you put them into produc-
tion to make sure they work as intended, and to make sure that one routine does
not counteract another one.
Restrictions and requirements for using generic conflict resolution

Observe the following limitations before implementing generic conflict resolution.
Use either generic conflict resolution or transformation for a table, but not both.
Although the same sp_cr PL/SQL package is used for conflict resolution and trans-
formation, transformed tables cannot be compared by SharePlex, so conflict resolu-
tion cannot succeed. If you use both, SharePlex will only call your transformation
routine. If appropriate, you can use generic conflict resolution and transformation for
different tables in the same configuration. For more information about transforma-
tion, see page 245.
Conflict resolution cannot be used for DDL changes, whether or not they are sup-
ported by SharePlex replication.
Any table to be accessed through PL/SQL for conflict resolution requires implicitly
granted privileges from the owner of the object to SharePlex.
Conflict resolution does not support changes to LONG or LOB columns.
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 supports tables with
identical owner and table names.
Creating a generic conflict resolution procedure

SharePlex defines PL/SQL record and table structures in a public package named sp_cr
that was installed during ora_setup in the SharePlex schema. The package uses the fol-
lowing parameters.
create package sp_cr as
type row_typ is record
(src_host varchar2(32) These are the IN variables
,src_ora_sid varchar2(32) passed to your procedure.
,src_ora_time varchar2(20)
,source_rowid varchar2(20)
,target_rowid varchar2(20)
,statement_type varchar2(6) These are the OUT vari-
,target_table varchar2(78) ables that must be set in
,oracle_err number your procedure and
,status number returned to SharePlex to
,action number direct its action.
,reporting number
);
This is the
type col_def_typ is record
datatype that is
(column_name user_tab_columns.column_name%type used to popu-
,datatype user_tab_columns.datatype%type late the
,is_key boolean col_def_tabtyp
,is_changed boolean table capturing
,old_value varchar2(32764) the information
,new_value varchar2(32764) needed for your
,current_value varchar2(32764) procedure.
);
type col_def_tabtyp is table of col_def_typ

CHAPTER 5 227
Explanation of IN variables passed by SharePlex to your procedure

For each row that causes a conflict, SharePlex passes this identifying information.
src_host This is the name of the source system (where the data was
changed). 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 This is the ORACLE_SID of the source database. It is case-sen-

sitive and is passed in the same case as in the oratab file, Win-
dows Registry or V$PARAMETER table.
src_ora_time This is the timestamp of the changed data in the source redo log
that is being replicated.
source_rowid This is the row ID of the source row (the one whose data was
replicated). It is passed as a literal within single quotes, for
example 123456.
target_rowid This is the row ID of the corresponding row in the target data-
base. SharePlex obtains the row ID by querying the 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 This is a letter, either I, U or D, indicating whether an INSERT,

UPDATE or DELETE statement caused the conflict.
target_table This is 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 the Oracle error number that caused the conflict.
Explanation of OUT variables passed by your procedure to

SharePlex
These variables direct the action of SharePlex based on the outcome of the procedure
(whether conflict resolution succeeded or failed).
status The status variable defines whether or not the conflict resolution
procedure resolved the conflict. You must specify a value for
this parameter.
A value of 0 implies successful resolution and directs Share-
Plex to proceed with the SQL statement. SharePlex does not
write any log entries to the Event Log when conflict resolu-
tion succeeds.
A value of 1 implies unsuccessful conflict resolution. In this
case, the action SharePlex takes depends on what you speci-
fied as the action variable.
action The action variable defines the action that you want SharePlex to
take as a result of an unsuccessful conflict resolution procedure.
You must specify a value for this parameter.
A value of 0 directs SharePlex NOT to post the SQL state-
ment. The outcome of this action depends on what you spec-
ify for the reporting variable.
The value of 1 is reserved for internal SharePlex use. Do not
use it.
A value of 2 directs SharePlex to try the next conflict resolu-
tion procedure that you listed in the conflict resolution file, if
one exists.
CHAPTER 5 229
reporting The reporting variable determines how SharePlex reports unsuc-

cessful conflict resolution results. You must specify a value for
this parameter.
A value of 0 directs SharePlex NOT to report an error or write
the failed SQL statement to the SID_errlog.sql log.
Values 1 and 2 are reserved for internal SharePlex use. Do not
use them.
A value of 3 directs SharePlex to write the failed SQL state-
ment to the SID_errlog.sql log and report the following error
to the Event Log: Warning: sp_opst_mt (for o.ora102-
o.ora102) 15020 - Table ABC.INVTABLE is out-of-sync. No
conflict resolution available.
Important! 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 or by using the Replication Monitor
component of the Quest CentralTM for Oracle database-management console. See the
SharePlex Reference Guide for more information about show log and other SharePlex
commands.
Explanation of col_def_typ datatype

For each replicated column of a row that caused a conflict, SharePlex provides the fol-
lowing information in the col_def_tabtyp table.
column_name This tells your procedure the name of the column that was repli-
cated from the source table, for example emp_last_name. This
value is not case-sensitive.
datatype This tells your procedure the datatype of the data in the repli-
cated column, for example VARCHAR2. This value is always in
capital letters.
is_key This tells your procedure whether or not the column is a key col-
umn. 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 This 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.
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.
For UPDATEs, is_changed is TRUE for non-key columns. For
key columns, is_changed normally is FALSE, because keys
should not change in peer-to-peer replication. However, Share-
Plex will pass a value for a changed key column, but if that key
value also was changed on the target system, SharePlex cannot
locate the correct row, and conflict resolution could fail.
For DELETEs, is_changed is always FALSE, because Share-
Plex replicates only the key values for a DELETE statement.
old_value This tells your procedure the old value of the replicated column,
before it was changed on the source system. 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 variable obtained from the target row, then
there is a conflict. This column is NULL for INSERTs, because
the row did not exist in the target database.
new_value This tells your procedure the new value of the replicated column,
as changed on the source system.
current_value This tells your procedure the current value of the column in the
target table. If SharePlex cannot locate the target row, the value
is NULL.
Possible entries in the col_def_tabtyp table

SharePlex creates a col_def_tabtyp PL/SQL table for each operation that caused a con-
flict. All fields are passed by SharePlex to your routine, although not all will have val-
ues if SharePlex cannot locate the row. The following tables illustrate the possible
outcomes of each type of operation.
CHAPTER 5 231
For INSERT statements
column_name is_changed old_value new_value current_value1 is_key
C1 TRUE NULL bind NULL FALSE
C2 TRUE NULL bind NULL TRUE
C3 FALSE NULL NULL 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.
For UPDATE statements
C1 TRUE bind bind NULL | target value FALSE
C2 FALSE bind NULL NULL | target value TRUE
C3 TRUE bind bind NULL | target value TRUE

1
When an UPDATE fails, it is because SharePlex cannot locate the row using the PRIMARY key
and the pre-images. If the row was not located, SharePlex 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.
For DELETE statements
C1 FALSE bind NULL NULL TRUE

1
When a DELETE fails, it is because SharePlex could not locate the row using the PRIMARY
key. Therefore, current_value is NULL.
Creating the generic conflict resolution procedure interface

Your procedure must use the following interface.
Template 20: CREATE/REPLACE PROCEDURE parameter declarations

Important! Substitute the
(table_info in out splex.sp_cr.row_typ,
SharePlex Oracle user for
col_values in splex.sp_cr.col_def_tabtyp) splex.
Tip: If you ran the SharePlex conflict resolution demonstration, 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. For more information about the
SharePlex demonstrations, see the SharePlex Installation and Demonstration Guide.
Creating the conflict resolution file for generic conflict resolution

After you create the conflict resolution procedure(s), construct the
conflict_resolution.SID file, which tells SharePlex which procedures to use.
A blank conflict resolution file was installed with SharePlex in the data sub-directory in
the SharePlex variable-data directory. 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 as listed in the oratab file or Windows
Registry. The SID is case-sensitive and must match the case in those locations. For
example, if the SID is ORCL8 in the oratab file or Registry, it cannot be orcl8 in the
files name. Do not change the name of this file, or SharePlex will not invoke the con-
flict resolution routines.
Important! There can be only one conflict_resolution.SID file per active configuration.
CHAPTER 5 233
Refer to the following template as you follow the steps to create the file entries.
Template 21: Conflict resolution file for generic conflict resolution

like:owner.%\_string I | U | D | IUD owner.procedure_name
For each conflict resolution procedure, create one line in the conflict resolution file. If
you are using more than one procedure, the order in which you list them in the conflict
resolution file determines their priority (in descending order). If you list a table-specific
procedure, SharePlex uses it before wildcard-specified procedures.
Use a separate line to list each procedure, pressing Enter at the end of each one. The fol-
lowing is an example conflict resolution file.
scott.sal IUD scott.sal_cr
like:scott.%\_corp\_emp IUD scott.emp_cr1
like:scott.%\_corp\_emp IUD scott.emp_cr2
like:scott% IUD scott.emp_cr3
scott.cust U scott.sal_cr
In the example, the scott.sal_cr routine is used for the scott.sal table before the
scott.emp_cr1 procedure is used for that table. The scott.emp_cr1 procedure is used
before the scott.emp_cr2 procedure for all tables meeting the search criteria, and so
forth. For scott.cust, a procedure is called for UPDATEs before the other routines are
used for all operations.
To create the conflict_resolution.SID entries
1 Change directories to the data sub-directory in the SharePlex variable-data directory.
2 Open the conflict_resolution.SID file in either the vi text editor (UNIX) or WordPad
(Windows).
3 [OPTIONAL] You can enter comment lines to identify the file or convey other informa-
tion. Precede each comment line with a pound (#) symbol to indicate that it is non-
functioning, and end each one by pressing Enter.
4 Specify the target table(s). You can specify an individual target table for a routine.
Type the owner and name, separating them with a dot (.) but no spaces.
Or...
You can use the LIKE operator and a SQL wildcard (%) to specify multiple tables
using a search string, as shown in Template 21 and in the following examples.
You can use an underscore (_) to denote a single-character wildcard. For table names
containing 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.
Examples:
like:scott.%\_corp\_emp
scott.emp
Note: If you are not using the LIKE operator, you need not specify the backslash escape
character when using table names containing underscores.
Do not press Enter after this entry.Type at least a space or tab to create a second col-
umn.
5 Specify the Operation Type(s). If the procedure is written for all types of SQL
statements, type the string IUD. If the procedure is operation-specific, type either an
I, a U, or a D. Do not press Enter after this entry.
6 Type at least a space or tab to create a third column.
7 Specify the Procedure. Type the owner and name of the conflict resolution proce-
dure, separating them with a dot (.) but no spaces.
Example: scott.emp_cr
The completed line should look like one of the following examples.
like:scott.%\_corp\_emp IUD scott.emp_cr
Or...
scott.emp U scott.emp_tr
Or...
like:scott.%\_corp\_emp U scott.emp_cr_u
8 Start a new line and repeat steps 4 through 7 for each additional conflict resolution
procedure.
9 When you are finished creating the conflict resolution file, save and close it using the
:wq command in vi or Save on the File menu in WordPad.
CHAPTER 5 235
Changing the conflict resolution file

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 so that it updates the resolution cache.
Using prepared procedures for conflict resolution

SharePlex provides the following optional prepared routines for use in conjunction with,
or instead of, custom routines. These options can be used with basic and generic conflict
resolution formats. There are no limitations on column types with the following pre-
pared procedures.
!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 synchroniza-
tion. 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 UPDATEs. To avoid out-of-sync errors, Quest recommends
using !UpdateUsingKeyOnly in conjunction with specific custom routines, relying on
!UpdateUsingKeyOnly as a final option if the custom routines fail. !UpdateUsing-
KeyOnly must be the last entry in the series 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.
Example conflict resolution file using !UpdateUsingKeyOnly
owner.table1 u owner.procedure_up_A
owner.table1 u owner.procedure_up_B
owner.table1 u !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.
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 the "column_name"
specified. 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 syn-
chronization. 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.
Example conflict resolution file using !MostRecentRecord
owner.table1 u owner.procedure_up_A
owner.table1 u !UpdateUsingKeyOnly
owner.table1 u !MostRecentRecord(C2)
C2 is the column_name which is a TIMESTAMP datatype
!DEFAULT parameter for prepared routines

To use the prepared routines or to use the prepared routines in combination with user
defined routines for all tables in the replication configuration, use the !DEFAULT
parameter. For tables where there is a custom routine in addition to, or instead of, pre-
pared routines, the custom routine takes priority over a 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.
Example conflict resolution file using !DEFAULT
!DEFAULT u !ControlExtendedCharSet
!DEFAULT d !ControlExtendedCharSet
james.table1 u james.procedure_upd
!DEFAULT u !UpdateUsingKeyOnly
james.table1 i james.procedure_ins
james.table1 d james.procedure_del
In the example, which uses conflict resolution, the !ControlExtendedCharSet proce-

dure is used for UPDATEs and DELETEs for all tables, including james.table1.
6
SharePlex Optional Setup
This chapter guides you through additional implementation options for improving repli-
cation performance and customizing SharePlex.
This chapter is divided into parts relating to the different aspects of replication that you
can customize.
Contents
Enhancing Post performance

Using transformation with SharePlex
Setting environment parameters
Using security with SharePlex
Other optional features
Part 1: Enhancing Post performance
This section addresses optional features that you can enable to optimize the perfor-
mance of the Post process. For additional tuning and troubleshooting information, see
the SharePlex Reference Manual.
Using INDEX hints for faster posting

When SharePlex performs UPDATEs and DELETEs on a target table, Oracle some-
times 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 correct
index on target objects. If Post is doing full-table scans on tables where there are defined
indices, use hints for those tables.
To enable the use of INDEX hints by SharePlex, 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.
The ora_setup process installs a blank hints.SID file on each system where you install
SharePlex. Use the hints.SID file that resides on the target system.
It is not necessary to include all replicating tables in the hints file. Oracle generally uses
the correct index, and including all of the tables in the file causes Post to reference the
file for each operation. This slows down posting. Use hints only for tables that need
them.
The default maximum number of hints (tablename/indexname pairs) is 100. You can
increase or decrease this value with the SP_OPO_HINTS_LIMIT parameter.
See Chapter 6 of the SharePlex Reference Manual for more information about Share-
Plex parameters. Changing this parameter requires stopping and starting Post.
CHAPTER 6 239
Configuring the hints file

To configure the hints file, you follow a process similar to creating a configuration.
1 On the target system, stop the Post process.
sp_ctrl(sysB)> stop post
2 On the target system, change directories to the data sub-directory of the SharePlex
variable-data directory.
3 Open the hints.SID file in vi (UNIX) or WordPad (Windows).
4 Precede any comments with the pound (#) symbol to render them nonfunctional.
5 On a non-comment line, enter the owner and name of the first target table, separat-
ing the two names with a dot (.). Leave no spaces between characters. Underscores
(_) are permissible. Do not press Enter.
source_owner.source_table_name
6 Type at least a few spaces or a tab, then enter the owner and name of the index to be
used for the table, separating the two names with a dot (.). Leave no spaces between
characters. Underscores (_) are permissible.
target_owner.target_table_index
7 Start a new line by pressing Enter.
8 Repeat steps 5 through 7 for each target table.
9 When you are finished, save and close the file using :wq command in vi or Save on
the File menu in WordPad.
10 On the target system, start the Post process.

sp_ctrl(sysB)> start post
Problem-solving for the hints file

If the hints file contains an invalid index, SharePlex uses it as a hint for the table. How-
ever, Oracle ignores invalid hints, so there is no error. SharePlex generates the following
errors in the event_Log when it encounters abnormal conditions relating to the use of
hints.
15050 hint file not found
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
Important! SharePlex expects to find a hints file in the data sub-directory, whether or not
it is populated. If a hints file does not exist, create one in the data sub-directory of the
variable-data directory on the target system. Use the hints.SID naming format. On
UNIX systems, you can issue a touch /variable_data_dir/data/hints.SID command to cre-
ate the file. Substitute the full path name of the SharePlex variable-data directory for
variable_data_dir, and substitute the ORACLE_SID of the target instance for SID.
Caching SQL statements for faster posting

The SQL cache feature of SharePlex caches frequently-used parsed and binded SQL
statements for reuse, so that SharePlex does not have to parse and bind them again when
they recur. You can tune this feature to maximize its advantages based on the amount of
repetitive statements your application generates.
When to use SQL Cache

SharePlex is installed with SQL Cache enabled. SQL Cache improves Posts perfor-
mance 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.
Enabling and configuring SQL Cache

The SQL Cache feature is controlled by the following SharePlex parameters:
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 set-
CHAPTER 6 241
ting of 1 disables SQL caching. When you disable SQL caching, SharePlex prints the
following entry in the event_log:
SQL Cache disabled.
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.
Important! Read all of the following documentation before tuning SP_OPO_MAX_CDA.
About open cursors

The Oracle parameter OPEN_CURSORS defines the total maximum number of cursors
that a process (such as Post) can open. This parameter needs to be set high enough so
that it cannot adversely affect Posts performance. This is true whether or not SQL cach-
ing is enabled.
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.
To view the OPEN_CURSORS value, query the database using the following SQL
statement:
SQL> select value from v$parameter where name = 'open_cursors';
The OPEN_CURSORS value can be modified or added if absent. It is suggested that

users consult the appropriate Oracle documentation prior to making changes to Oracle
parameters.
Guidelines for setting OPEN_CURSORS

To estimate a value for OPEN_CURSORS, 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 (see Figure 21 on page 243).
After you estimate the concurrent transactions to be expected, use the following formu-
las to determine the correct setting for OPEN_CURSORS in the SharePlex replication
environment.
With SQL Cache disabled
With 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 for-
mula is:
needed
With SQL Cache enabled
With SQL Cache enabled, 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 mini-
mum of 2 plus an additional 5). The formula is:
needed
How Post tracks open cursors

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.
CHAPTER 6 243
Tuning SQL Cache

To take full advantage of SQL Cache, determine the hit ratio for cached statements by
running sp_ctrl and issuing the show post detail command.
sp_ctrl> show post detail
SQL Cache performance

information
FIGURE 21: SQL Cache hits are displayed in the Post statistics using the show post detail com-
mand.
The SQL cache hit count field in the show post detail display 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 delete operations. In the above example, the hit ratio
is 36%. This indicates that Post is using cached statements 36 percent of the time.
View the hit ratio after several days of typical replication activity to gauge the ideal set-
ting for SP_OPO_MAX_CDA. If the hit ratio is under 50 percent, increase
* A message typically is a SQL operation or an internal SharePlex operation. For more information about messages,
see page 34.
SP_OPO_MAX_CDA, but do so only in a small increment of about 5 cursors. Then,

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 increasing
SP_OPO_MAX_CDA in small increments until the hit ratio remains constant.
Making large transactions faster

A single large SQL statement, such as those applied by application patches, can trans-
late into thousands or millions of individual UPDATE or DELETE statements for
SharePlex, all needing to be applied by Post to the target database. Such transactions
can cause posting to slow down significantly, which increases the latency between the
source and target data. You can avoid this issue with the following implementation pro-
cedure, which uses SharePlex optional features to bypass the Post process and apply the
statement directly through Oracle.
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 and
procedure, see page 424.
3 Edit your patch script to call SHAREPLEX_IGNORE_TRANS before update or

delete. 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.
CHAPTER 6 245
Part 2: Using transformation with SharePlex
Transformation directs the Post process to call a PL/SQL procedure (defined as a trans-
formation routine) instead of applying a SQL operation to the target database. Transfor-
mation enables replicated data to be manipulated before, or instead of, posting.
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. When writing your routine, is your responsi-
bility to include in your procedure the necessary SQL operations for posting.
Implementing transformation involves the following steps.
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. For more information about creating a configura-
tion, see SharePlex configuration construction on page 132.
Create transformation routine(s) using the instructions on page 249.
Create entries for those routines in the transformation.SID file using the instructions
on page 255.
Considerations for using transformation

Because transformation changes data and because SharePlex does not post the data,
transformation changes the behavior of replication. Review the following consider-
ations before implementing transformation.
Supported replication scenarios

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 practi-
cal for reporting, data distribution, and data mart and warehousing applications.
Transformation is not suitable for peer-to-peer or high-availability replication environ-
ments. High availability requires identical databases that are kept synchronized by repli-
cation. 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 trans-
formed, SharePlex cannot compare before and after values to verify synchronization
and detect conflicts.
For more information about high-availability replication, see Establishing replication for
high availability and data recovery on page 190. For more information about peer-to-
peer replication, see Establishing peer-to-peer replication on page 211.
Supported operations
Transformation supports only INSERT, UPDATE and DELETE operations. For each
table, you can use one transformation routine for each SQL operation. This provides the
following choices:
You can create one procedure for all three operation types.
Or...
You can create a procedure for each operation type.
And...
You can use one procedure for all tables. SharePlex allows this through the use of
wildcards to specify the tables.
Or...
You can create different procedures for different tables.
Examples:
TABLE PROCEDURE
scott.emp scott.emp_tr_insert
scott.emp scott.emp_tr_update
scott.emp scott.emp_tr_delete
CHAPTER 6 247
Or...
TABLE PROCEDURES
All tables in the scott schema scott.tr_insert
scott.tr_update
scott.tr_delete
Or...
TABLE PROCEDURE
All tables in the scott schema scott.tr_all
Or...
TABLE PROCEDURE
All tables in the scott schema scott.tr_all
scott.emp scott.tr_insert
If a transformation routine is specified for an individual table, such as for scott.emp in

the preceding example, 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. In the example, only scott.tr_insert is used for
INSERTs on scott.emp, but scott.tr_all is used for UPDATEs and DELETEs to
scott.emp. For all other tables in the scott schema, the scott.tr_all routine is used for
all DML statements.
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 opera-
tions. 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.
Synchronization
When data is transformed, SharePlex cannot compare before and after values to verify
synchronization. The only way to confirm synchronization is to use the compare com-
mand with the [key] option. This method is not a complete confirmation of synchroniza-
tion. It indicates whether or not there is a row on the target system with the same key as
the source row, so it only detects missing or extra rows. It does not (and cannot) indicate
whether values in non-key columns are properly correlated to those in the source col-
umns, because the target data was transformed.
For those reasons, [repair] command with [key] option cannot be used to resynchronize
data. You must devise your own resynchronization procedures based on your companys
business rules and the database environment.
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.
SQL> ALTER SESSION SET nls_date_format = 'MMDDYYYYHH24MISS'
Conflict resolution
Transformation and conflict resolution cannot be used for the same table in a configura-
tion. If appropriate, you can use generic conflict resolution and transformation for dif-
ferent tables. For more information about generic conflict resolution, see page 224. If
transformation and conflict-resolution routines exist for the same table, SharePlex uses
the transformation routine.
Other considerations
Transformation does not support changes to LOB and LONG columns.
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.
A known issue in PL/SQL prevents the SharePlex conflict resolution logic from call-
ing a conflict resolution routine 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
CHAPTER 6 249
more information. This issue does not affect replication; SharePlex supports tables
with identical owner and table names.
Creating transformation routines

Important! 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.
Transformation routines must be written with dynamic PL/SQL procedural language

using parameters and record and table structures defined in a public package named
sp_cr. This package was installed during ora_setup in the SharePlex schema. The
package uses the following parameters.
create package sp_cr as

type row_typ is record
(src_host varchar2(32) These are the IN variables
,src_ora_sid varchar2(32) passed to your procedure.
,source_rowid varchar2(20)
,target_rowid varchar2(20)
,statement_type varchar2(6)
,target_table varchar2(78) These are the OUT vari-
,oracle_err number ables that must be set in
,status number your procedure and
,action number returned to SharePlex to
,reporting number direct its action.
);
type col_def_typ is record

This is the
(column_name user_tab_columns.column_name%type
datatype that is
,datatype user_tab_columns.datatype%type used to popu-
,is_key boolean late the
,is_changed boolean col_def_tabtyp
,old_value varchar2(32764) table capturing
,new_value varchar2(32764) the information
,current_value varchar2(32764) needed for your
); procedure.
type col_def_tabtyp is table of col_def_typ

index by binary_integer;
Explanation of IN variables passed by SharePlex to your

procedure
For each change to a row that SharePlex replicates, SharePlex passes this identifying
information to your transformation routine.
src_host This is the name of the source system (where the data was
changed). 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.
CHAPTER 6 251
src_ora_sid This is the ORACLE_SID of the source database. It is case-sen-

sitive and is passed in the same case as in the oratab file, Win-
dows Registry or V$PARAMETER table.
source_rowid This is the row ID of the source row (the one whose data was
replicated). It is passed as a literal within single quotes, for
example 123456.
target_rowid This is the row ID of the corresponding row in the target data-
base. It is passed as a literal within single quotes, for example
123456. SharePlex obtains the row ID by querying the data-
base. If the row cannot be found using the PRIMARY key, the
value is NULL.
statement_type This is a letter, either I, U or D, indicating whether the operation

was an INSERT, UPDATE or DELETE statement.
target_table This is 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 SharePlex passes a value of 0 for this variable. This variable is

only used for conflict resolution.
Explanation of OUT variables passed by your procedure to

SharePlex
These variables direct the action of SharePlex based on the outcome of the procedure
(whether it succeeded or failed).
status The status variable defines whether or not the transformation

routine succeeded. You must specify a value for this parame-
ter.
A value of 0 implies successful execution. SharePlex does not
write any error messages to the Event Log when transforma-
tion succeeds. It continues its processing by reading the next
replicated operation in the post queue.
A value of 1 implies unsuccessful execution.
A value of 7 implies unsuccessful execution and instructs the
Post process to stop.
action The action variable defines the action that SharePlex takes. 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
reporting The reporting variable determines how SharePlex reports unsuc-

cessful transformation results. You must specify a value for this
parameter.
A value of 0 directs SharePlex NOT to report an error or write
the failed SQL statement to the SID_errlog.sql log.
Values 1 and 2 are reserved for internal SharePlex use. Do not
use them.
A value of 3 directs SharePlex to write the failed SQL state-
ment to the SID_errlog.sql log and report an error to the
Event Log.
CHAPTER 6 253
Explanation of col_def_typ datatype

For each replicated column of a row, SharePlex provides the following information in
the col_def_tabtyp table.
column_name This tells your procedure the name of the column that was repli-
cated from the source table, for example emp_last_name. This
value is not case-sensitive.
datatype This tells your procedure the datatype of the data in the repli-
cated column, for example VARCHAR2. This value is always in
capital letters.
is_key This tells your procedure whether or not the column is a key col-
umn. If it is a key column, SharePlex passes a value of TRUE. If
it is not a key column, SharePlex passes a value of FALSE.
is_changed This tells your procedure whether or not the column value has
changed. If it is changed, SharePlex passes a value of TRUE. If it
is not changed, SharePlex passes a value of FALSE.
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.
For UPDATEs, is_changed is TRUE for non-key columns. For
key columns, is_changed normally is FALSE, because keys typ-
ically do not change. However, SharePlex will pass a value for a
changed key column, but if that key value also was changed on
the target system, SharePlex cannot locate the correct row, and
there will be out-of-sync errors.
For DELETEs, is_changed is always FALSE, because Share-
Plex replicates only the key values for a DELETE statement.
old_value This 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.
new_value This tells your procedure the new value of the replicated column,
as changed on the source system.
current_value This tells your procedure the current value of the column in the
target table. If SharePlex cannot locate the target row, the value
is NULL.
Possible entries in the col_def_tabtyp table

SharePlex creates a col_def_tabtyp PL/SQL table for each replicated operation. All
fields are passed by SharePlex to your routine, although not all will have values if
SharePlex cannot locate the row. The following tables illustrate the possible outcomes
of each type of operation.
For INSERT statements
column_name is_changed old_value new_value current_value is_key
C1 TRUE NULL bind NULL FALSE
C2 TRUE NULL bind NULL TRUE
C3 FALSE NULL NULL NULL TRUE | FALSE
For UPDATE statements
column_name is_changed old_value new_value current_value* is_key
C1 TRUE bind bind NULL | target value FALSE
C2 FALSE bind NULL NULL | target value TRUE
C3 TRUE bind bind NULL | target value TRUE

*
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 col-
umn as well as the changed columns. If it cannot locate the row using just the PRIMARY key,
then current_value is NULL.
CHAPTER 6 255
For DELETE statements
column_name is_changed old_value new_value current_value is_key
C1 FALSE bind NULL NULL TRUE
Creating the transformation procedure interface

Your procedure must use the following interface.
Template 22: CREATE/REPLACE PROCEDURE parameter declarations

Important! Substitute the
(table_info in out splex.sp_cr.row_typ,
SharePlex Oracle user for
col_values in splex.sp_cr.col_def_tabtyp) splex.
Creating entries for the transformation.SID 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 transfor-
mation routine that it must call.
This file normally is installed in the data sub-directory of the SharePlex variable-data
directory. 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 as shown in the oratab file or Windows Registry. The SID is case-sensi-
tive and must match the case shown in those locations. For example, if the SID is
ORCL8 in the oratab file or Registry, it cannot be orcl8 in the transformation files
name. Do not change the name of this file, or SharePlex will not invoke the transfor-
mation routines.
Important! There can be only one transformation.SID file per active configuration.
For each transformation routine, create one line in the transformation file. Refer to the
following template as you follow the steps to create the file.
Template 23: transformation entry in transformation.SID file

like:owner.%\_string I | U | D | IUD owner.procedure_name
1 Change directories to the data sub-directory of the SharePlex variable-data directory.
2 Open the transformation.SID file in either the vi text editor (UNIX) or WordPad
(Windows).
3 [OPTIONAL] You can enter comment lines to identify the file or convey other informa-
tion. Precede each comment line with a pound (#) symbol to indicate that it is non-
functioning, and end each one by pressing Enter.
4 Specify the target table(s). You can specify an individual target table for a routine.
Type the owner and name, separating them with a dot (.) but no spaces.
Or...
You can use the LIKE operator and a SQL wildcard (%) to specify multiple tables
using a search string, as shown in Template 23 and in the following examples.
You can use an underscore (_) to denote a single-character wildcard. For table names
containing 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.
Examples:
like:scott.%\_corp\_emp
scott.emp
Note: If you are not using the LIKE operator, you need not specify the backslash escape
character when using table names containing underscores.
Do not press Enter after this entry.Type at least a space or tab to create a second col-
umn.
5 Specify the Operation Type(s). If the procedure is written for all types of SQL
statements, enter the string IUD. If the procedure is operation-specific, enter either
an I, a U, or a D. Do not press Enter.
6 Type at least a space or tab to create a third column.
7 Specify the Procedure. Type the owner and name of the transformation routine, sep-
arating them with a dot (.). Allow no space between any items.
Example: scott.emp_tr
CHAPTER 6 257
The completed line should look like one of the following examples.
like:scott.%\_corp\_emp IUD scott.emp_tr
Or...
scott.emp U scott.emp_tr_u
Or...
like:scott.%\_corp\_emp U scott.emp_tr_u
8 Start a new line and repeat steps 4 through 7 for each additional transformation rou-
tine.
9 When you are finished creating the conflict resolution file, save and close it using the
:wq command in vi or Save on the File menu in WordPad.
Changing the transformation file

You can change the transformation file any time during replication to add and remove
tables and procedures. When you change the transformation file, stop and re-start the
Post process so that it updates the resolution cache.
Part 3: Setting environment parameters
This section addresses environment-related aspects of customizing SharePlex.
Setting the SP_SYS_VARDIR environment variable

The SP_SYS_VARDIR environment variable points to the SharePlex variable-data
directory so that sp_cop can locate the configuration data, queues, logs and other infor-
mation. When there is only one instance of SharePlex installed in the normal manner on
a machine, this variable does not have to be set. On UNIX systems, the proddir/data/
defaults.yaml file points sp_cop to the variable-data directory. On Windows systems,
the variable-data directory is set in the SharePlex entry in the Registry.
Set SP_SYS_VARDIR when directed to do so by a documented SharePlex procedure.

For example, it is used when a replication configuration uses multiple instances of
sp_cop, which requires multiple variable-data directories. It also is used when Share-
Plex is installed within a high-availability cluster.
To set the SP_SYS_VARDIR environment variable

ksh shell:
export SP_SYS_VARDIR= /full pathname of variable-data directory
csh shell:
setenv SP_SYS_VARDIR /full pathname of variable-data directory
For more information about the SharePlex marker file, see The SharePlex directories
on page 37. For more information about installing SharePlex on clustered systems, see
the SharePlex Installation and Demonstration Guide.
CHAPTER 6 259
Setting an alternative port for sp_cop

The default TCP and UDP port numbers for SharePlex are both set to 2100 at the time
of installation. Unless you need to use a port number other than 2100, do not change the
port. Before selecting a port number, review the following points:
If you are using Oracle version 9.2.x, you need to change the SharePlex port number
because Oracle uses port 2100 for an XML daemon.
If you are running multiple instances of sp_cop on a system, alternative port num-
bers are used. Each instance has a unique variable-data directory and port number.
For more information about running multiple instances of sp_cop, see page 64.
When an alternative port is required, the same number must be used for the TCP and
UDP ports, and it must be used for the TCP and UDP ports for the associated
instances of sp_cop on all other machines involved in replication. The sp_cop pro-
cess listens on each system on TCP and UDP ports for communications from Share-
Plex processes on other systems in the network, such as a command or exchange
between the Export and Import processes. If the ports are different, sp_cop on one
system cannot connect to the sp_cop on another system to send or receive messages.
On the Windows platform, SharePlex permits a maximum of 64 port numbers
(SharePlex instances) on one system.
To set the SharePlex port on UNIX systems

To set the port number, a SharePlex Administrator must set both the TCP and UDP port
parameters in the paramdb file. To set the port number when you have an active
configuration, you will be instructed to stop access to the source objects and shut
down sp_cop.
1 [IF YOU ARE USING MULTIPLE VARIABLE-DATA DIRECTORIES ONLY] Export the SP_SYS_VARDIR
environment variable to point to the correct variable-data directory for the port you
are setting. See page 258 for instructions.
2 Export the following environment variables on the source and target systems.
ksh shell:
$ export SP_COP_TPORT=portnumber
$ export SP_COP_UPORT=portnumber
where portnumber is the new port number
csh shell:
$ setenv SP_COP_TPORT portnumber
$ setenv SP_COP_UPORT portnumber
where portnumber is the new port number
3 Change directories to the SharePlex product directory, then start sp_cop and sp_ctrl
on the source and target systems. If you are using multiple variable-data directories,
start sp_cop with the -uportnumber option, where portnumber is the port number you
are setting.
$ cd /SharePlex_product_dir/bin
$ ./sp_cop -uportnumber &
$ ./sp_ctrl
4 At the sp_ctrl prompt, set the following parameters on the source and target sys-
tems:
sp_ctrl> set param SP_COP_TPORT portnumber
sp_ctrl> set param SP_COP_UPORT portnumber
5 Do one of two things:
If there is not an active configuration, shut down sp_cop on the source and target
systems. The next time you start sp_cop, the new port number takes effect. You
are finished setting the port number.
sp_ctrl> shutdown
Or...
If there is an active configuration, stop access to the replicating objects on the
source system, then issue the flush command in sp_ctrl on the source system to
clear the queues. For datasource in the following syntax, substitute o. followed by
the ORACLE_SID of the source instance for example o.oraA. Proceed with the
rest of the steps.
sp_ctrl(sysA)> flush datasource
6 [ACTIVE CONFIGURATIONS ONLY] Issue the qstatus command on the source system to verify
that all of the messages reached the target system. Continue to issue the command
until the export queue is empty.
sp_ctrl> qstatus
CHAPTER 6 261
7 [ACTIVE CONFIGURATIONS ONLY] Issue the qstatus command on the target system to verify
that all of the messages were posted to the database. Continue to issue the command
until the post queue is empty.
sp_ctrl> qstatus
8 [ACTIVE CONFIGURATIONS ONLY] Issue the status command on the target system to verify
that Post stopped.
sp_ctrl> status
9 [ACTIVE CONFIGURATIONS ONLY] Shut down SharePlex on the source and target systems.
sp_ctrl> shutdown
10 [ACTIVE CONFIGURATIONS ONLY] Start sp_cop on the source and target systems. The new
port takes effect.
$ cd /SharePlex_product_dir/bin
$ ./sp_cop &
11 [ACTIVE CONFIGURATIONS ONLY] Start the Post process on the target system.
12 [ACTIVE CONFIGURATIONS ONLY] Allow users to access the replicating objects.
13 [ACTIVE CONFIGURATIONS ONLY] Verify that all SharePlex processes on the source and tar-
get systems are running.
sp_ctrl> status
To set the SharePlex port on Windows systems

The default port number for SharePlex is 2100, but there can be multiple port numbers
if you installed SharePlex to create multiple services for certain replication configura-
tions, such as consolidated replication. SharePlex port numbers are stored in the Win-
dows Registry. If it becomes necessary to change a port number, this is the SharePlex
entry location: \HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Soft-
ware\SharePlex.
To change the port number

4 In the Port list box, select the port number for the instance of SharePlex whose port
you want to change.
6 Click Close to close the SharePlex Utilities dialog box.

CHAPTER 6 263
7 From the Start menu, select Run.
8 In the Run dialog box, type regedit to open the Registry Editor.
9 In the Registry Editor, under \HKEY_LOCAL_MACHINE\Soft-

ware\Wow6432node\Quest Software\SharePlex, right click the ports folder name,
then select Rename. This highlights the port number.
10 Replace the highlighted port number with the new number.
11 By default, the Registry entry for the variable-data directory includes the port num-
ber, and it must be changed to reflect the new number. Click the Registry folder for
the new port number to highlight it.
12 Under Name in the pane on the right, right-click the SP_SYS_VARDIR entry that is
associated with the new port number, then select Modify.
13 In the Edit String dialog box, change the port number in the path to the new port
number, then click OK to return to the Registry Editor.
14 Exit the Registry Editor.
15 Go to the SharePlex product directory and rename the variable-data directory to

reflect the new port number.
16 Double-click the SpUtils desktop shortcut to open the SharePlex Utilities dialog
box again.
CHAPTER 6 265
17 In the Port list box, select the port number that you created.
18 Under SharePlex Service Status, click Install to establish the SharePlex service
under that port
19 After the Current State text box displays a message that the service is installed, click
Start to start the service.
20 Click Close to close the SharePlex Utilities dialog box.
Setting a default port for sp_ctrl

On Windows systems, you can set a default port number for the sp_ctrl process so that
it automatically connects to that port when it starts. This is useful when you have multi-
ple instances of SharePlex on the same system. You can connect to the other SharePlex
instances by using the port command after sp_ctrl starts. If you do not set a default port
number, sp_ctrl connects to the SharePlex instance with the lowest port number.
To set a default port for sp_ctrl

1 From the Start menu, click Run.
2 In the Run dialog box, type regedit, then click OK to run the Registry Editor pro-
gram.
3 Under My Computer, drill down to the SharePlex entry of

\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\Quest Software\Share-
Plex.
4 Click the SharePlex node.
5 In the Name column in the right pane, right click DefaultPort, then select Modify to
open the Edit String dialog box.
6 In the Value Data text box, enter the port number to be used as the default, then click
OK.
7 Exit the Registry Editor.
Defining an alternative editor

When you issue the create config or edit config command to create or change a Share-
Plex configuration, the command runs the default text editor. During installation on
UNIX systems, the text editor is set to vi because it is a universal ASCII editor. On Win-
dows systems, the text editor is set to WordPad, and files created through sp_ctrl in
WordPad are saved in ASCII text format.
It is recommended that you use the default editors. SharePlex reads configuration files
in ASCII format only, and sp_ctrl is configured to work with those editors. If you must
change the editor, use the following guidelines.
On a UNIX system, the new editor must be an ASCII text editor.
On a Windows system, you can use NotePad instead of WordPad because it is an
ASCII editor. Do not use a word processing program such as Microsoft Word, even
if you intend to save the file in text format. Configuration activation will fail.
CHAPTER 6 267
To change the editor on UNIX systems

To set a different ASCII text editor as the default for SharePlex on a UNIX system,
define it with the EDITOR variable in one of two ways:
To set the EDITOR variable each time you run sp_ctrl, enter the appropriate com-
mand at the UNIX prompt before starting sp_ctrl.
To set the EDITOR variable permanently, enter the appropriate command in the shell
startup script on each machine.
Syntax for the ksh shell

export EDITOR=name of new text editor
Syntax for the csh shell
setenv EDITOR name of new text editor
To change the editor on Windows systems

To change the text editor for SharePlex on a Windows system, change it through the
Registry. Instructions for changing Registry entries are on page 282.
Part 4: Using security with SharePlex
This section includes ways to employ security measures with SharePlex.
Enhancing security with host authorization

SharePlex provides host authorization security that verifies whether or not SharePlex
processes on other 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 for using the auth_hosts file

The file must be named auth_hosts and saved in the data sub-directory of the
SharePlex variable-data directory for SharePlex to use it. Do not save it in the data
The auth_hosts file is optional, but if it exists on a system, it must contain valid
entries. If an auth_hosts file exists but contains no entries, or if it contains invalid
entries, SharePlex sends an error message similar to the following example to the
Event Log: unauthorized connection attempt
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.
The name of the local system must be listed in this file, or host authorization will not
function.
To implement host authorization

1 Run an ASCII text editor such as vi (UNIX), NotePad (Windows), or WordPad (Win-
dows) to open a blank file. If you are using a UNIX text editor, change directories to
the data sub-directory of the SharePlex variable-data directory before you run the
editor.
2 [UNIX ONLY] Press the i key to enter text-input mode in vi.
CHAPTER 6 269
3 [OPTIONAL] Any number of lines can contain comments. Precede a comment line with a
pound symbol (#) to render it non-functional. End commented lines by pressing
Enter.
4 On the first non-commented line, enter the full machine name of the local system.
LocalSys.xyzcompany.com
6 Do one of two things:

To grant connection authorization on the local machine to all systems requesting it,
type the word all, then skip to step 9.
all
Or...
To grant connection permission on the local system to specific systems, type the full
host name of the first system to be granted connection.
system1.xyzcompany.com
8 For each additional system for which you are granting permission, start a new line in
the file and type its full name. End each line by pressing Enter.
Example of completed file:
LocalSys.xyzcompany.com
9 When you are finished editing the file, save it in one of the following two ways.
To save in vi
1 Press Esc to exit text-input mode.
2 Type :w auth_hosts, then press Enter.
3 Type :q!, then press Enter to return to the command-line.
To save in a Windows text editor
1 Click the File menu, then click Save.
2 In the Save in field, type the full path name of the data sub-directory of the
SharePlex variable-data directory, or use standard Windows methods to navigate
to that directory.
3 Click Save.
Data encryption and SharePlex

SharePlex uses the SSH Secure ShellTM utility to provide encryption for network ser-
vices 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 con-
nections through it. Client-server applications using the tunnel provide their own
authentication procedures the same way they would without the encrypted tunnel. The
following illustration shows how data from the source machine is replicated and sent via
the encrypted tunnel to the target machine.
Note: SSH is not included with Shareplex and must be purchased separately.
Configuring SharePlex and SSH

SharePlex can be configured to work with SSH (Secure Shell) software between a
source system and one target system.
To use SharePlex with SSH, set the following parameter as follows.
CHAPTER 6 271
SP_XPT_USE_LOCALHOSTThe SharePlex Export process reads this parameter

before making a TCP connection. If the parameter is enabled, the Export process
connects to the local host through a tunnel port number, instead of connecting
directly to a target system.
SP_XPT_PORT_OVERRIDE This parameter sets the tunnel port number, which
overrides the default SharePlex port.
To configure SharePlex to work with SSH port forwarding

1 On the source and target systems, choose an available local port to be used as the
tunnel port, according to the following instructions. It can be the same port on both
systems.
For peer-to-peer replication, choose the same port for both systems.
For uni-directional replication, choose a different local port for each target sys-
tem to which the source system will connect using SSH. One of those ports can be
the same port as the one SharePlex uses on the source system.
2 On the source and target systems, issue the SSH commands with the -L option to
build the tunnel using the ports that you designated.
$ ssh -L source_port:target_machine:target_port myuserid@target_machine -N -f
Note: SSH must be run with the -f option, which forces the SSH shell to run in the back-
ground. If you do not use the -f option, the terminal window from which SSH was
launched must be kept open. (SSH can not be started with the nohup option.)
You will be prompted for the password corresponding to myuserid@target_machine.

If you need to connect to multiple machines, simply specify more -L options in the
SSH command. Please refer to your SSH user documentation for syntax and exam-
ples.
3 On the source system, start sp_cop* and sp_ctrl.
4 In sp_ctrl, set the following parameter on the source system.

If there is only one target system, set the parameter on a global basis with the fol-
lowing syntax.
sp_ctrl(sysA)> set param SP_XPT_USE_LOCALHOST 1
Or...
* On UNIX systems, run sp_cop from the bin sub-directory of the product directory. On Windows systems, start the
SharePlex service from the Sp_Utils utility.
If you have multiple replication routes, you can use SSH only for one of them. In
that case, use a process-specific option to direct SharePlex to connect to the local
host for the route using SSH. Replication to the other target systems will connect
directly in the normal fashion.
sp_ctrl(sysA)> set param SP_XPT_USE_LOCALHOST to hostname 1
5 Verify the parameter changeby issuing the list param modified command.
sp_ctrl(sysA)> list param modified
6 Do one of the following, depending on whether or not there is an active configura-

tion.
[IF A CONFIGURATION IS ACTIVE] Shut down and then restart sp_cop on the source system
so that the parameter changes take effect.
sp_ctrl> shutdown
$ /productdir/bin/sp_cop &
Or...
[TO ACTIVATE A CONFIGURATION] Activate the replication configuration.
sp_ctrl(sysA)> activate config filename
CHAPTER 6 273
Part 5: Turning on Change Tracking
In some environments, there is a need to keep track of changes made to a set of tables in
the database. For example, in certain circumstances it can be important to track every
change made to a table to resolve customer disputes. SharePlex now has the option to
store the change data on a secondary server using log mining technology. The cost of
extracting changes from the source database using log mining is negligible, making use
of this functionality feasible. Since the change data is stored in a different database, all
change data inquires can be offloaded from the production database.
For every change to a row, SharePlex records the user id, timestamp, SCN, source row
id, key values, transaction id, operation type and the changed column values. For update
operations, SharePlex records the after image of the columns changed.
To set up the change tracking functionality:
"Define the table(s) in the configuration file, using the syntax for change tracking:
owner.table !cdc:owner.table <target host>@c.<target sid>
Note that a change tracker target is defined by prepending "!cdc:" to the target table
name and by using "c." instead of "o." in the SID specification.
Create the target table with the same name and the same structure as the source table,
except for constraints (Post will fail if there is a NOT NULL constraint on any of the
columns).
Run the following script to add columns to the target table for the userid, time, etc:
optdir/util/add_change_tracking_columns.sql
The add_change_tracking_columns script will add the following columns to the target
table:
SHAREPLEX_SOURCE_TIME TIMESTAMP
SHAREPLEX_SOURCE_USERID NUMBER
SHAREPLEX_SOURCE_OPERATION VARCHAR2(20)
SHAREPLEX_SOURCE_SCN NUMBER
SHAREPLEX_SOURCE_ROWID ROWID
SHAREPLEX_SOURCE_TRANS VARCHAR2(60)
SHAREPLEX_OPERATION_SEQ NUMBER
The SHAREPLEX_SOURCE_TIME column will have the time that the operation was
applied by Oracle on the source. The SHAREPLEX_SOURCE_USERID column will
have the user id from the source of the user that applied the change. The
SHAREPLEX_SOURCE_OPERATION column will be updated with one of six
possible values:
INSERT
UPDATE
DELETE
COMMIT
TRUNCATE
DROP COLUMN
The SHAREPLEX_SOURCE_SCN column will have the source SCN at the time that
the operation occurred. The SHAREPLEX_SOURCE_ROWID column will have the
rowid of the row changed. The SHAREPLEX_SOURCE_TRANS column will have
the transaction id with which the change is associated. The
SHAREPLEX_OPERATION_SEQ column will have an incrementing value for every
operation with the same transaction id.
The actual table columns are divided logically into the key columns, and the non-key
columns. For insert and update operations, SharePlex replicates the key columns and
the non-key columns that were changed by the original DML. When post inserts a row
into the target table it may insert a value into one or more of the table columns as
follows
Operation Key Columns Non-key Columns - updated

INSERT X X
UPDATE X X
DELETE X
If the parameter SP_OPO_TRACK_PREIMAGE is set, two rows will be inserted into

the target table for every update. The SHAREPLEX_SOURCE_OPERATION column
values for the two records will be:
UPDATE BEFORE
CHAPTER 6 275
UPDATE AFTER
The SP_OPO_TRACK_OPERATIONS parameter can be used to disable tracking of
inserts, updates or deletes. The default value is "I/U/D". To configure post so that only
the inserts and updates are tracked, change the parameter to "I/U".
The COMMIT record will only be written to the target table if the parameter
SP_OPO_TRACK_COMMITS parameter is set to 1. The parameter is set to 0 by
default.
To track all columns of the row when an update occurs, instead of just the changed
columns, perform the following on the source:
1 Turn on supplemental logging for all columns for each where this behavior is
desired. For example, "Alter table emp ADD SUPPLEMENTAL LOG DATA
(ALL) COLUMNS;".
2 Tell Shareplex to process these extra columns by turning on the

SP_OCT_USE_SUPP_KEYS parameter:
set param SP_OCT_USE_SUPP_KEYS 1

Note the following when using the change tracking feature:
The target table must not have PK, UK, not null, check, or default value constraints
Only ALTER TABLE ADD and ALTER TABLE MODIFY DDL will be applied to
the target table
Changes made to UDT or VARRAY columns will not be recorded on the target
If a DBMS_LOB operation is used to change a part of the LOB column, the value
stored for that column on the target will not be the complete LOB column
Part 6: Other optional features
This section includes other features that allow you to customize SharePlex to your
needs.
Configuring SharePlex startup status on Windows

systems
You can change the startup status of SharePlex from automatic to manual, or from man-
ual to automatic by using the Services Control Panel in the Computer Management
Administrative Tool (see page 277).
You also can control the user account that is responsible for SharePlex startup through
the Services Control Panel.
3 In the Service dialog box, click OK to complete the change and close the dialog box.
CHAPTER 6 277
To change SharePlex startup on Windows systems

1 From the Start menu, select Programs, then click Administrative Tools, then Com-
puter Management.
2 In the Computer Management window, expand the Services and Applications

node.
3 Click the Services sub-node, then scroll in the pane on the right to locate the Share-
Plex service.
4 Right-click the SharePlex service, then select Properties. This opens a SharePlex
Properties dialog box.
5 In the SharePlex Properties dialog box, click the General tab.
6 In the Startup Type drop-down list box, select either Automatic, Manual or Dis-
abled.
From the SharePlex Properties dialog box, you can specify a SharePlex Adminis-
trator as the only user who can change startup status of SharePlex, instead of grant-
ing anyone with System Account privileges that control. To change startup
permission, continue to the next step. To exit the SharePlex Properties dialog box
without changing startup permission, click OK.
CHAPTER 6 279
7 In the Properties dialog box, click the Log On tab.
8 In the Log on as option box, click This account, then click Browse to open the
Select User dialog box.
9 In the Select User dialog box, under Name, double-click the SharePlex Administra-
tor user.
The Log On dialog box appears, with the SharePlex Administrator displayed in the
This account field.
10 In the Password and Confirm fields, enter and confirm the password for the Share-
Plex Administrator account.
11 Click OK to apply the change and exit the Properties dialog box.
Setting SharePlex process priority on Windows systems

To change process priority for SharePlex, you must run the Windows Task Manager
with special privileges because the MKS NuTCRACKER environment controls the
SharePlex processes. You can change SharePlex process priority in one of the following
ways.
Setting priority with a SharePlex utility

The easiest and safest way to set process priority correctly is to set it from the Task
Manager function within the SpUtils or SpClient utility. Instructions for running SpCli-
ent are on page 454, and instructions for using SpUtils are on page 451. These utilities
enable you to limit the Task Manager view to the SharePlex processes, excluding all
other processes running on the system.
CHAPTER 6 281
Setting priority with a batch file

You can set process priority by running a batch file named DTaskmgr using the follow-
ing instructions.
To change process priority with DTaskmgr

1 Log onto the system as the System Administrator account.
2 Navigate to DTaskmgr in the bin sub-directory of the SharePlex product directory,

and run it. The Windows Task Manager opens with the special privileges.
3 Click the Processes tab to display all processes that are running.
4 Right-click the SharePlex process that you want to prioritize, then click Set Priority
and select the desired priority level.
5 The system prompts for verification. Click either Yes to implement the change or No
to cancel it.
6 Close the DTaskmgr dialog box.
Changing SharePlex Registry entries on Windows

systems
SharePlex records and reads default directory locations and other environment informa-
tion in the Windows Registry. The SharePlex Registry location is:
\HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Software\SharePlex
Each instance of SharePlex is recorded in the Registry as a port number, and each has its
own set of environment variables. Whenever you must add, change or remove environ-
ment variables for SharePlex, make the change in the Registry with the regedit pro-
CHAPTER 6 283
gram, using the following instructions. Any change to the environment requires
restarting the SharePlex service to take effect.
The following are the environment variables that can be set for SharePlex in the Regis-
try. Most of these are debugging parameters that you might be asked to set when you
place a call to Quest Technical Support.
EDITOR SP_DEBUG_OPC SP_SPIN_OPO

HOST SP_DEBUG_OPP SP_SPIN_ORD
LOGNAME SP_DEBUG_OPST SP_SPIN_XPT
OL_DEBUG SP_DEBUG_OPST SP_SPOOL_OCT
ORADUMP SP_DEBUG_OPST SP_SPOOL_OPO
SIM_KERNEL SP_DEBUG_ORD SP_SPOOL_OPO
SP_CNF_SKIP_ANALYZE SP_DEBUG_RMP SP_SPOOL_OPO
SP_CONF_SPIN SP_DEBUG_ROM SP_SPOOL_ORD
SP_COP_TPORT SP_DEBUG_SQL SP_STOP_GEN
SP_DEBUG_BIO SP_DEBUG_SQL_LCACHE SP_STOP_OCAP
SP_DEBUG_DDL SP_DEBUG_TRP SP_STOP_OPC
SP_DEBUG_FIO SP_OBJECTID SP_STOP_OPP
SP_DEBUG_GEN SP_OCAP_TEST_LOG1 SP_STOP_ROM
SP_DEBUG_KCA SP_OPO_DISCARD_MSG SP_SYS_HOST_NAME
SP_DEBUG_LCACHE SP_QUE_PAUSE SP_SYS_VARDIR
SP_DEBUG_MSG SP_QUE_SIGBUS USERNAME
SP_DEBUG_MSG SP_SPIN_CNC VERBOSE
SP_DEBUG_OCAP SP_SPIN_IMP
SP_DEBUG_OLOG SP_SPIN_OCT
To add a Registry entry

1 Shut down the SharePlex service.
3 In the Run dialog box, type regedit to run the Registry Editor.
4 Under \HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Software\SharePlex in the

Registry Editor, right click the SharePlex port number for the variable that you want
to add, then select New>String Value.
5 In the Name column of the pane on the right, replace the highlighted new string with
the SharePlex variable name.
Replace this with the

variable name.
CHAPTER 6 285
6 Right-click the new string, which now bears the variables name, then select Modify.
The Edit String dialog box appears.
7 In the Value data field of the Edit String dialog box, type the variables character
string.
8 Click OK, then close the Registry Editor.
9 Start the SharePlex service.
To change a Registry entry:

1 Shut down the SharePlex service.
3 In the Run dialog box, type regedit to run the Registry Editor.
4 Under \HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Software\SharePlex in the

Registry Editor, highlight the SharePlex port number for the variable that you want
to change. Its Registry entries are displayed in the pane on the right.
5 In the pane on the right, right-click the variable to be changed and select Modify.
6 In the Value Data field of the Edit String dialog box, enter the new string.
7 Click OK, then close the Registry Editor.
8 Start the SharePlex service.

7
Starting SharePlex Replication
The previous chapters provided you with the background to plan and establish your rep-
lication environment. This chapter explains how to synchronize the source and target
data and activate your configuration to begin SharePlex replication.
The first part of this chapter contains procedures for synchronizing the data. The second
part reviews the configuration activation process. Review the second part of the chapter
before you synchronize the data, because it will help you choose an activation method.
The third part of the chapter explains how to make changes to configurations.
This chapter assumes that you have:
Determined your replication strategy.
Configured your database and system to implement your replication strategy.
Learned how to build a SharePlex configuration.
Contents
Synchronizing data for the first time

Activating and deactivating configurations
Changing Configurations
Part 1: Synchronizing data for the first time
Replication requires matching sets of data source (original) data on the source sys-
tem and target (copy) data on each target system. Before you activate a configuration
for the first time, you must synchronize the source and target data for that configuration.
SharePlex maintains a synchronized environment through replication, but it does not
perform initial synchronization. This section explains how to synchronize your data
with the following methods for copying data from a source system to a target system.
Synchronizing data using an Oracle hot backup on an active database
Synchronizing data using an Oracle hot backup on a quiet database
Synchronizing data with export/import or store/restore from tape
Synchronizing data with FTP
Synchronizing data with transportable tablespaces
The procedures in this chapter include certain SharePlex commands. Before you exe-
cute a command, review its description in the SharePlex Reference Manual and famil-
iarize yourself with its syntax. In addition, review Activating and deactivating
configurations on page 308 to familiarize yourself with configuration activation
options.
CHAPTER 7 289
Synchronizing data using an Oracle hot backup on an

active database
SharePlex, in conjunction with activation, a hot backup and the reconcile command,
lets you perform initial synchronization to establish a target or secondary instance with-
out quieting the source database.
Warning!
To establish consolidated replication, 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 to copy the objects from the other instances.
Possible methods include export/import (see page 299), FTP (see page 302), and trans-
portable tablespaces (see page 305).
To establish peer-to-peer replication, you must quiet all of the secondary source sys-
tems for the duration of this procedure. 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. Do not use this procedure
until you understand the implications of using peer-to-peer replication. See Establishing
peer-to-peer replication on page 211 for more information.
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. Since Oracle runs as a service on Windows, this
procedure is necessary because the Registry entries are needed in order to perform the
database recovery process. You need not populate the database, since the hot backup
will do this.
Important! Before beginning this procedure, have your configuration(s) ready to be acti-
vated.
Procedure for all replication strategies except cascading

Use this procedure only for these replication scenarios:
Reporting and broadcast replication from one source system directly to one or
more target systems.
High availability replication from a primary system to one or more secondary sys-
tems that are ready for failover. (In this procedure, the secondary system is referred
to as the target system.)
Consolidated replication of different data from two or more source systems to a

central target system.
Peer-to-peer replication between two or more source systems. (In this procedure,
the trusted source system is referred to as the source system, and the secondary
system(s) is referred to as the target system.
For cascading replication (replicating to an intermediary system and, from there, to a

target system), use Procedure for cascading replication on page 292.
1 [UNIX 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 you will be activating.
2 On the source and target systems, install SharePlex according to the instructions in
the SharePlex Installation and Demonstration Guide, but only run ora_setup on the
source system. It cannot be run on the target system until that database has been
recovered and opened. (There must be a valid SID in the oratab file or Windows
Registry.) See Chapter 11 for instructions on running ora_setup or use the instruc-
tions in the SharePlex Installation and Demonstration Guide.
3 On the source and target systems, go to the bin sub-directory of the SharePlex prod-
uct directory, and start sp_cop and sp_ctrl.
4 On both systems, verify that the SharePlex processes are started.

sp_ctrl(sysA)> status
sp_ctrl(sysB)> status
5 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.
6 On the source system, run the Oracle hot backup.
7 When the backup is finished, activate the configuration on the source system.
8 On the source system, issue the show activate command to view activation status.
The command retains control of sp_ctrl until activation is finished.
sp_ctrl(sysA)> show activate
CHAPTER 7 291
9 When activation is complete, switch log files on the source system. Next, select one
of the following options.
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.
10 On the target system:
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 9.
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.
11 On the target system, open the database with the RESETLOGS option.
12 On the target system, run ora_setup on the database, but do not create a new user.
Choose the existing SharePlex user and password (copied in the backup) by choos-
ing n when prompted Would you like to create a new SharePlex user [y]. In
this case, you need not shut down SharePlex when you run ora_setup.
13 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 9.
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 9.

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.
14 On the target system, run the cleanup.sql script to truncate all of the SharePlex
internal tables. Instructions for running this script are on page 435.
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 cascading deletes, check constraints, and scheduled
jobs that perform DML.
17 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
titioned replication for any tables, delete the unneeded columns and rows from the
target tables.
18 [HIGH AVAILABILITY ONLY] On the target (secondary) system, stop Export.

sp_ctrl(sysB)> stop export
19 [HIGH AVAILABILITY AND PEER-TO-PEER ONLY] On the target (secondary) system, activate the
configuration.
sp_ctrl(sysB)> activate config filename
20 On the target system, start the Post process. The two instances are now in synchroni-
zation, and SharePlex will continue replicating to maintain synchronization.
21 [OPTIONAL] If this was only a partial backup, drop the tablespaces that were not copied
over during the hot backup.
Procedure for cascading replication

Use this procedure for cascading replication in which SharePlex posts to a database on
an intermediary system and then replicates the posted data to a target system. You will
apply the backup to the intermediary system first (represented as sysB), and then to
the target system (represented as sysC).
CHAPTER 7 293
are correct for the instances you will be establishing with the hot backup. The SID
must be the SID used in the routing map in the configuration you will be activating.
2 On all systems, install SharePlex according to the instructions in the SharePlex

Installation and Demonstration Guide, but only run ora_setup on the source system.
It cannot be run on the other systems until their databases have been recovered and
opened. (There must be a valid SID in the oratab file or Windows Registry.) See
Chapter 11 for instructions on running ora_setup or use the instructions in the
SharePlex Installation and Demonstration Guide.
3 On all systems, go to the bin sub-directory of the SharePlex product directory, and
start sp_cop and sp_ctrl.
4 On all systems, verify that the SharePlex processes are started.

sp_ctrl(sysC)> status
5 On the intermediary and target systems, stop the Post process. This allows replicated
data to accumulate in the post queue until the databases have been recovered.
sp_ctrl(sysC)> stop post
6 On the source system, run the Oracle hot backup.
7 After the backup is finished, activate the configuration on the source system.
9 After activation is complete, switch log files on the source system and 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 step 9.
11 On the intermediary system, open the database with the RESETLOGS option.
12 On the intermediary system, run ora_setup on the database, but do not create a new
user. Choose the existing SharePlex user and password (copied in the backup) by
choosing n when prompted Would you like to create a new SharePlex user
[y]. In this case, you need not shut down SharePlex when you run ora_setup.
13 On the intermediary system, issue the reconcile command. If you are using named
post queues, issue the command for each one. Substitute the sequence number of the
log that you noted in step 9. Issue the qstatus command if you are unsure of the
queue name. The reconcile process retains control of sp_ctrl until it is finished, and
then the sp_ctrl prompt returns.
sequence_number
For example: if you are reconciling 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
14 On the intermediary system, run the cleanup.sql script to truncate all of the Share-
Plex internal tables. Instructions for running this script are on page 435.
15 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.
16 On the intermediary system, disable cascading deletes, check constraints, and sched-
uled jobs that perform DML.
17 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(sysB)> set param SP_OCT_REPLICATE_POSTER 1
titioned replication for any tables, delete the unneeded columns and rows from those
tables on the intermediary system.
Important! Do not start any Post processes yet!

CHAPTER 7 295
19 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 from step 9.
20 On the target system, open the database with the RESETLOGS option.
21 On the target system, run ora_setup on the database, but do not create a new user.
Choose the existing SharePlex user and password (copied in the backup) by choos-
ing n when prompted Would you like to create a new SharePlex user [y]. In
this case, you need not shut down SharePlex when you run ora_setup.
22 On the target system, run the cleanup.sql script to truncate all of the SharePlex
internal tables. Instructions for running this script are on page 435.
23 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.
24 On the target system, disable cascading deletes, check constraints, and scheduled
jobs that perform DML.
tables on the target system.
26 On the intermediary system, activate the configuration using default multi-threaded

activation.
27 On the intermediary system, issue the show activate command to view activation
status. The command retains control of sp_ctrl until activation is finished.
sp_ctrl(sysB)> show activate
28 When activation of the intermediary configuration is complete, 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(sysC)> start post
Synchronizing data using an Oracle hot backup on a quiet

database
You can use SharePlex and an Oracle hot backup on a quiet database to establish a target
reporting instance, or to convert a hot standby database to a target reporting instance.
This procedure can be used for all replication configurations. It requires that users stop
accessing the production database while the hot backup and configuration activation
take place.
Warning!
To establish consolidated replication, 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 to copy the objects from the other instances.
Possible methods include export/import (see page 299), FTP (see page 302), and trans-
portable tablespaces (see page 305).
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. Since Oracle runs as a service on Windows, this
procedure is necessary because the Registry entries are needed in order to perform the
database recovery process. You need not populate the database, since the hot backup
will do this.
vated.
These instructions include references to an intermediary system, which is used in cas-

cading replication where SharePlex posts to a database on one system and then repli-
cates the posted data to another system. If you are not using this replication strategy, you
can ignore all references to an intermediary system.
or Windows Registry are correct for the instance(s) you will be establishing with the
hot backup. The SID must be the SID used in the routing map in the configuration(s)
you will be activating.
2 On the source system, install SharePlex and run ora_setup according to the instruc-
tions in the SharePlex Installation and Demonstration Guide.
CHAPTER 7 297
3 On the intermediary and target systems, install SharePlex, but do not run ora_setup.
You will do this after the backup.
4 On the source system, complete the Oracle hot backup.
5 On the source system, stop user access to the source database by shutting it down and
opening it in restricted mode.
6 On the source system, switch the redo logs, and record the log number.
7 On all systems, start sp_cop and sp_ctrl from the bin sub-directory of the SharePlex
product directory.
8 On all systems, verify that sp_cop and sp_ctrl are started.

9 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.
10 On the source system, activate the configuration using default multi-threaded activa-
tion.
12 When the activation is finished, allow users to access the source database again.
13 List the archive logs on the intermediary and target systems. Delete any logs after the
one whose number you recorded when you switched logs on the source system. That
log must be last, because it is the log to which Oracle must recover.
14 On the intermediary and target systems, recover the database (or hot standby) to the
log number that was recorded. Do not cancel the recovery or allow a partial recovery.
15 On the intermediary and target systems, open the database.
16 On the intermediary and target systems, run ora_setup on the instance, but do not
create a new user. Choose the existing SharePlex user and password by selecting n
when prompted Would you like to create a new SharePlex user [y]. See
Chapter 11 for instructions on running ora_setup, or use the instructions in the
Tip: You need not create a new user because the existing user was copied with the
backup.
17 On the intermediary and target systems, run the cleanup.sql script to truncate all of
the SharePlex internal tables. Instructions for running this script are on page 435.
18 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.
19 On the intermediary and target systems, disable cascading deletes, check constraints,
and scheduled jobs that perform DML.
tables on the intermediary and target systems.
21 [CASCADING REPLICATION 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(sysB)> set param SP_OPO_REPLICATE_POSTER 1
22 On the intermediary and target systems, activate the configuration.

23 After the activation of the configuration is complete, start the Post process on the
intermediary and target systems. The instances are now in synchronization, and
SharePlex will continue replicating.
CHAPTER 7 299
Synchronizing data with export/import or store/restore

from tape
The procedures for synchronizing source and target data with import/export and store/
restore from tape are the same. Follow these steps in the order written. This procedure
requires that users stop accessing the database while the copy and configuration activa-
tion take place.
These instructions assume you already created the target instance, installed SharePlex
on the source and target systems, and ran ora_setup on the source and target instances
according to the instructions in the SharePlex Installation and Demonstration Guide.
vated.
1 Stop access to the objects to be replicated on the source system.

If you are replicating for centralized reporting (consolidated replication), you can
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 instruc-
tions.
For peer-to-peer replication, stop access to all databases in the configuration,
including the trusted source.
2 Export or store the files from the source system (trusted source system in peer-to-
peer replication).
3 Start sp_cop and sp_ctrl on the source system. For consolidated replication using
separate instances of sp_cop, first export the port and SP_SYS_VARDIR variables
for the variable-data directory on this system.
4 Activate the configuration on the source system. See page 310 for information about
activating a configuration. For peer-to-peer replication, activate the configuration on
the trusted source system only. This allows the activation process to proceed while
you are making the copy.
5 Start sp_cop and sp_ctrl on the target system(s) and the intermediary system, if
using cascading replication.
For consolidated replication using separate instances of sp_cop, first export the
port and SP_SYS_VARDIR variables for the variable-data directories.
For peer-to-peer replication, start the sp_cop and sp_ctrl processes on the second-
ary source systems the ones to which you want to copy the trusted source sys-
tems data.
6 Stop Post on the target system(s) and the intermediary system, if using cascading
replication.
If this is a target system for consolidated replication running multiple instances of
sp_cop, stop Post for each one.
For peer-to-peer replication, stop Post on all secondary source systems.
Stopping Post allows any data that gets replicated before the target data is established
to collect in the post queue.
7 Allow users to access the database on the source system again (only the trusted
source system in peer-to-peer replication; all source systems in consolidated replica-
tion).
8 Use the status command on the source system to make sure the SharePlex processes
are running.
9 Import or restore the data on the target system(s) and intermediary system if using
cascading replication with an Oracle database on that system, or the secondary sys-
tem(s) for high availability and peer-to-peer replication.
10 Follow the appropriate instructions for managing triggers.

A For high availability replication: Run the sp_add_trigger.sql utility script
(SharePlex product directory/util) on the secondary tables to direct triggers to
ignore the SharePlex Oracle user.
B For peer-to-peer replication: Run the sp_add_trigger.sql utility script (SharePlex
product directory/util) on all tables to direct triggers to ignore the SharePlex Ora-
cle user.
C For all other replication scenarios: You can either disable triggers on the target
tables and the target tables on the intermediary system if using cascading replica-
tion, or run the sp_add_trigger.sql utility script (SharePlex product directory/util)
so that triggers will ignore the SharePlex user.
11 Disable check constraints, cascading deletes, and scheduled jobs that perform DML
on the target tables (and the target tables on the intermediary system if using cascad-
CHAPTER 7 301
ing replication). For peer-to-peer replication, all cascading delete functionality must
be incorporated into triggers on all replication systems.
tables.
13 [CASCADING REPLICATION ONLY] Set the SP_OPO_REPLICATE_POSTER parameter on the

intermediary system to 1. This directs SharePlex to capture posted changes on that
system and replicate them to the target system.
14 [CASCADING REPLICATION ONLY] Activate the configuration on the intermediary system.

15 [HIGH AVAILABILITY ONLY] Stop Export on the target system(s).

16 [HIGH AVAILABILITY AND PEER-TO-PEER REPLICATION ONLY] Activate a configuration on the sec-
ondary system (high availability) or all other source systems (peer-to-peer) that repli-
cates to the source (or trusted source) system.
17 Start Post on the target system(s), intermediary system (cascading replication) or all
systems (peer-to-peer replication). If this is a central target system running multiple
sp_cop instances, start Post for each one. SharePlex begins executing the SQL state-
ments that have been collecting in the post queue, keeping the source and target data
in sync.
18 [PEER-TO-PEER REPLICATION ONLY] Allow users to access the databases on all systems.
Synchronizing data with FTP

Follow these steps in the order written. These instructions assume you have already cre-
ated the target instance, installed SharePlex on the source and target systems, and ran
ora_setup on the source and target instances per the instructions in the SharePlex
Installation and Demonstration Guide. This procedure requires that users stop accessing
the database while the copy and configuration activation take place.
Important! Before beginning this procedure, have your configuration ready to be acti-
vated on the source system.
1 Shut down the source Oracle instance.

If you are replicating for centralized reporting (consolidated replication), you can
shut down all of the source instances at once and make the copies at the same time,
or you can synchronize each source instance one at a time using these instructions.
For peer-to-peer replication, shut down all databases in the configuration, includ-
ing the trusted source.
2 FTP the files from the source system to the target system(s), ensuring that you pre-
serve file permissions and ownerships. For peer-to-peer configurations, FTP the files
from the trusted source system to the other secondary source systems.
3 Start sp_cop and sp_ctrl on the source system. For consolidated replication using
separate instances of sp_cop, first export the port and SP_SYS_VARDIR variables
for the variable-data directory on this system.
4 Open the source Oracle instance but do not allow users to access it.
using cascading replication.
For consolidated replication using separate instances of sp_cop, first export the
port and SP_SYS_VARDIR variables for the variable-data directories.
CHAPTER 7 303
For peer-to-peer replication, start the sp_cop and sp_ctrl processes on the second-
ary source systems the ones to which you want to copy the trusted source sys-
tems data.
replication.
8 Allow users to access the database on the source system again (only the trusted
source system in peer-to-peer replication; all source systems in consolidated replica-
tion).
9 Use the status command on the source system to make sure the SharePlex processes
are running.
10 Open the target instance(s) and the intermediary instance if using cascading replica-
tion. Open all instances on all secondary source systems for peer-to-peer replication.
11 Import or restore the data on the target system(s), the intermediary system (cascading
replication), or the secondary source systems (peer-to-peer replication).

cle user.
tables (and the target tables on the intermediary system if using cascading repli-
cation), or run the sp_add_trigger.sql utility script (SharePlex product directory/
util) so that triggers will ignore the SharePlex user.
on the target tables and the target tables on the intermediary system if using cascad-
ing replication. For peer-to-peer replication, all cascading delete functionality must
tables.



systems (peer-to-peer replication). If this is a central target running multiple sp_cop
instances, start Post for each one. SharePlex begins executing the SQL statements
that have been collecting in the post queue, keeping the source and target data in
sync.
CHAPTER 7 305
Synchronizing data with transportable tablespaces

The transportable tablespace feature allows you to quickly synchronize and resynchro-
nize numerous objects with minimal downtime. It allows you to export just the metadata
(data dictionary) and then copy the datafiles. This method also moves indices, eliminat-
ing the need to rebuild them on the target system, and you can move multiple
tablespaces at one time.
These instructions assume familiarity with using the transportable tablespace feature
and contain only the steps required for using this feature to synchronize data for replica-
tion.
These instructions assume you already installed SharePlex on the source and target sys-
tems, and ran ora_setup on the source and target instances per the instructions in the
vated.
1 Set the source tablespace to READ ONLY (alter tablespace TRANS read only;).
using cascading replication. For consolidated replication using separate sp_cop pro-
cesses, first export the port and SP_SYS_VARDIR variables for the variable-data
directories. For peer-to-peer replication, start the sp_cop and sp_ctrl processes on
the secondary source systems the ones to which you want to copy the trusted
source systems data.
replication.
5 Export the metadata to an export file according to Oracles instructions.
6 When the export is finished, copy the datafiles to another location on the source sys-
tem (trusted source in peer-to-peer replication). This minimizes the impact on the
source database of copying the files to the target system.
7 Set the source tablespace(s) back to read/write mode (alter Tablespace NAME read
write;)
8 If any of the copied datafiles and tablespaces exist in the target database(s), interme-
diary database (cascading replication), or secondary databases (high availability or
peer-to-peer replication), drop them so that the copied files can be applied.
9 Copy the files from the new location on the source system to the target system(s) (or
secondary systems) and intermediary system (cascading replication).
10 On the systems to which you copied the files, use the Oracle import utility to import
the metadata and the tablespace definitions.
11 Set the tablespace(s) on those systems to read/write mode.
12 Open all instances to which you copied the files.

cle user.
tables (and the target tables on the intermediary system if using cascading repli-
cation), or run the sp_add_trigger.sql utility script (SharePlex product directory/
util) so that triggers will ignore the SharePlex user.
on the target tables and the target tables on the intermediary system if using cascad-
CHAPTER 7 307
ing replication. For peer-to-peer replication, all cascading delete functionality must
tables.



systems (peer-to-peer replication). If this is a central target running multiple sp_cop
instances, start Post for each one. SharePlex begins executing the SQL statements
that have been collecting in the post queue, keeping the source and target data in
sync.
Part 2: Activating and deactivating

configurations
When you activate a configuration, replication begins.
Important! Before you use the activate config command, be sure to run the verify con-
fig command. For more information on this command, refer to the SharePlex Reference
Manual.
The configuration remains active when you shut down sp_cop and when a system, the
network, or an Oracle instance becomes unavailable. Replication temporarily ceases,
and it resumes automatically when operations are restored.
A configuration ceases to be active when:
it is deactivated by an authorized SharePlex user with the deactivate config or abort
config command, or with a SharePlex utility that includes deactivation,
Or...
it is automatically deactivated by the activation of another configuration replicating
data from the same datasource (Oracle instance).
To activate a configuration, the database containing the objects to be replicated must be
mounted and open. The length of time that activation takes varies, depending on the
size, number and structure of the database objects, the amount of row chaining, and the
type of activation you are using.
About configuration activation

To activate a configuration, use the activate config command in sp_ctrl. When you are
following a documented SharePlex procedure, such as initial synchronization or resyn-
chronization, use the recommended command options.
Important! Before you use the activate config command, review that command and the
other configuration commands in the SharePlex Reference Manual.
CHAPTER 7 309
During activation, SharePlex performs the following procedures.
1. Assign an activation ID
An activation ID number is assigned that identifies the configuration activation and its
associated replication processes and queues. This number is stored in the
SHAREPLEX_ACTID internal table and is transparent to SharePlex users.
2. Create an object and partition cache

An object cache is built to map the Oracle object ID of each table and sequence to the
objects name.
For all tables, the object cache includes the name, size, and type of columns, NOT-
NULL constraints, and whether a column is part of a key.
For tables using vertically partitioned replication, additional column information is
included about the columns being replicated.
For tables using horizontally partitioned replication, SharePlex builds a partition
cache that records the partition conditions, routing and other essential information.
3. Add a configuration change marker

A configuration-change marker is placed in the data stream that tells sp_cop to gener-
ate 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

Configured tables are locked so that they can be activated. Tables are
locked in the following ways:
All tables added to replication are locked.
All tables removed replication are locked.
All tables in an active configuration where destination routes have changed are
locked, but not the tables whose routes did not change.
The tables are locked in a locking thread. As many tables can be locked concurrently as
there are threads. When the table is locked, an activation marker is placed in the data
stream that tells the capture process to start (or stop) replicating that table. The table is
then unlocked.
5. Unlock the tables

The tables are unlocked when activation is complete, and users can access the data once
again.
Before you activate a configuration

The following guidelines help ensure that activation is successful.
Consider using Oracle wildcards to simplify your config

Use of Oracle wildcards in the configuration file make it possible for you to specify all
the objects belonging to the same owner (or in the same schema) for replication using a
single entry. You may also include, in the single entry, exceptions using not notation.
You may also use wildcards to replicate a set of objects in a specific source schema to
the same objects on the target, but where the objects reside in under a different owner
(or schema) name on the target. When a new table is created, it can be automatically
added to replication if it meets the wildcard criteria. See page 137 for information on
using Oracle wildcards.
Other activation guidelines

Verify that the ORACLE_SID and ORACLE_HOME values are correct in the
oratab file or Windows Registry, and that the SID matches the one specified as the
datasource in the configuration.
Objects in the configuration must exist in the source instance before you activate. If
objects are listed in a configuration, but are not created until after activation, their
activation fails.
Oracle partitions on tables must be created before activation. Partitioning a table
while it is actively replicating causes SharePlex to lose the identifying information it
has compiled, and DML from that table partition is not replicated. To add an Oracle
partition to a replicating table, see page 379.
If you are using Oracle wildcards insure that all the conditions and limitations are
taken into account prior to activation. See page 137 for more information.
CHAPTER 7 311
Viewing 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 dis-
plays their status in the order in which they started.
Viewing configuration statistics

Use the show config command in sp_ctrl to view statistics for active configurations.
This command displays a configurations status, its datasource, the date and time it was
activated, and the number of objects that are configured.
Deactivating a configuration
To deactivate a configuration, you can:
activate a new configuration for the same datasource, which will deactivate the orig-
inal configuration.
Or...
use the deactivate config or abort config command in sp_ctrl.
The syntax for the deactivate config and abort config commands is shown below.
There are significant differences between the two commands. For more information
about these and other SharePlex commands, see the SharePlex Reference Manual.
sp_ctrl(sysA)> deactivate config filename
Or
sp_ctrl(sysA)> abort config filename
Warning! Deactivating or aborting a configuration stops replication. If users con-

tinue making changes to the configured objects, the source and target data can go out of
synchronization.
Part 3: Changing Configurations
These instructions assume you are familiar with configuration construction. For more
information about configuration construction, see Chapter 5.
To change an active configuration, copy the configuration with the copy config com-
mand, then edit it with the edit config command. Copying a configuration before mak-
ing changes preserves the original file in case it is needed again or a mistake is made
during editing. And, you can control when the new configuration is activated. For this
reason, SharePlex does not permit an active configuration to be edited directly.
Unless you are adding numerous objects to a configuration or adding tables with exten-
sive chaining, activation of an edited configuration is less time-consuming than the orig-
inal activation if you do not deactivate the original configuration. The new
configuration activates before the existing one deactivates, so SharePlex only analyzes
added, changed or removed objects. By contrast, when you deactivate the original con-
figuration and then activate a new one, SharePlex re-analyzes all the objects.
See Chapter 10 for procedures to follow when changing Oracle characteristics of repli-
cating objects.
Adding objects to an active configuration

When objects are added to an active configuration, only those objects are analyzed, so
the activation is less time-consuming than a first-time activation.
Tip: If you are using Oracle wildcards and the object that you are adding is covered by
the Oracle wildcard specification in the configuration file, it is not necessary to add the
object to the config file. Any new objects that match the criteria are automatically added
into replication. See page 137 for information on using Oracle wildcards.
CHAPTER 7 313
To add tables to an active configuration

1 Synchronize the new source and target tables according to the directions in Syn-
chronizing data for the first time on page 288. Do not deactivate the existing config-
uration.
2 In sp_ctrl, issue the copy config command. Substitute the original configurations
name for filename, and the name of the new configuration for newname. This creates
an exact copy of the configuration and returns you to the sp_ctrl prompt.
sp_ctrl(sysA)> copy config filename to newname
3 Open the new configuration using the edit config command. This opens the configu-
ration file in the default text editor for SharePlex (vi for UNIX, WordPad for Win-
dows).
sp_ctrl(sysA)> edit config newname
4 Add each new tables source owner and name, target owner and name, and routing
map to the new configuration.
Example
owner.table owner.target_table sysB@o.targetSID
5 Save the new configuration with either the :wq command if using vi or with Save on
the File menu if using WordPad.
6 When you are ready to activate the new configuration, stop user access to the added
tables.
7 In sp_ctrl, issue the activate config command for the new configuration.
sp_ctrl(sysA)> activate config newname
The old configuration automatically deactivates.
Warning! SharePlex executes the command without requiring confirmation.
8 Restore user access to the tables.

Adding sequences to an active configuration

Use one of the following sets of instructions to add sequences to an active configuration,
depending on whether or not the sequences are used to populate a column in a table.
To add a sequence that does not populate a column

The following procedure can be used whether or not a sequence populates a column in a
table. This procedure involves stopping user access to the objects. If a sequence popu-
lates a column in a table and you cannot stop user access, use the To add a sequence
that populates a column procedure, which follows this procedure.
1 Stop user activity on the source system.
dows).
4 Add the owner and name of each new source sequence, the owner and name of each
target sequence, and the routing map to the new configuration.
Example
owner.sequence owner.target_sequence sysB@o.targetSID
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} x {source_CACHE_value} = START_WITH_value
CHAPTER 7 315
8 Restore user activity on the source system.
To add a sequence that populates a column

Use this procedure to add a sequence to an active configuration if the sequence popu-
lates a column in a table and you cannot stop user access to the objects.
dows).
3 Add the owner and name of each new source sequence, the owner and name of each
target sequence, and the routing map to the new configuration.
Example
owner.sequence owner.target_sequence sysB@o.targetSID
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 syn-
chronization point between source and target data. For datasource in the following
syntax, substitute o. followed by the ORACLE_SID of the source instance for

example o.oraA.
7 After Post stops, issue the following Oracle command on the target system to find
the last known value of the sequence.
select max(column_name) = last known value
8 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.
9 Starting with the value obtained by the select max (column_name) command in step 7,
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.
10 To the value obtained in step 9, add another multiple of
{source_INCREMENT_BY_value x source_CACHE_value}. The result determines the
START WITH value of the target sequence. Continuing with the example, the
START WITH value would be:
40 + (2 x 10) = 60.
11 Create the target sequence with the START WITH value that you determined.
12 Start the Post process.

SharePlex will continue replicating, while keeping the target sequence at least one mul-
tiple of {source_INCREMENT_BY_value x source_CACHE_value} ahead of the source
sequence.
CHAPTER 7 317
IMPORTANT! Sequences continue to be incremented even when a transaction is rolled

back. If a source table using a replicated sequence has many rollback operations, it
causes sequence values to increase without actually being used in columns in the table.
As a result, when the next valid operation is replicated, the sequence value on the target
system could be less than the value in the replicated row. When there are numerous roll-
backs, 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.
Removing objects from an active configuration

Removing objects from an active 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 orig-
inal activation.
Tip: You can prevent posting for a table without removing it from the configuration file if,
for example, there is data corruption or some other reason for not wanting DML or DDL
operations on the table to be applied to the target table. To prevent posting for a table,
use the SP_OPO_DISABLE_OBJECT_NUM parameter. For more information about this
parameter, see the SharePlex Reference Manual.
To remove objects
1 In sp_ctrl, enter the copy config command. Substitute the original configurations
an exact copy of the configuration and returns you to the sp_ctrl prompt. Do not
deactivate the original configuration.
dows).
3 In the new configuration, delete the entry for each object to be removed from replica-
tion. (Or if the object you are removing from replication is covered by an entry that
employs Oracle wildcards, use not notation to exclude the object from replication.
See page 137 for information on using Oracle wildcards.).
4 Save the new configuration with either the :wq command if using vi, or with Save on
5 Stop user access to the removed objects.
6 In sp_ctrl, activate the new configuration when you are ready.

The original configuration automatically deactivates.

CHAPTER 7 319
7 After activation, restore user access to the objects.
Changing partitioned replication

You can change replication for a table that uses vertically or horizontally partitioned
replication while the configuration is active. For horizontally partitioned replication,
you might need to change the SHAREPLEX_PARTITION table as well as the configu-
ration, depending on the change required.
To change horizontally partitioned replication

To change replication for a table using horizontally partitioned replication, do one of the
following, referring to the preceding instructions in this chapter for changing configura-
tions, and in Configuration for horizontally partitioned replication on page 160, if
necessary.
To add a partition scheme, insert the scheme information and column conditions into
the SHAREPLEX_PARTITION table, and add a configuration line for the source
and target objects that will use that scheme.
To change a partition scheme, update or delete the rows in the
SHAREPLEX_PARTITION table that relate to that scheme. If the change involves
renaming the partition scheme itself, edit the configuration entry accordingly.
To remove a partition scheme from replication, remove the entry for that scheme
from the configuration file. You can, but are not required to, remove the partition
scheme information from the SHAREPLEX_PARTITION table.
To add a new target system to a partition scheme when that system is not also in a
routing map somewhere in the configuration, add a routing map for it in the configu-
ration. Begin the line with an exception marker (!) and one or more spaces, for exam-
ple:
! sysD@o.oraD
To change vertically partitioned replication

To change replication for a table that uses vertically partitioned replication, copy the
active configuration, then make the required changes to the column partition in the new
configuration, referring to the preceding instructions in this chapter for changing config-
urations and the instructions in Configuration for vertically partitioned replication on
page 172, if necessary. Stop user access to the affected table, then activate the new con-
figuration.
8
Using SharePlex in a High-
Availability Environment
This chapter shows you how to maintain replication in a high-availability UNIX envi-
ronment after a system or database failure, or for planned failover for maintenance or
other operations.
The procedures in this chapter assume true high availability, where primary (source) and
secondary (target) databases are mirrors of each other, including the owners and table
names.
Important! Before you use the procedures in this chapter, see Establishing replication
for high availability and data recovery on page 190 for instructions for establishing
SharePlex replication in a high-availability environment.
Contents
Failing over to a secondary system after an unplanned system failure

Failing back to the primary system after an unplanned system failure
Restoring replication when the secondary instance fails
Planned failover and failback
Failing over to a secondary system after an unplanned

system failure
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 replication environ-
ment, you can move users to the secondary (target) machine and then back again with
minimal downtime using SharePlex and a hot backup of the secondary instance.
For this procedure, you use activation and the reconcile command, which synchronizes
the results of the backup or copy with ongoing replicated user changes after the copied
instance is recovered.
This procedure addresses the SharePlex requirements for the failover. Instructions for
switching users back to the primary system begin on page 324.
This procedure assumes that:
You established a replication environment for high availability according to the
instructions in Establishing replication for high availability and data recovery on
page 190.
You activated a reverse configuration on the secondary system that is ready to repli-
cate users changes from that system to the primary system.
You have current backups of the UNIX files containing SharePlex environment
information as recommended in Regular SharePlex backups on page 129, so that
archives are available for restoration.
To fail over to the secondary system

1 Verify that Export is stopped on the secondary system.
2 Allow all of the transactions in the post queue on the secondary system to post to the
secondary instance. Use the qstatus command to check the posting process until the
number of backlogged messages is 0.
sp_ctrl(sysB)> qstatus
Note: Do not wait for the number of messages to be 0. SharePlex posts transactions as
they are received, but also retains them in the post queue in case of data recovery. A
commit releases them from the queue. If the primary system failed before the commit
CHAPTER 8 323
Using SharePlex in a High-Availability Environment
was received, these partial transactions remain in the queue indefinitely. This is
addressed later in these procedures.
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.
* If started, Export will repeatedly try to connect to the primary system, wasting system resources.
Failing back to the primary system after an unplanned

system failure
Follow these steps to move users back to the primary machine after it has been recov-
ered. This procedure is divided into phases to make it easier to understand and follow.
Phase 1: Restore the replication environment on the primary system

1 On the primary system, recover the SharePlex directories, system files and Oracle
files from the 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. When you copied the archived
SharePlex variable-data directory to the primary system, you copied the configura-
tion that was active before the system failed. This causes the Capture process to set
the transaction number to 1 when replication from the primary system resumes.
Phase 2: Purge the queues

5 Run sp_ctrl on both systems.
6 On both systems, use the syntax provided in the following examples to issue the
delete queue command to delete the following queues:
Note: The delete queue command will fail if there are messages in backlog.
A Delete the capture queue on the primary system

sp_ctrl(sysA)> delete queue datasource:C
Example: sp_ctrl(sysA)> delete queue o.oraA:C
B Delete the export queue on the primary system

sp_ctrl(sysA)> delete queue queuename:X
Example: sp_ctrl(sysA)> delete queue sysA:X

CHAPTER 8 325
C Delete the post queue on the secondary system

sp_ctrl(sysB)> delete queue queuename:P for datasource-datadest
Example: sp_ctrl(sysA)> delete queue sysA:P for o.oraA-o.oraB
Note: You are issuing the delete queue command on the primary system because you
restored the old SharePlex queues when you restored the archived SharePlex directo-
ries (capture and export from the primary configuration).
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. SharePlex will rebuild the queues when you reactivate the configu-
ration and the two systems are reconciled.
For more information about the delete queue command, see the SharePlex Reference
Manual.
Phase 3: Start replication from secondary to primary system

7 Issue the status command on the primary system to verify that all SharePlex pro-
cesses are stopped.
8 Stop the Post process on the primary system

sp_ctrl(sysA)> stop post
9 Start the Export process on the secondary system. This establishes communication
between the primary and secondary systems.
sp_ctrl(sysB)> start export
Phase 4: Synchronize the data

10 Do a hot backup on the secondary system using an Oracle hot backup.
When the hot backup is finished, switch log files on the secondary system and
make a note of the highest archive-log sequence number. Recover the primary
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
whose number you recorded. Open the database with the RESETLOGS option.
Note: This resets the sequences on the primary system to the top of the cache upon
startup.
11 On the primary system, issue the reconcile command. If you are using named post
queues, issue the command for each one. (Issue the qstatus command if you do not
know the queue name.) The reconcile process retains control of sp_ctrl until it is fin-
ished, and then the sp_ctrl prompt returns.
Use this command, substituting the sequence number of the log that you recorded in
step 10.
sp_ctrl(sysA)> 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(sysA)> reconcile queue SysA for o.oraA-o.oraA [seq 1234]
12 Disable or modify the following on the primary system.

triggers
foreign key constraints
cascading delete constraints
check constraints
scheduled jobs that perform DML
13 Log onto SQL*Plus on the primary system 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.
SQL> @/productdir/bin/cleanup.sql
14 Truncate the SHAREPLEX_TRANS table on the secondary system. This table con-
tains transaction information that the Post process was using before the primary sys-
tem failed, and therefore that information is obsolete. Truncating the table restores
transaction consistency between the two systems.
Phase 5: Activate replication on the primary system

15 In sp_ctrl, activate the configuration on the primary system using default multi-
threaded activation.
CHAPTER 8 327
16 Start Post on the primary system.

sp_ctrl(sysA)> start post
Phase 6: Restoring the object cache

17 Issue the status command on the primary system. You will see that Post has
stopped due to an error. The error is due to a missing object cache. The following
steps guide you in restoring the object-cache file.
18 Issue the show log command for the Event Log on the primary system, and filter
for the keyword objcache. Look for a Post error message referring to a file with a
name similar to the example below, containing the string objcache_sp_opst_mt, fol-
lowed 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 refer-
ring to a different object-cache file but ending with the same number, such as the
number .18 in the example.
sp_ctrl(sysA)> show log filter=objcache
Example Post object-cache file:

0x0a0100c5+PP+sys4+sp_opst_mt+o.quest-o.ov-objcache_sp_opst_mt.18
19 Make a note of the full pathname of the Post object-cache file(s) referenced in the
error message. The path will be the state directory in the SharePlex variable-data
directory, for example:
splex_vardir/state/0x0a0100c5+PP+sys4+sp_opst_mt+o.quest-o.ov-
objcache_sp_opst_mt.18.
20 Shut down SharePlex on the secondary system. This will flush Captures object
cache to disk so that the file can be copied to the primary system.
sp_ctrl(sysB)> shutdown
21 On the secondary system, change directories to the state sub-directory of the Share-
Plex variable-data directory and locate the Capture object-cache file. This file will
have a name similar to the one in the following example. 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.
Example Capture object-cache file:

o.quest-objcache_sp_ocap.18
22 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 in step 19.
23 Start Post on the primary system.

sp_ctrl(sysA)> start post
Phase 7: Switch users back to the primary system

24 Stop user access on the secondary system.
25 View the post queue on the primary system using the qstatus command. Continue
to view it until the number of messages is 0.
sp_ctrl(sysA)> qstatus
26 Shut down the secondary instance using the following Oracle command.
svrmgrl> shutdown
27 Start up the secondary instance using the following Oracle command.

svrmgrl> startup
Note: This resets the sequence on the secondary system to the top of the cache to syn-
chronize with the primary system.
28 Enable all database objects that were disabled on the primary system in preparation
for users to access them.
29 Start SharePlex on the secondary system.
30 Stop Post on the secondary system.

31 Move users back to the primary system.
32 Disable or modify the following on the secondary system according to your replica-
tion strategy, in preparation for the database to become the failover database again.
triggers
CHAPTER 8 329

check constraints
33 Start Post on the secondary system.
34 Use the qstatus command on the primary system to view the number of messages
in the post queue. Keep checking until the number of messages is 0.
35 When the number of messages is 0, switch users back to the primary system.
36 Stop Export on the secondary system to prevent accidental changes made on that
system from being replicated to the primary system.
Note: The secondary system is now in a failover-ready state again, with no users, an
active configuration, disabled or modified triggers, disabled constraints and scheduled
jobs, and a stopped Export process
Restoring replication when the secondary instance fails

You can use a hot backup and SharePlex to recover the secondary instance if it fails.
This eliminates the need to reactivate the configuration on the primary system after the
secondary instance is recovered.
you have established a replication environment for high availability according to the
instructions in the SharePlex Implementation Guide
you have an active reverse configuration on the secondary system that is ready to
replicate users changes back to the primary system.
you made regular backups of the UNIX files containing SharePlex environment
information as recommended in Regular SharePlex backups on page 129, so that
archives are available for restoration.
This procedure is divided into phases to make it easier to understand and follow.
Phase 1: Purge the queues

1 Stop the Post process and deactivate the configuration on the secondary system.
sp_ctrl(sysB)> deactivate config filename
Note: The deactivation causes an error: Error in sp_cnc. in the Event Log. You may
ignore it and continue with the procedure.
2 Run sp_ctrl on the primary system.
3 On the primary system, use the syntax provided in the following example to issue
the delete queue command to delete the post queue.
sp_ctrl(sysB)> delete queue queuename:P for datasource-datadest
Example: sp_ctrl(sysA)> delete queue sysA:P for o.oraA-o.oraB

CHAPTER 8 331
Note: You are issuing the delete queue command on the primary system because there
could be messages remaining from uncommitted transactions sent from the secondary
instance before it failed.
4 Truncate the SHAREPLEX_TRANS internal table on the primary machine. 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. Trun-
cating the tables restores transaction consistency.
5 Run sp_ctrl on the secondary system.
6 On the secondary system, use the syntax provided in the following examples to
issue the delete queue command to delete the following queues:
A Delete the capture queue on the secondary system

sp_ctrl(sysA)> delete queue datasource:C
Example: sp_ctrl(sysA)> delete queue o.oraA:C
B Delete the export queue on the secondary system

sp_ctrl(sysA)> delete queue queuename:X
Example: sp_ctrl(sysA)> delete queue sysA:X
Note: You are issuing the delete queue command 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. The goal of this procedure is to re-initialize replication by
resynchronizing the data, and therefore the existing transaction records must be purged.
Phase 2: Synchronize the data

Begin a hot backup on the primary system using an Oracle hot backup.
7 Switch log files on the primary system and make a note of the highest archive-log
sequence number.
8 Recover the secondary 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 7.
9 Open the database with the RESETLOGS option.
Note: This resets the sequence on the secondary system to the top of the cache upon
startup.
10 Log onto SQL*Plus as the SharePlex Oracle user on the secondary system, and run
the cleanup.sql script from the bin sub-directory of the SharePlex product directory.
This script truncates the SharePlex tables and updates the SHAREPLEX_ACTID
table.
SQL> @/productdir/bin/cleanup.sql
11 On the secondary system, issue the reconcile command. If you are using named
post queues, issue the command for each one. (Issue the qstatus command if you do
not know the queue name.) The reconcile process retains control of sp_ctrl until it is
finished, and then the sp_ctrl prompt returns.
Use the following command, substituting the sequence number of the log that you
recorded earlier.
sequence_number
syntax would be:
sp_ctrl(sysA)> reconcile queue SysA for o.oraA-o.oraA [seq 1234]
12 Disable or modify the following on the secondary system.

triggers
check constraints
13 When the sp_ctrl prompt returns, stop the Export process on the secondary system
so that nothing accidentally gets replicated to the primary system when the configu-
ration is re-activated.
CHAPTER 8 333
Phase 3: Start the replication processes on the secondary system

14 Activate the configuration on the secondary system using default multi-threaded
activation.
15 Start the Post process on the secondary system to start posting replicated data from
the primary system.
16 Start any other SharePlex processes on the secondary system that were stopped due
to error when the secondary instance failed.
sp_ctrl(sysB)> start service
The secondary instance is now ready for future failover.

Planned failover and failback

When you maintain a secondary instance with SharePlex in a high-availability environ-
ment, you can switch users to that system when maintenance or other operations must
be performed on the primary system.
you have established a replication environment for high availability according to the
instructions in Establishing replication for high availability and data recovery on
page 190.
you have an active reverse configuration on the secondary system that is ready to
replicate users changes back to the primary system.
there is enough disk space on the drive where the SharePlex queues are located on
the secondary system to hold accumulated messages while users work there.
To switch users to the secondary system

1 On the primary system, stop user access to the objects.
2 On the primary system, issue the flush command to flush the data to the secondary
system. This command stops the Post process on the secondary system and places a
marker in the data stream, establishing a synchronization point between the primary
and secondary data. In the syntax below, substitute o. followed by the
ORACLE_SID of the primary instance.
3 Verify that the Post process has stopped on the secondary system. (Keep issuing the
command until it shows that Post has stopped due to the flush.)
4 Verify that there are no messages in the capture and export queues on the primary
system, and none in the post queue on the secondary system. The Number of Mes-
sages and the Backlog (messages) fields must be 0.
5 Shut down SharePlex on the primary system (if needed).

CHAPTER 8 335
6 Shut down the instance on the primary system using the following Oracle com-
mand. You must use the abort option, not the immediate option, for this procedure.
svrmgrl> shutdown abort
Note: This resets the sequence on the primary system to the top of the cache upon
startup.
7 Verify that Export is stopped on the secondary system. This prevents users changes
from being replicated to the primary system until it is ready. The messages will accu-
mulate in the export queue.
svrmgrl> stop export
secondary system.
9 Run the script that enables triggers and constraints on the secondary system when
10 Implement the failover procedure for relocating users to the secondary system,
including starting the applications and starting jobs that were running on the primary
system.
11 Move users to the secondary system and let them resume working, but do not start
Export.
To switch users back to the primary system (planned failback)

When the primary system is ready to be used again, follow these steps to switch them
back to that system.
1 Open the primary instance.
Note: The sequence on the primary system is now at the top of the cache.
2 Disable or modify the following on the primary system:

triggers
foreign-key constraints
check constraints
3 Start SharePlex on the primary system (if needed).
4 Start Export on the secondary system so that SharePlex sends the accumulated mes-
sages to the primary system.
sp_ctrl(sysB)> start export
Note: SharePlex passes any sequence updates from the secondary system back to the
primary system when Export starts.
5 Stop Export on the primary system.

sp_ctrl(sysA)> stop export
6 Wait until Post on the primary system has processed the messages that accumulated
on the secondary system before proceeding to the next step.
7 On the secondary system, stop user access to the objects after Post has regained its
processing pace.
8 On the secondary system, flush the data to the primary system.

sp_ctrl(sysB)> flush datasource
9 Verify that the Post process has stopped on the primary system by issuing the status
command. Keep issuing the status command until it shows that Post has stopped.
10 Verify that there are no messages in the capture and export queues on the secondary
system, and none in the post queue on the primary system. The Number of Mes-
sages and the Backlog (messages) fields must be 0.
11 Shut down SharePlex on the secondary system.
12 Shut down the instance on the secondary system using the following Oracle com-
mand. You must use the abort option, not the immediate option, for this procedure.
svrmgrl> shutdown abort
CHAPTER 8 337
13 Start the instance on the secondary system using the following Oracle command.
svrmgrl> 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 sec-
ondary system is at the top of a cache.
primary system.
15 Run the script that enables triggers and constraints on the primary system when
16 Implement the failover procedure for relocating users back to the primary system,
including starting the applications and starting jobs that were running on the second-
ary system.
17 Switch users to the primary system and let them resume working, but do not start
Export. This prevents users changes from being replicated to the secondary system
until that machine is ready to received replicated data. The messages will accumulate
in the export queue. Use the following command to stop Export if it is running.
18 Disable or modify the following on the secondary system:

triggers
foreign-key constraints
check constraints
19 Start SharePlex on the secondary system.
20 Stop Export on the secondary system. This prevents accidental DML that might
occur on that system from replicating to the primary system.
21 Start Export on the primary system. The regular high-availability environment is

restored, where the secondary system is maintained by replication as a standby for
the primary system.
sp_ctrl(sysA)> start export
22 Start Post on the secondary system so that replicated changes from the primary sys-
tem begin posting to the secondary database.
9
Unattended SharePlex Monitoring
In addition to the interactive monitoring that you can do with the information com-
mands in sp_ctrl, SharePlex provides monitoring scripts and SNMP traps for unat-
tended monitoring of replication and remote notification of problems. This chapter
provides instructions for using these features.
Contents
Monitoring SharePlex on UNIX systems

Monitoring SharePlex on Windows systems
Using SNMP with SharePlex
Part 1: Monitoring SharePlex on UNIX systems
SharePlex is designed to run reliably in the background without supervision, but unfore-
seen situations can occur in any replication environment. For example, a system or the
network could fail and cause data to accumulate in the queues. Or, one or more Share-
Plex processes could stop as the result of a user command or an error. This section
explains how to use the SharePlex monitoring scripts to notify you of key replication
events.
Overview of the SharePlex Monitoring Utilities

SharePlex provides the following scripts for monitoring replication.
sp_eventmon monitors the SharePlex Event Log and reports errors that you specify in
a special file.
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.
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.
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.
The monitoring scripts provide the following benefits:
Less need for frequent status checks with sp_ctrl status commands.
Flexibility to run independently at regular intervals or as a scheduled crontab job.
Custom configuration capabilities.
Regular output to a log file on the system being monitored.
CHAPTER 9 341
E-mail and/or paging notification of conditions requiring immediate attention. The

subject field of the e-mail contains a brief notation of the problem, and the contents
provide the full message generated by the script.
Platform independence. All scripts are UNIX shell scripts.
Location of the monitoring utilities

The SharePlex monitoring utilities are located in the util sub-directory of the SharePlex
product directory on UNIX systems. Run the scripts from this location:
<optdir>/util
If you need to modify a script, modify it in the following location:
<optdir>/.app-modules
Requirements for using the monitoring utilities

The scripts must be customized to reflect your environment, such as the type of e-
mail or paging available.
To use the monitoring utilities, start sp_cop with the -uname option, where name can
be an identifier of your choice. Suggestions are:
--the SharePlex port number
--the ORACLE_SID of the instance for which replication is being monitored
--the SharePlex Administrators name
See Starting sp_cop with the -u option on UNIX systems on page 63 for instruc-
tions and syntax.
SharePlex must be running prior to executing a monitoring script.
The monitoring utility scripts must remain together in the installed directory
(/SharePlex_product_directory/util). Do not move these scripts to a different direc-
tory.
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.
Users of the monitoring utilities must have the following rights:
--local access to sp_ctrl and permission to run the script on the system on which the
sp_cop to be monitored is running.
--Korn (ksh) shell access and ps permission from the UNIX command line.
--read, write and execute permissions to the directory where the scripts reside.
The permission on the iwgrep utility must be 755.
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.
Paging requires that your service provider supports receiving e-mails on your paging
device.
Verify the ORACLE_HOME (the path to the ORACLE_HOME directory) for each
Oracle instance being monitored.
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.
Upgrade instructions
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.
CHAPTER 9 343
Monitoring the Event Log with sp_eventmon

The sp_eventmon monitoring utility monitors the SharePlex Event Log (event_log) at
set intervals for entries relating to key replication events. You can define the scan inter-
val and the error messages you want the script to detect. Each scan starts where the pre-
vious one stopped to keep the impact on the system minimal and prevent duplicate
warnings.
Actions taken by sp_eventmon

The sp_eventmon script takes the following actions after each scan of the Event Log:
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.
THE FOLLOWING ERRORS WERE FOUND IN THE SHAREPLEX EVENT LOG FOR
INSTANCE:SID
It also logs each error, the errors Event Log line number, the sp_cop instance name
(typically the port number), and the time and date of the errors occurrence.
If the e-mail option is enabled, the subject text is:
Errors found in SharePlex log!
Requirements for running sp_eventmon

Before you use the sp_eventmon utility, see Requirements for using the monitor-
ing utilities on page 341.
The sp_eventmon utility relies on the iwgrep program (see page 341), the error_list
file (described in this section), and a marker file named username.mrk (where user-
name 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.
When you run sp_eventmon, it creates the username.mrk file. This file prevents
duplicate warning messages from being sent to the log and your e-mail or pager. If
you delete this file, the script still will function, but sp_eventmon will start scanning
the Event Log from the beginning every time it starts. This causes warnings that
were previously generated to be sent again. Note that if you are running multiple
instances of sp_eventmon, each instance must be run under the name of a different
UNIX user. Thus, each *.mrk file will have a different name. For example, if you are
running three instances of sp_eventmon under the UNIX names of Adam, Bob, and
Charlie, you will have three *.mrk files named Adam.mrk, Bob.mrk, and Charlie.mrk.
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 pro-
gram cannot grep from it properly. Note that when you issue the truncate log com-
mand you must remove the username.mrk file. The next time you run sp_eventmon
it will create a new *.mrk file.See the SharePlex Reference Manual for more infor-
mation about the truncate log command.
Important! When there is an existing Event Log with errors in it and the sp_eventmon
monitoring 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.
Defining the error messages for notification

The sp_eventmon script scans for events listed in the error_list file, located in the util
sub-directory of the SharePlex product directory. The following are the default errors
for which sp_eventmon monitors:
Default errors monitored by sp_eventmon
SharePlex was shutdown. Activate config.

System call error. Deactivate config.
Queue partition is full. Bad config file.
Host is down. sp_cop was shutdown.
Internal error. Child process failed.
Out of sync. Error.
Poster failure.
Parameter was changed.
You can add custom error strings to the error_list by editing the file in any ASCII text
editor. Open the file and place each error string on a separate line.
CHAPTER 9 345
Setting IW_HOME
The IW_HOME variable must be customized for each machine because it points to the
directory in which the scripts and iwgrep reside. If you move iwgrep, you must re-set
this variable to the new path.
1 Open the sp_eventmon script in any ASCII text editor.
2 Type the correct path on the line where the IW_HOME variable appears, as shown in
the following example.
IW_HOME=/export/home/jdadd/monscripts
3 Save and close the script file. The script exports the IW_HOME variable when it
runs.
Defining the e-mail addresses

To execute sp_eventmon with the -m option (for e-mail notification), you first must
define the e-mail address(es) within the script. You can specify as many addresses as
you want.
1 Open the sp_eventmon 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.
scott@company.com, 12345678910@pageservice.com
3 Save and close the file.
4 Enable e-mail notification by including the -m option in the script syntax.
Syntax for sp_eventmon

nohup sp_eventmon -s 'sp_copname' -t interval -p path [-n name] [-m] /dev/null &
Required components
COMPONENT DESCRIPTION
nohup sp_eventmon The nohup command tells sp_eventmon to continue running in the
background if the user logs out. This ensures continuous monitoring.
The sp_eventmon component runs the script.
Required components (continued)

COMPONENT DESCRIPTION (continued)
-s 'sp_copname' This sets the name of sp_cop that was used when you started sp_cop
with the -u option. The name of sp_cop must be enclosed within sin-
gle quote marks. You can use this parameter more than once to moni-
tor multiple sp_cop instances on a system. Without this parameter,
sp_eventmon will not start.
/dev/null This 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.
-p path This variable sets the path to the SharePlex variable-data directory.
Without this variable, sp_eventmon assumes the default path.
& This runs the script in the background.
-t interval This sets the time interval between scans in seconds. The value can be
any positive integer.
Optional variables
VARIABLE DESCRIPTION
-n name This sets the name of the Event Log if it is something other than the
default name event_log.
-m This enables the e-mail/paging option. The sp_eventmon script
sends notification messages to all addresses coded in the script. With-
out this parameter, sp_eventmon does not send an e-mail, but only
logs errors to the log file.
CHAPTER 9 347
Monitoring the Capture process with sp_logmon

The sp_logmon monitoring utility helps prevent situations where you must resynchro-
nize because the redo logs wrapped before Capture was finished reading them. It moni-
tors 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
notifies you. This gives you time to correct the cause of the delay and restore the archive
logs, if necessary.
You can run this script for multiple SharePlex instances by using a different port number
for the -p argument in the syntax.
Actions taken by sp_logmon

The sp_logmon script takes the following actions after each analysis of the redo logs
and the Capture process:
If Capture falls a specified number of logs behind Oracle, sp_logmon generates a
warning in the logmon.log file and an e-mail message, if that option is enabled:
The SharePlex (port n) Capture process has fallen behind in capturing
information from the redo log by 10 files, which exceeds the threshold
(of 2 files), at Fri Oct 5 16:52:55 PDT 2001. Corrective action is
needed before the log wrap, or resynchronization will be necessary.
SharePlex (port n) may encounter a log wrap!
Requirements for running sp_logmon

Before you use the sp_logmon utility, see Requirements for using the monitoring
utilities on page 341.

To execute sp_logmon with the -m option (e-mail notification), you first must define
the e-mail address(es) within the script. You can specify as many addresses as you want.
Important! If the person modifying the script is someone other than a SharePlex user,
he or she needs to have these Oracle privileges:
CONNECT privileges
SELECT privileges for the V$LOG table
SELECT privileges for the SharePlex internal tables
1 Open the sp_logmon script in any ASCII text editor.

pager address. Separate multiple entries with a comma, as shown in the following
example.
Syntax for sp_logmon

nohup sp_logmon -p port_number -t interval -l integer [-m] /dev/null &
Required components
nohup sp_logmon The nohup command tells sp_logmon to continue running in the back-
ground if the user logs out. This ensures continuous monitoring. The
sp_logmon component runs the script.
-p port_number This sets the port number for the instance of sp_cop that you are moni-
toring. You can monitor different SharePlex instances by running
sp_logmon for each one, using different values for this argument.
/dev/null This redirects the notification output to the /dev/null device on the local
system so that the monitoring process continues to run in the back-
ground and generate output. To have the output appear on screen, omit
this argument.
-t interval This sets the time interval between scans in seconds. The value can be
any positive integer.
CHAPTER 9 349

-l integer This sets a threshold value (limit) for the permissible number of redo
logs between where Capture is reading and where Oracle is writing.
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.
Optional variables
VARIABLE DESCRIPTION
-m This enables the e-mail/paging option. The sp_logmon script sends
notification messages to all addresses coded in the script. Without
this parameter, sp_logmon does not send an e-mail, but only logs
errors to the log file.
Monitoring the SharePlex processes with sp_ps

The sp_ps monitoring utility monitors all SharePlex processes, including child pro-
cesses, associated with a specified sp_cop instance at regular intervals and reports
abnormal conditions. This script can monitor multiple installations of SharePlex on one
or more systems, and it accommodates uni-directional and bi-directional (peer-to-peer)
configurations.
Actions taken by sp_ps

After each scan of the processes, sp_ps takes the following actions:
When it finds an abnormal condition that requires immediate attention, sp_ps gener-
ates a notification message to one or more log files. Depending on whether you spec-
ify the sp_cop on a source system, target system, or for peer-to-peer replication, it
prints the appropriate version of the following message.
The [Capture | Reader | Export | Import | Post] process for [sp_cop_name]
Shareplex instance is down!
Urgent! A SharePlex process is down!
Requirements for running sp_ps

Before you use the sp_ps utility, see Requirements for using the monitoring utili-
ties on page 341.
Setting the scan interval

This variable specifies how long the sp_ps program waits between monitor checks. The
default is 2,000 seconds. To specify a different scan interval, follow these steps.
1 Open the sp_ps file in any ASCII text editor.
2 Change the interval= line to the scan interval that you want, for example:
interval=1500
You may enter any positive integer; a value of 0 is not valid.
3 Save the changes and close the file.
CHAPTER 9 351
Setting the e-mail option

The e-mail/paging option is enabled by default. Follow these directions to:
disable or enable the e-mail option.
define the e-mail address(es) where sp_ps will send notifications.
1 Open the sp_ps script in any ASCII text editor.

2 Set the MAILOPTION variable line to TRUE or FALSE, as shown in the following
example.
MAILOPTION=TRUE enables the e-mail feature (this is the default).
MAILOPTION=FALSE disables the e-mail feature.
3 To add e-mail and/or pager address strings, type them after the MailUserName= vari-
able. Use the full e-mail and/or pager address.You can specify as many addresses as
you want. Separate multiple entries with a comma, as shown in the following exam-
ple.
4 Save and close the file. When the script executes with e-mail enabled, notifications
are sent to all addresses.
Syntax for sp_ps

nohup sp_ps 'sp_cop -uname' CONFIGURATION > /dev/null &
Required components
nohup sp_ps The nohup command tells sp_ps to continue running in the back-
ground if the user logs out. This ensures continuous monitoring. The
sp_ps component runs the script.
'sp_cop -uname ' This is a required part of the syntax and must be enclosed within
single quote marks as shown. The -uname option must reflect
exactly the same name that was used when sp_cop was started with
the -u option. When this argument is used alone without the -uname
option, sp_ps assumes you want to monitor the sp_cop that uses
the default SharePlex port of 2100. You can use this parameter more
than once to monitor multiple sp_cop processes.

CONFIGURATION This variable refers to the replication configuration of the SharePlex
instance being monitored whether it is on the source system, the
target system, or is part of peer-to-peer replication. This value must
be entered in CAPITAL letters.
Valid values for CONFIGURATION
For uni-directional replication:
SOURCE monitors the Capture, Read and Export processes on
the source system.
TARGET monitors the Import and Post processes on the target
system.
For peer-to-peer replication:
MULTI-SOURCE tells the script to monitor the Capture, Read,
Export, Import and Post processes on each system. (In peer-to-peer
replication, the configuration on each system generates an Import
and Post process on the other system.)
Note: If you are running peer-to-peer replication on the same sys-
tem, there will be no Import or Export processes.
/dev/null This 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
CHAPTER 9 353
Monitoring the queues with sp_qstatmon

The sp_qstatmon utility monitors the status of the capture and post queues for mes-
sage* 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, sys-
tem or network problem. This gives you time to correct the problem before the queues
exceed their allocated space on the filesystem.
Actions taken by sp_qstatmon

The sp_qstatmon script takes the following actions after each analysis of the queues:
The following notice is printed in the capstat.log (for the capture queue) or post-
stat.log (for the post queue) and in the e-mail message, if that option is enabled.
The backlog of messages in the [capture/post] queue is currently
value. This exceeds the threshold of [-c | -d value]. Please take cor-
rective action.
SharePlex [capture/post] queue backlog threshold exceeded!
Note: The sp_qstatmon script does not support monitoring multiple (named) post
queues. Please consult the release notes for future releases of SharePlex to determine if
this capability has been added.
Requirements for running sp_qstatmon

Before you use the sp_qstatmon utility, see Requirements for using the monitoring
utilities on page 341.
The sp_qstatmon utility creates some temp files in the directory where it resides.
Please assign write permission to that directory for sp_qstatmon.

1 Open the sp_qstatmon script using any ASCII text editor.
see page 34.
pager address. You can specify as many addresses as you want. Separate multiple
entries with a comma, as shown in the following example.
scott@company.com, 12345678910@pageservice.com.
Syntax for sp_qstatmon

nohup sp_qstatmon -v path -t n -p port_number [-c integer] [-d integer] [-m] > /dev/null
&
Required components
nohup sp_qstatmon The nohup command tells sp_qstatmon to continue running in the
background if the user logs out. This ensures continuous monitor-
ing. The sp_qstatmon component runs the script.
-v path This 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 the following error message:
Error...please enter a valid variable data directory path.
/dev/null This 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.
-t n This sets the time interval between scans in seconds. This value can
be any positive integer.
-p port_number This sets the port number for the sp_cop you want to monitor. You
can monitor multiple instances of SharePlex by running the script
for each one, using different values for this argument.
Optional variables
OPTIONAL VARIABLES DESCRIPTION
- c integer This sets the threshold value (limit) for the number of messages in
the capture queue. This value can be any positive integer. Without
this parameter, sp_qstatmon defaults to 100 messages.
CHAPTER 9 355
Optional variables (continued)

OPTIONAL VARIABLES DESCRIPTION (continued)
- d integer This sets the threshold value (limit) for the messages in the post
queue. This value can be any positive integer. Without this parame-
ter, sp_qstatmon defaults to 100 messages.
-m This variable enables the e-mail/paging option. The sp_qstatmon
script sends notifications to all addresses coded in the script. With-
out this parameter, sp_qstatmon does not send an e-mail, but only
logs errors to the log file.
Part 2: Monitoring SharePlex on Windows

systems
SharePlex is designed to run reliably without supervision, but unforeseen situations can
occur in any replication environment. For example, a system or the network could fail
and cause data to accumulate in the queues. Or, one or more SharePlex processes could
stop as the result of a user command or an error. This section explains how to use the
Sp_Nt_Mon utility to send e-mail notifications of key replication events.
Overview of Sp_Nt_Mon
Sp_Nt_Mon runs in the background. It sends alerts to one or more designated e-mail
addresses to notify you of the following:
The status of the Capture, Read, Export, Import, Post, and Sp_Copsrv.exe pro-
cesses.
The volume of the capture and post queues.
Latency between redo logs being processed by Oracle and by SharePlex.
The following messages in the Event Log:
SharePlex was shutdown Activate config

System call error Deactivate config
Queue partition is full Bad config file
Host is down sp_cop was shutdown
Internal error Child process failed
Out of sync Error
Poster failure ORA-(error number)
Parameter was changed
CHAPTER 9 357
Configuring Sp_Nt_Mon
Sp_Nt_Mon reads its input from the sp_nt_mon.txt file, which resides in the data sub-
directory of the SharePlex variable-data directory. To configure monitoring, edit this
file.
To open the sp_nt_mon.txt file

1 From the Start menu, select Programs, then select SpClient from the SharePlex pro-
grams group.
2 On the SpClient toolbar, click the SpMonitor button.
SpMoni-
tor
3 In the Port list box in the SharePlex Monitor dialog box, select the port number of
the instance of SharePlex that you want to monitor, then click Configure Monitor.
The sp_nt_mon.txt file is displayed in the default text editor (NotePad by default).
Tip: You can change the default text editor for SpClient in the Windows Registry. The
entry name is HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\Quest Soft-
ware\SharePlex Remote.
To configure Sp_Nt_Mon
1 You can add comments to the file, making certain to precede all comment lines with
a pound symbol (#) and end each one by pressing Enter.
2 Sp_Nt_Mon polls SharePlex at specified intervals. The default is every 60 seconds.

To change the default, set the value on the Time Interval line to the desired poll
interval.
# Time interval for Sp_NT_Mon to check - default = 60 seconds.
Time Interval: 60
3 An e-mail address is required for Sp_Nt_Mon. The only output is through e-mail.
The value of the Send Email alert line must be set to 1. Disabling e-mail notification
with a value of 0 disables the scripts functionality.
# Send email alerts - 0 = send no alerts via email; 1 = send email
alerts.
Send Email alert: 1
4 On the SMTP Server Name line, enter the name of the SMTP server for the e-mail
account.
# The name of the SMTP Server.
SMTP Server Name: smtpserver.yourcompany.com
5 On the Email Address line, enter one or more e-mail addresses, separating each
address with a space. Allow the line to wrap, if necessary.
# Add the list of email addresses you wish to send alert messages to,
separated by spaces.
#
Email Address: YourName@YourCompany.com OtherName@YourCompany.com
6 For each line for the replication processes (Cop, Capture, Read, Export, Import,
Post), set the value to 1 to have Sp_Nt_Mon monitor the process. If a process stops
CHAPTER 9 359
for any reason, Sp_Nt_Mon issues an alert. To disable monitoring of a process, use
the default of 0.
# Processes to monitor - 0 = do not monitor; 1 = monitor this process.
Cop: 1
Capture: 1
Read: 1
Export: 1
Import: 1
Post: 1
7 For each line for the replication queues (Capture Threshold, Post Threshold), enter
the number of messages* that you consider an alert threshold for backlogged mes-
sages. If a queues backlog volume reaches this threshold, Sp_Nt_Mon issues an
alert. Set this value to a number well below that which would result in a queues
exceeding its disk space. This gives you enough time to add disk space or resolve
any problems that are causing the backlog. To disable monitoring of a queue, use the
default value of 0.
# Queue Thresholds
#
# A threshold of 0 (Zero) means do not monitor this queue.
Capture Threshold: 100000
Post Threshold: 100000
8 To monitor the Event Log, set the Monitor Event Log field to 1. This enables moni-
toring of all supported Event Log messages. To disable Event Log monitoring, use
the default of 0.
# Monitor the Event Log - 0 (zero) do not monitor; 1 = Monitor Event
Log
Monitor Event Log: 1
9 To monitor the latency between the redo log that Oracle is writing to, and the log that
SharePlex is processing, set the Redo Log Monitor field to 1. To disable redo log
monitoring, use the default of 0.
# Monitor Redo Logs - 0 (zero) do not monitor; 1 = Monitor Log
Redo Log Monitor: 1
see page 34.
10 If you enabled redo log monitoring, use the Redo Threshold field to set the maximum
permissible number of logs for Oracle to be ahead of SharePlex in processing. The
default is 2 logs, but you can set a value from 1 to the number of redo logs.
# If Redo Log Monitor enabled, specify a threshold value for the per-
missible number of redo logs for Oracle to be ahead of SharePlex.
# This parameter is optional, will default to 2 if not specified.
Redo Threshold: 3
11 From the File menu, click Save to save and close the file.
12 Keep the SharePlex Monitor dialog box open
Important! Do not rename this file, or the Sp_Nt_Mon utility will exit with an error.
Running Sp_Nt_Mon
After you configure Sp_Nt_Mon, run it from the SpClient interface by selecting the
port number of the instance of SharePlex that you want to monitor and then clicking
Start. Sp_Nt_Mon continuously monitors SharePlex until it is shut down from SpCli-
ent.
When Sp_Nt_Mon starts, the Start button becomes a Stop button. To shut down
Sp_Nt_Mon, click Stop.
FIGURE 22: The Sp_Nt_Mon Share-

Plex Monitor:
Click here to start or stop

Sp_Nt_Mon.
Click here to configure the monitor

parameters.
CHAPTER 9 361
Part 3: Using SNMP with SharePlex
SharePlex provides agent support for Simple Network Management Protocol on all
UNIX and Windows platforms supported by SharePlex replication.
You can configure the SharePlex SNMP agent to send SNMP traps for any or all of the
following SharePlex events:
SharePlex logic errors and errors that cause replication processes to stop
System-related errors encountered by SharePlex
Other SharePlex errors
Out-of-sync conditions
SharePlex startup
SharePlex shutdown
When a replication process starts
When a replication process stops
The error text for the event is included in the trap and is the same error that appears in
the Event Log.
Overview of the SharePlex SNMP agent

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.
Note: The 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.
Configuring SNMP monitoring

To enable SNMP support for SharePlex, set the following parameters. Some are
required and others are optional. All changes take effect after you re-start sp_cop.
Enabling SNMP monitoring

SNMP monitoring of SharePlex replication is controlled by the
SP_SLG_SNMP_ACTIVE parameter. By default, the parameter is set to 0, which dis-
ables SNMP support. To enable SNMP support, set this parameter to 1.
Configuring the agent

To configure the agent to communicate with the NMS, set the following required
parameters. Each parameter must have a value if the SP_SLG_SNMP_ACTIVE param-
eter is enabled.
Parameter Name Set value to

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
Configuring the traps

The following parameters encompass all of the replication events for which you can
configure SharePlex to send SNMP traps. They all are flags. A setting of 0 disables the
parameters functionality (meaning that SharePlex does not send a trap for the event). A
setting of 1 enables it (SharePlex sends a trap). You can enable any or all trap parame-
ters.
Parameter Name Event Monitored

SP_SLG_SNMP_INT_ERROR SharePlex logic errors and errors that cause
processes to exit
CHAPTER 9 363
Parameter Name Event Monitored

SP_SLG_SNMP_SYS_ERROR System-related errors encountered by Share-
Plex
SP_SLG_SNMP_ERROR Other SharePlex errors
SP_SLG_SNMP_OUT_OF_SYNC When replication is out of synchronization
SP_SLG_SNMP_STARTUP When SharePlex starts up
SP_SLG_SNMP_SHUTDOWN When SharePlex shuts down
SP_SLG_SNMP_LAUNCH When a SharePlex process starts
SP_SLG_SNMP_EXIT When a SharePlex process stops
To set the parameters

1 From the bin sub-directory of the SharePlex product directory, run sp_ctrl.
2 In sp_ctrl, use the following syntax to set each parameter.

sp_ctrl> set param [paramname] [value]
3 Re-start the sp_cop process.

10
Changing Oracle Characteristics Of
Replicated Objects
To change Oracle characteristics of objects in an active configuration, there are special

procedures to follow in view of the fact that SharePlex is continuously replicating data
that you want to keep synchronized. This chapter provides guidelines for performing
those operations.
Important! These procedures must be performed by an experienced SharePlex user

who is familiar with the softwares functionality and commands.
Contents
Performing DDL changes to replicating objects

Making other Oracle changes
Part 1: Performing DDL changes to replicating

objects
SharePlex replicates some, but not all, DDL operations. For a list of DDL operations
that SharePlex does and does not support, plus exclusions and restrictions, see What
SharePlex replicates on page 76.
Supported DDL operations can be made without reactivating the configuration or stop-
ping user access to objects, and without repeating the changes on the target system.
SharePlex performs the replicated DDL on the target system, and no special procedures
are required.
This part of the chapter contains procedures for making DDL changes that are not sup-
ported by SharePlex replication. Follow these procedures to prevent errors that can
cause data to go out of synchronization. For some procedures, you will need to reacti-
vate the configuration. The procedures are organized in alphabetical order according to
the Oracle commands to which they apply. For all other DDL commands, see the
generic procedure Making other non-replicated DDL changes on page 367.
Important! TRUNCATE is supported by SharePlex replication. To prevent errors, disable

foreign key constraints in other tables that relate to the table being truncated before issu-
ing the TRUNCATE statement. SharePlex references the foreign keys on those tables
and returns an error message if it cannot find them.
CREATE TABLE
If you are using Oracle wildcards and the table that you are adding is covered by the Oracle wild-
card specification in the configuration file, it is not necessary to add the table to the config file as
described below. When the config file is reactivated, any new objects that match the criteria are
added into replication. See page 137 for information on using Oracle wildcards.
Requires configuration reactivation
To add a table to the database and include it in an active configuration, follow these
steps.
1 Add the table to the source and target databases, and ensure that the data is synchro-
nized if the tables are populated. If you prefer, you can add the table to the configura-
CHAPTER 10 367
Changing Oracle Characteristics Of Replicated Objects
tion before you add it to the database, as instructed in the following steps, but the
table must exist in the database prior to activating the new configuration.
titioned replication for this table, delete unneeded columns and rows from the target
table as needed.
3 Run sp_ctrl.
4 Copy the active configuration, but do not deactivate it. Use the show config or list
config command if you are unsure of the name.
5 Edit the new configuration to add the new tables owner and name, target table and
routing information.
6 Save the new configuration file with the :wq command if using vi, or with Save on
7 Use default multi-threaded activation to activate the new configuration. You are
warned that this configuration deactivates the one that is active. Proceed with the
activation. The only table requiring analysis is the new one.
Making other non-replicated DDL changes

Requires configuration reactivation
Perform all other non-replicated DDL changes manually on the source and target sys-
tems according to the following steps.
1 Stop access to the source Oracle instance (and all instances if using peer-to-peer rep-
lication).
2 On the source system, use the command below to flush the data from source to target
systems. For datasource, substitute o. followed by the source databases
ORACLE_SID for example o.oraA. 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.
3 Using the lstatus command in sp_ctrl on the target system(s), verify that the post
queue for that datasource is empty on each system, and that the Post process has
stopped. The number of messages in the post queue should be 0.
sp_ctrl(sysB)> lstatus
4 When all of the data is posted and Post is stopped, make the DDL changes on the
source system.
5 Reactivate the configuration on the source system using default multi-threaded acti-
vation. This instructs SharePlex to rebuild its internal tables to incorporate the DDL
changes.
6 Resume user activity on the source system. The replicated data accumulates in the
Post queues until Post is restarted.
7 While Post is stopped, make the same DDL changes on the target systems.
8 [HIGH AVAILABILITY AND PEER-TO-PEER REPLICATION ONLY] If you are using replication for high
availability or peer-to-peer replication, reactivate the configurations on all of the sec-
ondary systems.
9 Start Post on all target systems. SharePlex resumes replication from where it
stopped, and the data remains synchronized.
CHAPTER 10 369
Part 2: Making other Oracle changes
This part of the chapter provides procedures for making other, non-DDL changes to the
database while replication is active.
Moving the location of ORACLE_HOME on UNIX systems

Changing the location of ORACLE_HOME requires re-linking SharePlex to the Oracle
libraries. Follow these steps.
1 Shut down SharePlex.
sp_ctrl> shutdown
2 Move the ORACLE_HOME.
3 Update the oratab file to the path for the new ORACLE_HOME.
4 Update the defaults.yaml file in the [proddir]/data directory with the path for the new
ORACLE _HOME.
5 Re-start SharePlex.
Changing the target ORACLE_SID

Changing the name of the target database (which changes the ORACLE_SID) requires a
configuration reactivation. Follow these steps.
1 Run sp_ctrl on the source system.
2 Copy the active configuration on the source system, but do not deactivate it. Use the
show config or list config command if you are unsure of the name.
3 Open the new configuration and change all routing maps for this target system to the
new ORACLE_SID. The routing map is the entry in the third column of each line
that looks like this: targetsystem@o.targetSID.
4 Save the configuration (use :wq in vi or Save on the File menu in WordPad), but do
not reactivate it yet.
5 Stop user activity on the source tables involved in replication.
6 On the source system, use the following command to flush the data remaining in the
queues to the target database. For datasource, substitute o. followed by the source
databases ORACLE_SID for example o.oraA. This command stops the Post pro-
cess and establishes a synchronization point between the source and target databases.
7 Activate the new configuration on the source system. You are warned that this con-
figuration deactivates the one that is active. Proceed with the activation. Because
SharePlex does not need to analyze the tables, the activation will be brief.
8 Allow users to resume work on the source database.
9 On the target system, issue the status command to verify that Post stopped. If Post
still is running, continue to issue the status command until Post is stopped.
10 After Post stops, shut down the target database and rename the ORACLE_SID.
CHAPTER 10 371
11 Start the Post process on the target system.

CHAPTER 10 373
CHAPTER 10 375
CHAPTER 10 377
11
Performing Administrative
Operations
Performing system and software maintenance on machines running SharePlex requires

special procedures in view of the fact that SharePlex is replicating data that you want to
keep synchronized. This chapter provides guidelines for performing those operations.
Important! These procedures must be performed by an experienced SharePlex user

who is familiar with the softwares functionality and commands.
Contents
Installing patches and upgrades

Migrating your Oracle database
Administering the SharePlex Oracle account
Changing the SharePlex user (or user and password) on UNIX systems
Running ora_setup on UNIX systems
Running OraSetup on Windows systems
Performing other administrative operations
Removing SharePlex from a UNIX system
Removing SharePlex from a Windows system
Part 1: Installing patches and upgrades
This part of the chapter contains instructions for the following:

Installing application patches and upgrades on systems running SharePlex
Installing OS and Oracle patches on systems running SharePlex
Installing SharePlex upgrades
Installing SharePlex patches
Installing application patches and upgrades on systems

running SharePlex
The content of an application patch or upgrade and its relationship to your replication
environment both determine how (or if) it needs to be applied on the target system, and
what you need to do afterward. Before you select a procedure to follow in this section,
review Determining how to apply a patch or upgrade and Applying patches or
upgrades when using partitioned replication on page 382 before you select a procedure
to follow.
Determining how to apply a patch or upgrade

There are different procedures for applying a patch or upgrade while replication is in
process. Which one to choose depends on whether or not your patch or upgrade includes
DML and/or DDL that affects the replicating objects. Refer to the following table to
determine which procedure to use.
CHAPTER 11 381
Performing Administrative Operations
Patch and upgrade procedure chart
USE PROCEDURE A or B
Source System Target System
if patch/upgrade does ANY of
Instructions Instructions
these...
Makes DDL changes to tables other Edit (if necessary) and reactivate Apply the patch/upgrade to the tar-
than with DDL commands repli- the configuration per procedure get to apply the DDL.2
cated by SharePlex1 instructions so that SharePlex can
analyze the changes.
Does a table reorg (or other pro- Reactivate the configuration per Applying the patch/upgrade to the
cess) which uses a temporary table procedure instructions so that target is optional. Reorgs on target
that is renamed into a permanent SharePlex can obtain the new tables do not affect replication,
position in the database object ID(s). because SharePlex does not use the
object ID on the target.2
Adds new tables Edit the configuration to add the Perform the patch/upgrade to add
tables, then activate the edited con- the tables on the target if you want
figuration. to replicate to them.2
Creates or modifies triggers or con- The effects of the triggers or con- Apply the patch/upgrade and dis-
straints such as cascading deletes straints will be replicated by Share- able the triggers and constraints on
Plex. No action needed on source the target, because their actions will
system. already have been replicated by
SharePlex.
Adds indices, stored procedures No action needed. Optional. You can apply the patch/
and/or packages to source system upgrade if desired for high avail-
ability.
Changes users and security on No action needed. Optional. You can apply the patch/
source system upgrade if desired for high avail-
ability.
USE PROCEDURE C
Source System Target System
if patch/upgrade does any of
Instructions Instructions
these things ONLY...
Makes DML changes to tables No action needed. These changes Do not apply patch/upgrade on the
are replicated to the target system. target. The changes are replicated.
Makes DDL changes to tables using No action needed. These changes Do not apply patch/upgrade on the
DDL commands replicated by are replicated to the target system. target. The changes are replicated.
SharePlex1
1
For a list of DDL that SharePlex replicates, see the Release Notes that correspond to your version of SharePlex.
2
If you plan to use the target system for high availability, activate the configuration on the target system, too.
Applying patches or upgrades when using partitioned

replication
If a table affected by a patch/upgrade is, or will be, involved in partitioned replication,
take into account the following as you follow the procedure you have selected based on
the Patch and upgrade procedure chart on page 381.
Vertically partitioned replication

If columns are added, but they will not be part of a column partition, drop those col-
umns from the target table after the patch/upgrade is applied, if needed.
If columns are added, and they will be part of a column partition, add those columns
to the source and target column lists in the configuration file, then reactivate the con-
figuration.
If columns are deleted, but they are part of a column partition, remove those columns
from the source and target column lists in the configuration file, then reactivate the
configuration.
If column characteristics (name, datatype, size, etc.) are changed, and those columns
are part of a column partition, update the source and target column lists (if names
changed) in the configuration file and reactivate the configuration.
Horizontally partitioned replication

If rows are added, and they will be part of a partition scheme, add a column condi-
tion for them in the SHAREPLEX_PARTITION table, then stop user access to the
table and reactivate the configuration. See Changing partitioned replication on
page 319 for more information.
If rows are deleted, and they are part of a partition scheme, remove their column con-
dition from the partition scheme in the SHAREPLEX_PARTITION table, then stop
user access to the table and reactivate the configuration. See Changing partitioned
replication on page 319 for more information.
CHAPTER 11 383
Procedure A deactivation and reactivation (requires quiet

system)
This procedure is the basic way to install an application patch or upgrade if it includes
changes to the database that are not replicated by SharePlex. You will deactivate the
configuration so that SharePlex can rebuild its object information to incorporate the
changes. When you reactivate the configuration, SharePlex will re-analyze all of the
objects again. To avoid a deactivation, use Procedure B.
1 Stop access to the Oracle instance on all systems (source and target).
2 On the source system, issue the flush command to flush the data to all target sys-
tems. This command stops Post and places a marker in the data stream that estab-
lishes a synchronization point between source and target data. For datasource in the
following syntax, substitute o. followed by the ORACLE_SID of the source instance
for example o.oraA.
3 Deactivate the configuration on the source system.

4 You can follow either set of steps in the following table for the rest of the procedure.
The steps in the second column minimize production downtime.
Basic process Process that minimizes downtime
1 Apply the patch/upgrade on the source and 1 Apply the patch/upgrade on the source sys-
target systems. tem.
2 [PARTITIONED REPLICATION ONLY] Make any 2 [PARTITIONED REPLICATION ONLY] Make any
required configuration changes and delete required configuration changes as recom-
columns and/or rows as recommended in mended in Applying patches or upgrades
Applying patches or upgrades when using when using partitioned replication on
partitioned replication on page 382. page 382.
3 If the patch/upgrade created or modified 3 Activate the configuration on the source

triggers, re-run sp_add_trigger.sql on the system.
target systems or disable the triggers. For sp_ctrl(sysA)> activate config filename
more information, see page 106.
4 Grant users access to the source instance.
4 Activate the configuration on the source
system. 5 Apply the patch/upgrade on the target sys-
sp_ctrl(sysA)> activate config filename tems.
5 Grant users access to the source and target 6 If the patch/upgrade created or modified
instances. triggers, re-run sp_add_trigger.sql on the
target systems or disable the triggers. For
6 Start Post on the target systems. more information, see page 106.
7 [PARTITIONED REPLICATION ONLY] Perform all
appropriate operations as recommended in
Applying patches or upgrades when using
partitioned replication on page 382.
8 Start Post on the target systems.

CHAPTER 11 385
Procedure B Patches and upgrades with an Oracle hot

backup (maintain an active database)
You can use an Oracle hot backup to copy patches or upgrades from the source system
to the target system without having to deactivate the configuration on the source system
or stop user access. You use the reconcile command to identify and eliminate the fol-
lowing:
duplicate DML from the operation that was replicated but was also applied by the
backup.
duplicate DDL from those operations that was replicated but also applied by the
backup. (SharePlex replicates some, but not all, DDL.)
User (OLTP) transactions that were replicated but also applied by the backup.
Using this procedure instead of applying the Oracle operations directly on the target
system 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.
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 opera-
tion only adds an index or stored procedures, or when it only changes security.
To prepare for the copy

1 Stop user access to the instances involved in replication on the source and target
systems, but do not shut down SharePlex.
2 Change to the bin sub-directory of the SharePlex product directory on the source
system, and run sp_ctrl.
3 On the source system, issue the flush command to flush the data to the target sys-
tem. This command stops Post and places a marker in the data stream that establishes
a synchronization point between source and target data. For datasource in the follow-
ing syntax, substitute o. followed by the ORACLE_SID of the source instance for
example o.oraA.
4 Apply the patch or upgrade on the source system.
5 Allow users to resume activity on the source system.

6 On the source system, do any of the following that applies to the results of the patch
or upgrade:
If the patch did this... Do the following...
Changed the structure of a table Reactivate the configuration. Do not deacti-

(unless supported DDL was used). vate the configuration that is active.
Or... sp_ctrl(sysA)> activate config file-
Used a temporary table that was name
renamed to a table in the database,
such as a reorganization, which
changes the object ID.
Added objects that must be repli- 1 Copy the configuration.

cated.
sp_ctrl(sysA)> copy config filename to
newname
2 Edit the new configuration to add the

objects.
3 Save the configuration by using :wq if

using vi or by selecting Save from the
File menu if using WordPad.
4 Activate the new configuration.
sp_ctrl(sysA)> activate config file-

name
Affected objects for which you are See Applying patches or upgrades when
using partitioned replication. using partitioned replication on page 382 for
more information.
To make the copy

To make the copy on the source system, use an Oracle hot backup.
1 Switch log files on the source system and make a note of the highest archive-log
sequence number.

CHAPTER 11 387
2 Recover the target 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 recorded in the previous step.
To prepare the target instance

4 Run ora_setup on the target instance, but do not create a new user. Choose the
existing SharePlex user and password (copied in the backup) by choosing n when
prompted Would you like to create a new SharePlex user. See page 407 for instruc-
tions for running ora_setup. For this procedure, you can leave SharePlex running
when you run ora_setup.
5 On the target system, issue the reconcile command for each post queue, using one
of the following options where queuename is the name of the post queue, datasource-
datadest is o.sourceSID-o.targetSID, and sequence_number is the sequence number of
the log after which you cancelled the recovery of the target database. Issue the qsta-
tus command if you are unsure of the queue name.

sequence_number
reconcile syntax would be:
sp_ctrl(sysB)> reconcile queue SysA for o.oraA-o.oraA [seq 1234]
The reconcile process retains control of sp_ctrl until it is finished, and then the sp_ctrl
prompt returns.
6 Disable or modify the following on the target system according to your replication
strategy:
triggers
check constraints
7 [PARTITIONED REPLICATION ONLY] If you are using horizontally partitioned or vertically par-
titioned replication, delete unneeded columns and rows from the target tables as
necessary.
8 Start the Post process on the target system. The two instances are now in synchroni-
zation, and SharePlex resumes replication.
Procedure C
Use this procedure only if all of the operations applied by a patch or upgrade are sup-
ported by SharePlex (replicated). Such patches or upgrades need only be applied to the
source table, because they will be replicated to the target table. Supported operations are
the following:
DML changes.
DDL changes replicated by SharePlex. For a list of DDL that SharePlex does and
does not replicate, see the Release Notes that correspond to your version of Share-
Plex.
1 Stop access to the Oracle instances on all systems (source and target).
2 On the source system, issue the flush command to flush the data to the target sys-
tems. This command stops Post and places a marker in the data stream that estab-
lishes a synchronization point between source and target data. For datasource in the
following syntax, substitute o. followed by the ORACLE_SID of the source instance
for example o.oraA.
3 Apply the patch or upgrade on the source system. The changes are replicated to the
target system.
4 Allow users access to the source instance again.
5 If the patch or upgrade created or modified triggers, re-run sp_add_trigger.sql on

the target system or disable the triggers, as required for your replication strategy. For
more information, see page 106.
6 Start Post on each target system.
7 Allow users to access the target instance.

CHAPTER 11 389
Installing SharePlex upgrades

To upgrade SharePlex to a more recent version, follow the upgrade instructions in the
Upgrade Guide for the new version. If you do not have the Upgrade Guide, contact
Quest Technical Support. You might need to upgrade Oracle if your current version is
not supported by the new version.
Installing SharePlex patches

Quest is committed to maintaining the SharePlex software to ensure peak performance
and reliability. SharePlex is continually tested by the SharePlex Quality Assurance team
and the development team. Patches are issued when necessary in response to issues
uncovered during internal testing or as a result of customer support calls.
To determine if there are any patches for your version of SharePlex, contact Quest
Technical Support. You will be provided with download instructions, if needed.
Downloading SharePlex .tpm files for installs, upgrades,

and patches
The installation files are self-extracting .tpm files that either can be downloaded from
Support Link or installed using the product CD-ROM (patches are only available from
Support Link).
Installing OS and Oracle patches on systems running

SharePlex
Before installing an operating system patch or an Oracle DBMS patch, contact Quest
Technical Support to determine if your version of SharePlex supports the new version of
the operating system or Oracle database.
An Oracle patch could create or modify triggers. After applying an Oracle patch, run
sp_add_trigger.sql on the target system or disable the triggers, as appropriate for your
replication strategy. For more information, see page 106.

Migration refers to the act of moving your Oracle database from one location to another,
either virtually or physically. The database can be moved
from a lower version of Oracle to a higher version, as in moving from Oracle 8i to
10g/11g.
from one operating system to another, as in HP-UX to AIX.
from a lower version of an operating system to a higher version, as in Sun Solaris 2.6
to Solaris 2.9.
The following migration procedures use either the Oracle hot backup procedure or the
Oracle export/import utilities.
Migrating from Oracle 8i/9i to 10g/11g between different operating systems using
Oracle export/import
Migrating from Oracle 8i/9i to 10g/11g between different operating systems using
Oracle hot backup and activation
Migrating from Oracle 8i/9i to 10g/11g using Oracle export/import
Migrating from Oracle 8i/9i to 10g/11g using Oracle hot backup
CHAPTER 11 391
Migrating from Oracle 9i to 10g/11g between different operating

systems using Oracle export/import
The following procedure can be used when you are migrating your Oracle database
from one Oracle version to another between machines that are running different operat-
ing systems. For example, you might have Sun Solaris as the source and AIX as the tar-
get. Note that this procedure uses the Oracle export and import utilities, while the next
migration procedure use the Oracle hot backup procedure.
The procedure begins with a list of steps that you perform first on the target system,
followed by another list of steps that you perform on the source system, before return-
ing to the target system to complete the procedure.
On TARGET machine
1 Install Oracle 10g/11g and create a 10g/11g database. Refer to your Oracle documen-
tation for instructions.
2 Start the database.
3 Install Shareplex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
Important! Do not run ora_setup now!
4 Start sp_cop and log on to sp_ctrl.
5 Stop Post.
6 In sp_ctrl on the target system, issue the shutdown command to shut down Share-
Plex.
On SOURCE machine
7 Install Shareplex on the source machine if it is not already installed. Refer to the
SharePlex Installation and Demonstration Guide for instructions.
8 Run ora_setup, again following the procedure in the SharePlex Installation and
9 Stop user access to the source database by shutting it down and opening it in
restricted mode.
10 Start the Oracle export utility using option CONSISTENT=Y.
11 Activate a configuration using default multi-threaded activation.

12 When activation is complete, allow users to access the source database again.
On TARGET machine
13 Import the data using the export file from the source system.
14 Run ora_setup on the database, but do not create a new user. Choose the existing
SharePlex user and password (copied in the backup) by choosing "n" when prompted
"Would you like to create a new SharePlex user [y]." In this case, you need not
shut down SharePlex when you run ora_setup.
15 Start SharePlex.
16 Run the cleanup.sql script to truncate all of the SharePlex internal tables. Instruc-
tions for running this script are on page 435.
17 Disable triggers on the tables, or run the sp_add_trigger.sql utility script (found on
page 427) so that the triggers ignore the SharePlex user.
18 Disable cascading deletes, check constraints, and scheduled jobs that perform DML.
19 Stop Export.
20 Activate the configuration to ensure you can failover.

21 Start the Post process. The two instances are now in synchronization, and SharePlex
will continue replicating to maintain synchronization.
sp_ctrl(sysB)> Start post
CHAPTER 11 393
Migrating from Oracle 9i to 10g/11g between different operating

systems
The following procedure should be used when you are migrating your Oracle database
from one Oracle version to another between machines that are running different operat-
ing systems. For example, you might have Sun Solaris as the source and AIX as the tar-
get. The intermediary server used during the migration should be running the same
operating system as the source machine.
On TARGET machine
1 Install Oracle 10g/11g and create a 10g/11g database. Refer to your Oracle documen-
tation for instructions.
2 Start the database.
3 Install Shareplex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
5 Stop Post.
6 In sp_ctrl on the target system issue the shutdown command to shut down Share-
Plex.
On SOURCE machine
7 Install Shareplex on the source if it is not already installed. Refer to the SharePlex
Installation Guide for instructions.
8 Run ora_setup, following the procedure in the SharePlex Installation Guide.
9 Activate a configuration on the source system.

10 Run the Oracle hot backup procedure on the source system.

11 Switch log files on the source system and note the number of the new archive-log
file. Continue with step 12.
On an INTERMEDIARY server (should be same OS as source)

12 Install Oracle 9i, create the database, and start it.
13 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.
15 Run the Oracle export utility on the database.
On TARGET machine
16 Import the data using the export file from the intermediary server.
18 Start SharePlex.
19 Issue the reconcile command. If you are using named post queues, issue the com-
mand for each one. Substitute the sequence number of the log that you noted in step
18 (for Intermediary server). Issue the qstatus command if you are unsure of the
queue name. The reconcile process retains control of sp_ctrl until it is finished, and
then the sp_ctrl prompt returns.
sequence_number
CHAPTER 11 395
23 Stop Export.
24 Activate the configuration.

sp_ctrl(sysB)> Start post
Migrating from Oracle 9i to 10g/11g using Oracle export/import

This procedure can be used
On TARGET machine
1 Install Oracle 9i (if not already installed), create the database, and then start it.
2 Install Oracle 10g/11g. Refer to your Oracle documentation for instructions.
3 Install SharePlex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
4 Start Shareplex.
5 Stop Post.
6 Stop Shareplex.
On SOURCE machine
7 Install Shareplex on the source system if it is not already installed. Refer to the
8 Run ora_setup, following the procedure in the SharePlex Installation and Demon-
stration Guide.
9 Start sp_cop.
10 Stop user access to the source database by shutting it down and opening it in
restricted mode.
11 Activate a configuration using default multi-threaded activation.

12 Start the Oracle export utility using option CONSISTENT=Y.
13 Issue the flush command. This command stops Post and places a marker in the data
stream that establishes a synchronization point between source and target data. For
datasource in the following syntax, substitute o. followed by the ORACLE_SID of
the primary instance - for example, o.oraA.
sp_ctrl(sysB)> flush o. <datasource>
CHAPTER 11 397
14 When the flush process is complete, allow users to access the source database again.
On TARGET machine
15 Import the data using the export file from the source system.
16 Upgrade the Oracle 9i instance to 10g/11g. Use the upgrade procedure provided in
your Oracle documentation.
18 Start SharePlex.
mand for each one. Substitute the sequence number of the log that you noted in step
15. Issue the qstatus command if you are unsure of the queue name. The reconcile
process retains control of sp_ctrl until it is finished, and then the sp_ctrl prompt
returns.
sequence_number
23 Stop Export.
24 Activate the configuration to ensure you can failover.

CHAPTER 11 399
Migrating from Oracle 9i to 10g/11g using Oracle hot backup

This procedure is used when operating systems and their versions remain the same on
the source and target machines, and a database backup taken on the source server is
recovered on the target server.
On TARGET machine
1 Install Oracle 9i.
2 Install Oracle 10g/11g.
3 Install SharePlex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
5 Stop Post.
6 In sp_ctrl on the target system, issue the shutdown command to shut down Share-
Plex.
On SOURCE machine
7 Install Shareplex on the source system if it is not already installed. Refer to the
8 Run ora_setup, again following the procedure in the SharePlex Installation and
9 Start sp_cop.
10 Stop Export.
11 Activate a configuration on the source systemn.

12 Run the Oracle hot backup procedure on the source system.
13 Switch log files on the source system and note the number of the new archive log
file. Continue with step 14.
On TARGET machine
14 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.
16 Upgrade the Oracle 9i instance to Oracle 10g/11g. Use the upgrade procedure pro-
vided in your Oracle documentation.
18 Start SharePlex.
mand for each one. Substitute the sequence number of the log that you noted in either
step 7 or 11, respectively. Issue the qstatus command if you are unsure of the queue
name. The reconcile process retains control of sp_ctrl until it is finished, and then
the sp_ctrl prompt returns.
sequence_number
23 Stop Export.
CHAPTER 11 401
24 Activate the configuration, which ensures that users can failover.

Part 2: Administering the SharePlex Oracle

account

Changing the SharePlex password on UNIX systems
Changing the SharePlex user (or user and password) on UNIX systems
Changing the SharePlex password on UNIX systems

To change the password for the SharePlex Oracle user, use the following procedure to
run the ora_chpwd utility. This utility changes the password of the SharePlex user
account in Oracle and in the SharePlex paramdb file. To use ora_chpwd, SharePlex
must be installed on the system and there must be an existing SharePlex user in the data-
base.
Run ora_chpwd for each Oracle instance where you want to change the SharePlex pass-
word. Changing the password with ora_chpwd requires a non-root, DBA privileged
user. All existing SharePlex objects in the instance remain intact and unchanged.
Warning! The ora_chpwd utility changes only the Oracle password for SharePlex. Do
not use it to create a new SharePlex user. To change the SharePlex user (or user and
password together) run ora_setup as instructed in Changing the SharePlex user (or
user and password) on UNIX systems on page 406.
CHAPTER 11 403
To run ora_chpwd
1 Verify the Oracle_SID by viewing the oratab file.
On HP-UX and IBM AIX machines On Sun Solaris machines

$ cd /etc On the Solaris platform, the oratab
$ more oratab file should be located in the var/
opt/oracle directory, but some-
You will see a display similar to this: times there is an oratab file in the
qa81:/qa/oracle/ora10/product /etc directory as well. If so, relo-
In this example, qa81 is the ORACLE_SID cate or remove any oratab file in
and /qa/oracle/ora10/product is the the /etc directory.
ORACLE_HOME directory.
Warning! Sometimes oratab files have an asterisk (*) symbol instead of an entry for the
ORACLE_SID. This causes ora_setup to fail. Ensure that a valid ORACLE_SID exists in
the oratab file.
2 Shut down sp_cop on the source and target systems.

3 Run ora_chpwd from its location in the bin sub-directory of the SharePlex product
directory.
$ /product_dir/bin/ora_chpwd
4 You are prompted for the ORACLE_SID of the instance for which you want to
change the SharePlex password. SharePlex reads the current SharePlex users envi-
ronment and displays that users ORACLE_SID as the default. Press Enter to accept
the default, or type the correct ORACLE_SID.
This program allows you to change the password of the SharePlex user account
needed to run Oracle replication. In response to prompts, a carriage return
will choose the default given in brackets. If there is no default, a reply
must be entered.
Please enter the SID where SharePlex is installed [np73]:
5 You are prompted for a password to connect to the database as SYSTEM. Enter a
valid password for the SYSTEM account, or press Enter to use the default of Man-
ager. The password is not echoed.
In order to change the password for the SharePlex user account, we
must connect to the database as SYSTEM.
Enter password for the SYSTEM account, which will not echo [MANAGER]:
connecting--This may take a few seconds.
Note: You are allowed five attempts to enter a valid password. After five invalid pass-
words, the utility aborts.
6 You are prompted for the name of the existing SharePlex user. There is no default for
this step. You must enter the name of the existing SharePlex user. SharePlex reads
the paramdb file to ensure that the name is valid.
Enter the current username for SharePlex user:
Note: Ora_chpwd permits five attempts to enter a valid user name. After five invalid
names, the utility aborts.
7 You are prompted for the new password, which must have a valid Oracle password
format. The password is not echoed.
Enter new password for SharePlex user:
8 You are prompted to enter the new password again to confirm it. Re-type it exactly as
you typed it before.
Re-enter password for SharePlex user:
Note: Ora_chpwd permits five attempts to enter and confirm the new password. After
five invalid attempts, it prompts you to try again or quit the utility. Type y at the prompt to
keep trying or type n to quit.
The utility displays the status of the change and then notifies you when the password
has been successfully changed in Oracle and in the SharePlex paramdb file. You are
returned to the UNIX prompt.
Changing SharePlex parameter database...
SharePlex password change completed successfully
chicago:judy: $
Problem solving tips for ora_chpwd

If SharePlex cannot change the password in Oracle, either because an incorrect Ora-
cle format was used or for some other reason, ora_chpwd exits and displays the
SQL statement it used and the Oracle error code.
If ora_chpwd successfully changes the password in Oracle but cannot change it in
the paramdb, it exits and displays the following message.
Warning: Password changed for SharePlex in Oracle Database.
Error making change in SharePlex parameter database.
CHAPTER 11 405
Verify that nobody deleted or moved the paramdb from the data sub-directory of the
SharePlex variable-data directory or changed permissions for it. And, find out if the
paramdb has been corrupted.
The passwords in Oracle and the paramdb must be identical for replication to pro-
ceed.
Changing the SharePlex user (or user and password) on

UNIX systems
Note: To change only the password for the SharePlex Oracle user, follow the procedure
Changing the SharePlex password on UNIX systems on page 402.
To change the SharePlex user name in Oracle, run ora_setup to create a new SharePlex
user. Instructions for running ora_setup are on page 407. Before you run ora_setup,
read the following directions.
To change the user when a configuration is active

1 During ora_setup, you will be instructed to shut down sp_cop. SharePlex will
resume replication when you start sp_cop again.
2 After you run ora_setup, but before you start sp_cop again, copy the existing
SharePlex database objects from the previous users schema into the new one. Copy-
ing the objects provides the new SharePlex user with the configuration data and
other information needed to continue replication under the current configuration(s).
3 To minimize the time that data capture is stopped while users are making transac-
tions, start sp_cop as soon as you are finished running ora_setup.
For a list of the SharePlex internal tables, see page 36.
To change the user when a configuration is not active

If there is not an active configuration, follow the instructions for running ora_setup as
though you were doing an initial Oracle setup for SharePlex.
CHAPTER 11 407

To run ora_setup
1 Start the Oracle database instance, if it is not already.
2 Log onto UNIX as a non-root user with DBA privileges.
3 View the oratab file, and make certain that the values for ORACLE_SID and
ORACLE_HOME directory paths are valid.
The oratab file is typically located in the /etc directory; however, it may be located
in the var/opt/oracle directory, as is the case for Sun Solaris platforms. If the oratab
file is located in the var/opt/oracle directory ensure that no other version of this file
exists in the /etc directory. (The ora_setup process first looks in the /etc directory
and then the var/opt/oracle directory. If there are multiple oratab files they should
be identical or have different file names.)
Warning! Sometimes oratab files have an asterisk (*) symbol instead of an entry for the
ORACLE_SID, and that can cause ora_setup to fail. Ensure that the oratab file contains
a valid ORACLE_SID.
4 Make a note of the ORACLE_SID. You will need it for the setup process. To set the
ORACLE_SID as the default, export it by typing one of the following commands.
ksh shell:
export ORACLE_SID=OracleSID of this instance

csh shell:
setenv ORACLE_SID OracleSID of this instance
5 [FOR CONFIGURATIONS USING MULTIPLE VARIABLE-DATA DIRECTORIES] Export the environment vari-
able that points to the variable-data directory for the SharePlex instance for which
you are running ora_setup.
ksh shell:
export SP_SYS_VARDIR=/full pathname of variable-data directory
csh shell:
6 Change directories to the bin sub-directory of the SharePlex product directory.

$ cd /product_dir/bin
7 If sp_cop is running, run sp_ctrl and shut down sp_cop with the following com-
mand. SharePlex cannot be running when you run ora_setup.
$ ./sp_ctrl
sp_ctrl> shutdown
8 From the bin sub-directory of the SharePlex product directory, run the ora_setup
program.
$ ./ora_setup
9 Follow the prompts through the ora_setup process. You will need the following
information to complete the process:
ORACLE_SID
SYSTEM account password
SharePlex User name and password
If this is the first time ora_setup is being run, create a new SharePlex user. If this
is not the first time that ora_setup is being run you may use the existing SharePlex
Admin user or you may elect to use another existing SharePlex user.
DEFAULT tablespace for use by SharePlex
TEMPORARY tablespace for use by SharePlex
INDEX tablespace(s) for use by SharePlex
If you are running ASM.
Default options are shown in brackets [ ]. To choose the default, press Enter.
Note: Enter the SYSTEM account password appended with @alias_name, where
alias_name is the TNS alias, for example manager@oraB.
Note: You are allowed five attempts to enter a valid password for an existing user. At any
point, you can press Enter to return to the Create New User prompt. After five invalid
passwords, you are also returned to the Create New User prompt. Enter y to create a
new user or n to quit ora_setup. If you quit, SharePlex will not be established as an Ora-
cle user.
CHAPTER 11 409
Note: If you have an active configuration and you would like to change the SharePlex
Oracle user, to preserve the current replication environment copy the SharePlex objects
from the existing SharePlex users schema to the new SharePlex users schema. When
prompted for the SharePlex Oracle user specify the changed SharePlex Oracle user.
10 When the ora_setup program completes the Oracle setup process it will exit with
confirmation of a successful setup:
Setup completed successfully
The sp_change_trigger.sql script is documented on page 426.


Requirements for OraSetup
Run OraSetup for each Oracle instance involved in SharePlex replication on all
source and target systems.
Within a cluster, run it on the primary node (the one to which the shared disk con-
taining the variable-data directory is mounted) so that the SharePlex user and pass-
word are registered in the SharePlex paramdb file. You do not need to run it on the
other cluster nodes.
For centralized reporting (consolidated replication) using separate variable-data
directories, run OraSetup for each variable-data directory.
Do not alter the SharePlex internal objects. If you have questions or concerns about
these objects, contact Quest Technical Support.
The Oracle 9.2.0.2 or higher client must be installed on the system where you are
running OraSetup.
To run OraSetup
1 Start the Oracle database instance, if it is not already.
2 Launch the SpUtils from the shortcut on the Windows desktop and select the Ora-
Setup tab from the SharePlex Utilities dialog box.
3 Follow the prompts through the OraSetup process. You will need the following
information to complete the process:
SharePlex port number

ORACLE_SID
SYSTEM account password
SharePlex User name and password
Note: If this is the first time OraSetup is being run, create a new SharePlex user. If this
is not the first time that OraSetup is being run you may use the existing SharePlex user
or you may elect to use another existing SharePlex user.
DEFAULT tablespace for use by SharePlex

TEMPORARY tablespace for use by SharePlex
INDEX tablespace(s) for use by SharePlex
CHAPTER 11 411
If you are running ASM on an ASM supported platform.
Note: You are allowed five attempts to enter a valid password for an existing user. At any
point, you can press Enter to return to the Create New User prompt. After five invalid
passwords, you are also returned to the Create New User prompt. Enter y to create a
new user or n to quit OraSetup. If you quit, SharePlex will not be established as an Ora-
cle user.
Note: If you have an active configuration and you would like to change the SharePlex
Oracle user, to preserve the current replication environment copy the SharePlex objects
from the existing SharePlex users schema to the new SharePlex users schema. When
prompted for the SharePlex Oracle user specify the changed SharePlex Oracle user.
4 When the OraSetup program completes the Oracle setup process it will display a
confirmation of a successful setup:
OraSetup Finished Successfully

5 Click OK to close the SharePlex Utilities dialog box.
The sp_change_trigger.sql script is documented on page 426.

Part 3: Performing other administrative

operations

Performing system backups on systems running SharePlex
Performing system backups on systems running

SharePlex
Performing 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, copying the same data as you would on the source system. To
perform a partial backup on the target system, follow these instructions.
1 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 synchroniza-
tion point between source and target data. For datasource in the following syntax,
substitute o. followed by the ORACLE_SID of the source Oracle instance.
3 Back up the data on the target system (which now matches the source data at the
flush marker).
4 Start the Post process on the target system. Post resumes posting data.
CHAPTER 11 413
Performing a full backup on the source system

To back up the entire source system, including SharePlex, you must shut down Share-
Plex replication on that system. To stop replication properly, and to start it again after
the backup, follow these instructions.
1 Stop all system activity on the source system.
2 Start sp_ctrl on the source system.
3 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 synchroniza-
tion point between source and target data. For datasource in the following syntax,
substitute o. followed by the ORACLE_SID of the source Oracle instance.
4 Shut down SharePlex on the source system using the following command, which
enables SharePlex to stop its replication processes in a normal manner. This com-
mand shuts down SharePlex on UNIX and Windows systems.
5 Shut down the network and the Oracle instance on the source system.
6 Perform the backup on the source system.
7 Start the network and the Oracle instance on the source system.
8 Start sp_cop (UNIX) or the SharePlex service (Windows) on the source system.
9 Start sp_ctrl on the source system.
10 Allow users to access the Oracle instance on the source system.
11 Start Post on the target system.


To remove SharePlex from a UNIX source or target system, use the following proce-
dure.
Use this procedure only if a system no longer will be used for replication or if you are
directed to use it by Quest Technical Support or another documented procedure.
Installing a SharePlex upgrade or reinstalling the software without un-installing it pre-
serves existing data files. Before you upgrade or re-install SharePlex, see the Release
Notes for the version you are installing to familiarize yourself with any special upgrade
or installation requirements.
Removing SharePlex
This procedure removes the SharePlex product and variable-data directories, including
user-created files such as configuration files, conflict-resolution files, and hints files. If
there are any files you would like to keep, those files should be backed up, copied, or
archived before starting the procedure.
This script does not remove the SharePlex internal tables, their indices, or other Share-
Plex database objects. Use standard Oracle methods to remove those objects.
To run splex_remove
1 Log on as the user that installed SharePlex. (The splex_remove script should be run
by the user who installed SharePlex. Permissions errors may occur and the
splex_remove script will not be able to find installation details if another user
attempts to remove SharePlex using the splex_remove script.)
2 Shut down SharePlex using sp_ctrl.

sp_ctrl(system:port)> shutdown
When you have finished with this step, exit out of sp_ctrl.
3 Use the following command to make certain that no other users are running Share-
Plex and that there are no SharePlex processes running, including sp_cop.
# ps -ef | grep sp_
4 If any SharePlex processes are running, shut them down or use the UNIX kill com-
mand to terminate them.
CHAPTER 11 415
5 Run the splex_remove script from outside the SharePlex installation directory. (The
splex_remove script must be run from outside of the installation directories to pre-
vent removal errors caused by trying to delete the current working directory.
# /product_dir/install/splex_remove
When the splex_remove process has is complete, the script will print the location of
the removal log file to the screen.
Overview of the removal process

Removing SharePlex from a Windows system involves the following procedures.
Shutting down the SharePlex service.
Removing the SharePlex software and system files.
Removing the MKS Toolkit (formerly known as NuTCRACKER) operating envi-
ronment.
Manually removing files that are not removed by the uninstaller.
Manually removing the SharePlex user and database objects.
Files removed by the uninstall program

When SharePlex was installed, a file named install.log was installed in the SharePlex
product directory. This file contains a record of all files created on the system by the
installation program. When you run the uninstall program to remove SharePlex, it reads
install.log to determine which files to remove.
The following components are removed by the automatic uninstall option of the unin-
stall program for all instances of SharePlex (all SharePlex services on all ports).
The SharePlex Registry entries.
The SharePlex desktop icons.
The SharePlex menu items (except for the top-level Program Manager Group
folder).
The SharePlex product directory.
The uninstall program also contains a custom uninstall option that enables you to selec-
tively remove files.
Files not removed by the uninstall program

The uninstall program does not remove the following components.
Files that already existed on the system when the current version of SharePlex was
installed.
CHAPTER 11 417
Files created by SharePlex or a user in the product or variable-data directory after the
current version of SharePlex was installed. Such files can be removed manually after
SharePlex is removed. This is standard procedure for most Windows applications.
The SharePlex variable-data directory. To remove this directory, delete it through the
operating system. The uninstall program does not remove this directory because
there could be user-created files, such as configuration files and custom parameter
settings, that you want to keep for a future installation of SharePlex.
To remove the SharePlex service

Before you remove the SharePlex software from the system, follow these steps to stop
and remove each SharePlex service on the system.
1 Double-click the SpUtils desktop icon.
2 In the Port list box, select the port number for the SharePlex instance that you want
to remove.
4 Click Apply to stop the service. The Current State field displays the status.
5 [FOR MULTIPLE SHAREPLEX SERVICES] While in the SharePlex Services dialog box, repeat
the preceding steps to stop each SharePlex service.
6 After the SharePlex service stops, click Remove.
7 Click Apply to remove the services key from the Registry.
8 [FOR MULTIPLE SHAREPLEX SERVICES] While in the SharePlex Services dialog box, repeat
steps 6 and 7 for all SharePlex services to remove their Registry keys.
9 Click Close to close the SharePlex Service dialog box.
To remove the SharePlex software and system files

1 From Start menu, click Programs, then navigate to the SharePlex program folder
and click Uninstall.
Or...
Use the Add/Remove Programs tool in the Windows Control Panel.

2 In the Select Uninstall Method dialog box, select an uninstall option.
Select Automatic to remove everything listed in Files removed by the uninstall

program on page 416. This is the recommended procedure because it is the clean-
est way to remove SharePlex from the system.
Or...
Select Custom to selectively remove files. Use this option only if you must retain
some files while deleting others.
Or...
Select Repair to re-install files or update Registry entries. This option might
require the original SharePlex installation CD if the installation files are not avail-
able.
3 Click Next to continue. You are prompted based on the uninstall option that you
selected. Follow the remaining steps for the option that you selected, either Auto-
matic uninstall, Custom uninstall, or Repair.
CHAPTER 11 419
Automatic uninstall
In the Perform Uninstall dialog box, click Finish to complete the uninstall, or click
Back to perform a custom uninstall.
The automatic uninstall finishes and exits.

Custom uninstall
In the Select Private Files to Remove dialog box, select the files that you want to
remove by clicking them. To deselect a file, click it again.
Or...
Select all of the files by clicking the Select All button. This has the same effect as if
you had selected the Automatic uninstall option.
To clear your selections and start selecting files over again, click Select None.
4 Click Next to continue.
5 For the next series of dialog boxes, use the same procedure as before to select com-
ponents to be removed. Remaining component types for which you can make selec-
tions are:
Directories.
INI files to remove.
INI files to edit back to the way they were before SharePlex was installed.
Registry keys to remove.
Registry trees to remove.
Registry keys to edit back to the way they were before SharePlex was installed.
CHAPTER 11 421
Sub-systems to remove.
6 In the Perform Uninstall dialog box, click Finish to begin the uninstall process, or
click Back to change any of your selections. The removal process finishes and exits.
Repair
In the Perform Repair dialog box, click Finish. The repair function detects items need-
ing repair and performs the repair automatically.
To remove the MKS Toolkit operating environment

1 From the Start menu, click Settings, then click Control Panel.
2 In the Control Panel dialog box, double-click Add/Remove Programs.
3 In the Add/Remove Programs dialog box, highlight MKS Platform Components.
4 Click Change/Remove.
5 Search the Registry to ensure that any Mortice Kern Systems, MKS and Data
Focus entries from HKEY_LOCAL_MACHINE\Software are removed. If you locate any
such entries, remove them.
Important! If you intend to reinstall SharePlex or MKS Toolkit, it will not reinstall unless
these Registry entries are removed.
not familiar with the Registry, consult your System Administrator for assistance.
To remove the SharePlex user and database objects

To remove the SharePlex user and database objects from the Oracle instance, use stan-
dard Oracle methods for removing users and objects. See Oracles documentation for
instructions if needed.
12
SharePlex Utilities
This chapter explains how to use the SharePlex utilities. Some utilities are available for
both UNIX and Windows platforms, and others are only available on UNIX systems.
Note: You might see programs in the SharePlex directories that appear to be utilities. Do
not run these programs. They are for use by Quest Technical Support and the develop-
ment team, and they can adversely affect replication if used improperly. Use only the util-
ities documented in this chapter.
Contents
Preventing DML transactions from replicating with create_ignore.sql

Using the SharePlex trigger scripts
Viewing and manipulating queue files with qview
Purging the variable-data directory with clean_vardir.sh
Truncating the SharePlex tables with cleanup.sql
Debugging networking and/or firewall issues using the socket_test utility
Restoring replication to an initial state with ora_cleansp
Using the SharePlex license key utilities
Using the SpUtils utility
Using the SpClient remote-access utility
Preventing DML transactions from replicating with

create_ignore.sql
Supported platforms: UNIX and Windows
Some SharePlex procedures for making DDL changes during active replication require
preventing certain DML operations, generally internal Oracle operations, from being
replicated to the target system. You might encounter other reasons to prevent DML
operations from being posted to a target database.
To prevent DML from replicating, run the create_ignore.sql utility script, which cre-
ates a public procedure named SHAREPLEX_IGNORE_TRANS in the source data-
base. When executed at the start of a transaction, the procedure makes the Capture
process ignore DML operations that occur from the point of execution until the transac-
tion is either committed or rolled back. Thus, the affected operations are not replicated.
Only DML operations are affected by the SHAREPLEX_IGNORE_TRANS proce-
dure. It does not cause SharePlex to skip DDL operations, including TRUNCATE.
DDL operations are implicitly committed by Oracle, so they render the procedure
invalid.
To run create_ignore.sql
Run the create_ignore.sql script from the util sub-directory in the SharePlex prod-
uct directory.
Run it as the SharePlex Oracle user so that procedure is created in the SharePlex
schema.
The script executes the following PL/SQL:

CREATE OR REPLACE PROCEDURE SHAREPLEX_IGNORE_TRANS AS
TNUM NUMBER;
BEGIN
INSERT INTO SHAREPLEX_TRANS (TRANS_NUM, QUE_SEQ_NO_1, QUE_SEQ_NO_2,
COMBO, OP_TYPE) VALUES (-999,0,0,'DUMMY',0);
DELETE FROM SHAREPLEX_TRANS WHERE TRANS_NUM=-999 AND COMBO='DUMMY'
AND OP_TYPE=0;
END;
/
GRANT EXECUTE ON SHAREPLEX_IGNORE_TRANS TO PUBLIC;
/
CHAPTER 12 425
SharePlex Utilities
To execute SHAREPLEX_IGNORE_TRANS
Call SHAREPLEX_IGNORE_TRANS only at the beginning of a transaction contain-
ing operations that you do not want replicated. If it is called in the middle of a transac-
tion, replicated operations preceding the start of the procedure will remain in the post
queue indefinitely awaiting a COMMIT, because SharePlex does not release messages
without one. The COMMIT will not arrive because Capture ignores all operations in the
transaction after the procedure is called. The Read process will retain unwanted cache
information on those records indefinitely.
1 Log onto SQL*Plus as the SharePlex user.
$ sqlplus name/password
2 Execute the SHAREPLEX_IGNORE_TRANS procedure at the beginning of the

transaction that you want to skip.
SQL> execute SharePlex_schema.SHAREPLEX_IGNORE_TRANS;
3 In one transaction, make the changes to the database that you do not want replicated.
They will be ignored by Capture.
4 After the COMMIT or ROLLBACK, replication of subsequent transactions resumes

normally.
Using the SharePlex trigger scripts

DML changes caused by a trigger on a source object enter the redo log, and therefore
are replicated and posted to the target database by SharePlex. If a trigger on the target
object initiates those same DML changes, it will cause out-of-sync errors.
Triggers are used as part of the application to make changes to data. If the change of
data occurs on a table in replication, SharePlex will replicate the trigger action. If the
trigger is employed on the target, essentially performing the same task as SharePlex rep-
lication, SharePlex will flag these rows as out of sync.
For more information about the effects of triggers on replication, see Triggers on
page 106.
SharePlex provides three interactive scripts that you can run in SQL*Plus to manage
triggers so that they do not interfere with replication. Review the following points
before you run the scripts.
The scripts support row-level triggers only. They cannot be modified to support any
other type of trigger. If your applications use other triggers, modify them for the
SharePlex user separately.
The scripts operate on all objects in the Oracle instance, whether or not they are part
of replication.
The scripts must be run for target objects. Do not run them on the source objects
unless you are using peer-to-peer replication.
Note: If you choose to run this script on source objects, please be aware that the triggers
will not fire when you execute DML as the shareplex user on source.
The scripts should not be used if source and target objects are both on the same
machine. In this configuration, the user can disable triggers on target objects.
The scripts reside in the util sub-directory of the SharePlex product directory.
Important! To run the scripts, you must have access to both the SYS and DBA objects. A
SharePlex user created by ora_setup has this access.
CHAPTER 12 427
SharePlex Utilities
sp_add_trigger.sql
Use sp_add_trigger.sql when you cannot disable triggers on target objects, such as for
peer-to-peer and high-availability configurations. This script changes the triggers so that
they ignore the SharePlex Oracle user associated with the Post process, but fire for all
other users. It inserts the following WHEN clause into each trigger in the database.
when user != SharePlex_username begin
The script prompts for the SharePlex user name, and then it modifies the triggers. It
does not modify triggers belonging to SYS, SYSTEM, and SCOTT.
Syntax
SQL> @absolute_pathname/sp_add_trigger.sql
sp_change_trigger.sql
Use sp_change_trigger.sql to replace the name of the SharePlex user in the WHEN
clause that was created with sp_add_trigger.sql. It prompts for the current SharePlex
user name and for the new user name. Change the SharePlex user in Oracle before you
run this script. For instructions for changing the SharePlex user, see page 406.
Syntax
SQL> @absolute_pathname/sp_change_trigger.sql
sp_remove_trigger.sql
Use sp_remove_trigger.sql to remove the WHEN clause created with
sp_add_trigger.sql. It prompts for the SharePlex user name and then automatically
removes the WHEN clause from all of the triggers. Use this script if you no longer will
be replicating to those tables. If you continue to use SharePlex to replicate to those
tables without disabling the triggers, the triggers will fire when SharePlex posts data,
and SharePlex will generate out-of-sync errors.
Syntax
SQL> @absolute_pathname/sp_remove_trigger.sql
Viewing and manipulating queue files with qview

Through the qview utility, you can view queue names and remove old queue files. The
qview tools described here do not deactivate the configuration. The qview utility is
located in the bin sub-directory of the SharePlex product directory. It is run from the
UNIX or Windows command line.
Warning! Do not use qview for the first time without the assistance of Quest Technical
Support. If this utility is not used properly, it can damage the replication environment and
require resynchronization and reactivation.
Running qview on Windows systems

To run qview on the Windows platform while the SharePlex service is running, log onto
the system as the Administrator user. On Windows, there is only one Administrator
user. Other users, whether or not they have Administrator privileges (members of
Administrators group), cannot run qview.
Other users with Administrator privileges can run qview if the SharePlex service is shut
down.
Using the list command in qview

Use the list command to list all queues for all active configurations on a system. Use the
following syntax on the command line:
UNIX syntax
qview list
Windows syntax
qview -rportnumber list
The command lists each queue, the replication process that writes to it, and the replica-
tion process that reads it. For example, for the capture queue, it lists the Capture process
and the Read process.
CHAPTER 12 429
SharePlex Utilities
A capture queue is designated with a +C.

An export queue is designated with a +X.
A post queue is designated with a +P.
The following is an example of the qview list output.
The following queues exist:
capture
queue o.ora920+C
WRITER +PA+o.ora920+sp_ocap+o.ora920 Capture process
READER +PR+o.ora920+sp_ordr+o.ora920 Read process
export
queue
elliot+X
WRITER +PR+o.ora920+sp_ordr+o.ora920 Read process
READER +PX+elliot+sp_xport+0x0a01014e (10.1.1.78) Export process
post
queue
elliot+P+o.ora920-o.ora920
subqueues range from 2 to 6
WRITER +PI+elliot+sp_mport+0x0a01014e (10.1.1.78) Import process
READER +PP+elliot+sp_opst_mt+o.ora920-o.ora920 Post process
Using the trim command in qview

The SharePlex post queue actually consists of a number of subqueues, each approxi-
mately corresponding to a user session on the source system. The Post process uses the
subqueues to establish Oracle sessions for the target instance. The number of subqueues
that exist at a given time on a target system reflects the peak activity on the source sys-
tem since replication started.
SharePlex routinely writes replicated data from the subqueues to associated datafiles on
disk as part of its checkpoint recovery system. Each subqueue can have one or more
datafiles associated with it, each with a default size of 8 MB. If the entire 8 MB file size
is not consumed, a datafile remains on the system even though the data was posted and
read/released. Consequently, the higher the activity level on the source system, the more
datafiles on disk. The size in megabytes (MB) for the post queue in a qstatus display is
the actual disk space that the datafiles occupy.
For example, suppose there were 100 concurrent sessions on the source system, creating
100 subqueues in the post queue on the target system. And, suppose the datafiles were
only partially full when the activity level droppedhalf full, for example, or 4 MB of 8
MB usedand thus were not deleted. The post queue on that system would consist of
100 datafiles at 4 MB each, totalling 400 MB of disk space.
Using the trim command in qview, you can routinely eliminate obsolete subqueue files
that were read-released, while preserving the ones containing data not yet committed to
the target database. The trim command does not eliminate queue files for subqueues 0
or 1, because those are the most heavily used subqueues.
Note: Run the trim command in qview on the target system only.
To run the trim command

SharePlex can remain running when the trim command is issued.
1 To ensure the integrity of the queues, stop the Import and Post processes on the tar-
get system. Stopping Import and Post prevents them from accessing the queues
while the trim command is running.
sp_ctrl(sysB)> stop import

Note: If one or both of those processes is not stopped, qview returns this error message:
que_INUSE: Que is already open.
2 Change directories to the bin sub-directory on the target system. The trim function
affects the post queue.
3 Enter the following command at the command prompt.
UNIX syntax
qview trim
Windows syntax
qview -rportnumber trim
If you are using basic replication with one post queue (no named queues or repli-
cation from more than one source machine), the command executes and returns the
command prompt.
If there are more than one post queue (named queues or replication from more than
one source machine), qview prompts you to select the one you want the command
to affect, as shown in the following example. You can only trim one queue at a
time. To trim a large number of queues with one command, use the qview com-
mand trimall described in the subsection that follows.
Queue zac+P+o.ora920-o.ora920 (y/n) <n>? n
Queue elliot+P+o.ora920-o.ora920 (y/n) <n>? y
CHAPTER 12 431
SharePlex Utilities
Note: If you do not select a queue, qview returns this error message: que_NOEXIST:
Queue does not exist.
Creating a full rollback message

Users can create a full rollback message using the fullrb command in qview. Using the
transaction id from the otrans command, qview will open the Capture queue, write an
out-of-band full rollback message to the Capture queue and then write commit.
Using the otrans command

This command scans the Capture queue starting at the read release point, and scans for
the number of messages specified. The qview utility prints the transaction id, the num-
ber of operations (records), the DML type operation (if there is only one) and the object
id modified (if there is only one).
The following example describes how to execute a full rollback using the otrans cand
fullrb ommands in qview:
1 Stop the Capture process.
sp_ctrl(sysA)> stop capture
2 Launch the qview utility and execute the otrans command, including the number of
messages:
vqiew> otrans 500000
The resulting qview information should look similar to the followig:
Full rollback 8(7).752562-3(139) --- 99999 Update operations on object
id 466857
Open transaction 8(23).752700-2(14162) --- 2001 Update operations
(1000 backward operations) on object id 466857
3 Execute the fullrb command using the the transaction id from the otrans information
above:
vqiew> fullrb 8(7).752562-3(139)
The resulting qview information should look similar to the following:
Current queue o.ora920+C user +PA+o.ora920+sp_ocap+o.ora920
Full rollback record written to capture queue at 378744, id 1102
odr_magic 0x4f445235
odr_op ODR_FULL_ROLLBACK (50)

odr_trans 8(7).752562-3(139)
odr_time 01/01/88 00:00:00 (0)
4 Using sp_ctrl, restart the Capture process.
sp_ctrl(sysA)> start capture
CHAPTER 12 433
SharePlex Utilities
Purging the variable-data directory with clean_vardir.sh

Supported platforms: UNIX only
The clean_vardir.sh script restores the variable-data directory to an initial state. It is an
alternative to using ora_cleansp in situations where you do not want to truncate the
SharePlex internal tables.
Unless a documented SharePlex procedure requires running this script, contact Quest
Technical Support before running it for the first time. This utility rarely is appropriate in
a production environment. It deactivates the configuration, and using it improperly can
result in replication problems and the need to resynchronize the data. Usually, there is
another alternative.
The clean_vardir.sh script removes the following:
the queue files in the rim sub-directory.
the log files in the log sub-directory. The Event log retains one entry reflecting the
clean_vardir.sh procedure.
the contents of the statusdb file in the data sub-directory.
the contents of the dump and state sub-directories.
The clean_vardir.sh script preserves user-created files such as configuration files, con-
flict-resolution files, hint files, the paramdb, and the oramsglist file.
The clean_vardir.sh script deactivates configurations. To start replication after running
clean_vardir.sh, you must activate a configuration.
Tip: To truncate only the SharePlex tables without removing the files in the variable-data
directory, use the cleanup.sql script (see page 435). To completely restore SharePlex to
an initial state by removing the SharePlex files and truncating the SharePlex tables, use
ora_cleansp (see page 439).
To run clean_vardir.sh
Run this script on UNIX systems only.
1 Shut down sp_cop.
2 Set the SP_SYS_VARDIR environment variable to point to the SharePlex variable-
data directory. If SP_SYS_VARDIR is not set, clean_vardir.sh uses the vardir listed
in the proddir/data/defaults.yaml file, where the proddir is where the script was
invoked from.
To set the SP_SYS_VARDIR environment variable

ksh shell:
export SP_SYS_VARDIR= /full pathname of variable-data directory
csh shell:
3 Run clean_vardir.sh from the bin sub-directory of the SharePlex product directory.
Run it as a SharePlex Administrator. Use the following syntax, where Oracle_version
is either 9i, 10gor 11g.
./clean_vardir.sh Oracle_version
4 When the script is finished running, you are returned to the UNIX prompt.
Note: The utility might generate an error message stating that clean_vardir.sh cannot
remove the .../save_SharePlex_version directory. You may manually remove this direc-
tory.
CHAPTER 12 435
SharePlex Utilities
Truncating the SharePlex tables with cleanup.sql

The cleanup.sql utility is a SQL script that truncates all of the SharePlex internal tables
except the SHAREPLEX_PARTITION table, which contains partition schemes that
might be needed again. It does not remove the SharePlex Oracle user, password, or
demonstration objects from the database.
The cleanup.sql script is an alternative to using ora_cleansp when you want to retain
replication data in the SharePlex variable-data directory.
Unless a documented SharePlex procedure requires running this script, contact Quest
Technical Support before running it for the first time. This utility rarely is appropriate in
a production environment. Using it improperly can result in replication problems and
the need to resynchronize the data. Usually, there is another alternative.
Tip: To remove only the SharePlex files in the variable-data directory, use the
clean_vardir.sh script (see page 433). To completely restore SharePlex to an initial
state by removing the SharePlex files and truncating the SharePlex tables, use
ora_cleansp (see page 439).
To run cleanup.sql
1 Log into Oracle as the SharePlex user. The SharePlex tables belong to 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 certain to run this
script as the correct one.
Tip: To find out the name of the SharePlex account, use the following command:
$ cat SharePlex_variable_data_directory/data/paramdb | grep SP_ORD_OWNER.
You will see a display similar to this: SP_ORD_OWNER_O.oraA jdadd.
The first component is the ORACLE_SID (oraA in the example).
The second component is the Oracle account name (jdadd in the example).
2 Run the cleanup.sql script in SQL*Plus. It prompts you for the SharePlex user name
and password.
SQL> @absolute_pathname/cleanup.sql
The script logs into SQL*Plus and truncates the SharePlex tables.
Debugging networking and/or firewall issues using the

socket_test utility
The socket_test utility was designed to debug networking and/or firewall issues for
Import, Export, and Compare/Repair. This section explains how to use this utility in an
environment configured with Network Address Translation.
Using the socket_test utility in a NAT configured environment

Network Address Translation (NAT) enables a local-area network (LAN) to use one set
of IP addresses for private internal traffic and another set of addresses for public exter-
nal traffic. NAT acts as a bridge and an interpreter between the two networks, e.g., a pri-
vate LAN and the public Internet, or a secure network and an insecure network.
Determining if your system is using NAT

Execute nslookup, using the same host name, from the source and target machines. If
the results reflect different values it is likely that the systems are working in a NAT con-
figured environment.
Running the socket_test utility

The socket_test is designed to simulate the behavior of the Compare Server and the
Compare Client. If the socket_test utility is successful there are no network or firewall
issues to prevent the source and target from communicating.
The socket_test utility is located in the utility sub-directory of the SharePlex product
directory on UNIX and Linux systems.
1 Execute the socket_test utility, on the source machine, using the server option. The
user can also specify a specify port number in the command line.
irvqasuf > socket_test server
The socket_test server will display the host IP address and the port number,
10.1.0.146 and 57370 respectively, in the example that follows. The server will
remain in a waiting state until the socket_test client connects to it.
socket_test - version: 1.2
HP-UX irvqasuf B.11.11 U 9000/800 1141089608 unlimited-user license
Program executing as server..., Thu Mar 9 19:58:22 2006
CHAPTER 12 437
SharePlex Utilities
SP_SYS_HOST_NAME was not set.

server host name: irvqasuf
server IP: 10.1.0.146
Port Number: 57370
2 Execute the socket_test utility, on the target machine, using the client option. The
user will need to provide the socket_test server network IP address (or if you are
working in a NAT configured environment you will need to provide the NAT IP
address of the source machine) and the port number issued by the socket_test
server. If the you specified the port number use that port number instead.
irvlabu01 > socket_test client 10.1.0.146 57370
If the socket test is successful the socket_test client will display the following mes-
sage:

SunOS irvlabu01 5.9 Generic_112233-12 sun4u sparc SUNW,Sun-Fire-880
Program executing as client..., Thu Mar 9 19:52:40 2006
client host name: irvlabu01
client IP: 10.1.0.36
Client is try to connect to.....
Server Host: 10.1.0.146
Server Port: 57370
rb(512):ReadWriteCnt = 0, readCnt=0, readBytes=0, writeCnt=0,
writeBytes=0re:ReadWriteCnt = 1, readCnt=1, totalRBytes=512, writeCnt=0,
totalWBytes=0
-m,0,0,-s,0,-l,10000000,-t,0,-r,0,-o,0,-x,0,0,0,0,0,0,
SUCCESSFULLY read/write messages from server
CE:ReadWriteCnt = 1, readCnt=1, totalRBytes=512, writeCnt=0, totalWBytes=0
Client completed successfully, Thu Mar 9 19:52:40 2006
Program exiting..., Thu Mar 9 19:52:40 2006
If the socket test is not successful the socket_test client will display the following:

SunOS irvlabu01 5.9 Generic_112233-12 sun4u sparc SUNW,Sun-Fire-880
Program executing as client..., Thu Mar 9 20:02:26 2006
client host name: irvlabu01
client IP: 10.1.0.36
Client is try to connect to.....
Server Host: 10.1.0.146

Server Port: 57370
Error calling connect in connect_to_server
Error 146: Connection refused
Error 146 calling connect_to_server
CE:ReadWriteCnt = 0, readCnt=0, totalRBytes=0, writeCnt=0, totalWBytes=0
Error in client, Thu Mar 9 20:02:26 2006
3 If the socket test is successful the socket_test server on the source machine will
append the following text to the text displayed in step 1 above:
Connected to client
WB(512):ReadWriteCnt = 0, readCnt=0, readBytes=0, writeCnt=0, writeBytes=0
WE:ReadWriteCnt = 1, readCnt=0, totalRBytes=0, writeCnt=1, totalWBytes=512
SE:ReadWriteCnt = 1, readCnt=0, totalRBytes=0, writeCnt=1, totalWBytes=512
Server completed successfully, Thu Mar 9 20:00:07 2006
Program exiting..., Thu Mar 9 20:00:07 2006
If the socket test is not successful the socket_test server will remain in a waiting
state until the socket_test client connects to it.
In the event of an unsuccessful socket test or if an error occurs execute Ctrl-C on the
source machine to exit out of the socket_test server.
CHAPTER 12 439
SharePlex Utilities
Restoring replication to an initial state with ora_cleansp

The ora_cleansp utility removes the current replication state on a system, including
deactivating configurations. This can be acceptable in a test or demonstration environ-
ment, but it rarely is appropriate in a production environment. Unless a documented
procedure or demonstration requires running ora_cleansp (OraCleanSp on Win-
dows systems), contact Quest Technical Support for assistance before running this
utility for the first time. There are other alternatives to running ora_cleansp.
How ora_cleansp works

ora_cleansp works in two stages to restore replication to an initial state, as follows:
ora_cleansp first truncates all of the SharePlex internal tables, except for the
SHAREPLEX_PARTITION table, which contains partition schemes that might be
needed again. It does not remove the SharePlex Oracle user, password, or demonstration
objects.
After the tables are truncated, ora_cleansp removes the following components from the
SharePlex variable-data directory:
the queue files in the rim sub-directory.
the log files in the log sub-directory. The Event log retains one entry reflecting the
outcome of the ora_cleansp procedure.
the contents of the statusdb file in the data sub-directory.
the contents of the dump and state sub-directories.
ora_cleansp preserves user-created files such as configuration files, conflict-resolution

files, transformation files, hint files, the paramdb, and the oramsglist file.
ora_cleansp deactivates configurations. To start replication after running ora_cleansp,
you must activate a configuration.
Other alternatives to ora_cleansp

To stop activity for a configuration without truncating the SharePlex tables and
restoring replication to an initial state, you might be able to use the abort config or
purge config command in sp_ctrl. For more information about these commands,
see the SharePlex Reference Manual.

To truncate the SharePlex tables without purging files in the variable-data directory,
you can run the cleanup.sql script (from the bin sub-directory of the product direc-
tory on UNIX systems or the util sub-directory of the product directory on Windows
systems).
On UNIX systems, you can purge the files in the variable-data directory without
truncating the SharePlex tables by running the clean_vardir.sh script from the bin
Important! ora_cleansp must be run on all source and target systems to restore replica-
tion to an initial state. To verify if and when ora_cleansp was run on a system, view the
Event Log on that system.
Before running ora_cleansp

4 Log on as a SharePlex Administrator.
5 [UNIX ONLY] Set the SP_SYS_VARDIR environment variable to point to the SharePlex
variable-data directory. If you are running multiple instances of sp_cop using multi-
ple variable-data directories, set SP_SYS_VARDIR for the variable-data directory
that you want to restore.
ksh shell:
$ export SP_SYS_VARDIR=/SharePlex_vardir_absolute_path
csh shell:
$ setenv SP_SYS_VARDIR /SharePlex_vardir_absolute_path
6 Run sp_ctrl from the bin sub-directory of the SharePlex product directory.
7 Shut down sp_cop.

sp_ctrl> shutdown
8 Verify that all SharePlex processes are stopped by using either the ps -ef | grep sp_
command on UNIX systems or Taskmgr from the SpUtil program on Windows sys-
tems.
CHAPTER 12 441
SharePlex Utilities
9 Kill all orphan SharePlex processes by using either the kill -9 command on UNIX
systems or the KillSharePlex.bat program on Windows systems.
10 [UNIX ONLY] If you have not done so already, view the oratab file to determine the val-
ues for ORACLE_HOME and ORACLE_SID for the instance.
$ cd /etc
$ more oratab
11 [UNIX ONLY] Set the ORACLE_HOME and ORACLE_SID environment variables.

ksh shell:
$ export ORACLE_HOME=[value from oratab file]
$ export ORACLE_SID=[value from oratab file]
csh shell:
$ setenv ORACLE_HOME [value from oratab file]
$ setenv ORACLE_SID [value from oratab file]
12 Run ora_cleansp using one of the following methods, depending on the platform.
Running ora_cleansp on a UNIX system

1 Change directories to the bin sub-directory of the SharePlex product directory (this
must be the current working directory), and run ora_cleansp with the SharePlex
Oracle user account and password. When run as a different user, ora_cleansp
does not truncate the SharePlex tables.
$ ./ora_cleansp SharePlex_username/SharePlex_password
Tip: To find out the name of the SharePlex account, use the following command:
$ cat SharePlex_variable_data_directory/data/paramdb | grep SP_ORD_OWNER.
You will see a display similar to this: SP_ORD_OWNER_O.oraA jdadd.
The first component after the dot is the ORACLE_SID (oraA in the example).
The second component is the Oracle account name (jdadd in the example).
2 View the Event Log after you run the utility to confirm its results.
Note: The utility might generate an error message stating that it cannot remove the .../
save_SharePlex_version directory. You can remove this directory.
Running OraCleanSp on a Windows system

Or...
Navigate to the bin sub-directory of the SharePlex product directory, then double-
click the SpUtils program icon.
CHAPTER 12 443
SharePlex Utilities
2 In the SharePlex Utilities dialog box, click the OraCleanSp tab.
3 In the Port list box, select the port number for the instance of SharePlex for which
you are running OraCleanSp.
4 Under SharePlex User Info, enter the following information.
In the User text box, type the name of the SharePlex Oracle user for the designated
instance of SharePlex. OraCleanSp must run as the SharePlex Oracle user.
In the Password text box, type the password for the SharePlex user.
In the Oracle SID text box, type the ORACLE_SID of the Oracle instance for
which you are running OraCleanSp.
5 Click Clean to execute OraCleanSp. Processing progress is displayed in the text box
at the bottom of the dialog box.
6 Click Close to close the dialog box.

Using the SharePlex license key utilities

Supported platforms: UNIX, Linux, and Windows
SharePlex licenses are issued for a machine ID number (CPU ID). Each license pro-
vided is specific for a particular host, operating system, and number of CPUs. Existing
customers will need to get a new license key before upgrading to SharePlex version 5.x.
Important! You can use a SharePlex license utility on the primary node of a cluster to
install licenses for all secondary nodes in the cluster because they all share one variable-
data directory, but you cannot add licenses for non-clustered machines from one
machine. The license utility must be run on each non-clustered replication system so that
the license information is installed in the paramdb in the variable-data directory on each
system.
Overview of the license utilities

SharePlex provides utilities for viewing and adding license keys and viewing a machine
ID. There are different license utilities on UNIX and Windows platforms.
UNIX and Linux systems

On UNIX and Linux systems, separate utilities are used for:
Adding a license key to a UNIX or Linux system.
Generating a license key on a UNIX or Linux system
Viewing a license key on a UNIX or Linux system.
Windows systems
On Windows systems, one utility handles all of the licensing functions for SharePlex.
See page 447.
Adding a license key to a UNIX or Linux system

On UNIX and Linux systems, SharePlex provides a utility named splex_add_key for
adding license keys to existing SharePlex installations such as when you are convert-
ing from a demo license to a permanent one.
CHAPTER 12 445
SharePlex Utilities
You can use splex_add_key to license one system, or you can use it to license multiple
systems in a cluster.
To run splex_add_key
1 In sp_ctrl, shut down SharePlex.
sp_ctrl> shutdown
2 Change directories to the install sub-directory of the SharePlex product directory,

and run the splex_add_key script. The following choices are displayed.
SharePlex License Utility
1) Read license key from file
2) Enter license key manually
3) Add license key for alternate host
q) Quit License Utility
Enter option:
3 Choose the appropriate option, 1 for reading the license key from a file, 2 for enter-
ing it manually or 3 for adding a license key for an alternate host.
Note: If you choose option 3, you are asked to Enter Machine ID as many times as you
like, until you enter q to quit.
4 Enter the license key, paying attention to spaces and capitalization if you are entering
it manually, and press Enter. Repeat steps 3 - 4 for each machine.
Note: When adding a license key with splex_add_key, the string needs to contain the
following before the actual license key: SPLEXKEY=.
5 Select the q option to exit the script.
6 Start SharePlex to begin or resume replication.
Generating a license key on a UNIX or Linux system

On UNIX and Linux systems, the splex_uname utility collects the local machine infor-
mation in order for Quest to generate a license key.
The splex_uname utility is located in the install sub-directory of the SharePlex product
directory on UNIX and Linux systems. It displays the hostname of the local system, the
host ID, the operating system, machine model, CPU type, CPU speed, and the number
of CPUs on the local system.
To run splex_uname
To collect the local machine information, run splex_uname and a display similar to fol-
lowing is shown:
$ /splex/proddir/install/splex_uname
Local system info:
Host Name = irvspxu09
Host ID = 2198894273 (831076C1 HEX)
Operating System = SunOS
Machine model = SUNW,UltraAX-i2
CPU Type = sparc9
CPU Speed = 500
Number of CPUs = 1
Viewing a license key on a UNIX or Linux system

On UNIX and Linux systems, the splex_get_key utility provides a convenient way to
determine if a machine has a valid SharePlex license (such as if you are using a demo
license and do not know its expiration date), or to find out the actual license number
itself.
The splex_get_key utility is located in the install sub-directory of the SharePlex prod-
uct directory on UNIX and Linux systems. It displays the customer name, the license
number for the local machine, the product name, and, if the license is a demo license,
the expiration date of the license.
To run splex_get_key
To view a license number, run splex_get_key. A display similar to following results:
$ /splex/proddir/install/splex_get_key
Customer Name = quest
License Key = EANLCF3P56F8M1JB1K6RBJCBB6TBEP0
Product Name = SharePlex Oracle
License type = demo key
Expired on = 01/01/2008 12:00 AM
CHAPTER 12 447
SharePlex Utilities
Licensing SharePlex on a Windows system

On Windows platforms, all licensing functions are performed through the SpUtils util-
ity, including viewing the machine ID for a system.
To run SpUtils
2 On the Windows desktop, double-click the SpUtils shortcut.
Or...
Click the Start button on the Windows taskbar, then click Programs and navigate to
SpUtils in the SharePlex programs group.
3 In the SharePlex Utilities dialog box, click the SharePlex Services tab.
4 In the Port list box under SharePlex Services, select the port number for the
instance of SharePlex that you are licensing.
5 Under SharePlex Service Status, click Stop, then wait for the Current State field to
display a message stating that the service stopped.
CHAPTER 12 449
SharePlex Utilities
6 In the SharePlex Utilities dialog box, click the License Key tab.
7 If the port for the instance of SharePlex for which you are adding or viewing the
license key is not displayed in the Port list box, select the correct port number.
8 Click Add License. To add a license key, either copy it from a file and use the Con-
trol+v keys to paste it into the License Key text box, or enter it manually, including
spaces. The key is case-sensitive. Click Ok.
9 Information about the license is displayed in two places: the License Info box,
which lists the information about the host machine, and the Status text box at the
bottom of the dialog box, which tells you if the license key is a permanent key or a
temporary one (expiration date is given)
10 [CLUSTERS ONLYMUST BE PERFORMED ON THE PRIMARY NODE] To add a license for a secondary
node of a cluster, select the Add Alternate Host Id check box, then select the
machine ID from the CPU ID list box. Repeat this step for all secondary nodes in the
cluster.
11 In the SharePlex Utilities dialog box, click the SharePlex Services tab.
12 Under SharePlex Service Status, click Start when you are ready to start SharePlex.
13 Click Close to close the SpUtils utility.

CHAPTER 12 451
SharePlex Utilities
Using the SpUtils utility

Supported platforms: Windows only
On Windows systems, SharePlex provides the SpUtils utility, which enables you to start
SharePlex and run select management utilities from one interface.
To run SpUtils, double-click the SpUtils shortcut on the Windows desktop.
Or...
SpUtils in the SharePlex programs group. The SharePlex Utilities dialog box appears.
Viewing the installation information from SpUtils

Click the Information tab to view information about the system where SharePlex is
installed and about the SharePlex version and environment.
Controlling the SharePlex service from SpUtils

Click the SharePlex Services tab to install, start, stop, or remove a SharePlex service
(instance of SharePlex). For more information about running SharePlex, see Chapter 3.
For more information about installing and removing the SharePlex service, see the
Running OraSetup from SpUtils

Click the OraSetup tab to run the OraSetup utility, which establishes an Oracle account
for SharePlex and installs database objects necessary for replication. For more informa-
tion about running OraSetup, see page 410.
Running OraCleanSp from SpUtils

Click the OraCleanSp tab to run the OraCleanSp utility, which removes the current
replication environment. For more information about running OraCleanSp, see
page 439.
Managing license keys from SpUtils

Click the License Key tab to view, add, or change the SharePlex license key for an
instance of SharePlex, and to view the machine ID number associated with the license
key. For more information about managing license keys, see page 444.
Terminating a process or setting priority from SpUtils

Click the TaskMgr tab to run the Windows Task Manager with special privileges so that
you can terminate SharePlex processes or set their priority. You cannot terminate Share-
Plex processes or set process priority through the regular Windows Task Manager
because the NuTCRACKER environment controls the SharePlex processes.
CHAPTER 12 453
SharePlex Utilities
The dialog box displays only the SharePlex processes, filtering out other processes on
the system. To terminate a process or set its priority, right-click the process name in the
dialog box, then select either End Process or Set Priority (shown below).
Using the SpClient remote-access utility

Supported platforms: Windows only
On Windows systems, you can use the SpClient utility instead of other remote-access
programs (such as Terminal Server) to log onto any replication system from one central
machine and perform the following SharePlex functions:
Control the SharePlex service
Run OraCleanSp
Run OraSetup
Run SplexAddKey
Run a special Task Manager with the correct privileges to kill SharePlex processes
and change priority
Activate and configure the Sp_Nt_Mon monitoring utility
SpClient is installed automatically when you install SharePlex, or you can install it as a
stand-alone program on a machine that is not used for replication. SpClient runs on any
Windows machine.
SpClient has two components:
The sp_remote agent runs in the background as a service on machines where you
are running SharePlex. It starts when the system starts.
The sp_client process is the user interface, which you can run from any machine
whether or not SharePlex is installed there.
CHAPTER 12 455
SharePlex Utilities
The SpClient toolbar

Figure 23 illustrates the SharePlex tool bar buttons. These buttons are inactive until you
log onto a system. The other buttons are standard Windows buttons.
FIGURE 23: The SpClient interface
The SpClient buttons are, from left to right in Figure 23:

Remote logon to connect to a remote replication machine
Local logon to connect to the local machine
Logoff to end the current session of SpClient
SpServices to install, remove, start, or stop the SharePlex service. For more informa-
tion about controlling the SharePlex service, see Chapter 3.
OraCleanSp to run OraCleanSp to restore replication to an initial state. For more
information about running OraCleanSp, see page 439.
SpOraSetup to create or change the SharePlex Oracle user and set up the instance
for SharePlex replication. For more information about running OraSetup, see page 410.
SpAddKey to add a SharePlex license key to a machine and to find out the machine
ID number.
SpTaskMngr to open a SharePlex-filtered version of the Windows Task Manager to
terminate SharePlex processes and set process priority. For more information, see the
instructions on page 459.
SpMonitor to configure and run the Sp_Nt_Mon monitoring script. For more infor-
mation about using Sp_Nt_Mon to monitor replication, see Monitoring SharePlex on
Windows systems on page 356.
SpClient menus
SpClient includes standard Windows File, Edit, View and Help menus. In addition, the
Access and Select menus let you perform the same tasks as the toolbar buttons.
Whether to use the menu or the toolbar is a matter of personal preference.
SpClient output window

SpClient prints to screen every action it executes, as shown in the following example.
SpClient output does not enter the Event Log. To save a sessions records, you can print
the output or save it to a text file using standard Windows Print and Save commands
from the File menu.
Running SpClient
Use any standard Windows method to launch SpClient.
From the Start menu, navigate to the SpClient shortcut in the SharePlex Programs
folder.
Or...
Use Windows Explorer to navigate to the bin sub-directory of the SharePlex product
directory. Double-click the SpClient program.
CHAPTER 12 457
SharePlex Utilities
Connecting with SpClient

When you run SpClient, it opens a blank client window containing a display area and a
Windows menu bar and toolbar. To begin using SpClient, log onto either a remote sys-
tem or the local system, depending on the location of the SharePlex instance you want
to affect.
To log onto the local system

1 On the toolbar, click the Local Logon button.
Local
Logon
button
SpClient does not request logon information for the local machine. It uses the logon
that you supplied when you logged onto Windows. It verifies the logon in the output
window. When logon is verified, the other SpClient buttons on the toolbar become
active (displayed in color instead of gray).
To log onto a remote system

1 On the toolbar, click the Remote Logon button.
Remot
e
Logon
The Remote Access dialog box appears.
2 In the Remote Access dialog box, enter the following:

In the User Name field, enter a valid Windows logon name. This user must be a
member of the SharePlex Admin group on the remote machine. This is true for
the system Administrator, as well as all other users.
In the Password field, enter the password for that user.
In the Machine Name field, enter the name of the replication system to which you
want to connect. The sp_remote client must be installed on that system for the
connection to succeed.
In the Port Number field, enter the port number for SpClient on that machine. Do
not enter the port number for SharePlex.You can either accept the default port
number for SpClient (2101) or enter a different port number where SpClient was
installed on that machine.
CHAPTER 12 459
SharePlex Utilities
3 To initiate the connection, click Connect. SpClient displays the connection status at
the bottom of the Remote Access dialog box.
4 Click Done to close the dialog box. The other SpClient buttons on the toolbar are
now active (displayed in color instead of gray).
Logging off
To log off from the local system or a remote system, click the Logoff button on the tool-
bar. SpClient terminates the connection, but the SpClient interface remains active to
enable logon to a different system.
Logoff
button
Running the SpClient Task Manager

The SpClient Task Manager provides a filtered view of the Windows Task Manager that
displays only the SharePlex processes on the machine to which you connected. The dis-
play is continuously updated.
1 On the toolbar, click the SpTaskMngr button.
SpTaskMngr
button
The SpClient Task Manager window appears, showing all SharePlex processes for
the port number displayed in the list box. To display processes for other SharePlex
port numbers, select the port number from the list box.
CHAPTER 12 461
SharePlex Utilities
2 [OPTIONAL] To kill a SharePlex process, right-click the process name, then select End
Process.
3 [OPTIONAL] To change the priority of a SharePlex process, right click the process name,
then click Set Priority and select a priority setting.
4 Click Exit to close the Task Manager and return to the SpClient interface.
Glossary
active-active See peer-to-peer replication.

replication
ALTER TABLE A DDL command that changes a tables structure, storage characteristics or
other parameters. Some ALTER TABLE commands are replicated by Share-
Plex.
archive log A permanent record of all the transactions made against an Oracle instance.
bi-directional Replication that goes in both directions: from the source to the target, and
replication then from the target back to the source, used in disaster recovery and peer-
to-peer replication.
BLOB An acronym for Binary Large Object. This is a built-in Oracle datatype con-
sisting of unstructured (not recognized by the database) binary data of up to
4 GB in length that is stored in the database. Some examples of BLOBs are
photographs, video clips, sound files, and other files stored in proprietary
format.
asynchronous Replication that does not require the source and target instances and network
replication to be accessible at all times. Instead, it allows activity to continue on the
source and lets transactions queue if the network, target system or target
instance is down.
capture queue A temporary data repository for raw Oracle data that SharePlex copies from
the Oracle redo logs for replication.
Capture process One of the major SharePlex processes. Residing on the source system, it
copies the source data from the Oracle redo logs and places it into the cap-
ture queue.
cascading delete A constraint set on data that, when a DELETE operation is performed on a
primary key column, automatically initiates a DELETE operation on the row
containing the related foreign key in a dependent table.
cascading A multi-tiered replication strategy that uses an intermediary target system to

replication pass replicated data on to remote target system(s) that are not networked to
the source system.
chained row A row in a table that is stored in more than one database block and therefore
has several row pieces. These have a negative impact on the performance of
the system and on the replication speed of SharePlex.
checkpoint A process used by SharePlex to facilitate safe, asynchronous transport of

recovery system data by acknowledging the receipt of packets and monitoring their sequence.
This enables SharePlex to identify missing elements and request re-trans-
mission.
check constraint A constraint the ensures that the value of a piece of data meets a certain con-
dition, such as being greater than or equal to 0.
CLOB An acronym for Character Large Object. This is a built-in Oracle datatype
consisting of fixed or variable-width character data of up to 4 GB in length
that is stored in the database. An example of a CLOB is an unstructured
XML document or an ASCII text file.
cold backup A physical backup of the database made after the database has been shut
down.
column A field in a database record.
COMMIT An Oracle SQL command that makes a series of changes permanent.
configuration A file containing the specifications that tell SharePlex which objects to repli-
cate, and to which target systems the replicated data should be sent.
conflict resolution User-defined instructions that tell the Post process what action should be
taken when the pre-image of data from the source system does not match the
local data on the target system. Conflicts often occur in peer-to-peer envi-
ronments where it is possible for different users to change the same data on
different systems.
consolidated Replication of different data from different machines to a single machine to

replication provide a centralized reporting instance.
constraint A restriction imposed on a piece of data in an Oracle database, limiting its

(integrity value or use.
constraint)
database A collection of datafiles and the software that manipulates it.

GLOSSARY 465
datasource The SharePlex term for the Oracle instance containing the objects being rep-
licated by SharePlex for Oracle. This is also the term for the source UNIX
filesystem in SharePlex FS software from Quest.
datatype One of the several kinds of data that can be stored and manipulated by Ora-
cle, such as dates, numbers or characters.
data definition This is the SQL language used to define data in a database, such as when
language creating and altering tables. SharePlex replicates some DDL.
data dictionary A read-only set of tables that provides information about the database. The
data dictionary is central to database operations because it contains informa-
tion about schemas, storage, column defaults, integrity constraints, user
information, permissions, and other information. The data dictionary is
stored in the SYSTEM tablespace.
data distribution The process of sending data to remote offices.
data manipulation This is the SQL language used to insert, update or delete data in a database.
language SharePlex replicates all DML.
data warehousing Enterprise-wide data storage that encompasses current and archived data.
data mart An alternative to data warehousing that stores only a subset of an organiza-
tions data intended for use by an individual department or group of users.
DDL See data definition language.
destination data Sometimes used synonymously with target data. This is the copy of the
source data that SharePlex maintains in the target instance on the target sys-
tem.
destination Sometimes used synonymously with target system. This is the system or sys-
system tems containing the objects to which the replicated data is written by Share-
Plex.
direct-path load Data loaded directly into a database in pre-formatted blocks instead of using
INSERT statements.
disaster recovery The ability to continue computer operations after the primary computers and
related hardware/software are disabled by unplanned outages such as a fire
or earthquake.
DML See data manipulation language.
downtime Planned or unplanned time when a computer is unavailable.

ERP Enterprise Resource Planning software. A group of business applications

such as Oracle Applications that work in concert with each other to manage
data consistently throughout an organization.
event A single incident in the SharePlex process, such as the startup of a process,
the execution of a command, or the establishment of a connection.
Event Log A log maintained by SharePlex that records all replication events, such as
the activation of a process or the issuing of a command, used primarily for
problem solving.
export/import The process used by Oracle to copy data between tables.
export queue A temporary data repository created by SharePlex which holds data that is
ready to be transported from a source system to the target system.
Export process One of the major SharePlex processes. Residing on the source system, it
sends replicated data from the source system to the target system over the
TCP/IP network.
fault tolerance The ability of a process to handle interruptions without adversely affecting
data or processing integrity.
file transfer A method of copying/moving data from one system to another.

protocol
foreign key The primary key of one table that is stored in another referenced table. It
establishes a relationship between the tables and allows users to access the
information in both tables quickly and efficiently.
FTP See file transfer protocol.
high availability The ability to continue normal operations despite the requirements to be
down for planned computer maintenance.
host Another term for an individual computer system.
horizontally Also known as selective row replication, this feature of SharePlex allows
partitioned you to replicate selected rows of a table, based on column conditions that
replication you define before configuration activation.
hot backup A physical backup of the database while the database is open and in
ARCHIVELOG mode.
hot standby An alternate online database that, when opened, is ready to take over for the
production database in the event of an emergency or planned downtime.
GLOSSARY 467
Import process One of the major SharePlex processes. Residing on the target system, it
receives the replicated data from the source system and places it in a post
queue for subsequent writing to disk.
index Created for a table to allow faster access to the table data by organizing and
referencing each rows key; without an index, the entire table must be
scanned by Oracle and SharePlex. Adding an index greatly speeds replica-
tion processing.
instance A single manifestation of an Oracle database complete with datafiles, con-

nectivity information, shared area memory and its own name, number, and
parameters. Multiple instances can run on one computer using one installa-
tion of Oracle.
key definition SharePlex allows you to specify one or more columns to be used as a key
when a table does not have a unique or primary key. The key definition is
specified in the configuration file.
latency The difference in time between when the source data is changed and when
the target data reflects that change. SharePlex minimizes latency because it
replicates changes continuously, instead of waiting for a commit to be
issued.
load balancing The distribution of processing among multiple computers.
LOB Oracle acronym for Large Object. A LOB can be large graphics files, for-
matted text files, audio, video and other unstructured data of up to four GB
in size that is stored in a database. SharePlex replicates BLOB and CLOB
large objects. (See BLOB and CLOB.)
log-based The type of replication used by SharePlex that reads the online redo logs
replication instead of triggers.
log wrap The overwriting of the first Oracle redo log after the last one allocated to the
instance has filled up. This has important implications for SharePlex replica-
tion.
LONG columns A column in a table reserved for large chunks of data. LONG columns are
replicated by SharePlex, but tables containing LONG columns should have a
primary key for faster processing.
master database A database that contains a complete copy of the objects and is independent
of any other database in the replication hierarchy. This also is known as a
production or source database.
message A message is a packet of information that is sent from Capture to the other
replication processes in sequence. 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 opera-
tion. Large operations like those on LONG or LOB columns can be spread
among 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. In general, unless
you are replicating numerous changes to LONGs and BLOBs, you can
assume that the number of messages that you see in a process or queue status
display approximately corresponds to the same number of SQL operations.
named queue A SharePlex queue other than the default queue created by SharePlex; a
named queue is created when a user defines it within the configuration file.
object A table, sequence or other entity within an Oracle database.
object cache An internal table maintained by SharePlex that maps an object ID to the
object name, creating a snapshot of all the objects that contains the name,
size and type of columns in each one, along with any constraints.
OLTP Online transaction processing, generally a high-intensity data processing

environment.
ORACLE_SID The system (server) identification name or number of the Oracle instance.
ORACLE_HOME The environment in which the Oracle software runs, including the location
of the software files.
ora_setup A program provided with SharePlex that sets up SharePlex as an Oracle user
during installation.
partitioned Selective replication of rows and/or columns; see horizontally partitioned

replication replication and vertically partitioned replication.
peer-to-peer Replication strategy where users on the source and one or more target sys-
replication tems all make changes concurrently to the same data while SharePlex repli-
cates it, using conflict resolution routines to determine how to handle
duplicity. This strategy is also known as active-active, master-to-master
or multi-master replication.
posting A SharePlex term for the process of writing replicated data to disk on the tar-
get system.
GLOSSARY 469
post queue A temporary data repository that receives replicated data from the Import
process on a target system and holds it until the Post process writes it to disk.
Post process One of the major SharePlex processes. Residing on the target system, it is
responsible for making sure source and target data match and writing
changes to the target instance.
pre-image A snapshot of the most recent source data values before the current block of
changes was made. Before applying those changes to the target instance, the
Post process compares the pre-image with the target data to ensure that the
values are the same. If the values are different, the data is out of sync.
primary key/ A column or set of columns containing unique identifying values for each
unique key row in a table, such as a customer ID number. Using a primary key on tables
increases the speed of SharePlex replication.
ps -ef | grep A UNIX command used for culling out selected information from the UNIX
filesystem.
query A request for information from a database.
queue An interim data repository created by SharePlex to store replicated data as it

is passed along its route from the source to the target system. There are three
queues: the capture and export queues on the source system, and the post
queue on the target system.
raw device A storage unit on a system that is devoid of operating system or application
software or formatting, used only for storing raw data.
Read process One of the major SharePlex processes. Residing on the source system, it
takes replicated raw data from the capture queue and prepares it for export to
the target system.
redo logs Temporary log files maintained by Oracle that record every user transaction
for recovery purposes and, if specified, are periodically written to permanent
archive logs. SharePlex reads the redo logs in order to replicate the data
specified in a configuration.
referential A property that guarantees that values in one column depend on values in
integrity another column.
replication The process of copying data from a source machine to a target machine for
backup, reporting or other purposes. SharePlex is a type of replication soft-
ware.
ROLLBACK The SQL statement that undoes all changes made to a database since the last
COMMIT statement.
rollback segments Internal Oracle safety devices that are used to reconstruct lost information in
the data recovery process. SharePlex uses the rollback segment to maintain a
snapshot of all current transactions.
routing map The information in a configuration that tells SharePlex where to send the
replicated data. The basic components of a routing map are the target
machines name and the ORACLE_SID of the target instance.
row All fields in one database record.
Row ID map An internal table that SharePlex maintains to keep track of chained rows in a
table.
SELECT An Oracle SQL command that retrieves information from a database.
sequence An Oracle function that provides a list of numbers in order.
SharePlex FS Software from Quest that replicates UNIX filesystems, allowing replication
of files outside of the Oracle instance for use in disaster recovery strategies.
source data The original, or master, data that is being replicated.
source system The machine on which the original (source) data to be replicated resides.
sp_cnc The SharePlex command and control program. This is the process that car-
ries out user commands.
sp_cop The SharePlex master control program. It runs in the background on both
source and target machines to establish and coordinate replication processes.
sp_ctrl The SharePlex command-line interface program through which users issue
commands to monitor and control replication.
SQL Structured Query Language, the standard for data access in most database
environments, and the language used by SharePlex in the replication pro-
cess.
SQL*Net A type of communications software that connects systems in a network to an

Oracle database.
SQL statement One or more SQL commands and qualifying clauses that tell Oracle exactly
what the user wants to do.
GLOSSARY 471
Status Database A record provided by SharePlex of key replication events, used primarily for
monitoring and problem solving purposes.
stored procedure Established rules and application logic for manipulating data which are
maintained as a group of SQL and PS/SQL code that resides within the data-
base instead of within the application on the client machine. This speeds up
Oracle processing and also allows repeat use of the code by other users and
applications.
synchronization The process of making target data identical to source data. SharePlex repli-
cation maintains synchronization between the source and all target systems
to provide an alternate instance for backup, recovery, reporting and other
purposes.
table A way of structuring data using sets of rows and columns.
tablespace The storage space allocated to a defined group of tables in the Oracle data-
base.
target data The copy of the source data that SharePlex maintains in the target instance
on the target system.
target system A system to which the original (source) data is replicated for reporting,
recovery or other purposes.
TCP/IP A network communication protocol used by SharePlex.
text editor A program that handles the input of programming statements or text entries
in files.
transformation This SharePlex feature allows you to manipulate replicated data instead of
posting it, using custom PL/SQL procedures. The procedure manipulates the
data and controls where the resultant data is posted.
trigger A program within the Oracle instance that initiates an action when an event
such as updating a record occurs.
TRUNCATE A SQL command that erases all the data from a table.
uni-directional Replication that goes in one direction only: from source to target system.
replication
vertically Also known as selective column replication, this feature of SharePlex allows
partitioned you to replicate selected columns of a table, as specified in the configuration
replication file.
views A representation of an existing table that can be used in the same manner as
a table but does not actually exist as an object with physical storage space. It
is a way for controlling the way a table can be seen by different users.
WHERE clause A clause within a SQL statement that refines the way a SQL command
affects data.
Appendix A
Third Party Licensing
SharePlex for Oracle contains the following third party components with copyright
acknowledgements and licensing statement requirements.
Copyright Acknowledgements
libstdc++
Licensed under the GNU General Public License with runtime exception version 2.0.
Copyright 1989, 1991 Free Software Foundation, Inc.
Source was not modified. A copy of the source can be found at http://rc.quest.com.
The original distribution license can be found via the libstdc++ home page at http://
www.quest.com/legal/third-party-licenses.aspx or by contacting Quest Software.
Ruby
Licensed under the Ruby License.
Copyright 2007 Yukihiro Matsumoto
Source was not modified. The original distribution can be found via the Ruby home
page at http://www.ruby-lang.org/en/ or contact Quest Software.
STEMKIT-CPP
Licensed under the MIT License.
http://sourceforge.net/projects/stemkit
Tecla
http://www.astro.caltech.edu/~mcs/tecla/
Copyright 2000 by Martin C. Shepherd.
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this soft-
ware and associated documentation files (the "Software"), to deal in the Software with-
out restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, and/or sell copies of the Software, and to permit persons to whom
the Software is furnished to do so, provided that the above copyright notice(s) and this
permission notice appear in all copies of the Software and that both the above copyright
notice(s) and this permission notice appear in supporting documentation.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WAR-
RANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL
THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE
LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUEN-
TIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CON-
NECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Except as contained in this notice, the name of a copyright holder shall not be used in
advertising or otherwise to promote the sale, use or other dealings in this Software with-
out prior written authorization of the copyright holder.
TSC-TPM
Licensed under the BSD License.
http://sourceforge.net/projects/tsc-tpm/
License Statements
GNU General Public License with runtime exception
http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/COPYING
Version 2, June 1991
Copyright 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies of this license document,
but changing it is not allowed.
Preamble
APPENDIX A 475
The licenses for most software are designed to take away your freedom to share and
change it. By contrast, the GNU General Public License is intended to guarantee your
freedom to share and change free software--to make sure the software is free for all its
users. This General Public License applies to most of the Free Software Foundation's
software and to any other program whose authors commit to using it. (Some other Free
Software Foundation software is covered by the GNU Library General Public License
instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General
Public Licenses are designed to make sure that you have the freedom to distribute cop-
ies of free software (and charge for this service if you wish), that you receive source
code or can get it if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these
rights or to ask you to surrender the rights. These restrictions translate to certain respon-
sibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you
must give the recipients all the rights that you have. You must make sure that they, too,
receive or can get the source code. And you must show them these terms so they know
their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this
license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone
understands that there is no warranty for this free software. If the software is modified
by someone else and passed on, we want its recipients to know that what they have is
not the original, so that any problems introduced by others will not reflect on the origi-
nal authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid
the danger that redistributors of a free program will individually obtain patent licenses,
in effect making the program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
GNU GENERAL PUBLIC LICENSE

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION
AND MODIFICATION
This License applies to any program or other work which contains a notice placed by
the copyright holder saying it may be distributed under the terms of this General Public
License. The Program, below, refers to any such program or work, and a work based
on the Program means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it, either verbatim or with
modifications and/or translated into another language. (Hereinafter, translation is
included without limitation in the term modification.) Each licensee is addressed as
you.
Activities other than copying, distribution and modification are not covered by this
License; they are outside its scope. The act of running the Program is not restricted, and
the output from the Program is covered only if its contents constitute a work based on
the Program (independent of having been made by running the Program). Whether that
is true depends on what the Program does.
1 You may copy and distribute verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and appropriately pub-
lish on each copy an appropriate copyright notice and disclaimer of warranty; keep
intact all the notices that refer to this License and to the absence of any warranty; and
give any other recipients of the Program a copy of this License along with the Pro-
gram.
You may charge a fee for the physical act of transferring a copy, and you may at your
option offer warranty protection in exchange for a fee.
2 You may modify your copy or copies of the Program or any portion of it, thus form-
ing a work based on the Program, and copy and distribute such modifications or
work under the terms of Section 1 above, provided that you also meet all of these
conditions:
a You must cause the modified files to carry prominent notices stating that you
changed the files and the date of any change.
b You must cause any work that you distribute or publish, that in whole or in
part contains or is derived from the Program or any part thereof, to be licensed as
a whole at no charge to all third parties under the terms of this License.
c If the modified program normally reads commands interactively when run, you
must cause it, when started running for such interactive use in the most ordinary
way, to print or display an announcement including an appropriate copyright
notice and a notice that there is no warranty (or else, saying that you provide a
warranty) and that users may redistribute the program under these conditions,
and telling the user how to view a copy of this License. (Exception: if the Pro-
gram itself is interactive but does not normally print such an announcement, your
work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of
that work are not derived from the Program, and can be reasonably considered inde-
APPENDIX A 477
pendent and separate works in themselves, then this License, and its terms, do not
apply to those sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based on the Program,
the distribution of the whole must be on the terms of this License, whose permissions
for other licensees extend to the entire whole, and thus to each and every part regard-
less of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work
written entirely by you; rather, the intent is to exercise the right to control the distri-
bution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the
Program (or with a work based on the Program) on a volume of a storage or distribu-
tion medium does not bring the other work under the scope of this License.
3 You may copy and distribute the Program (or a work based on it, under Section 2) in
object code or executable form under the terms of Sections 1 and 2 above provided
that you also do one of the following:
a Accompany it with the complete corresponding machine-readable source code,

which must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange; or,
b Accompany it with a written offer, valid for at least three years, to give any third
party, for a charge no more than your cost of physically performing source distri-
bution, a complete machine-readable copy of the corresponding source code, to
be distributed under the terms of Sections 1 and 2 above on a medium customar-
ily used for software interchange; or,
c Accompany it with the information you received as to the offer to distribute cor-
responding source code. (This alternative is allowed only for noncommercial
distribution and only if you received the program in object code or executable
form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modifi-
cations to it. For an executable work, complete source code means all the source
code for all modules it contains, plus any associated interface definition files, plus
the scripts used to control compilation and installation of the executable. However,
as a special exception, the source code distributed need not include anything that is
normally distributed (in either source or binary form) with the major components
(compiler, kernel, and so on) of the operating system on which the executable runs,
unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a
designated place, then offering equivalent access to copy the source code from the
same place counts as distribution of the source code, even though third parties are
not compelled to copy the source along with the object code.
4 You may not copy, modify, sublicense, or distribute the Program except as expressly
provided under this License. Any attempt otherwise to copy, modify, sublicense or
distribute the Program is void, and will automatically terminate your rights under
this License. However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such parties remain in
full compliance.
5 You are not required to accept this License, since you have not signed it. However,
nothing else grants you permission to modify or distribute the Program or its deriva-
tive works. These actions are prohibited by law if you do not accept this License.
Therefore, by modifying or distributing the Program (or any work based on the Pro-
gram), you indicate your acceptance of this License to do so, and all its terms and
conditions for copying, distributing or modifying the Program or works based on it.
6 Each time you redistribute the Program (or any work based on the Program), the
recipient automatically receives a license from the original licensor to copy, distrib-
ute or modify the Program subject to these terms and conditions. You may not
impose any further restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to this License.
7 If, as a consequence of a court judgment or allegation of patent infringement or for

any other reason (not limited to patent issues), conditions are imposed on you
(whether by court order, agreement or otherwise) that contradict the conditions of
this License, they do not excuse you from the conditions of this License. If you can-
not distribute so as to satisfy simultaneously your obligations under this License and
any other pertinent obligations, then as a consequence you may not distribute the
Program at all. For example, if a patent license would not permit royalty-free redis-
tribution of the Program by all those who receive copies directly or indirectly
through you, then the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular
circumstance, the balance of the section is intended to apply and the section as a
whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other
property right claims or to contest validity of any such claims; this section has the
sole purpose of protecting the integrity of the free software distribution system,
which is implemented by public license practices. Many people have made generous
APPENDIX A 479
contributions to the wide range of software distributed through that system in reli-
ance on consistent application of that system; it is up to the author/donor to decide if
he or she is willing to distribute software through any other system and a licensee
cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a conse-
quence of the rest of this License.
8 If the distribution and/or use of the Program is restricted in certain countries either
by patents or by copyrighted interfaces, the original copyright holder who places the
Program under this License may add an explicit geographical distribution limitation
excluding those countries, so that distribution is permitted only in or among coun-
tries not thus excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
9 The Free Software Foundation may publish revised and/or new versions of the Gen-
eral Public License from time to time. Such new versions will be similar in spirit to
the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a

version number of this License which applies to it and any later version, you have
the option of following the terms and conditions either of that version or of any later
version published by the Free Software Foundation. If the Program does not specify
a version number of this License, you may choose any version ever published by the
Free Software Foundation.
10 If you wish to incorporate parts of the Program into other free programs whose dis-
tribution conditions are different, write to the author to ask for permission. For soft-
ware which is copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our decision will be
guided by the two goals of preserving the free status of all derivatives of our free
software and of promoting the sharing and reuse of software generally.
NO WARRANTY
11 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PRO-
GRAM AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRAN-
TIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR-
POSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFEC-

TIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
OR CORRECTION.
12 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO

IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY
WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMIT-
TED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GEN-
ERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING
BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INAC-
CURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAIL-
URE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
As a special exception, you may use this file as part of a free software library without
restriction. Specifically, if other files instantiate templates or use macros or inline func-
tions from this file, or you compile this file and link it with other files to produce an exe-
cutable, this file does not by itself cause the resulting executable to be covered by the
GNU General Public License. This exception does not however invalidate any other
reasons why the executable file might be covered by the GNU General Public License.
END OF TERMS AND CONDITIONS
MIT License
http://www.opensource.org/licenses/mit-license.php
Permission is hereby granted, free of charge, to any person obtaining a copy of this soft-
ware and associated documentation files (the "Software"), to deal in the Software with-
out restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, subject to the following conditions: The
above copyright notice and this permission notice shall be included in all copies or sub-
stantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WAR-
RANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPY-
RIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIA-
BILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
APPENDIX A 481
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE

USE OR OTHER DEALINGS IN THE SOFTWARE.
BSD License
http://opensource.org/licenses/bsd-license.php
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of condi-
tions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials
provided with the distribution.
Neither the name of the organization nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior written
permission
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT-
NESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTI-
TUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI-
NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
Ruby License
http://www.ruby-lang.org/en/about/license.txt/
Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>. You
can redistribute it and/or modify it under either the terms of the GPL (see COPYING.txt
file), or the conditions below:
1 You may make and give away verbatim copies of the source form of the software
without restriction, provided that you duplicate all of the original copyright notices
and associated disclaimers.
2 You may modify your copy of the software in any way, provided that you do at least
ONE of the following:
a place your modifications in the Public Domain or otherwise make them Freely
Available, such as by posting said modifications to Usenet or an equivalent
medium, or by allowing the author to include your modifications in the software.
b use the modified software only within your corporation or organization.
c rename any non-standard executables so the names do not conflict with standard
executables, which must also be provided.
d make other distribution arrangements with the author.
3 You may distribute the software in object code or executable form, provided that you
do at least ONE of the following:
a distribute the executables and library files of the software, together with instruc-
tions (in the manual page or equivalent) on where to get the original distribution.
b accompany the distribution with the machine-readable source of the software.
c give non-standard executables non-standard names, with instructions on where
to get the original software distribution.
d d make other distribution arrangements with the author.
4 You may modify and include the part of the software into any other software (possi-
bly commercial). But some files in the distribution are not written by the author, so
that they are not under this terms. They are gc.c(partly), utils.c(partly), regex.[ch],
st.[ch] and some files under the ./ missing directory. See each file for the copying
condition. 90 SharePlex Manager SharePlex Manager User Guide
5 The scripts and library files supplied as input to or produced as output from the soft-
ware do not automatically fall under the copyright of the software, but belong to
whomever generated them, and may be sold commercially, and may be aggregated
with this software.
6 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR

IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE.
Index 483
Index
Symbols
/etc/group file 49
/etc/services file 129
& argument 49, 66
Numerics
508 compliance xv
abort config command 311

abstract datatypes
in partitioned replication 160
planning for 108
Access menu in SpClient 456
accessibility xv
account
for starting SharePlex (Windows) 278
in Oracle
UNIX 407
Windows 410
activate config command 308
activation process
description 308
guidelines 310
troubleshooting, see SharePlex Reference Manual
viewing status and statistics 311
Administrators Guide Version 8.0 (document revision 2)
adding
named queues
export 150
post 155
partition schemes and conditions 319
primary key 101
sequences to replication 314
SharePlex license key 444
table
to replication 312
to the database 366
unique index 101
Administrator, SharePlex
authority to
create configurations 132
set port number 259
start SharePlex 48
specifying startup authority on Windows systems 278
alerts
monitoring scripts (UNIX) 340
monitoring utility (Windows) 356
ALTER TABLE command
RENAME TO 111
application patches and upgrades 380
app-modules directory
UNIX systems 38
archive logging, considerations for replication 114
ASM 114
asynchronous transport 30
auth_hosts file 268
authorization level
SharePlex commands 55
starting SharePlex 48
Index 485
backups
full system 413
Oracle hot backup
on active source database 289
on quiet database 296
partial system 412
SharePlex 129
bandwidth for SharePlex 128
batch loads 113
bi-directional replication
description 83
establishing for
high availability 190
peer-to-peer replication 211
bin directory
UNIX systems 37
bin sub-directory 456
Windows systems 39
binaries
location 33
running 44
broadcast replication
establishing 194203
using for
distributing data 84
distributing processing and balancing loads 85
buffer size 119
build_config.sql script 179
caching SQL statements 240

capstat.log 353
Capture process
DDL logging 112
description 32
stopping 114
capture queue
description 30
monitoring 353, 356
cascading deletes, considerations for replication 104
cascading replication
description 86
establishing 197
case-sensitivity, in configuration 136139
centralized reporting
description 87
establishing 204210
changes, how applied by SharePlex 34
changing
configurations 312
data instead of posting 245
key values 101
location of ORACLE_HOME 369
OPEN_CURSORS 117
process priority on Windows systems 280
replicating objects 366
SharePlex password on UNIX systems 402
SharePlex Registry entries 282
SharePlex startup on Windows systems 276
SharePlex text editor 266
SharePlex user in trigger WHEN clause 427
SharePlex user name 406
target objects 99
target ORACLE_SID 370
transformation file 257
character sets
establishing 119
supported by SharePlex 119
check constraints, performance issues 105
checkpoint
in redo logs 36
recovery system 30
cleanup.sql script 435
clean_vardir.sh script 433
clusters
routing maps for 142
setting SP_SYS_VARDIR for 258
Index 487
collectors
planning for replication 108
column conditions
changing 319
creating 163
description 161
supported datatypes and syntax 166
viewing 171
column partition
excluded column partition 174, 175
column-level replication
changing 319
configuring 172
description 132
columns
in horizontally partitioned replication 166
requirements for replication 97
selective replication of 172
commands, SharePlex
authorization levels 55
getting scroll bar for output 56
issuing from
remote system 56
sp_ctrl, interactively 56
UNIX command line 55
maximum string length 55
to use for
activating configurations 308
connecting to alternate sp_cop 56
copying configurations 312
creating configurations 135
deactivating replication 311
defining default system 57
editing a configuration 179
shutting down replication 53
stopping a replication process 52
viewing activation status 311
viewing configuration statistics 311
viewing queue status 154
viewing replication processes 154
see also SharePlex Reference Manual
COMMIT statement
and Post read/release 119
and replication 35
and tuning log buffer size 119
comparing tables for synchronization 99
compression of archive logs 114
condition, column
changing 319
creating 163
description 161
viewing 171
config directory
UNIX systems 38
config sql script 183
config sub-directory
description 28
Windows systems 40
Index 489
configurations
activation
description 308
statistics for 311
adding objects
sequences 314
tables 312
change marker for 309
changing 312
components of 135
creating for
data distribution 194
distributed processing 194
faster posting 155
high availability and data recovery 190
multiple targets 148
peer-to-peer replication 222
replication through intermediary system 197
reporting 186
selective column replication 172
selective row replication 160
deactivating 311
description 28
in cluster environments 142
information in internal tables 36
methods for creating
basic 145
multiple targets 148
quick-build for entire database 183
quick-build for multiple tables in a schema 179
separating data with named export queues 150
removing configured objects 318
reverse configuration 192
troubleshooting, see SharePlex Administrators Guide
configuring
database for replication 95
objects for replication 132
system for replication 122
using Oracle wildcards 137
conflict resolution
description 211
connection
security with auth_hosts file 268
terminating from remote system 459
to sp_cop 54
consolidated replication
description 87
establishing 204210
constraints, integrity 104
converting data during replication 245
CPU
requirements for replication 123
create config command 145, 266
CREATE TABLE command 366
create_ignore.sql utility 424
creating
column partitions 174
configurations 132
multiple variable-data directories 64
named queues
export 150
post 155
SharePlex Oracle user
on UNIX 407
on Windows systems 410
simulated key 134, 140
transformation components 249
unique index in absence of primary keys 101
See also defining
crontab 340
cursors, setting 117
Index 491
data
changing what is replicated 312
configuring for replication 132
converting during replication 245
directory in product directory
Windows 39
directory in variable-data directory
Windows 40
distribution
description 84
establishing replication for 194
guidelines for replication 90
integrity assurance 90
preventing from replicating 424
recovery
description 83
planned failover procedures 334
unplanned failover procedures 322
strategies for replication 80
warehousing/mart
description 87
data directory
UNIX systems 37, 38
Data Focus 42
database
changing
during replication 365
SharePlex password 402
SharePlex user (UNIX) 406
creating SharePlex account
UNIX 407
Windows 410
Oracle supplemental logging 95
patches and upgrades
application 380
Oracle 389
datafiles
location of 123
on raw devices 114
datasource
description 135
multiple replicating, separating 150
datatypes
abstract
guidelines for replicating 108
converting through transformation 245
in SHAREPLEX_PARTITION table 164
in source and target columns 90, 98
large, in named queues 134
LOB, replication requirements 108
object-relational 108
supported for horizontal partitioning 166
user-defined
dates, replicating 121
db directory
UNIX systems 38
db sub-directory
Windows systems 40
DDL
changes to target objects 99
logging DDL 112
performing on replicating objects 366
renaming tables 111
replication of 110
supported and non-supported 76
deactivate config command 311, 383
Index 493
default
behavior for
DDL error on target 112
direct-load replication 113
SQL Cache 240
startup on Windows systems 42
configuration directory 135
errors monitored by sp_eventmon 344
export queue 30
number of hints 238
NuTCRACKER folder 42
parameter settings, file containing 37
post queue 31
SharePlex environment for Windows 41
SharePlex port number 259
overriding 271
size of queue file 429
system for sp_ctrl 57
text editor 266
values in extra target columns 97
DEFAULT conflict resolution parameter 236
defining
character sets 119
column partitions 174
data to be replicated 132
default system for sp_ctrl 57
simulated key 134, 140
See also creating
definitions, of terms 463
delete queue command 330
DELETE statement
disabling cascading on target 104
out-of-sync conditions for 91
replicating 34
deleting
dependent rows (ON DELETE CASCADE) 104
entries from conflict resolution file 224
entries from transformation file 257
objects from configuration 318
queues
during failover procedure 324, 330
through qview 428
through sp_ctrl, see SharePlex Reference Manual
DEMO_DEST table 37
DEMO_SRC table 37
desktop shortcut for SharePlex 50
direct-path loads, conditions for replicating 113
disabling cascading deletes 104
distributed processing
description 85
DML
changes to target objects 99
locks 116
DML_LOCKS parameter 116
driver, Oracle JDBC version 121
dropping
DTaskmgr.bat 281
dump directory
UNIX systems 38
dump sub-directory
Windows systems 40
edit config command 266

editor, default and alternative 266
e-mail alerts
monitoring scripts (UNIX) 340
monitoring utility (Windows) 356
environment variables, SharePlex 41, 282
errlog.sql 36
error.splex log 343
error_list file 344
Index 495
errors, viewing 35
Event Log
monitoring with sp_eventmon 343
events, replication
monitoring 343
viewing 35
exception marker 170
Export process
creating multiple 150
description 32
export queue
description 30
named 150
export/import (Oracle)
description 26
using to synchronize data 299
failover and failback

planned 334
preparing backups 129
unplanned 322
foreign keys
replication considerations 104
FTP, using to synchronize data 302
full table scans, replication impact 101
Generating a license key on a UNIX or Linux system 445

glossary of terms 463
handshaking process 30
high availability
backup recommendations 129
description 83
procedures for failover and failback 321
hints, using to expedite Post process 238

horizontally partitioned replication
changing 319
configuring 160
description 132
hot backup
with Oracle for synchronization 289, 296
how SharePlex replicates 46
I/O intensive operations 123

icons for SpClient 455
Import process, description 32
index-organized tables 104
indices
location of SharePlex indices 123
need for in replication 102
using INDEX hints for posting 238
init.ora file
DML_LOCKS parameter 116
LOG_PARALLELISM parameter 118
PROCESSES parameter 117
INSERT statement
in horizontally partitioned replication 160
install directory
UNIX systems 38
integrity constraints in replication 104
intermediary system
description 86
establishing replication with 197
internal tables, SharePlex
creating
UNIX systems 407
Windows systems 410
descriptions 36
truncating 435
Index 497
iwgrep utility
setting IW_HOME variable 345
used in monitoring 343
IW_HOME variable 345
iwsnmptrap for SNMP 361
Java, JDBC driver version 121

JDBC driver version 121
keys on tables
changing values 101
foreign 104
in peer-to-peer replication 216
need for 100
simulating 134, 140
kill command 342
Label Security, Oracle 122

LAN, in high availability configuration 83
language, setting for SharePlex 119
large objects, considerations for replication 108
latency
causes of 101, 113
how SharePlex minimizes 35
monitoring for 347, 359
lib directory
UNIX systems 38
license key
adding 444
viewing 446
list command in qview 428
load balancing
description 85
LOB datatypes
in selective row replication 160
isolating in separate queues 108
Local Logon button 457
local system, logging on with SpClient 457
locally-managed tablespaces
and index-organized tables 104
locks, DML 116
log buffer size 119
log directory
UNIX systems 38
log sub-directory
Windows systems 40
logging off with SpClient 459
login security features 268
logmon.log 347
LOG_PARALLELISM parameter 118
logs
archive 114
for sp_ps 350
out-of-sync SQL 36
redo 114
sp_eventmon 343
sp_logmon 347
sp_qstatmon 353
LONG datatype
considerations for replication 110
-m argument 345
MailUserName 348
MailUserName variable 345
mailx program 342
memory
for LOB replication 109
requirements for SharePlex processes 125
used by queues 124
menus for SpClient 456
message 34
Index 499
meta-inf directory
UNIX systems 38
MKS Platform Components 42
MKS Toolkit
description 42
monitoring
utilities for UNIX systems 340
utility for Windows systems 356
with SNMP traps 361
Mortice Kern Systems 42
moving
location of ORACLE_HOME 369
multiple
configurations on a system 28
databases on same system 150
instances of SharePlex on same system 64, 67
objects with same names 139
port numbers 259
Post processes 33
source systems
centralized reporting 87, 207
peer-to-peer replication 88, 211
target systems
configuration for 148
description 8486
UPDATES and DELETES, and indices 238
variable-data directories 64
versions
SharePlex 70
named queues
export
and LOBs 108
creating 150
post 155
names
of configurations 135
of monitoring scripts 340
of replication strategies 80
of SharePlex directories 37
of SharePlex logs
of SharePlex processes 32
of SharePlex programs 44
of SharePlex queues 30
of source and target columns 97
of source and target tables 98
NAT 436
network
controlling when SharePlex sends data 35
how SharePlex uses 35
recovery from failures 35
requirements 128
security features 268
Network Address Translation 436
Network Management Station (NMS) 361
NLS_LANG environment variable 119
NULLs in keys, considerations for replication 100
number
activation ID number 309
for PROCESSES parameter 118
of columns in tables 97
of database writers 119
of DML locks for SharePlex 116
of hints, maximum 238
of indices on a table 104
of messages for Post read/release 119
of OPEN_CURSORS 117
of SQL Cache cursors 241
of sub-queue files 109
of target routes, maximum 142
SharePlex port 259
NuTCRACKER
and changing process priority 280
Index 501
object
cache 130, 309
ID 36
types
replicating 108
object-relational structures 108
ON DELETE CASCADE, considerations for replicating 104
online transaction processing (OLTP) 88
OPEN_CURSORS parameter
setting for replication 117
setting for SQL Cache 241
ora_chpwd utility 402
Oracle
9i
DDL Logging 112
error handling 112
renaming tables 111
buffer size 119
DDL replication 110
hot backup, to synchronize data
active source database 289
quiet source database 296
JDBC driver version 121
Label Security 122
patches and upgrades 389
supported and non-supported features 76
Oracle wildcards
in configuration files 137
ora_cleansp
how to use 439
running remotely with SpClient 455
OraCleanSp, see ora_cleansp
ORACLE_HOME
changing location of 369
determining 136
ORACLE_SID
changing target 370
determining 136
ora_setup
running on UNIX systems 407
running on Windows systems (OraSetup) 410
running remotely with SpClient 455
OraSetup, see ora_setup
oratab file 129, 136, 407
out-of-sync tables
causes of 90, 114
prevention planning 95
viewing statements for 36
parameter for
keys that permit NULLs 100
number of
DML locks 116
hints 238
open cursors 117
processes in Oracle 117
read/release interval 119
replication of
DDL 110
direct loads 113
posted data 200
shared memory for queues 109
SharePlex text editor
SharePlex variable-data directory 258
SNMP traps 362
SQL Cache 240, 241
SSH 271
using prepared conflict resolution for all tables 236
partition schemes and conditions
adding and changing 319
creating 163
description 161
viewing 171
Index 503
partitioned replication
and application patches or upgrades 382
changing 319
description 96, 132
of columns (vertical) 172
of rows (horizontal) 160
partitioned tables
and replication 310
partitions
for selective column replication 174
for selective row replication 161
pass-through system 86
password for SharePlex, changing
UNIX systems 402
Windows systems 410
patches
application 380
applying with Oracle hot backup or DBCopy 385
OS and Oracle 389
SharePlex 389
peer-to-peer replication
assigning transaction priority 221
description 88
establishing 211
requirements for
archive logging 115
cascading deletes 105, 218
LOB replication 109
primary keys 101, 216
sequences 108, 217
triggers 106, 218
target table access during 100
updating inventory/account balances 219
performance, improving
changing
log buffer size 119
Post read/release 119
process priority 127
disabling check constraints 105
tuning Post process ??245
using
indices 102
keys 100
permissions
for monitoring utilities 342
for starting SharePlex 48
see also privileges
per-process memory requirements 125
placeholder for routing map 170
port number
multiple SharePlex instances
UNIX systems 64
Windows systems 67
multiple SharePlex versions 70
setting
UNIX systems 259
Windows systems 261
Post process
configuring for faster posting
with INDEX hints 238
with named post queues 155
with SQL caching 240
DDL logging 112
description 33
ensuring data integrity 90
monitoring 350
things that reduce performance 101, 103, 108, 118, 119
post queue
deleting sub-queues 429
description 30
monitoring 353, 356
named 155
poststat.log 353
pre-image 91
Index 505
preventing
cascading deletes from firing 104
character set errors 119
contention on SHAREPLEX_TRANS table 122
DML transactions from replicating 424
drive-related I/O contention 123
excessive Post I/O for small transactions 119
failures to connect to Oracle 117
full table scans during posting 102
key changes in peer-to-peer replication 216
log wrap-related problems 114
loss of SharePlex environment 129
OPEN_CURSORS errors 117
open-files limitation during posting 126
process priority-related slowdowns 127
queue space problems 124
referential integrity corruption on target 104
SharePlex from running out of DML locks 116
SharePlex process failure 126
target table access 99
triggers from firing on target 106
unauthorized connections to sp_cop 268
users from entering duplicate data 102
primary key
replication considerations 100
simulating a key 134, 140
priority, setting for SharePlex
UNIX systems 128
Windows systems 280
privileges
granting for
DML on target system 100, 192
SharePlex as Oracle user 407, 410
SharePlex for conflict resolution 225
SharePlex for transformation 247
SharePlex startup on Windows systems 278
required for
changing SharePlex Oracle password 402
changing SharePlex process priority 280, 452
modifying monitoring scripts 348
running qview on Windows systems 428
problem-solving, see SharePlex Reference Manual
Index 507
procedure for
activating and deactivating configurations 308
adding license key 444
applying patches
application 380
OS and Oracle 389
SharePlex 389
configuring
data for replication 132
SharePlex for SSH port forwarding 271
high availability
failing back to primary system 324
failing over to secondary system after system failure 322
planned failover and failback 334
restoring replication after secondary instance failure 330
Oracle Setup
UNIX 407
Windows 410
performing
DDL on replicating objects 366
system backups 412
upgrades, SharePlex 389
preventing
DML from replicating 424
triggers firing for SharePlex 426
removing
current replication state 439
data from variable-data directory 433
old queues 428
SharePlex 414, 416
running
different versions of SharePlex 70
multiple instances of SharePlex 64
setting environment parameters 258
shutting down SharePlex 52
starting
replication systems 47
SharePlex without replication processes 59
SharePlex, normal manner 48
transforming data 245
truncating SharePlex tables 435
See also changing

procedures, stored
for transforming data instead of posting 245
process ID 49
processes
location of 33
monitoring
UNIX systems 350
Windows systems 356
multiple sp_cop 64
priority, setting for SharePlex
UNIX systems 128
Windows systems 280
remote viewing and termination (Windows) 459
SharePlex, description 32
starting SharePlex without 59
tab in Task Manager 281
PROCESSES parameter, setting for replication 117
product directory, description 37
Program Files folder 456
qstatus command 322

queues
description 30
location and optimization 125
maximum number on a system 151, 155
monitoring
UNIX systems 353
Windows systems 356
named
export 150
post 155
removing old queue files 429
viewing and removing with qview 428
qview utility 428
RAID devices 125

Index 509
raw devices
redo logs on 114
SharePlex on 123
Read process, description 32
read/release
by Post process 429
by Post upon COMMIT 119
during SharePlex shutdown 53
parameter for Post 119
read-consistency marker 36
Reconcile
to a SCN 291
to a sequence number 291
reconcile command
in failback 326
in failover 322
in initial synchronization
with hot backup on active database 291, 294
when secondary instance fails 332
with hot copy to apply patches 387
recovery
after secondary instance failure 330
after system failure 322, 324
checkpoint
explanation 30
Post checkpoint 119
data, replication strategy for
description 83
establishing 190
redo logs
archiving option 116
ASM 114
on raw devices 114
operations that bypass 116
optimal location 123
referential integrity constraints
Registry, changing
SharePlex environment 282
SharePlex text editor 266
Remote Access window for SpClient 459
Remote Logon button 457
remote system
controlling access from 268
issuing sp_ctrl commands for 56
running utilities for 454
selective replication to 132
strategy for replicating to 84, 85, 197
removing
data from SharePlex tables 435
entries from
configuration 318
conflict resolution file 224
transformation file 257
Windows Registry 282
old queue files 429
SharePlex
from UNIX systems 414
from Windows systems 416
SharePlex directories 37
table
from replication 318
renaming tables 111
replicating
cascading deletes 104
DDL 110
direct-path loads 113
DML from triggers 106
entire tables 97
LOBs 108
LONGs 110
object-relational structures 108
operations that bypass redo logs 116
selected columns 172
selected rows 160
sequences 106
Index 511
replication
between tables on same system 81, 186
for centralized reporting
description 87
establishing 204210
for data distribution
description 84
establishing 194
for data warehousing/mart
description 87
establishing 204210
for distributed processing
description 85
establishing 194
for distribution through intermediary system
description 86
establishing 197
for high availability and data recovery
description 83
establishing 190
for load balancing
description 85
establishing 194
for multiple peers
description 88
establishing 211
for reporting 81
description 81
establishing 186
messages, definition 34
monitoring
on Windows with Sp_NT_Mon 356
with SNMP 361
with UNIX scripts 340
planning and requirements 75
preventing for specific transactions 424
restoring to initial state 439
starting and stopping 4852
supported and non-supported Oracle components 76
reporting
replication for data warehousing/mart
description 87
establishing 204210
replication to maintain a reporting instance
description 81
establishing 186
rim directory
UNIX systems 38
rim sub-directory 124, 125
Windows systems 40
rollback segment
optimal location 123
routing map
description 141
for multiple target systems 133
limitations 142
placeholder in configuration file 170
row-level replication
changing 319
configuring 160
description 132
rows
Oracle Label Security 122
selective replication of 160
-s option when starting sp_cop 59

same-system replication (UNIX only)
description 81
establishing 187
save directory
UNIX systems 38
save sub-directory
Windows systems 40
saving
files for backup 129
SpClient output 456
state of replication when shutting down 53
Index 513
scheme, partition
adding and changing 319
creating 163
description 161
viewing 171
SCN 291
scripting
alteration of triggers to ignore SharePlex 427
configurations
build_config.sql 179
config.sql 183
disabling of cascading deletes 104
purging of variable-data directory 433
replication monitoring
sp_eventmon 343
sp_logmon 347
sp_ps 350
sp_qstatmon 353
truncating of SharePlex tables 435
scroll bar, in sp_ctrl for Windows 56
security
controlling remote connections 268
for starting and stopping SharePlex 48
row-level, and replication 122
Select menu in SpClient 456
selective replication
description 96, 132
of columns 172
of rows 160
sequence number 291
sequences
service, SharePlex (Windows systems)
starting 50
starting remotely 455
setting, see changing
SharePlex
architecture diagram 29
backing up 129
binaries (processes), location 33
changing
environment parameters 258
password 402
port number 259
user name/password 406
commands, see SharePlex Reference Manual
configurations
activating 308
creating 132
description 28
desktop shortcut 50
in high availability environment 321
internal tables
creating on UNIX systems 407
creating on Windows systems 410
list of 36
monitoring 339
Oracle account
Windows systems 410
overview 2541
patches 389
process priority
UNIX systems 128
Windows systems 280
processes
description 32
location of 123
monitoring 350, 356
product directory 37
queues
description 30
location and sizing 124
viewing and removing 428
remote connection and control 454
removing
UNIX systems 414
Index 515
Windows systems 416

replication options 96
replication strategies 8089
requirements for replication
database 95
system 122
resources consumed 124
routing limitations 142
running
multiple sp_cop sessions 64, 67
multiple versions on same system 70
with SharePlex FS 62
service
controlling with SpClient 455
removing 416
services (see SharePlex processes)
starting
basic startup procedure 48
with -u option 63
without replication processes (-s option) 59
startup on Windows systems 276
supported and non-supported Oracle features 76
upgrading 389
utilities 423
variable-data directory
UNIX systems 38
Windows systems 40
SharePlex FS, running with SharePlex for Oracle 62
SHAREPLEX_ACTID table 36
SHAREPLEX_COMMAND table 36
SHAREPLEX_CONFIG table 36
SHAREPLEX_DATAEQUATOR table 36
SHAREPLEX_IGNORE_TRANS procedure 424
SHAREPLEX_LOBMAP table 36
SHAREPLEX_MARKER table 36
SHAREPLEX_OBJMAP table 36
SHAREPLEX_PARTITION table 37, 164
SHAREPLEX_TRANS table 37
preventing contention on 122
show activate command 311
show config command 311

SID_errlog.sql 36
snapshots 26
SNMP, using with SharePlex 361
socket_test 436
source
meaning of 27
objects
description 137, 139
planning for replication 95
system
multiple 211
trusted 221
table names 98
sp_add_trigger.sql utility 384, 427
sp_change_trigger.sql utility 427
sp_client process 454
SpClient utility 454
sp_cop
connections
security for 268
with sp_ctrl 54
description 44
differences between UNIX and Windows systems 46
running multiple sessions
on same UNIX system 64
setting alternative port for 259
shutting down 52
starting
basic startup procedure 48
with -s option 59
with -u option 63
without SharePlex services (processes) 59
SP_COP_IDLETIME parameter 115
sp_copsrv.exe 46
SP_COP_TPORT parameter 260
SP_COP_UPORT parameter 260
Index 517
sp_ctrl
connecting to alternate port 56
defining default system 57
description 44
maximum number of characters 55
running for one command 55
running interactively for multiple commands 56
starting 54
stopping 57
sp_ctrl.exe. See sp_ctrl
spelling case, in configuration 136139
sp_eventmon monitoring utility 343
SP_IMP_WCMT_MSGCNT parameter 115
splex_add_key utility
running locally (UNIX) 444
running remotely through SpClient 455
splex_get_key utility 446
splex_uname utility 445
sp_logmon monitoring utility 347
sp_mport 32, 46
Sp_Nt_Mon monitoring script 356
sp_nt_mon.txt file 357
sp_ocap 32, 46
SP_OCT_CHECKPOINT_FREQ parameter 115
SP_OCT_REPLICATE_DLOAD parameter 113
SP_OCT_REPLICATE_POSTER parameter 200
SP_OPO_HINTS_LIMIT parameter 238
SP_OPO_MAX_CDA parameter 241
SP_OPO_READRELEASE_INTERVAL parameter 119
SP_OPO_SQL_CACHE_DISABLE parameter 240
SP_OPO_STOP_ON_DDL9I_ERR parameter 112
sp_opst 46
SP_ORD_CDA_LIMIT parameter 115
SP_ORD_DELAY_RECORDS parameter 115
SP_ORD_LDA_ARRAY_SIZE parameter 115
sp_ordr 32, 46
SP_ORD_RMSG_LIMIT parameter 115
Spotlight on Oracle 108
sp_ps monitoring utility 350
sp_qstatmon monitoring utility 353
SP_QUE_SHMSIZE parameter 109
sp_remote 454
sp_remove_trigger.sql utility 427
SP_SLG_SNMP_ACTIVE parameter 362
SP_SLG_SNMP_COMMUNITY parameter 362
SP_SLG_SNMP_ERROR parameter 363
SP_SLG_SNMP_EXIT parameter 363
SP_SLG_SNMP_HOST parameter 362
SP_SLG_SNMP_INT_ERROR parameter 362, 386
SP_SLG_SNMP_LAUNCH parameter 363
SP_SLG_SNMP_MJR_ERRNUM parameter 362
SP_SLG_SNMP_MNR_ERRNUM parameter 362
SP_SLG_SNMP_OUT_OF_SYNC parameter 363
SP_SLG_SNMP_SHUTDOWN parameter 363
SP_SLG_SNMP_STARTUP parameter 363
SP_SLG_SNMP_SYS_ERROR parameter 363
SP_SYS_IN_SYNC parameter 100
SP_SYS_VARDIR, setting 258
SpUtils utility 451
sp_xport 32, 46
SP_XPT_PORT_OVERRIDE parameter 271
SP_XPT_USE_LOCALHOST parameter 271
SQL Cache
and OPEN_CURSORS 117
running 240
tuning 243
SQL statement
and index hints 238
caching for faster posting 240
definition of out-of-sync 90
how SharePlex constructs 34
use of system-defined name for abstract datatype 108
viewing for out-of-sync tables 36
SQL*Loader 113
SSH port forwarding 271
SSH Secure Shell
parameters for 270
Index 519
starting
replication 308
replication servers 47
SharePlex 48
controlling startup mode 276
SpClient 456
sp_ctrl 54
state directory
UNIX systems 38
state sub-directory 130
Windows systems 40
Status Database 35
stopping
Capture process 114
for DDL errors (9i) 112
replication 311
replication processes 52
SharePlex 52
sp_ctrl 57
store/restore to synchronize data 299
striped devices and SharePlex 125
synchronization
causes of out-of-sync conditions 90, 99
explanation of 27, 90
verifying 99
with FTP 302
with import/export 299
with Oracle hot backup
active database 289
quiet database 296
with transportable tablespaces 305
system
backup on replication machine 412
failover/failback procedures 322, 324
licensing for SharePlex 444
remote
accessing in Windows 454
connecting with sp_ctrl 56
secure connections 268
removing SharePlex from
UNIX procedure 414
Windows procedure 416
tablespace in Oracle 123
System Change Number 291
tables
accessing on target 99
adding
to the database 366
configuration script for multiple 179, 183
dropping
from configuration 318
instance-specific 98
key requirements 100
foreign keys 104
name of source and target 98
not replicated 99
partitioned 310
SharePlex internal tables 36
structure requirements 97
to exclude from replication 98
Index 521
target
meaning of 27
objects
commands to verify synchronization 99
description 140
planning for replication 95??
ORACLE_SID, changing 370
system
how SharePlex applies changes to 34
maximum number of 142
replicating to central 87, 204210
replicating to multiple 8486, 148, 194202
row IDs on 100
verifying synchronization on 90
Task Manager
changing process priority 280, 452
identifying processes 47
running remotely with SpClient 455, 459
TCP/IP
how SharePlex uses 35
security for 268
setting SharePlex port for 259
SharePlex bandwidth requirements for 128
temp directory
UNIX systems 38
temp files generated by sp_qstatmon 353
terms, glossary of 463
testing new version of SharePlex 70
text editor, defining 266
timestamp priority in conflict resolution 221
Title page version
Version 6.0.0 Release i
toolbar for SpClient 455
transformation of data 245
transformation.SID file 255
transportable tablespaces, using for synchronization 305
traps, SNMP for SharePlex 361
triggers
requirements for SharePlex 106
utilities for changing 426
trim command in qview 429

troubleshooting replication, see SharePlex Reference Manual
truncate log command 344
TRUNCATE PARTITION command
trusted source priority in conflict resolution 221
tuning
parameters, SharePlex xi
the Post process 238244
types, user-defined
replication requirements 108
-u option when starting sp_cop 63

uni-directional replication
description 81
establishing 186
uninstalling SharePlex
from UNIX systems 414
from Windows systems 416
unique key on tables
description 100
simulating a key 134, 140
uniqueness, ensuring for rows 100
UPDATE statement
upgrades
application 380
applying with Oracle hot backup or DBCopy 385
OS and Oracle 389
SharePlex 389
Index 523
user
access on target system 99
command levels for sp_ctrl 55
command-line interface 36, 44
file for groups 129
group for starting SharePlex 49, 50
SharePlex
changing on UNIX systems 402
disabling triggers for 106
privilege for SYS.QSA_KTFBUE view 104
user-defined types
planning for 108
util directory
UNIX systems 38
Windows systems 39
utilities
debugging network issues 436
managing SharePlex 451
monitoring replication 340
remote access 454
V$LOG table 348

variable-data directory
description 37
when running multiple sp_cop processes 64
variables, environment
UNIX systems 258
Windows systems
varrying array (VARRAY) collectors
planning for 108
verifying
synchronization 99
that SharePlex processes are running 47
Veritas Quick I/O and replication 128
versions
Oracle JDBC driver 121
SharePlex, running different 70
vertically partitioned replication

changing 319
configuring 172
description 132
rules for use 98
using when column names are different 97
with horizontally partitioned replication 160
viewing
activation status 311
configuration statistics 311
number of concurrent sessions 241
out-of-sync SQL 36
partition schemes 171
queues
names of 428
status and disk space 429
SharePlex processes on Windows systems 47
SQL Cache hit count 243
WAN
in high availability configuration 83
SharePlex support for 35
web browser 88
WHEN clause, in triggers 427
WHERE clause
exclusion of LONGs 110
in SharePlex statements 91, 101
Index 525
Windows
adding SharePlex license key 444
changing SharePlex Registry entries 282
configuring SharePlex startup 276
determining ORACLE_SID 136
differences from UNIX systems 46
displaying scroll bar in sp_ctrl 56
identifying SharePlex processes on 47
Registry environment for SharePlex 41
removing SharePlex 416
running
different SharePlex versions 74
multiple instances of SharePlex 64
OraSetup 410
sp_ctrl 56
setting
alternative editor 266
process priority 280
SharePlex port 261
SharePlex control utility 451
SharePlex directories 39
starting
SharePlex 50
SharePlex without replication processes 60
work tables 98

SharePlex Original Admin Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SharePlex Original Admin Guide

Uploaded by

Copyright:

Available Formats

SharePlex

SharePlex For Oracle

Viewing this manual in PDF format ............................................................................................ xii

Chapter 1: Whats New in 8.0

Chapter 2: How SharePlex Works

How SharePlex uses the network................................................................................................. 35

Chapter 3: Running the SharePlex Programs

Introduction to the SharePlex programs....................................................................................... 44

Starting SharePlex without starting replication processes ........................................................... 59

Chapter 4: Planning SharePlex Replication

What SharePlex replicates ........................................................................................................... 76

Replication to maintain a reporting instance................................................................................ 81

Replication for centralized reporting ...........................................................................................87

Understanding synchronization ....................................................................................................90

Chapter 5: Preparing for SharePlex Replication

Configuration options .................................................................................................................132

Establishing replication for reporting .........................................................................................186

Chapter 6: SharePlex Optional Setup

Using INDEX hints for faster posting........................................................................................ 238

Considerations for using transformation.................................................................................... 245

Setting the SP_SYS_VARDIR environment variable ............................................................... 258

Enhancing security with host authorization ............................................................................... 268

Part 6: Other optional features

Configuring SharePlex startup status on Windows systems...................................................... 276

Chapter 7: Starting SharePlex Replication

Synchronizing data using an Oracle hot backup on an active database..................................... 289

Part 2: Activating and deactivating configurations

About configuration activation ...................................................................................................308

Adding objects to an active configuration ..................................................................................312

Chapter 8: Using SharePlex in a High-Availability Environment

Chapter 9: Unattended SharePlex Monitoring

Overview of the SharePlex Monitoring Utilities ........................................................................340

Overview of Sp_Nt_Mon ...........................................................................................................356

Part 3: Using SNMP with SharePlex

Overview of the SharePlex SNMP agent................................................................................... 361

Chapter 10: Changing Oracle Characteristics Of Replicated Objects

CREATE TABLE ...................................................................................................................... 366

Moving the location of ORACLE_HOME on UNIX systems .................................................. 369

Chapter 11: Performing Administrative Operations

Changing the SharePlex password on UNIX systems ............................................................... 402

Performing system backups on systems running SharePlex...................................................... 412

Chapter 12: SharePlex Utilities

Using the SharePlex trigger scripts ............................................................................................426

About this manual

This manual provides instructions for:

Viewing this manual in PDF format

Conventions used in this manual

The following icons are used to highlight important or helpful information:

About Quest Software

Contact Quest Software

Contact Quest Support

This release of SharePlex includes the following new features:

1 Create the wallet directory if necessary. For instance, $ORACLE_BASE/admin/

4 Switch the log file:

3 Quiesce the source TDE tables.

6 Bring up SharePlex and re-activate immediately.

7 The source activity can be restarted.

For help on setting a value in the target configuration:

When the target is a table in Oracle:

Keyword Column type Default column name Description

Example with default column names:

Change Tracking Enhancements

Control changed from parameter to source configuration

Note: Since it is no longer being used, SP_OPO_TRACK_CHANGES has been depre-