Professional Documents
Culture Documents
SharePlex 7.6 Admin Guide
SharePlex 7.6 Admin Guide
For Oracle
Administrator’s Guide
Version 7.6
Quest® Software, Inc. © 2011 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 purchaser’s personal use without the written permission of Quest Software, Inc.
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
www.quest.com
email: legal@quest.com
Refer to our Web site for regional and international office information.
Warranty
The information contained in this document is subject to change without notice. Quest Software makes no
warranty of any kind with respect to this information. QUEST SOFTWARE SPECIFICALLY DISCLAIMS
THE IMPLIED WARRANTY OF THE MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. Quest Software shall not be liable for any direct, indirect, incidental, consequential, or other dam-
age alleged in connection with the furnishing or use of this information.
Trademarks
Quest, Quest Software, the Quest Software logo, and SharePlex®are trademarks and registered trademarks of
Quest Software, Inc in the United States of America and other countries. Other trademarks and registered
trademarks used in this guide are property of their respective owners.
World Headquarters
5 Polaris Way
Aliso Viejo, CA 92656
www.quest.com
e-mail: info@quest.com
CHAPTER 1 iii
Please refer to our Web site for regional and international office information.
Understanding synchronization.................................................................................................... 69
Configuring system resources for replication .............................................................................. 71
Configuring the database for replication...................................................................................... 74
Configuring the system for replication ...................................................................................... 102
Other implementation considerations ........................................................................................ 109
TABLE OF CONTENTS vii
Installing application patches and upgrades on systems running SharePlex ............................. 360
Installing SharePlex upgrades.................................................................................................... 369
Installing SharePlex patches ...................................................................................................... 369
Downloading SharePlex .tpm files for installs, upgrades, and patches ..................................... 369
Installing OS and Oracle patches on systems running SharePlex.............................................. 369
Migrating your Oracle database................................................................................................. 370
Part 2: Administering the SharePlex Oracle account
Glossary .......................................................................................................................................443
Index ..............................................................................................................................................463
xii SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
ABOUT THIS MANUAL xiii
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.
xiv SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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)
xvi SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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 xvii
Please refer to our web site for regional and international office information.
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
4 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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).
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 5
How SharePlex Works
For more information about the ways to establish replication for your database environ-
ment, see Chapter 4 and Chapter 5.
6 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
8 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 9
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.
10 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 11
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.
12 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
• 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.
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.
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.
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.
18 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
20 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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
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
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 23
Running the SharePlex Programs
• 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.
System startup
When you start systems that are involved in replication, start the components in this
order:
1 Start the system.
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
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 Oracle’s 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.
• If your database's character set is not using the default US7ASCII character set, you
must set the NLS_LANG environment variable to the database's setting before you
start SharePlex (sp_cop). This ensures that characters greater than 7F replicate cor-
rectly. Normally SharePlex detects the database’s setting and uses the correct set, but
setting the environment variable is a precaution in the event that SharePlex cannot
detect the database’s setting.
Warning! If the database is using the default US7ASCII character set, do not set
NLS_LANG, or characters greater than 7F will not replicate correctly.
CHAPTER 3 27
Running the SharePlex Programs
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.
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.
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 &
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 29
Running the SharePlex Programs
4 In the Port list box, select the port number for the instance of SharePlex that you
want to 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 434 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.
30 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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.
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.
32 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
4 In the Port list box, select the port number for the instance of SharePlex that you
want to shut down.
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 434 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 33
Running the SharePlex Programs
Any SharePlex user can run sp_ctrl, but in order to execute a command, a user must
have that command’s 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.
Or…
$ cd /productdir/bin
$ ./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-
34 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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
Or…
$ cd /productdir/bin
$ ./sp_ctrl
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.
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\SOFTWARE\Quest Soft-
ware\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 different port number than the default, start
sp_ctrl and use the port command to specify the alternative port number.
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
36 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 37
Running the SharePlex Programs
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
Or...
$ cd /productdir/bin
$ ./sp_cop -s &
FIGURE 5: The status of SharePlex processes after starting sp_cop with the -s option.
After you issue the startup command, you can stop individual replication processes as
needed.
The replication processes remain stopped when SharePlex starts until you issue the start
command for each process that you want to start.
CHAPTER 3 39
Running the SharePlex Programs
Syntax
sp_ctrl(sysA)> start {capture | read | export | import | post}
For more information about sp_ctrl commands, see the SharePlex Reference Manual.
40 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 41
Running the SharePlex Programs
Or...
$ cd /productdir/bin
$ ./sp_cop -uname &
42 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 43
Running the SharePlex Programs
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
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 241 for instructions on
setting the port numbers.
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.
44 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 directory’s
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
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.
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.
46 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
2 Double-click the SpUtils desktop shortcut to open the SharePlex Utilities dialog
box.
4 In the Port list box, select the port number for the instance of SharePlex that you
want to start.
6 When the Current State text box shows that the service has started, you can start
another instance of SharePlex.
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
48 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Version A Version B
/splex/VerA/prod_dirA /splex/VerB/prod_dirB
/splex/VerA/var_dirA /splex/VerB/var_dirB
CHAPTER 3 49
Running the SharePlex Programs
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.
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.
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).
4 Issue the set param command for the following SharePlex parameters.
sp_ctrl(sysA)> set param SP_COP_TPORT port number for Version A
5 Shut down and then restart sp_cop for the parameter changes to take effect.
sp_ctrl(sysA)> shutdown
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.
$ /splex/VerA/prod_dirA/bin/sp_cop -uVerA &
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
This section will help you decide which objects to include in your replication configura-
tion and which objects to exclude.
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-
56 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 57
Planning SharePlex Replication
• 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 the following character sets:
• US7ASCII
• WE8ISO8859P1
• UTF8
• AL32UTF8
• AL16UTF16
• KO16KSC5601 (Refer to the third bullet for restrictions on using this character set)
For other information regarding character sets, refer to the section on Character Sets
later in this chapter.
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.
58 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
• 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 table’s 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.
CHAPTER 4 59
Planning SharePlex Replication
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.
scott.emp bill.emp
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.
62 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
CHAPTER 4 63
Planning SharePlex Replication
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.
64 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
CHAPTER 4 65
Planning SharePlex Replication
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 63 and page 64) with high availability (see
page 62), 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.
66 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
CHAPTER 4 67
Planning SharePlex Replication
Peer-to-peer replication
sales.dat
cust.dat
mfg.dat
emp.dat
sales.dat sales.dat
cust.dat cust.dat
mfg.dat mfg.dat
emp.dat emp.dat
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.
CHAPTER 4 69
Planning SharePlex 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 227).
• 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 75).
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.
70 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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.
SHMBRK Sets the distance between private and shared data space
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.
The database can also be set so that Oracle will log the primary key columns of every
row modified, the key columns of a unique key for every row modified, or both. Share-
Plex will take advantage of the key information logged in the redo log when posting the
modifications on the target. If the key column values for a row update are not in the redo
log, then 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 performance. For this reason we recommend that both primary and unique key
supplemental logging be enabled.
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.
76 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Table structure
SharePlex supports replication between identical and non-identical target schemas,
depending on how replication is configured.
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.
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.
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.
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 row’s 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
80 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 89.
• 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 115 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 81 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 196.
value. For example, assume that the values in the following sample key column are
increased by 1:
Key_Col
1
4
5
7
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.)
update x set a=6 where a=5; (This will be successful.)
update x set a=8 where a=7; (This will be successful.)
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 191 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
82 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 values—such as a person’s
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 220 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 doesn’t 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 Post’s 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.
CHAPTER 4 83
Planning SharePlex Replication
• 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.
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 406.
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.
CHAPTER 4 85
Planning SharePlex Replication
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 violation—the 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 trigger’s
procedural statement that tells it to ignore operations posted by the SharePlex user.
For more information about this script, see page 406.
• 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-
86 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
• 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.
CHAPTER 4 87
Planning SharePlex 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-
88 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
CHAPTER 4 89
Planning SharePlex Replication
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.
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-
90 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
CHAPTER 4 91
Planning SharePlex Replication
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
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.
92 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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
94 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 Oracle’s 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
SharePlex Reference Manual.
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
database’s 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.
For more information about SharePlex parameters and the set param command, see the
SharePlex Reference Manual.
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 223 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.
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.
98 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Transaction size
Normally, Post performs an internal read/release after it receives each COMMIT, which
means it purges that transaction’s 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 12.
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.
CHAPTER 4 99
Planning SharePlex Replication
The default behavior for SharePlex is to bypass the Oracle character set conversion. You
do not need to set any parameters to archive this behavior.
100 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
To use the Oracle character set conversion, set the SP_OPO_CHARACTERSET param-
eter to the characterset of the source database. SharePlex uses these parameters to notify
Oracle what character set the data is encoded in. The SP_OPO_CHARACTERSET
parameter controls replication for regular character columns such as CHAR,
VARCHAR2 and CLOB.
Note: Shareplex will convert NVARCHAR and NCLOB data by default if the source data-
base’s NLS_NCHAR_CHARACTERSET is not the same as the target database’s
NLS_NCHAR_CHARACTERSET
.
Support for NCHAR, NVARCHAR and NCLOB was added in SharePlex 5.0. Before
version 5.0, a similar parameter, SP_OPO_NLS_LANG, controlled character set con-
version. Because support for NCHAR implies support for more than one character set,
additional parameters were created for SharePlex 5.0 and the parameter
SP_OPO_NLS_LANG is now depreciated.
For more information about these parameters, refer to the SharePlex Reference Guide.
1 In sp_ctrl on the source system and the target system, shut down SharePlex.
sp_ctrl(sysA)> shutdown
sp_ctrl(sysB)> shutdown
CHAPTER 4 101
Planning SharePlex Replication
2 On the source system and the target system, export the following environment vari-
able. AMERICAN_AMERICA must be in capital letters.
(ksh)
export NLS_LANG=AMERICAN_AMERICA.database_character_set
- or -
(csh)
setenv NLS_LANG AMERICAN_AMERICA.database_character_set
4 In sp_ctrl on the source system, set the following parameter using the source data-
base’s ORACLE_SID and character set. AMERICAN_AMERICA must be in capital
letters.
sp_ctrl(sysA)> set param sp_ord_nls_lang ORACLE_SID,
AMERICAN_AMERICA.database_character_set
5 In sp_ctrl on the source system, stop the Read process, then start it again. This acti-
vates the new parameter setting.
sp_ctrl(sysA)> stop read
6 In sp_ctrl on the target system, set the following parameter using the target data-
base’s ORACLE_SID and character set. AMERICAN_AMERICA must be in capital
letters.
sp_ctrl(sysB)> set param sp_opo_nls_lang
AMERICAN_AMERICA.database_character_set
7 In sp_ctrl on the target system, stop the Post process, then start it again. This acti-
vates the new parameter setting.
sp_ctrl(sysB)> stop post
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.
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.
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
104 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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
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.
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.
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.
CHAPTER 4 107
Planning SharePlex Replication
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
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)
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 Oracle’s 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.
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
CHAPTER 4 109
Planning SharePlex Replication
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.
All platforms
• the entire SharePlex product and variable-data directories
110 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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
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 system—the 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.
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.
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 system—the 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 want—to
replicate different tables at different times for example—but 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 54.
CHAPTER 5 115
Preparing for SharePlex Replication
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.
• 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’;
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).
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 119
Preparing for SharePlex Replication
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 .....
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 165.
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
table’s configuration entry.
• For horizontally partitioned replication (replication of selected rows) the routing
map is listed in a partition scheme, and the partition scheme’s name is the last com-
ponent of the table’s 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
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 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 123
Preparing for SharePlex Replication
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 159). This method permits a maximum of 25 queues per sp_cop instance,
which includes any named post queues (see page 135) and default queues that are
used by that instance of sp_cop.
• 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 124, 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 65 for a description and page 177 for information about establishing this strat-
egy.
• There is a limit of nine queues for AIX systems.
124 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 125
Preparing for SharePlex Replication
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
126 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 128 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 121.
CHAPTER 5 127
Preparing for SharePlex Replication
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.
128 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
* 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 121.
CHAPTER 5 129
Preparing for SharePlex Replication
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
130 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 131
Preparing for SharePlex Replication
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 135.
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.
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.
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. Substitute 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. Datasource is not case-sensitive. The 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 (.). 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
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.
!key (col_name, col_name)
CHAPTER 5 133
Preparing for SharePlex Replication
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:
* 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 121.
134 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 135
Preparing for SharePlex Replication
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. Substitute 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 these items. Datasource is not case-sensitive. The
SID is case-sensitive.
Datasource:o.SID
138 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
6 On the next line, type the owner and name of the first source object, separating them
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
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.
!key (col_name, col_name)
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.
11 To create additional named post queues for other objects, repeat steps 5 through 9
using a new queue name.
* 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 121.
CHAPTER 5 139
Preparing for SharePlex Replication
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.
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.
140 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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.
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
Chapter of the SharePlex Reference Guide.
• Use the compare command. For more information about this command, see
Chapter 1 of the SharePlex Reference Guide.
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.
CHAPTER 5 145
Preparing for SharePlex Replication
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
the sample table in Figure 10 on page 141 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 141 could be “West Coast employees” for
rows that are replicated to the company’s Western region.
3 In the TARGET_OWNER column, enter one of the following for the target table’s
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”.
5 In the ROUTE column, enter the SharePlex routing map* for this column condition.
* 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 121.
146 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
• 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
CHAPTER 5 147
Preparing for SharePlex Replication
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-
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.
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
148 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
Note: The entry on the second line is needed only if a route in a partition scheme does
not exist on a configuration line.
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
CHAPTER 5 149
Preparing for SharePlex Replication
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 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 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
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.
!key (col_name, col_name)
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
150 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
3 Type at least a few spaces or, if you are using tabs to maintain columns, tab to the
second or third column.
• 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.
* 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 121.
152 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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. Substitute 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 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 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 155
Preparing for SharePlex Replication
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)
156 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 table’s 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.
!key (col_name, col_name)
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
table’s 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 157
Preparing for SharePlex Replication
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.
* 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 121.
CHAPTER 5 159
Preparing for SharePlex Replication
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 161
Preparing for SharePlex Replication
Target machine Enter the name of the target machine, for example SystemA, then
press Enter. A target system’s 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.
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.
162 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 editor’s 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 163
Preparing for SharePlex Replication
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.
164 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Name of the Target Enter the name of the target machine, for example SystemA, then press
machine Enter. A target system’s 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 85.
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 editor’s standard save command.
CHAPTER 5 165
Preparing for SharePlex 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 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
A template for creating the appropriate configuration(s) for each strategy is provided.
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.
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.
• 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 387 for instructions.
• Before you synchronize data to begin replication, ensure that all data and system
issues have been addressed according to the guidelines in Chapter 4 for the tables
required for reports and queries.
168 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
• Install SharePlex in the normal manner. See the SharePlex Installation and Demon-
stration Guide for instructions.
• Run ora_setup for this instance. See page 387 for instructions.
• Before you synchronize data to begin replication, ensure that all data and system
issues have been addressed according to the guidelines in Chapter 4.
• Referring to Template 7 on page 166, create a configuration using this instance’s
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 154). If you are using horizontally parti-
tioned replication for a table, create partition schemes and use them in the routing
map (see page 140). Specify the local system’s name in the routing map.
CHAPTER 5 169
Preparing for SharePlex Replication
Replicating sequences for reporting is not necessary, so do not include them in this
configuration.
• Perform initial synchronization by making a copy of the source data, applying it to
the target tables, and activating the configuration. See Chapter 7 for an appropriate
procedure to follow.
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 171
Preparing for SharePlex Replication
remains in an activated state with the Export process on that system stopped in readiness
for failover.
• Install SharePlex and run ora_setup in the normal manner. See page 387 for instruc-
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 Chapter of the
SharePlex Reference Guide for more information about SharePlex commands and
parameters.
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 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 269) so that users can continue accessing the primary database.
• Maintain backups of replication files as recommended in “Regular SharePlex back-
ups” on page 109.
174 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
CHAPTER 5 177
Preparing for SharePlex Replication
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.
178 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
build the configuration (see page 159). Or, use the config.sql script to configure the
entire database (see page 163).
For Scenario B: Referring to Template 15 on page 179, 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 154). If you are using horizontally partitioned replication for a table, create
partition schemes and use them in the routing map (see page 140).
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.)
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.
On all 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 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.
182 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 128 for instructions
If you are using vertically partitioned replication for a table, include the column parti-
tion or excluded column partition (see page 154). If you are using horizontally parti-
tioned replication for a table, create partition schemes and use them in the routing map
(see page 140).
To establish replication, follow the instructions in “Establishing replication for data dis-
tribution or distributed processing” on page 174 and “Establishing replication through
an intermediary system” on page 177.
184 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 185
Preparing for SharePlex Replication
Depending on the system’s 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 187.
The following instructions are for consolidated replication using a single instance of
sp_cop.
The following configuration examples show two source systems, sysA and sysB, both
replicating to target system sysC.
not be replicated for reporting or archiving, so do not include them in the configura-
tions.
On all 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 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 187
Preparing for SharePlex Replication
The following configuration examples show two source systems, sysA and sysB, both
replicating to target system sysC.
• 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 42 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 all 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 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 191
Preparing for SharePlex Replication
• 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.
• 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;
and SysC) are used, but there could be more systems replicating among one another.
The following table is used in the example.
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 195
Preparing for SharePlex Replication
The primary key must be created to contain enough information about a row so there
can be no question about that row’s 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 193 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.
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.
seller example, when the first customer’s 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 user’s 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 customer’s purchase) minus the net change of 2.
The result of this procedure’s 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, CustomerA’s spouse makes a withdrawal of $250 on SysB,
and the application updates the database on that system to $1250. When CustomerA’s
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 spouse’s 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 201
Preparing for SharePlex Replication
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.
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.
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.
Example configuration
Datasource:o.oraA
sales.dat1 sales.dat2 sysB@o.oraB
CHAPTER 5 203
Preparing for SharePlex Replication
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.
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_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.
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.
208 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 209
Preparing for SharePlex Replication
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.
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.
210 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
Important! There can be only one conflict_resolution.SID file per active configuration.
CHAPTER 5 213
Preparing for SharePlex Replication
Refer to the following template as you follow the steps to create the file entries.
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...
214 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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 215
Preparing for SharePlex Replication
Important! If the database is using the default US7ASCII character set, do not set
NLS_LANG before starting SharePlex, or characters greater than 7F will not replicate
correctly.
If you followed these recommendations and still are experiencing replication problems
caused by invalid characters, use the !ControlExtendedCharSet routine for UPDATEs
and DELETEs. This routine converts replicated characters that fall into the extended
ASCII set (greater than 127) to a more standard format that Oracle will not misinterpret.
Then it re-executes the UPDATE or DELETE statement to resolve the conflict.
Characters in the extended ASCII set are usually not well defined. They tend to be spe-
cific to a country, application or operating system. On rare occasions, another platform
such as a Microsoft Windows application inserts these characters into the source data-
base, and Oracle misinterprets them. SharePlex replicates the characters to the target
CHAPTER 5 217
Preparing for SharePlex Replication
database. If Post subsequently needs to update or delete the affected row, it cannot find
it and returns an error.
When using !ControlExtendedCharSet, list it first among other routines for UPDATE
and DELETE statements to set it as first priority. Its name is case sensitive. Type it
exactly as shown in these instructions, with no spaces. Do not list the procedure owner
name with this routine in the configuration file.
Example conflict resolution file using !ControlExtendedCharSet
owner.table1 u !ControlExtendedCharSet
owner.table1 u owner.procedure_up_A
owner.table1 u owner.procedure_up_B
!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
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
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.
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 221
SharePlex Optional Setup
2 On the target system, change directories to the data sub-directory of the SharePlex
variable-data directory.
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.
9 When you are finished, save and close the file using :wq command in vi or Save on
the File menu in WordPad.
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 table’s 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.
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.
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:
10 + (peak number of concurrent transactions x 2) = minimum open cursors
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:
10 + (peak number of concurrent transactions x 7) = minimum open cursors
needed
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 12.
226 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 404.
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 person’s 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 112.
• Create transformation routine(s) using the instructions on page 231.
• Create entries for those routines in the transformation.SID file using the instructions
on page 237.
For more information about high-availability replication, see “Establishing replication for
high availability and data recovery” on page 170. For more information about peer-to-
peer replication, see “Establishing peer-to-peer replication” on page 191.
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 229
SharePlex Optional Setup
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
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.
230 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 company’s
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 204. 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 231
SharePlex Optional Setup
more information. This issue does not affect replication; SharePlex supports tables
with identical owner and table names.
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 233
SharePlex Optional Setup
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.
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."
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
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.
236 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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 239
SharePlex Optional Setup
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.
For more information about the SharePlex marker file, see “The SharePlex directories”
on page 15. For more information about installing SharePlex on clustered systems, see
the SharePlex Installation and Demonstration Guide.
CHAPTER 6 241
SharePlex Optional Setup
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 243
SharePlex Optional Setup
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.
sp_ctrl(sysB)> start post
13 [ACTIVE CONFIGURATIONS ONLY] Verify that all SharePlex processes on the source and tar-
get systems are running.
sp_ctrl> status
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.
244 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
4 In the Port list box, select the port number for the instance of SharePlex whose port
you want to change.
8 In the Run dialog box, type regedit to open the Registry Editor.
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.
246 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
16 Double-click the SpUtils desktop shortcut to open the SharePlex Utilities dialog
box again.
CHAPTER 6 247
SharePlex Optional Setup
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.
2 In the Run dialog box, type regedit, then click OK to run the Registry Editor pro-
gram.
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.
• 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.
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
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.
LocalSys.xyzcompany.com
system1.xyzcompany.com
system2.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.
252 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
Note: SSH is not included with Shareplex and must be purchased separately.
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.)
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.
254 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
• 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
$ /productdir/bin/sp_cop &
Or...
• [TO ACTIVATE A CONFIGURATION] Activate the replication configuration.
sp_ctrl(sysA)> activate config filename
CHAPTER 6 255
SharePlex Optional Setup
This section includes other features that allow you to customize SharePlex to your
needs.
3 Click the Services sub-node, then scroll in the pane on the right to locate the Share-
Plex service.
CHAPTER 6 257
SharePlex Optional Setup
4 Right-click the SharePlex service, then select Properties. This opens a SharePlex
Properties dialog box.
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.
258 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
8 In the Log on as option box, click This account, then click Browse to open the
Select User dialog box.
CHAPTER 6 259
SharePlex Optional Setup
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.
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.
CHAPTER 6 261
SharePlex Optional Setup
5 The system prompts for verification. Click either Yes to implement the change or No
to cancel it.
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\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-
262 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
gram, using the following instructions. Any change to the environment requires
restarting the SharePlex service to take effect.
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 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.
3 In the Run dialog box, type regedit to run the Registry Editor.
CHAPTER 6 263
SharePlex Optional Setup
5 In the Name column of the pane on the right, replace the highlighted new string with
the SharePlex variable name.
6 Right-click the new string, which now bears the variable’s name, then select Modify.
The Edit String dialog box appears.
7 In the Value data field of the Edit String dialog box, type the variable’s character
string.
3 In the Run dialog box, type regedit to run the Registry Editor.
5 In the pane on the right, right-click the variable to be changed and select Modify.
CHAPTER 6 265
SharePlex Optional Setup
6 In the Value Data field of the Edit String dialog box, enter the new string.
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
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 289 to familiarize yourself with configuration activation
options.
CHAPTER 7 269
Starting SharePlex Replication
Important! Before beginning this procedure, have your configuration(s) ready to be acti-
vated.
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.
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.
sp_ctrl(sysB)> stop post
7 When the backup is finished, activate the configuration on the source system.
sp_ctrl(sysA)> activate config filename
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 271
Starting SharePlex Replication
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.
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
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 415.
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.
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.
sp_ctrl(sysB)> start post
21 [OPTIONAL] If this was only a partial backup, drop the tablespaces that were not copied
over during the hot backup.
1 [UNIX SYSTEMS] Verify that the ORACLE_SID and ORACLE_HOME in the oratab file
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.
3 On all systems, go to the bin sub-directory of the SharePlex product directory, and
start sp_cop and sp_ctrl.
sp_ctrl(sysB)> status
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(sysB)> stop post
7 After the backup is finished, activate the configuration on the source system.
sp_ctrl(sysA)> activate config filename
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
9 After activation is complete, switch log files on the source system and make a note of
the highest archive-log sequence number.
svrmgrl> alter system switch logfile;
274 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest seq
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 415.
16 On the intermediary system, disable cascading deletes, check constraints, and sched-
uled jobs that perform DML.
18 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
titioned replication for any tables, delete the unneeded columns and rows from those
tables on the intermediary system.
CHAPTER 7 275
Starting SharePlex Replication
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 415.
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.
25 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
titioned replication for any tables, delete the unneeded columns and rows from those
tables on the target system.
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(sysB)> start post
29 [OPTIONAL] If this was only a partial backup, drop the tablespaces that were not copied
over during the hot backup.
CHAPTER 7 277
Starting SharePlex Replication
Important! Before beginning this procedure, have your configuration(s) ready to be acti-
vated.
2 On the source system, install SharePlex and run ora_setup according to the instruc-
tions in the SharePlex Installation and Demonstration Guide.
278 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
3 On the intermediary and target systems, install SharePlex, but do not run ora_setup.
You will do this after the 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.
svrmgrl> alter system switch logfile;
7 On all systems, start sp_cop and sp_ctrl from the bin sub-directory of the SharePlex
product directory.
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.
sp_ctrl(sysB)> stop post
10 On the source system, activate the configuration using default multi-threaded activa-
tion.
sp_ctrl(sysA)> activate config filename
11 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
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.
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”
CHAPTER 7 279
Starting SharePlex Replication
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
SharePlex Installation and Demonstration Guide.
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 415.
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.
20 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
titioned replication for any tables, delete the unneeded columns and rows from those
tables on the intermediary and target systems.
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.
sp_ctrl(sysB)> start post
24 [OPTIONAL] If this was only a partial backup, drop the tablespaces that were not copied
over during the hot backup.
280 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Important! Before beginning this procedure, have your configuration(s) ready to be acti-
vated.
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 291 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.
sp_ctrl(sysA)> activate config filename
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.
CHAPTER 7 281
Starting SharePlex Replication
• 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-
tem’s 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.
sp_ctrl(sysB)> stop post
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.
sp_ctrl(sysA)> status
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.
ing replication). For peer-to-peer replication, all cascading delete functionality must
be incorporated into triggers on all replication systems.
12 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
titioned replication for any tables, delete the unneeded columns and rows from those
tables.
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.
sp_ctrl(sysB)> activate config filename
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.
sp_ctrl(sysB)> start post
18 [PEER-TO-PEER REPLICATION ONLY] Allow users to access the databases on all systems.
CHAPTER 7 283
Starting SharePlex Replication
Important! Before beginning this procedure, have your configuration ready to be acti-
vated on the source system.
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.
5 Activate the configuration on the source system. See page 291 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.
sp_ctrl(sysA)> activate config filename
6 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.
284 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
• 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-
tem’s data.
7 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.
sp_ctrl(sysB)> stop post
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.
sp_ctrl(sysA)> status
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).
13 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-
ing replication. For peer-to-peer replication, all cascading delete functionality must
be incorporated into triggers on all replication systems.
14 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
titioned replication for any tables, delete the unneeded columns and rows from those
tables.
18 [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.
sp_ctrl(sysB)> activate config filename
19 Start Post on the target system(s), intermediary system (cascading replication) or all
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.
sp_ctrl(sysB)> start post
20 [PEER-TO-PEER REPLICATION ONLY] Allow users to access the databases on all systems.
286 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Important! Before beginning this procedure, have your configuration(s) ready to be acti-
vated.
1 Set the source tablespace to READ ONLY (alter tablespace TRANS read only;).
2 Activate the configuration on the source system. See page 291 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.
sp_ctrl(sysA)> activate config filename
3 Start sp_cop and sp_ctrl on the target system(s) and the intermediary system, if
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 system’s data.
4 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.
CHAPTER 7 287
Starting SharePlex Replication
Stopping Post allows any data that gets replicated before the target data is established
to collect in the post queue.
sp_ctrl(sysB)> stop post
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.
ing replication. For peer-to-peer replication, all cascading delete functionality must
be incorporated into triggers on all replication systems.
15 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
titioned replication for any tables, delete the unneeded columns and rows from those
tables.
19 [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.
sp_ctrl(sysB)> activate config filename
20 Start Post on the target system(s), intermediary system (cascading replication) or all
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.
sp_ctrl(sysB)> start post
21 [PEER-TO-PEER REPLICATION ONLY] Allow users to access the databases on all systems.
CHAPTER 7 289
Starting SharePlex Replication
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.
Important! Before you use the activate config command, review that command and the
other configuration commands in the SharePlex Reference Manual.
290 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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
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.
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 117 for information on using Oracle wildcards.
294 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
2 In sp_ctrl, issue the copy config command. Substitute the original configuration’s
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 table’s 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
2 In sp_ctrl, issue the copy config command. Substitute the original configuration’s
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 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
5 Save the new configuration with either the :wq command if using vi or with Save on
the File menu if using WordPad.
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
7 In sp_ctrl, issue the activate config command for the new configuration.
sp_ctrl(sysA)> activate config newname
296 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
2 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
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
4 Save the new configuration with either the :wq command if using vi or with Save on
the File menu if using WordPad.
5 In sp_ctrl, issue the activate config command for the new configuration.
sp_ctrl(sysA)> activate config newname
6 On the source system, flush the data from source system to the target system. This
command stops Post and places a marker in the data stream that establishes a syn-
chronization point between source and target data. For datasource in the following
CHAPTER 7 297
Starting SharePlex Replication
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.
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.
298 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 configuration’s
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. Do not
deactivate the original configuration.
sp_ctrl(sysA)> copy config filename to newname
2 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
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 117 for information on using Oracle wildcards.).
4 Save the new configuration with either the :wq command if using vi, or with Save on
the File menu if using WordPad.
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 170 for instructions for establishing
SharePlex replication in a high-availability environment.
Contents
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 303
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.
304 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 &
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.
sp_ctrl(sysA)> deactivate config filename
Note: The delete queue command will fail if there are messages in backlog.
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.
9 Start the Export process on the secondary system. This establishes communication
between the primary and secondary systems.
sp_ctrl(sysB)> start export
• 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.
306 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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]
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.
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
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 Capture’s 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.
308 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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
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.
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
• foreign key constraints
CHAPTER 8 309
Using SharePlex in a High-Availability Environment
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.
sp_ctrl(sysA)> qstatus
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.
sp_ctrl(sysB)> stop export
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
310 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
This procedure is divided into phases to make it easier to understand and follow.
Note: The deactivation causes an error: “Error in sp_cnc.” in the Event Log. You may
ignore it and continue with the procedure.
3 On the primary system, use the syntax provided in the following example to issue
the delete queue command to delete the post queue.
Note: The delete queue command will fail if there are messages in backlog.
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.
6 On the secondary system, 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.
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.
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.
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.
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(sysA)> reconcile queue SysA for o.oraA-o.oraA [seq 1234]
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.
sp_ctrl(sysB)> stop export
15 Start the Post process on the secondary system to start posting replicated data from
the primary system.
sp_ctrl(sysB)> start post
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
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.
sp_ctrl(sysA)> flush datasource
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.)
sp_ctrl(sysB)> status
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.
sp_ctrl(sysA)> qstatus
sp_ctrl(sysB)> qstatus
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
8 Run the script that grants INSERT, UPDATE and DELETE access to all users on the
secondary system.
9 Run the script that enables triggers and constraints on the secondary system when
users begin using this system.
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.
Note: The sequence on the primary system is now at the top of the cache.
• check constraints
• scheduled jobs that perform DML
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.
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.
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.
sp_ctrl(sysA)> status
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.
sp_ctrl(sysA)> qstatus
sp_ctrl(sysB)> qstatus
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 317
Using SharePlex in a High-Availability Environment
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.
14 Run the script that grants INSERT, UPDATE and DELETE access to all users on the
primary system.
15 Run the script that enables triggers and constraints on the primary system when
users begin using this system.
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.
sp_ctrl(sysA)> stop export
20 Stop Export on the secondary system. This prevents accidental DML that might
occur on that system from replicating to the primary system.
sp_ctrl(sysB)> stop export
318 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
22 Start Post on the secondary system so that replicated changes from the primary sys-
tem begin posting to the secondary database.
sp_ctrl(sysB)> start post
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
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.
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 323
Unattended SharePlex Monitoring
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.
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 325
Unattended SharePlex Monitoring
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.
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 327
Unattended SharePlex Monitoring
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.
330 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
* A message typically is a SQL operation or an internal SharePlex operation. For more information about messages,
see page 12.
334 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
2 Add the address strings after the MailUserName= variable. Use the full e-mail and/or
pager address. You can specify as many addresses as you want. Separate multiple
entries with a space, 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.
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 335
Unattended SharePlex Monitoring
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:
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.
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).
338 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Tip: You can change the default text editor for SpClient in the Windows Registry. The
entry name is HKEY_LOCAL_MACHINE\SOFTWARE\Quest Software\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.
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 queue’s 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 queue’s
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
* A message typically is a SQL operation or an internal SharePlex operation. For more information about messages,
see page 12.
340 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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.
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.
342 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Contents
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 54.
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 351.
2 Copy the active configuration, but do not deactivate it. Use the show config or list
config command if you are unsure of the name. Make a note of the name, because
you will need it later.
sp_ctrl(sysA)> copy config filename to newname
4 Locate the line containing the table to which you are adding the LOB column, and
use a pound symbol (#) to comment it out of the file, as shown in the following
example.
# scott.emp scott.emp sysB@o.oraB
5 Save the new configuration file with the :wq command if using vi, or with Save on
the File menu if using WordPad.
6 Stop user access to the table to which you are adding the LOB column.
7 Activate the new configuration. You are warned that this configuration deactivates
the one that is active. Proceed with the activation, which removes the table from rep-
lication.
sp_ctrl(sysA)> activate config newname
9 Activate the original configuration, which includes the uncommented entry for the
table. You are warned that this configuration deactivates the one that is active. Pro-
ceed with the activation, which commences replication for the table again. The only
object that is locked is the table to which you added the LOB column.
sp_ctrl(sysA)> activate config filename
10 Grant users access to the table to which you added the LOB column.
Important! Enabling row movement on tables that contain LOBs is not supported.
ALTER TABLE...RENAME TO
To rename a table in an active configuration, use one of the following procedures,
depending on whether you are renaming a source table or a target table.
2 Copy the active configuration, but do not deactivate it. Use the show config or list
config command if you are unsure of the name.
sp_ctrl(sysA)> copy config filename to newname
3 Open the new configuration using the edit config command. This command opens
the configuration file in the default text editor for SharePlex (vi for UNIX, WordPad
for Windows).
sp_ctrl(sysA)> edit config newname
4 Edit the new configuration to change the name of the source table.
5 Save the new configuration with either the :wq command if using vi or with Save on
the File menu if using WordPad.
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 Edit the new configuration to change the name of the source table (if needed) and the
target table in the file.
5 Save the new configuration with either the :wq command if using vi or with Save on
the File menu if using WordPad.
6 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 database’s
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.
sp_ctrl(sysA)> flush datasource
9 When Post stops from the flush, rename the target table.
10 Start Post.
350 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
CREATE TABLE
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-
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.
Tip: If you are using Oracle wildcards and the table that you are adding is covered by the
Oracle wildcard specification in the configuration file, it is not necessary to add the table
to the config file. When the config file is reactivated, any new objects that match the crite-
ria are added into replication. See page 117 for information on using Oracle wildcards.
2 [PARTITIONED REPLICATION ONLY] If you are using vertically partitioned or horizontally par-
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.
sp_ctrl(sysA)> copy config filename to newname
5 Edit the new configuration to add the new table’s owner and name, target table and
routing information.
sp_ctrl(sysA)> edit config newname
6 Save the new configuration file with the :wq command if using vi, or with Save on
the File menu if using WordPad.
CHAPTER 10 351
Changing Oracle Characteristics Of Replicated Objects
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.
sp_ctrl(sysA)> activate config newname
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 database’s
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.
sp_ctrl(sysA)> flush datasource
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.
sp_ctrl(sysA)> activate config filename
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.
352 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
sp_ctrl(sysA)> activate config filename
9 Start Post on all target systems. SharePlex resumes replication from where it
stopped, and the data remains synchronized.
sp_ctrl(sysB)> start post
CHAPTER 10 353
Changing Oracle Characteristics Of Replicated Objects
This part of the chapter provides procedures for making other, non-DDL changes to the
database while replication is active.
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.
354 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
sp_ctrl(sysA)> copy config filename to newname
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.
sp_ctrl(sysA)> edit config newname
4 Save the configuration (use :wq in vi or Save on the File menu in WordPad), but do
not reactivate it yet.
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
database’s ORACLE_SID — for example o.oraA. This command stops the Post pro-
cess and establishes a synchronization point between the source and target databases.
sp_ctrl(sysA)> flush datasource
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.
sp_ctrl(sysA)> activate config newname
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.
sp_ctrl(sysB)> status
10 After Post stops, shut down the target database and rename the ORACLE_SID.
CHAPTER 10 355
Changing Oracle Characteristics Of Replicated Objects
Contents
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.
362 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
sp_ctrl(sysA)> flush datasource
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.
364 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 362. page 362.
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 85.
sp_ctrl(sysB)> start post
7 [PARTITIONED REPLICATION ONLY] Perform all
appropriate operations as recommended in
“Applying patches or upgrades when using
partitioned replication” on page 362.
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.
sp_ctrl(sysA)> flush datasource
6 On the source system, do any of the following that applies to the results of the patch
or upgrade:
Affected objects for which you are See “Applying patches or upgrades when
using partitioned replication. using partitioned replication” on page 362 for
more information.
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.
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.
For example, if you are replicating from instance oraA on SysA to oraA on SysB, the
reconcile syntax would be:
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
• foreign key constraints
• cascading delete constraints
• check constraints
• scheduled jobs that perform DML
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.
368 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
8 Start the Post process on the target system. The two instances are now in synchroni-
zation, and SharePlex resumes replication.
sp_ctrl(sysB)> start post
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.
sp_ctrl(sysA)> flush datasource
3 Apply the patch or upgrade on the source system. The changes are replicated to the
target system.
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.
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 371
Performing Administrative Operations
3 Install Shareplex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
5 Stop Post.
sp_ctrl(sysB)> stop post
6 In sp_ctrl on the target system, issue the shutdown command to shut down Share-
Plex.
sp_ctrl(sysB)> shutdown
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
Demonstration Guide.
372 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
9 Stop user access to the source database by shutting it down and opening it in
restricted mode.
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 415.
17 Disable triggers on the tables, or run the sp_add_trigger.sql utility script (found on
page 407) so that the triggers ignore the SharePlex user.
18 Disable cascading deletes, check constraints, and scheduled jobs that perform DML.
19 Stop Export.
sp_ctrl(sysB)> stop export
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 373
Performing Administrative Operations
On TARGET machine
1 Install Oracle 10g/11g and create a 10g/11g database. Refer to your Oracle documen-
tation for instructions.
3 Install Shareplex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
5 Stop Post.
sp_ctrl(sysB)> stop post
6 In sp_ctrl on the target system issue the shutdown command to shut down Share-
Plex.
sp_ctrl(sysB)> shutdown
On SOURCE machine
7 Install Shareplex on the source if it is not already installed. Refer to the SharePlex
Installation Guide for instructions.
11 Switch log files on the source system and note the number of the new archive-log
file. Continue with step 12.
svrmgrl> alter system switch logfile;
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.
On TARGET machine
16 Import the data using the export file from the intermediary server.
17 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.
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.
sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest seq
sequence_number
20 Run the cleanup.sql script to truncate all of the SharePlex internal tables. Instruc-
tions for running this script are on page 415.
21 Disable triggers on the tables, or run the sp_add_trigger.sql utility script (found on
page 407) so that the triggers ignore the SharePlex user.
22 Disable cascading deletes, check constraints, and scheduled jobs that perform DML.
CHAPTER 11 375
Performing Administrative Operations
23 Stop Export.
sp_ctrl(sysB)> stop export
25 Start the Post process. The two instances are now in synchronization, and SharePlex
will continue replicating to maintain synchronization.
sp_ctrl(sysB)> Start post
376 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
On TARGET machine
1 Install Oracle 9i (if not already installed), create the database, and then start it.
3 Install SharePlex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
4 Start Shareplex.
5 Stop Post.
sp_ctrl(sysB)> stop post
6 Stop Shareplex.
On SOURCE machine
7 Install Shareplex on the source system if it is not already installed. Refer to the
SharePlex Installation and Demonstration Guide for instructions.
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.
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 377
Performing Administrative Operations
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.
17 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.
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
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.
sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest seq
sequence_number
20 Run the cleanup.sql script to truncate all of the SharePlex internal tables. Instruc-
tions for running this script are on page 415.
21 Disable triggers on the tables, or run the sp_add_trigger.sql utility script (found on
page 407) so that the triggers ignore the SharePlex user.
22 Disable cascading deletes, check constraints, and scheduled jobs that perform DML.
23 Stop Export.
sp_ctrl(sysB)> stop export
25 Start the Post process. The two instances are now in synchronization, and SharePlex
will continue replicating to maintain synchronization.
sp_ctrl(sysB)> start post
378 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
CHAPTER 11 379
Performing Administrative Operations
On TARGET machine
1 Install Oracle 9i.
3 Install SharePlex, following the instructions in the SharePlex Installation and Dem-
onstration Guide.
5 Stop Post.
sp_ctrl(sysB)> stop post
6 In sp_ctrl on the target system, issue the shutdown command to shut down Share-
Plex.
sp_ctrl(sysB)> shutdown
On SOURCE machine
7 Install Shareplex on the source system 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
Demonstration Guide.
9 Start sp_cop.
10 Stop Export.
sp_ctrl(sysA)> stop export
13 Switch log files on the source system and note the number of the new archive log
file. Continue with step 14.
svrmgrl> alter system switch logfile;
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.
17 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.
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 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.
sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest seq
sequence_number
20 Run the cleanup.sql script to truncate all of the SharePlex internal tables. Instruc-
tions for running this script are on page 415.
21 Disable triggers on the tables, or run the sp_add_trigger.sql utility script (found on
page 407) so that the triggers ignore the SharePlex user.
22 Disable cascading deletes, check constraints, and scheduled jobs that perform DML.
23 Stop Export.
sp_ctrl(sysB)> stop export
CHAPTER 11 381
Performing Administrative Operations
25 Start the Post process. The two instances are now in synchronization, and SharePlex
will continue replicating to maintain synchronization.
sp_ctrl(sysB)> start post
382 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 386.
CHAPTER 11 383
Performing Administrative Operations
To run ora_chpwd
1 Verify the Oracle_SID by viewing the oratab file.
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.
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 user’s envi-
ronment and displays that user’s 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.
384 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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: $
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.
386 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 387. Before you run ora_setup,
read the following directions.
2 After you run ora_setup, but before you start sp_cop again, copy the existing
SharePlex database objects from the previous user’s 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.
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:
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:
388 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 389
Performing Administrative Operations
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 user’s schema to the new SharePlex user’s 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:
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:
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.
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 user’s schema to the new SharePlex user’s 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:
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.
sp_ctrl(sysB)> start post
CHAPTER 11 393
Performing Administrative Operations
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.
sp_ctrl(sysA)> flush datasource
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.
sp_ctrl(sysA)> shutdown
5 Shut down the network and the Oracle instance 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.
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.)
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 395
Performing Administrative Operations
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.
396 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
The uninstall program also contains a custom uninstall option that enables you to selec-
tively remove files.
• 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.
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.
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.
Automatic uninstall
In the Perform Uninstall dialog box, click Finish to complete the uninstall, or click
Back to perform a custom uninstall.
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.
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 401
Performing Administrative Operations
• 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.
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.
402 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Important! If you intend to reinstall SharePlex or MKS Toolkit, it will not reinstall unless
these Registry entries are removed.
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 System Administrator for assistance.
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
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.
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
3 In one transaction, make the changes to the database that you do not want replicated.
They will be ignored by Capture.
For more information about the effects of triggers on replication, see “Triggers” on
page 85.
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 407
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 386.
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
408 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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 411
SharePlex Utilities
Note: If you do not select a queue, qview returns this error message: que_NOEXIST:
Queue does not exist.
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
412 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Tip: To truncate only the SharePlex tables without removing the files in the variable-data
directory, use the cleanup.sql script (see page 415). To completely restore SharePlex to
an initial state by removing the SharePlex files and truncating the SharePlex tables, use
ora_cleansp (see page 419).
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
414 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
in the proddir/data/defaults.yaml file, where the proddir is where the script was
invoked from.
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 415
SharePlex Utilities
Tip: To remove only the SharePlex files in the variable-data directory, use the
clean_vardir.sh script (see page 413). To completely restore SharePlex to an initial
state by removing the SharePlex files and truncating the SharePlex tables, use
ora_cleansp (see page 419).
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.
416 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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:
If the socket test is not successful the socket_test client will display the following:
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 419
SharePlex Utilities
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
sub-directory of the SharePlex product directory.
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.
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.
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 421
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
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.
$ ./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.
422 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Note: The utility might generate an error message stating that it cannot remove the .../
save_SharePlex_version directory. You can remove this directory.
Or...
Navigate to the bin sub-directory of the SharePlex product directory, then double-
click the SpUtils program icon.
CHAPTER 12 423
SharePlex Utilities
3 In the Port list box, select the port number for the instance of SharePlex for which
you are running OraCleanSp.
• 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.
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.
Windows systems
On Windows systems, one utility handles all of the licensing functions for SharePlex.
See page 427.
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
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.
5 Select the q option to exit the script.
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
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 427
SharePlex Utilities
To run SpUtils
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.
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.
428 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 429
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 ONLY—MUST 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.
430 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Or...
Click the Start button on the Windows taskbar, then select Programs and navigate to
SpUtils in the SharePlex programs group. The SharePlex Utilities dialog box appears.
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).
434 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 435
SharePlex Utilities
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 336.
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 does not enter the Event Log. To save a session’s 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...
CHAPTER 12 437
SharePlex Utilities
• Use Windows Explorer to navigate to the bin sub-directory of the SharePlex product
directory. Double-click the SpClient program.
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).
438 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Remot
e
Logon
number for SpClient (2101) or enter a different port number where SpClient was
installed on that machine.
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
440 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
SpTaskMngr
button
CHAPTER 12 441
SharePlex Utilities
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.
442 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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
ALTER TABLE A DDL command that changes a table’s 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.
444 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
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.
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.
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 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-
tion’s data intended for use by an individual department or group of users.
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.
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 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.
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.
high availability The ability to continue normal operations despite the requirements to be
“down” for planned computer maintenance.
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 447
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 row’s key; without an index, the entire table must be
scanned by Oracle and SharePlex. Adding an index greatly speeds replica-
tion processing.
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.
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.
448 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 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.
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.
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 449
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.
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.
450 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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
machine’s name and the ORACLE_SID of the target instance.
Row ID map An internal table that SharePlex maintains to keep track of chained rows in a
table.
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 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 statement One or more SQL commands and qualifying clauses that tell Oracle exactly
what the user wants to do.
GLOSSARY 451
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.
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.
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.
452 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
454 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 455
Third Party Licensing
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.
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 457
Third Party Licensing
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:
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.
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 459
Third Party Licensing
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.
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
460 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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 461
Third Party Licensing
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:
462 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
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.
Index
Symbols
/etc/group file 27
/etc/services file 110
& argument 27, 44
adding
LOB column 346
named queues
export 130
post 135
partition schemes and conditions 300
primary key 80
sequences to replication 295
SharePlex license key 424
table
to replication 293
to the database 350
unique index 80
Administrator, SharePlex
authority to
create configurations 112
set port number 241
start SharePlex 26
specifying startup authority on Windows systems 257
alerts
monitoring scripts (UNIX) 320
monitoring utility (Windows) 336
ALTER TABLE command
ENABLE ROW MOVEMENT 347
MOVE table clause 347
RENAME TO 90, 348
to add a LOB column 346
application patches and upgrades 360
app-modules directory
UNIX systems 16
archive logging, considerations for replication 93
ASM 93
asynchronous transport 8
auth_hosts file 250
authorization level
SharePlex commands 33
starting SharePlex 26
Index 465
backups
full system 393
Oracle hot backup
on active source database 269
on quiet database 277
partial system 392
SharePlex 109
bandwidth for SharePlex 108
batch loads 92
bi-directional replication
description 62
establishing for
high availability 170
peer-to-peer replication 191
bin directory
UNIX systems 15
bin sub-directory 437
Windows systems 17
binaries
location 11
running 22
broadcast replication
establishing 174–183
using for
distributing data 63
distributing processing and balancing loads 64
buffer size 98
build_config.sql script 159
capture queue
description 8
monitoring 333, 336
cascading deletes, considerations for replication 83
cascading replication
description 65
establishing 177
case-sensitivity, in configuration 116–119
centralized reporting
description 66
establishing 184–190
changes, how applied by SharePlex 12
changing
configurations 293
data instead of posting 227
key values 80
location of ORACLE_HOME 353
OPEN_CURSORS 96
process priority on Windows systems 259
replicating objects 346
SharePlex password on UNIX systems 382
SharePlex Registry entries 261
SharePlex startup on Windows systems 255
SharePlex text editor 248
SharePlex user in trigger WHEN clause 407
SharePlex user name 386
target objects 78
target ORACLE_SID 354
transformation file 239
character sets
establishing 26, 98
supported by SharePlex 98
verifying 100
check constraints, performance issues 84
checkpoint
in redo logs 14
recovery system 8
cleanup.sql script 415
clean_vardir.sh script 413
Index 467
clusters
routing maps for 122
setting SP_SYS_VARDIR for 240
collectors
in partitioned replication 140
planning for replication 87
column conditions
changing 300
creating 143
description 141
supported datatypes and syntax 146
viewing 151
column partition
excluded column partition 154, 155
column-level replication
changing 300
configuring 152
description 112
columns
adding LOB 346
in horizontally partitioned replication 146
requirements for replication 76
selective replication of 152
468 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
commands, SharePlex
authorization levels 33
getting scroll bar for output 34
issuing from
remote system 34
sp_ctrl, interactively 34
UNIX command line 33
maximum string length 33
to use for
activating configurations 289
connecting to alternate sp_cop 34
copying configurations 293
creating configurations 115
deactivating replication 292
defining default system 35
editing a configuration 159
shutting down replication 31
stopping a replication process 30
viewing activation status 292
viewing configuration statistics 292
viewing queue status 134
viewing replication processes 134
see also SharePlex Reference Manual
COMMIT statement
and Post read/release 98
and replication 13
and tuning log buffer size 98
comparing tables for synchronization 78
compression of archive logs 93
condition, column
changing 300
creating 143
description 141
supported datatypes and syntax 146
viewing 151
config directory
UNIX systems 16
config sql script 163
config sub-directory
description 6
Windows systems 18
Index 469
configurations
activation
description 289
statistics for 292
adding objects
sequences 295
tables 293
change marker for 290
changing 293
components of 115
creating for
data distribution 174
distributed processing 174
faster posting 135
high availability and data recovery 170
multiple targets 128
peer-to-peer replication 202
replication through intermediary system 177
reporting 166
selective column replication 152
selective row replication 140
deactivating 292
description 6
in cluster environments 122
information in internal tables 14
methods for creating
basic 125
multiple targets 128
quick-build for entire database 163
quick-build for multiple tables in a schema 159
separating data with named export queues 130
removing configured objects 299
renaming objects in
source table 348
target table 348
reverse configuration 172
troubleshooting, see SharePlex Administrator’s Guide
470 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
configuring
database for replication 74
objects for replication 112
system for replication 102
using Oracle wildcards 117
conflict resolution
description 191
connection
security with auth_hosts file 250
terminating from remote system 439
to sp_cop 32
consolidated replication
description 66
establishing 184–190
constraints, integrity 83
converting data during replication 227
CPU
requirements for replication 104
create config command 125, 248
CREATE TABLE command 350
create_ignore.sql utility 404
creating
column partitions 154
configurations 112
using Oracle wildcards 117
multiple variable-data directories 42
named queues
export 130
post 135
partition schemes and conditions 141
SharePlex Oracle user
on UNIX 387
on Windows systems 390
simulated key 114, 120
transformation components 231
unique index in absence of primary keys 80
See also defining
crontab 320
cursors, setting 96
Index 471
data
changing what is replicated 293
configuring for replication 112
converting during replication 227
directory in product directory
Windows 17
directory in variable-data directory
Windows 18
distribution
description 63
establishing replication for 174
guidelines for replication 69
integrity assurance 69
preventing from replicating 404
recovery
description 62
establishing replication for 170
planned failover procedures 314
unplanned failover procedures 302
strategies for replication 59
warehousing/mart
description 66
establishing replication for 184–190
data directory
UNIX systems 15, 16
Data Focus 20
database
changing
during replication 345
SharePlex password 382
SharePlex user (UNIX) 386
configuring for replication 74
creating SharePlex account
UNIX 387
Windows 390
Oracle supplemental logging 74
patches and upgrades
application 360
Oracle 369
472 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
datafiles
location of 103
on raw devices 93
datasource
description 115
multiple replicating, separating 130
datatypes
abstract
guidelines for replicating 87
converting through transformation 227
in SHAREPLEX_PARTITION table 144
in source and target columns 69, 77
large, in named queues 114
LOB, replication requirements 87
object-relational 87
supported for horizontal partitioning 146
user-defined
guidelines for replicating 87
dates, replicating 102
db directory
UNIX systems 16
db sub-directory
Windows systems 18
DDL
changes to target objects 78
logging DDL 91
performing on replicating objects 346
renaming tables 90
replication of 89
supported and non-supported 54
deactivate config command 292, 363
Index 473
default
behavior for
DDL error on target 91
direct-load replication 92
SQL Cache 222
startup on Windows systems 20
character set 26
configuration directory 115
errors monitored by sp_eventmon 324
export queue 8
number of hints 220
NuTCRACKER folder 20
parameter settings, file containing 15
post queue 9
SharePlex environment for Windows 19
SharePlex port number 241
overriding 253
size of queue file 409
system for sp_ctrl 35
text editor 248
values in extra target columns 76
DEFAULT conflict resolution parameter 217
defining
character sets 98
column partitions 154
data to be replicated 112
default system for sp_ctrl 35
partition schemes and conditions 141
simulated key 114, 120
See also creating
definitions, of terms 443
delete queue command 310
DELETE statement
disabling cascading on target 83
out-of-sync conditions for 70
replicating 12
474 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
deleting
dependent rows (ON DELETE CASCADE) 83
entries from conflict resolution file 204
entries from transformation file 239
objects from configuration 299
queues
during failover procedure 304, 310
through qview 408
through sp_ctrl, see SharePlex Reference Manual
DEMO_DEST table 15
DEMO_SRC table 15
desktop shortcut for SharePlex 28
direct-path loads, conditions for replicating 92
disabling cascading deletes 83
distributed processing
description 64
establishing replication for 174
DML
changes to target objects 78
locks 95
DML_LOCKS parameter 95
driver, Oracle JDBC version 102
dropping
partition schemes and conditions 300
DTaskmgr.bat 260
dump directory
UNIX systems 16
dump sub-directory
Windows systems 18
errors, viewing 13
Event Log
monitoring with sp_eventmon 323
events, replication
monitoring 323
viewing 13
exception marker 150
Export process
creating multiple 130
description 10
export queue
description 8
named 130
export/import (Oracle)
description 4
using to synchronize data 280
handshaking process 8
high availability
backup recommendations 109
description 62
establishing replication for 170
procedures for failover and failback 301
476 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
iwgrep utility
setting IW_HOME variable 325
used in monitoring 323
IW_HOME variable 325
iwsnmptrap for SNMP 341
keys on tables
changing values 80
foreign 83
in peer-to-peer replication 196
need for 79
simulating 114, 120
kill command 322
LOB datatypes
adding LOB column 346
in selective row replication 140
isolating in separate queues 87
Local Logon button 437
local system, logging on with SpClient 437
locally-managed tablespaces
and index-organized tables 83
locks, DML 95
log buffer size 98
log directory
UNIX systems 16
log sub-directory
Windows systems 18
logging off with SpClient 439
login security features 250
logmon.log 327
LOG_PARALLELISM parameter 97
logs
archive 93
for sp_ps 330
out-of-sync SQL 14
redo 93
sp_eventmon 323
sp_logmon 327
sp_qstatmon 333
LONG datatype
considerations for replication 89
-m argument 325
MailUserName 328
MailUserName variable 325
mailx program 322
memory
for LOB replication 88
requirements for SharePlex processes 106
used by queues 104
menus for SpClient 436
message 12
Index 479
meta-inf directory
UNIX systems 16
MKS Platform Components 20
MKS Toolkit
description 20
monitoring
utilities for UNIX systems 320
utility for Windows systems 336
with SNMP traps 341
Mortice Kern Systems 20
MOVE clause of ALTER TABLE command 347
moving
location of ORACLE_HOME 353
rows with ALTER TABLE command 347
multiple
configurations on a system 6
databases on same system 130
instances of SharePlex on same system 42, 45
objects with same names 119
port numbers 241
Post processes 11
source systems
centralized reporting 66, 187
peer-to-peer replication 67, 191
target systems
configuration for 128
description 63–65
UPDATES and DELETES, and indices 220
variable-data directories 42
versions
SharePlex 48
named queues
export
and LOBs 87
creating 130
post 135
480 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
names
of configurations 115
of monitoring scripts 320
of replication strategies 59
of SharePlex directories 15
of SharePlex logs
of SharePlex processes 10
of SharePlex programs 22
of SharePlex queues 8
of source and target columns 76
of source and target tables 77
NAT 416
network
controlling when SharePlex sends data 13
how SharePlex uses 13
recovery from failures 13
requirements 108
security features 250
Network Address Translation 416
Network Management Station (NMS) 341
NLS_LANG environment variable 98
NULLs in keys, considerations for replication 79
number
activation ID number 290
for PROCESSES parameter 97
of columns in tables 76
of database writers 98
of DML locks for SharePlex 95
of hints, maximum 220
of indices on a table 83
of messages for Post read/release 98
of OPEN_CURSORS 96
of SQL Cache cursors 223
of sub-queue files 88
of target routes, maximum 122
SharePlex port 241
NuTCRACKER
and changing process priority 259
Index 481
object
cache 110, 290
ID 14
types
replicating 87
object-relational structures 87
ON DELETE CASCADE, considerations for replicating 83
online transaction processing (OLTP) 67
OPEN_CURSORS parameter
setting for replication 96
setting for SQL Cache 223
ora_chpwd utility 382
Oracle
9i
DDL Logging 91
error handling 91
renaming tables 90
buffer size 98
configuring for replication 74
DDL replication 89
hot backup, to synchronize data
active source database 269
quiet source database 277
JDBC driver version 102
Label Security 102
patches and upgrades 369
supported and non-supported features 54
Oracle wildcards
in configuration files 117
ora_cleansp
how to use 419
running remotely with SpClient 435
OraCleanSp, see ora_cleansp
ORACLE_HOME
changing location of 353
determining 116
ORACLE_SID
changing target 354
determining 116
482 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
ora_setup
running on UNIX systems 387
running on Windows systems (OraSetup) 390
running remotely with SpClient 435
OraSetup, see ora_setup
oratab file 110, 116, 387
out-of-sync tables
causes of 69, 93
prevention planning 74
viewing statements for 14
parameter for
keys that permit NULLs 79
number of
DML locks 95
hints 220
open cursors 96
processes in Oracle 96
read/release interval 98
replication of
DDL 89
direct loads 92
posted data 180
shared memory for queues 88
SharePlex port number 242
SharePlex text editor
SharePlex variable-data directory 240
SNMP traps 342
SQL Cache 222, 223
SSH 253
using prepared conflict resolution for all tables 217
partition schemes and conditions
adding and changing 300
creating 143
description 141
supported datatypes and syntax 146
viewing 151
Index 483
partitioned replication
and application patches or upgrades 362
changing 300
description 75, 112
of columns (vertical) 152
of rows (horizontal) 140
partitioned tables
and replication 291
partitions
for selective column replication 154
for selective row replication 141
pass-through system 65
password for SharePlex, changing
UNIX systems 382
Windows systems 390
patches
application 360
applying with Oracle hot backup or DBCopy 365
OS and Oracle 369
SharePlex 369
peer-to-peer replication
assigning transaction priority 201
description 67
establishing 191
requirements for
archive logging 94
cascading deletes 84, 198
LOB replication 88
primary keys 80, 196
sequences 87, 197
triggers 85, 198
target table access during 79
updating inventory/account balances 199
484 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
performance, improving
changing
log buffer size 98
Post read/release 98
process priority 108
disabling check constraints 84
tuning Post process ??–227
using
indices 81
keys 79
permissions
for monitoring utilities 321
for starting SharePlex 26
see also privileges
per-process memory requirements 106
placeholder for routing map 150
port number
multiple SharePlex instances
UNIX systems 42
Windows systems 45
multiple SharePlex versions 48
setting
UNIX systems 241
Windows systems 243
Post process
configuring for faster posting
with INDEX hints 220
with named post queues 135
with SQL caching 222
DDL logging 91
description 11
ensuring data integrity 69
monitoring 330
things that reduce performance 80, 82, 87, 97, 98
post queue
deleting sub-queues 409
description 8
monitoring 333, 336
named 135
poststat.log 333
pre-image 70
Index 485
preventing
cascading deletes from firing 83
character set errors 98
contention on SHAREPLEX_TRANS table 102
DML transactions from replicating 404
drive-related I/O contention 103
excessive Post I/O for small transactions 98
failures to connect to Oracle 96
full table scans during posting 81
key changes in peer-to-peer replication 196
log wrap-related problems 93
loss of SharePlex environment 109
OPEN_CURSORS errors 96
open-files limitation during posting 106
process priority-related slowdowns 108
queue space problems 104
referential integrity corruption on target 83
row movement operations from replicating 347
SharePlex from running out of DML locks 95
SharePlex process failure 106
target table access 78
triggers from firing on target 85
unauthorized connections to sp_cop 250
users from entering duplicate data 81
primary key
in peer-to-peer replication 196
replication considerations 79
simulating a key 114, 120
priority, setting for SharePlex
UNIX systems 108
Windows systems 259
486 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
privileges
granting for
DML on target system 79, 172
SharePlex as Oracle user 387, 390
SharePlex for conflict resolution 205
SharePlex for transformation 229
SharePlex startup on Windows systems 257
required for
changing SharePlex Oracle password 382
changing SharePlex process priority 259, 432
modifying monitoring scripts 328
running qview on Windows systems 408
problem-solving, see SharePlex Reference Manual
Index 487
procedure for
activating and deactivating configurations 289
adding license key 424
applying patches
application 360
OS and Oracle 369
SharePlex 369
configuring
data for replication 112
SharePlex for SSH port forwarding 253
high availability
failing back to primary system 304
failing over to secondary system after system failure 302
planned failover and failback 314
restoring replication after secondary instance failure 310
Oracle Setup
UNIX 387
Windows 390
performing
DDL on replicating objects 346
system backups 392
upgrades, SharePlex 369
preventing
DML from replicating 404
triggers firing for SharePlex 406
removing
current replication state 419
data from variable-data directory 413
old queues 408
SharePlex 394, 396
running
different versions of SharePlex 48
multiple instances of SharePlex 42
setting environment parameters 240
shutting down SharePlex 30
starting
replication systems 25
SharePlex without replication processes 37
SharePlex, normal manner 26
transforming data 227
truncating SharePlex tables 415
488 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
raw devices
redo logs on 93
SharePlex on 103
Read process, description 10
read/release
by Post process 409
by Post upon COMMIT 98
during SharePlex shutdown 31
parameter for Post 98
read-consistency marker 14
Reconcile
to a SCN 271
to a sequence number 271
reconcile command
in failback 306
in failover 302
in initial synchronization
with hot backup on active database 271, 274
when secondary instance fails 312
with hot copy to apply patches 367
recovery
after secondary instance failure 310
after system failure 302, 304
checkpoint
explanation 8
Post checkpoint 98
data, replication strategy for
description 62
establishing 170
redo logs
archiving option 95
ASM 93
considerations for replication 92
on raw devices 93
operations that bypass 95
optimal location 103
referential integrity constraints
considerations for replication 83
490 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
Registry, changing
SharePlex environment 261
SharePlex port number 243
SharePlex text editor 248
Remote Access window for SpClient 439
Remote Logon button 438
remote system
controlling access from 250
issuing sp_ctrl commands for 34
running utilities for 434
selective replication to 112
strategy for replicating to 63, 64, 177
removing
data from SharePlex tables 415
entries from
configuration 299
conflict resolution file 204
transformation file 239
Windows Registry 261
old queue files 409
partition schemes and conditions 300
SharePlex
from UNIX systems 394
from Windows systems 396
SharePlex directories 15
table
from replication 299
renaming tables 90
renaming tables during replication 348
Index 491
replicating
cascading deletes 83
DDL 89
direct-path loads 92
DML from triggers 85
entire tables 76
LOBs 87
LONGs 89
object-relational structures 87
operations that bypass redo logs 95
selected columns 152
selected rows 140
sequences 85
492 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
replication
between tables on same system 60, 166
for centralized reporting
description 66
establishing 184–190
for data distribution
description 63
establishing 174
for data warehousing/mart
description 66
establishing 184–190
for distributed processing
description 64
establishing 174
for distribution through intermediary system
description 65
establishing 177
for high availability and data recovery
description 62
establishing 170
for load balancing
description 64
establishing 174
for multiple peers
description 67
establishing 191
for reporting 60
description 60
establishing 166
how SharePlex replicates 10
messages, definition 12
monitoring
on Windows with Sp_NT_Mon 336
with SNMP 341
with UNIX scripts 320
planning and requirements 53
preventing for specific transactions 404
restoring to initial state 419
starting and stopping 26–30
supported and non-supported Oracle components 54
Index 493
reporting
replication for data warehousing/mart
description 66
establishing 184–190
replication to maintain a reporting instance
description 60
establishing 166
rim directory
UNIX systems 16
rim sub-directory 104, 106
Windows systems 18
rollback segment
optimal location 103
routing map
description 121
for multiple target systems 113
for selective row replication 145
limitations 122
placeholder in configuration file 150
row movement, and replication 347
row-level replication
changing 300
configuring 140
description 112
rows
move using ALTER TABLE command 347
Oracle Label Security 102
selective replication of 140
saving
files for backup 110
SpClient output 436
state of replication when shutting down 31
scheme, partition
adding and changing 300
creating 143
description 141
viewing 151
SCN 271
scripting
alteration of triggers to ignore SharePlex 407
configurations
build_config.sql 159
config.sql 163
disabling of cascading deletes 83
purging of variable-data directory 413
replication monitoring
on Windows systems 336
sp_eventmon 323
sp_logmon 327
sp_ps 330
sp_qstatmon 333
truncating of SharePlex tables 415
scroll bar, in sp_ctrl for Windows 34
security
controlling remote connections 250
for starting and stopping SharePlex 26
row-level, and replication 102
Select menu in SpClient 436
selective replication
description 75, 112
of columns 152
of rows 140
sequence number 271
sequences
guidelines for replicating 85
in peer-to-peer replication 197
service, SharePlex (Windows systems)
starting 28
starting remotely 435
Index 495
SharePlex
architecture diagram 7
backing up 109
binaries (processes), location 11
changing
environment parameters 240
password 382
port number 241
user name/password 386
commands, see SharePlex Reference Manual
configurations
activating 289
creating 112
description 6
using Oracle wildcards 117
desktop shortcut 28
in high availability environment 301
internal tables
creating on UNIX systems 387
creating on Windows systems 390
list of 14
monitoring 319
Oracle account
Windows systems 390
overview 3–19
patches 369
process priority
UNIX systems 108
Windows systems 259
processes
description 10
location of 103
monitoring 330, 336
product directory 15
queues
description 8
location and sizing 104
viewing and removing 408
remote connection and control 434
removing
UNIX systems 394
Index 497
sp_ctrl
connecting to alternate port 34
defining default system 35
description 22
maximum number of characters 33
running for one command 33
running interactively for multiple commands 34
starting 32
stopping 35
sp_ctrl.exe. See sp_ctrl
spelling case, in configuration 116–119
sp_eventmon monitoring utility 323
SP_IMP_WCMT_MSGCNT parameter 94
splex_add_key utility
running locally (UNIX) 424
running remotely through SpClient 435
splex_get_key utility 426
splex_uname utility 425
sp_logmon monitoring utility 327
sp_mport 10, 24
Sp_Nt_Mon monitoring script 336
sp_nt_mon.txt file 337
sp_ocap 10, 24
SP_OCT_CHECKPOINT_FREQ parameter 94
SP_OCT_REPLICATE_DLOAD parameter 92
SP_OCT_REPLICATE_POSTER parameter 180
SP_OPO_HINTS_LIMIT parameter 220
SP_OPO_MAX_CDA parameter 223
SP_OPO_NLS_LANG parameter 101
SP_OPO_READRELEASE_INTERVAL parameter 98
SP_OPO_SQL_CACHE_DISABLE parameter 222
SP_OPO_STOP_ON_DDL9I_ERR parameter 91
sp_opst 24
SP_ORD_CDA_LIMIT parameter 94
SP_ORD_DELAY_RECORDS parameter 94
SP_ORD_LDA_ARRAY_SIZE parameter 94
SP_ORD_NLS_LANG parameter 101
sp_ordr 10, 24
SP_ORD_RMSG_LIMIT parameter 94
Spotlight on Oracle 87
sp_ps monitoring utility 330
500 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
starting
replication 289
replication servers 25
SharePlex 26
controlling startup mode 255
SpClient 436
sp_ctrl 32
state directory
UNIX systems 16
state sub-directory 110
Windows systems 18
Status Database 13
stopping
Capture process 93
for DDL errors (9i) 91
replication 292
replication processes 30
SharePlex 30
sp_ctrl 35
store/restore to synchronize data 280
striped devices and SharePlex 105
synchronization
causes of out-of-sync conditions 69, 78
explanation of 5, 69
verifying 78
with FTP 283
with import/export 280
with Oracle hot backup
active database 269
quiet database 277
with transportable tablespaces 286
502 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
system
backup on replication machine 392
configuring for replication 102
failover/failback procedures 302, 304
licensing for SharePlex 424
remote
accessing in Windows 434
connecting with sp_ctrl 34
secure connections 250
removing SharePlex from
UNIX procedure 394
Windows procedure 396
tablespace in Oracle 103
System Change Number 271
tables
accessing on target 78
adding
to the database 350
configuration script for multiple 159, 163
dropping
from configuration 299
for selective row replication 144
instance-specific 77
key requirements 79
foreign keys 83
name of source and target 77
not replicated 78
partitioned 291
renaming during replication 348
SharePlex internal tables 14
structure requirements 76
to exclude from replication 77
Index 503
target
meaning of 5
objects
commands to verify synchronization 78
description 120
planning for replication 74–??
ORACLE_SID, changing 354
system
configuring for replication 102
how SharePlex applies changes to 12
maximum number of 122
replicating to central 66, 184–190
replicating to multiple 63–65, 128, 174–182
row IDs on 79
verifying synchronization on 69
Task Manager
changing process priority 259, 432
identifying processes 25
running remotely with SpClient 435, 440
TCP/IP
how SharePlex uses 13
security for 250
setting SharePlex port for 241
SharePlex bandwidth requirements for 108
temp directory
UNIX systems 16
temp files generated by sp_qstatmon 333
terms, glossary of 443
testing new version of SharePlex 48
text editor, defining 248
timestamp priority in conflict resolution 201
Title page version
Version 6.0.0 Release i
toolbar for SpClient 435
transformation of data 227
transformation.SID file 237
transportable tablespaces, using for synchronization 286
traps, SNMP for SharePlex 341
triggers
requirements for SharePlex 85
utilities for changing 406
504 SHAREPLEX® FOR ORACLE
Administrator’s Guide Version 7.6
user
access on target system 78
command levels for sp_ctrl 33
command-line interface 14, 22
file for groups 110
group for starting SharePlex 27, 28
SharePlex
changing on UNIX systems 382
disabling triggers for 85
privilege for SYS.QSA_KTFBUE view 83
user-defined types
in partitioned replication 140
planning for 87
util directory
UNIX systems 16
Windows systems 17
utilities
debugging network issues 416
managing SharePlex 431
monitoring replication 320
remote access 434
WAN
in high availability configuration 62
security features 250
SharePlex support for 13
web browser 67
WHEN clause, in triggers 407
WHERE clause
exclusion of LONGs 89
in SharePlex statements 70, 80
Index 507
Windows
adding SharePlex license key 424
changing SharePlex Registry entries 261
configuring SharePlex startup 255
determining ORACLE_SID 116
differences from UNIX systems 24
displaying scroll bar in sp_ctrl 34
identifying SharePlex processes on 25
Registry environment for SharePlex 19
removing SharePlex 396
running
different SharePlex versions 52
multiple instances of SharePlex 42
OraSetup 390
sp_ctrl 34
setting
alternative editor 248
process priority 259
SharePlex port 243
SharePlex control utility 431
SharePlex directories 17
starting
SharePlex 28
SharePlex without replication processes 38
work tables 77