SharePlex For Oracle ®
Reference Guide Version 7.5
Quest® Software, Inc. © 2010 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:
[email protected] 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 damage 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.
Third Party Licensing For a list of third party components and their applicable licensing please refer to Appendix A in the SharePlex Administrator’s Guide.
World Headquarters 5 Polaris Way Aliso Viejo, CA 92656 www.quest.com e-mail:
[email protected]
CHAPTER 1
Please refer to our Web site for regional and international office information.
SharePlex® For Oracle Reference Guide Updated 06/02/10 Version 7.5
iii
IV
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Table of Contents About this guide Viewing this guide in PDF format............................................................................................... xii Conventions used in this guide ................................................................................................... xiii About Quest Software.................................................................................................................. xv Chapter 1: Using SharePlex Commands Part 1: Overview of SharePlex commands
Monitoring replication with SharePlex commands ....................................................................... 2 Controlling replication with SharePlex commands ....................................................................... 2 Understanding command authorization levels............................................................................... 3 SharePlex commands at a glance................................................................................................... 5 Part 2: Using SharePlex commands
Issuing SharePlex commands ...................................................................................................... 13 Issuing commands for a remote system....................................................................................... 14 Issuing commands for clustered systems..................................................................................... 15 Getting online help in sp_ctrl....................................................................................................... 15 Producing a scroll bar for viewing command output (Windows)................................................ 15 Alphabetical reference for SharePlex commands........................................................................ 16 abort config .................................................................................................................................. 17 abort service................................................................................................................................. 19 activate config.............................................................................................................................. 22 orainfo.......................................................................................................................................... 28 authlevel....................................................................................................................................... 30 clear status.................................................................................................................................... 31 compare config ............................................................................................................................ 33 compare table............................................................................................................................... 55
vi
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
copy/append ................................................................................................................................. 87 copy config................................................................................................................................... 99 create config............................................................................................................................... 101 deactivate config ........................................................................................................................ 102 delete queue................................................................................................................................ 104 edit.............................................................................................................................................. 107 edit config .................................................................................................................................. 110 exit.............................................................................................................................................. 111 expand ........................................................................................................................................ 112 flush............................................................................................................................................ 114 help............................................................................................................................................. 117 host ............................................................................................................................................. 119 hostinfo....................................................................................................................................... 121 list config.................................................................................................................................... 122 list param.................................................................................................................................... 124 lstatus ......................................................................................................................................... 127 port ............................................................................................................................................. 131 purge config ............................................................................................................................... 133 qstatus......................................................................................................................................... 135 quit ............................................................................................................................................. 137 reconcile ..................................................................................................................................... 138 redo............................................................................................................................................. 142 remove config ............................................................................................................................ 143 remove log compare................................................................................................................... 144 rename config............................................................................................................................. 147 report .......................................................................................................................................... 148 reset param ................................................................................................................................. 150 set log ......................................................................................................................................... 154 set param .................................................................................................................................... 156 show ........................................................................................................................................... 162 show activate.............................................................................................................................. 166 show capture .............................................................................................................................. 169 show compare ............................................................................................................................ 173 show config ................................................................................................................................ 182 show export ................................................................................................................................ 185
TABLE OF CONTENTS
vii
show import ................................................................................................................................186 show log......................................................................................................................................187 show post ....................................................................................................................................191 show read ....................................................................................................................................200 show sql ......................................................................................................................................203 show statusdb..............................................................................................................................205 show sync ...................................................................................................................................207 shutdown.....................................................................................................................................209 start .............................................................................................................................................211 startup .........................................................................................................................................214 status ...........................................................................................................................................216 stop..............................................................................................................................................218 truncate log .................................................................................................................................222 usage ...........................................................................................................................................223 verify config ...............................................................................................................................224 version ........................................................................................................................................226 view config .................................................................................................................................227 view log options..........................................................................................................................228 Chapter 2: SharePlex Parameters About SharePlex parameters ......................................................................................................230 Where parameter information is stored ......................................................................................230 Setting and activating parameters ..............................................................................................230 Viewing a list of SharePlex parameters......................................................................................233 Parameter categories...................................................................................................................234 Descriptions of user-configurable SharePlex parameters...........................................................234 Chapter 3: Preventing and Solving Replication Problems Part 1: Tools for preventing and solving problems
Viewing the Status Database ......................................................................................................286 Viewing the Event Log...............................................................................................................286 Viewing the user issued commands............................................................................................287 Viewing the other log files .........................................................................................................288 Viewing and terminating SharePlex processes...........................................................................290 Using the status and lstatus commands to view status ...............................................................294
viii
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Using the verify config command to test a configuration.......................................................... 295 Using the compare commands to verify synchronization.......................................................... 295 Changing the IP address on the target machine ......................................................................... 295 Getting syntax help for commands ............................................................................................ 296 Monitoring replication to detect and prevent problems ............................................................. 297 Part 2: Solving Oracle Setup problems
Incorrect ORACLE_SID and/or ORACLE_HOME.................................................................. 299 More than one oratab file (Sun Solaris) ..................................................................................... 300 Asterisk as the ORACLE_SID entry ......................................................................................... 300 Legacy /etc/logingroups file (HP systems) ................................................................................ 300 Part 3: Solving configuration problems
SharePlex cannot locate the configuration................................................................................. 301 A configuration will not activate ............................................................................................... 301 Activation takes too long ........................................................................................................... 306 Explanation of configuration command errors .......................................................................... 307 Part 4: Solving synchronization problems
How SharePlex reports out-of-sync conditions ......................................................................... 311 Find and correct the problem before you resynchronize! .......................................................... 312 How to detect and correct common out-of-sync conditions. ..................................................... 313 How to resynchronize objects .................................................................................................... 324 Part 5: Solving replication problems
Replication is too slow............................................................................................................... 330 Capture stopped.......................................................................................................................... 336 Post stopped ............................................................................................................................... 337 The post queue is not emptying ................................................................................................. 339 There is an extra import process ................................................................................................ 340 There is a “failure to write and open queue” error..................................................................... 341 The queues are corrupted ........................................................................................................... 341 The post queue seems too large ................................................................................................. 341 You had to unexpectedly stop replication (UNIX) .................................................................... 342 sp_cop is using too much CPU time .......................................................................................... 344 A table stopped replicating ........................................................................................................ 344
TABLE OF CONTENTS
ix
A source table is corrupted .........................................................................................................344 SharePlex is running out of disk space .......................................................................................345 Oracle 9i+ DDL is not replicating ..............................................................................................346 Oracle 9i+ DDL is not completely displayed in the Event Log .................................................347 Post generates ORA-1762 errors ................................................................................................347 Post generates a shared memory error ........................................................................................348 SharePlex does not run on a Windows system ...........................................................................349 Explanation of replication error messages..................................................................................351 Part 6: Solving other problems
A configuration was accidentally deleted...................................................................................359 Conflict resolution generates compile errors..............................................................................359 The reconcile command is slow to complete..............................................................................359 Machine names cannot be resolved ............................................................................................360 A “Can’t unlink file” error occurs on Windows systems ...........................................................360 Solving connection errors ...........................................................................................................360 Solving compare command errors ..............................................................................................362 Solving errors for other sp_ctrl commands ...............................................................................365 Part 7: How to get help
Before you call Quest Technical Support...................................................................................370 Other information to send...........................................................................................................372 How to use Quest support...........................................................................................................372 Index ..............................................................................................................................................373
x
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
ABOUT THIS GUIDE
xi
About this guide This guide is a reference for the following: SharePlex commands — an overview of the commands that control replication through sp_ctrl, an explanation of command authorization levels, and detailed documentation for each command. SharePlex parameters — an overview of the SharePlex tuning parameters, how they are set and stored, and detailed documentation for parameters that can be changed by SharePlex users. Problem prevention and solving tips — a guide to help you prevent and resolve common problems that might be encountered during configuration activation and replication, plus an overview of the tools available for preventing, detecting and correcting problems. Users of the SharePlex Reference Guide should have a thorough understanding of SharePlex before issuing commands, changing parameters or attempting to solve problems. Please see the SharePlex Administrator’s Guide for information about:
• • • • • •
How SharePlex works. How to run the SharePlex programs. How to plan, implement and monitor a replication environment. Failover/failback procedures for high-availability environments. Procedures for performing administrative operations. How to use SharePlex utilities.
xii
SHAREPLEX FOR ORACLE Reference Guide Version 7.5
Viewing this guide in PDF format This manual is available in Adobe® PDF format on a documentation CD provided with the SharePlex software and from the Quest SupportLink web site at http://support.quest.com. The PDF document is viewable with Adobe Acrobat® Reader Version 7 or 8 which is free software that can be downloaded from the Adobe web site at http://www.adobe.com if it is not installed on your system.
ABOUT THIS GUIDE
xiii
Conventions used in this guide The following typographic conventions are used in this guide. Command-line syntax is expressed in Arial Narrow. The following explains the syntax 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 example command strings to emphasize required user defined variables in long strings. Example: reconcile queue {queuename} for {datasource-datadest} [on host]
• A vertical bar, or “pipe” character ( | ) within brackets or braces indicates that you can use only one of the enclosed components. Example: abort service {service | all} Names of commands, programs, directories and files are expressed in Arial Bold; other names are expressed in capital letters using the default font. Examples: The sp_ctrl program is located in the bin directory. Open the oramsglst file. Find the value for ORACLE_HOME. Click Apply. System displays, such as prompts and command output, are expressed in Courier. Examples: sp_ctrl(sysA)> User is a viewer (level=3)
xiv
SHAREPLEX FOR ORACLE Reference Guide Version 7.5
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 system (or primary system) is referred to as SysA. Target systems (or secondary systems) are referred to as SysB, SysC, SysD, and so forth. The following icons are used to highlight important or helpful information:
This icon denotes additional information that you should know.
This icon denotes advice that can help you save time or prevent problems.
This icon calls attention to critical issues that must not be ignored.
This icon refers you to related documentation for more information.
ABOUT THIS GUIDE
xv
About Quest Software Now more than ever, organizations need to work smart and improve efficiency. Quest Software creates and supports smart systems management products—helping our customers solve every day IT challenges faster and easier. Visit www.quest.com for more information.
Contacting Quest Software Email:
[email protected]
Mail:
Quest Software, Inc. World Headquarters 5 Polaris Way Aliso Viejo, CA 92656 USA
Web site:
http://www.quest.com
Please refer to our web site for regional and international office information.
Contacting Quest Support Quest Support is available to customers who have a trial version of a Quest product or who have purchased a Quest product and have a valid maintenance contract. Quest Support provides unlimited 24x7 access to SupportLink, our self-service portal. Visit SupportLink at http://support.quest.com/ From SupportLink, you can do the following:
• Retrieve thousands of solutions from our online Knowledgebase • Download the latest releases and service packs • Create, update and review Support cases View the Global Support Guide for a detailed explanation of support programs, online services, contact information, and policies and procedures. The guide is available in at: http://support.quest.com/
xvi
SHAREPLEX FOR ORACLE Reference Guide Version 7.5
1 Using SharePlex Commands This chapter shows you how to use the sp_ctrl commands that configure, start, stop, control, and monitor the replication process. It is divided into parts for easier use. The first part provides an overview of the available commands and command authorization levels. The second part contains guidelines for using the commands followed by an alphabetical reference guide with full descriptions and syntax. Contents Overview of SharePlex commands Using SharePlex commands
2
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Part 1: Overview of SharePlex commands SharePlex requires little user intervention to maintain a replication environment, but occasionally you will need to make adjustments, diagnose a problem, or perform status checks. Many of these tasks are performed by issuing commands in sp_ctrl.
Monitoring replication with SharePlex commands Like any mission-critical software, SharePlex should be monitored regularly for situations or events that could interfere with processing, especially those that could result in loss of data synchronization. The information commands summarized on page 7 help you monitor different aspects of replication. Issue them frequently to:
• • • • • •
Monitor for out-of-sync tables. Verify that replication processes are running. View the number of replicated messages in the queues. View the Event Log to view warnings, errors and other notifications. View process statistics that are helpful for tuning and problem solving. Detect tables or operations that are slowing down the replication process.
Tip: To supplement the information commands, you can configure the SharePlex monitoring scripts to notify you when key replication events occur. For more information, see Chapter 9 of the SharePlex Administrator’s Guide.
Controlling replication with SharePlex commands Complementing the information commands are numerous other commands that enable you to:
• Create, verify, copy, edit, or delete configurations. • Start, stop or abort replication processes. • Delete and rebuild corrupt queues.
CHAPTER 1 Using SharePlex Commands
• • • • • •
3
Remove orphaned Export processes. Change parameter settings and port connections. Detect and repair out-of-sync target rows. Remove old messages from the logs. View command syntax. Repeat a previous command.
Understanding command authorization levels To execute a command, a SharePlex user must have that command’s authorization level or higher. You assign a user’s authorization level when you add that person to one of the SharePlex user groups on the system where he or she will be issuing commands. Each group represents a different level of authorization. The groups were created when SharePlex was installed. The table on page 4 shows the SharePlex user authorization levels, groups and roles.
4
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
User Authorization Levels and Roles AUTH LEVEL
USER TYPE
USER GROUP USER ROLES
1
Administrator
spadmin
Can issue all SharePlex commands. Commands that can only be issued by a SharePlex Administrator are:
• startup, shutdown • all configuration commands relating to an active configuration
• all parameter commands except list • • • •
param start capture stop capture abort capture truncate log
2
Operator
spopr
Can issue all SharePlex commands except those listed above.
3
Viewer
spview
Can view lists, status screens, and logs to monitor replication only.
To add SharePlex users Decide the authorization level you want each user to have, and then add the names to the corresponding groups using the operating system’s standard method for adding users.
UNIX systems Edit the /etc/group file.
Windows systems Use the Users and Passwords control panel or the Computer Management tool in Administrative Tools.
CHAPTER 1 Using SharePlex Commands
5
SharePlex commands at a glance This section provides an overview of all SharePlex commands, grouped according to the processes or functions they control. Commands with an asterisk (*) should be issued frequently. A detailed, alphabetical reference guide for SharePlex commands begins on page 17.
Configuration commands The configuration commands control all aspects of managing SharePlex configurations. List of configuration commands Command
Auth. Level
abort config
1
Immediately terminates replication for the designated configuration file whether or not data has posted. Deactivates the configuration and deletes queues and processes.
activate config
1
Begins replication of the data specified in a configuration.
copy config
2
Duplicates a configuration to edit and save as a new file.
create config
2
Creates a new configuration file in which you enter information about objects to be replicated.
deactivate config
1
Gracefully terminates replication of the data specified in a configuration, allowing data in the queues to be posted to the target database before the queues are deleted.
edit config
2
Modifies an existing configuration file using the default text editor.
list config
3
Displays all of the configuration files on a source system, both active and inactive.
purge config
1
Removes data from queues generated by an active configuration, but does not deactivate the configuration or remove the queues themselves.
remove config
2
Deletes a configuration file from the system permanently.
Description
6
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5 List of configuration commands (continued) Command
Auth. Level
Description
rename config
2
Assigns a different name to a configuration file.
verify config
3
Verifies that the objects in a configuration are valid and that the configuration is structured properly to ensure successful activation and replication.
view config
3
Displays the contents of a configuration file.
Connect commands The connect commands control connections made to replication systems through the sp_ctrl interface. List of connect commands Command
Auth. Level
exit
3
Exits the sp_ctrl command-line session and disconnects the TCP/IP link. (Used interchangeably with quit.)
host
3
Sets a default machine for the current sp_ctrl connection.
port
3
Sets a default sp_cop port number for the current sp_ctrl session.
quit
3
Exits the sp_ctrl command-line session and disconnects the TCP/IP link. (Used interchangeably with exit.)
Description
CHAPTER 1 Using SharePlex Commands
7
Information commands The information commands provide information about the replication environment. Use these commands when you are trying to resolve a replication problem or you want to view certain process conditions. List of information commands Command
Auth. Level
Description
orainfo
3
Displays the Oracle database information.
copy/append status
3
Displays status history for previous copy/append commands
lstatus
3
Displays detailed information about the state of SharePlex replication.
qstatus*
3
Displays the state of the capture, export and post queues.
report copy/append
3
Displays copy/append history for a table.
show
3
Displays the source and destination of the data being processed by each replication process on a system, and displays the status of each process.
show activate
3
Displays the status of all configuration activation activity on a source system.
show capture
3
Displays brief or detailed statistics for the Capture process for use in tuning and problem solving.
show compare
3
Displays the results of the compare config and compare table commands.
show config
3
Displays properties of the active configuration.
show export
3
Displays the number of messages sent to the target system(s).
show import
3
Displays the number of messages received from the source system(s).
show log
3
Displays the Event Log, Command Log, Verify Log, Trace Log, or a process log.
show post
3
Displays brief or detailed statistics for the Post process for use in tuning and problem solving.
8
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5 List of information commands (continued) Command
Auth. Level
show read
3
Displays brief or detailed statistics for the Read process for use in tuning and problem solving.
show sql
3
Displays the current or last SQL statement processed by the Post process.
show statusdb*
3
Displays the Status Database, which contains records of important replication events.
show sync*
3
Displays information about out-of-sync conditions.
status*
3
Displays an overview of the state of SharePlex replication.
Description
Maintenance commands The maintenance commands control command displays and files. List of maintenance commands Command
Auth. Level
clear status
2
Removes warning messages from the Status Database.
remove log compare
3
Removes old compare reports and logs from the system.
set log
3
Sets the default values for the show log command.
truncate log
1
Clears the records from the Event Log, with the exception of logged commands.
Description
CHAPTER 1 Using SharePlex Commands
9
Parameter commands The parameter commands control the environment parameters that define how SharePlex operates. List of parameter commands Command
Auth. Level
list param
3
Displays a list of SharePlex parameters with current and default values and set-at points.
reset param
1
Restores the value of a SharePlex parameter to the default setting.
set param
1
Changes the value of a SharePlex parameter on a global basis or for a specified replication process.
Description
Properties commands The properties commands display information about a user’s authorization level, the local system, and the local SharePlex installation. List of properties commands Command
Auth. Level‘
authlevel
3
Displays the SharePlex authorization level of a user who logs into sp_ctrl.
hostinfo
3
Displays a machine’s name and operating system.
version
3
Displays the version of SharePlex installed on a machine.
Description
10
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Queue commands The queue commands eliminate orphaned or corrupt queues, and they delete orphaned export processes. List of queue commands Command
Auth. Level
delete queue
2
Removes a capture, export or post queue if the queue is orphaned or corrupted.
delete quser
2
Removes an unneeded Export process when a target system is removed from the replication configuration.
Description
Run Commands The run commands control the operation of SharePlex with options for starting and stopping processes, starting and shutting down replication, re-synchronizing data, and enabling/disabling confirmation messages. List of run commands Command
Auth. Level
abort service
2 or 1
Stops one or all replication processes immediately, without finishing processing. (Level 1 required for Capture.)
clear status
3
Removes warning messages from the Status Database.
shutdown
1
Shuts down sp_cop and all replication processes.
start
2 or 1
Starts a replication process. (Level 1 required for Capture.)
startup
1
Starts replication if sp_cop was started with the -s option to keep the SharePlex replication processes stopped.
stop
2 or 1
Stops a replication process gracefully after it is finished reading from or writing to its queues. (Level 1 required for Capture.)
Description
CHAPTER 1 Using SharePlex Commands
11
Synchronization commands The synchronization commands control aspects of data synchronization. List of synchronization commands Command
Auth. Level
compare config
2
Compares the contents of all tables in a configuration to those of the target tables to verify synchronization and repair out-of-sync rows, if necessary.
compare table
2
Compares the contents of a source table to those of a target table to verify synchronization and repair out-of-sync rows, if necessary.
copy/append
2
Uses the Oracle Export/Import utility to allow users to set-up replication and/or (re)synchronize tables already in replication.
flush
2
Puts a marker in the data stream to establish a point of synchronization between the source and target data, then stops the Post process at that point.
reconcile
1
Synchronizes the results of a hot backup or hot copy applied to the target system with ongoing user transactions from the source system.
Description
Miscellaneous commands These miscellaneous commands provide additional controls for using SharePlex. List of miscellaneous commands Commands
Auth. Level
edit
3
Displays the previously issued command in the text editor so that you can edit it and execute the edited version.
expand
3
Will expand a wildcard specification and display the expanded specification to the screen.
help
3
Displays descriptions and syntax for SharePlex commands from the sp_ctrl command-line interface.
Description
12
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5 List of miscellaneous commands (continued) Commands
Auth. Level
Description
redo
N/A
Executes the previous command again.
usage
3
Displays the syntax for a SharePlex command.
view log options
3
Displays the default values for the show log command.
CHAPTER 1 Using SharePlex Commands
13
Part 2: Using SharePlex commands This part provides basic information about issuing SharePlex commands and an alphabetical reference guide for each one.
Issuing SharePlex commands SharePlex commands are issued through the sp_ctrl command-line interface. The sp_ctrl prompt appears in one of two ways, depending on whether or not you set a default system. sp_ctrl>
Basic sp_ctrl prompt.
sp_ctrl(this_host:3304) >
Prompt when a default system and port are set by issuing the host (see page 119) and port (see page 131) commands.
The following are guidelines for issuing SharePlex commands:
• You can run sp_ctrl and issue commands for a local machine where SharePlex is running, or you can use one of the [on host] options to issue commands from one machine to affect any other machine involved in replication (see the following topic).
• To issue commands for a machine, sp_cop must be running on that machine. • The maximum string length of a SharePlex command is 255 characters, including spaces. To work around this operating-system limitation, use the edit command. For more information, see page 107. For more information on running sp_ctrl, see the SharePlex Administrator’s Guide.
14
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Issuing commands for a remote system To issue a command that will affect a remote machine and to script commands that include a login name, password, port number, or combination of those items, use one of the [on host] command options. These options are available for most commands. To determine whether or not the [on host] options are available for a command, look in the command’s syntax description in the alphabetical reference section in this chapter. The following table describes the command options for remote connection using the [on host] options. [on host] options OPTION
DESCRIPTION
on host
Use this option to execute a command on a system other than the one to which you currently are connected. (The current system is shown in parentheses after the sp_ctrl prompt.) You are prompted for a login name and password for the system to which you are connecting. This option, if used, must be the last component of a command’s syntax. Example: sp_ctrl(sysB)> status on SysA In this example, the status command is being issued on sysB to show replication status on sysA.
on host:portnumber
Use this option for scripting SharePlex commands when a remote login and port number must be provided. This option, if used, must be the last component of a command’s syntax. Example: sp_ctrl(sysB)> status on SysA:8304
on login/password@host
Use this option for scripting SharePlex commands when a remote login, password, and host name must be provided. This option, if used, must be the last component of a command’s syntax. Example: sp_ctrl(sysB)> status on john/rosebud@SysA
on login/password@host:portnumber
Use this option for scripting SharePlex commands when a remote login, password, host name, and port number must be provided. This option, if used, must be the last component of a command’s syntax. Example: sp_ctrl(sysB)> status on john/rosebud@SysA:8304
CHAPTER 1 Using SharePlex Commands
15
Issuing commands for clustered systems To issue sp_ctrl commands on clustered systems, use the name set with the SP_SYS_HOST_NAME parameter as the host in the [on host] options when connecting from a remote system, or set it as the default for sp_ctrl by using the host command (see page 119). For more information about configuring SharePlex within a cluster, see the SharePlex Installation and Demonstration Guide.
Getting online help in sp_ctrl To view descriptions and syntax for SharePlex commands from within the sp_ctrl interface, issue the help command (see page 117). To view just the syntax for a command, issue the usage command (see page 223).
Producing a scroll bar for viewing command output (Windows) Scrolling might be necessary to view the entire output of certain sp_ctrl commands. If your Command Prompt window does not have a scroll bar, you can change the window properties to produce one. 1 Click the Command Prompt icon at
the top left corner of the console, then select Properties from the menu.
2 In the Command Prompt Properties dialog box, click the Layout tab.
16
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
3 In the Screen Buffer Size option box, increase the Height value until it
produces a scroll bar in the Command Prompt window. 4 Click OK to apply the settings.
5 In the Apply Properties To Shortcut dialog
box, select one of the options, either to apply the new properties to the current command session or to apply them as the new default for all sessions. 6 Click OK to close the dialog box.
Alphabetical reference for SharePlex commands The remainder of this chapter contains detailed documentation for each SharePlex command. The commands appear in alphabetical order, beginning on the next page.
CHAPTER 1 Using SharePlex Commands
17
abort config Use the abort config command to deactivate a configuration instantly and delete all associated queues and replication processes at the same time. This command stops all replication activity for the configured datasource on the source and target systems, whether or not data in the queues has been posted. It is a forceful deactivation. The abort config command is effective when there has been a system, configuration, or data problem and you need to prevent posting to the target system(s). Because you are deleting whatever data remains in the pipeline, the source and target instances will go out of synchronization after this command takes effect. If any SharePlex replication process stops before or during the abort config command, the command also stops. When the process starts again, the command resumes working. This allows abort config to work even if the network is temporarily down — it remains in the queues until the connection is restored.
Aborting when there are multiple active configurations When there are multiple active configurations on the same source system, use the abort config command only if there are named export queues that separate the replication streams for each one. Without named export queues, SharePlex funnels all replicated data through one export queue, and an abort config command for one configuration deletes the data for all of them. To create named queues, see Chapter 5 of the SharePlex Administrator’s Guide. Authorization level: Issued for: Related commands:
Administrator (1) source system deactivate config, purge config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
abort config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
18
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to abort. Configuration names are case-sensitive. Example: sp_ctrl(sysA)> abort config sales
CHAPTER 1 Using SharePlex Commands
19
abort service Use the abort service command to terminate a SharePlex replication process (service) immediately, whether or not that process has finished reading from, or writing to, its queues. This command is effective when you cannot wait for a process to stop gracefully, or in unusual circumstances when a process will not shut down when you issue the stop command. This command does not affect replicated data. The data remains safely in the queues, and SharePlex resumes normal processing when the process is started again. A process aborted with the abort service command remains stopped even if SharePlex is shut down and re-started. Only the start command can start it again (see page 211). The abort service command provides options with which you can abort a process for any (or all) systems, or for a named queue, without affecting replication for other routes. Authorization level: Issued for:
Operator (2); Administrator (1) to abort Capture abort service for Capture, Read and Export are issued for
the source system. abort service for Import and Post are issued for the target system. Related commands:
start, stop
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
abort service service
[to host] [from host] [for datasource] [for datasource-datadest] [queue queuename]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
20
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments ARGUMENT
DESCRIPTION
service
The SharePlex replication process you want to abort. Valid values are: Capture Read Export Import Post Example: sp_ctrl(sysA)> abort service capture
Command options OPTION
DESCRIPTION
to host
This option aborts Export to a designated system, while allowing Export to other systems to continue. • host is the name of the target system. Example: sp_ctrl(sysA)> abort service export to sysB In this example, Export is aborted from sysA to sysB, but other Export processes from sysA to other target systems will continue.
from host
This option aborts Import from a designated system, while allowing Import from other systems to continue. • host is the name of the source system. Example: sp_ctrl(sysD)> abort service import from sysC In this example, Import from sys C is aborted on sysD, but other Import processes on sysD from other source systems will continue.
for datasource
This option aborts Capture or Read for a designated datasource, but other replicating datasources on the same system are unaffected. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. Example: sp_ctrl(sysA)> abort service read for o.oraA In this example, Read is aborted on sysA for instance oraA, but other Read processes for other instances on sysA will continue.
CHAPTER 1 Using SharePlex Commands
21
Command options (continued) OPTION
DESCRIPTION
for datasource-datadest
This option aborts Post for a designated source SID-target SID data stream, while allowing other Post activities to continue. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target Oracle instance. Example: sp_ctrl(sysC)> abort service post for o.oraA-o.oraC In this example, Post is aborted on sysC for instance oraA replicating to oraC, but other Post processes on sysC will continue.
queue queuename
This option aborts the Export, Import or Post process associated with a named queue, while allowing replication through other named queues to continue. • queuename is the name of the queue. Example: sp_ctrl(sysA)> abort service export queue QA In this example, Export of data through named export queue QA is aborted on sysA, but Export will continue for data assigned to all other named queues.
22
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
activate config Use the activate config command to activate a configuration. Replication begins immediately as soon as the activation process is complete. 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 configured objects, the amount of row chaining, and the type of activation you are using. You can activate one configuration per datasource (Oracle instance) on each system. For example, if there are ConfigA, ConfigB and ConfigC for instance ora10, you can activate only one of them at a time. Activating another configuration for the same datasource automatically deactivates the first one. The process that sp_cop calls to activate a configuration is sp_tconf. If you ever need to kill an activation process, look for that name. The activation process retains control of the sp_ctrl interface until the activation is finished. To activate multiple configurations for different datasources on the same system, activate the first one, 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.
Available activation methods SharePlex provides the following methods for activating a configuration.
• Default activation • Live activation
Using default activation The default activate config command initiates a multi-threaded process that creates one or more asynchronous parallel threads, each handling the analysis for a different object. All tables are locked for the entire configuration activation, during which time users cannot access them. Multi-threaded processing makes this time as short as possible. If one or more objects should fail to activate, SharePlex continues to activate the other ones. If SharePlex cannot obtain a lock on any table in the configuration, the entire activation will fail. To minimize the amount of time that users are locked out of tables, you can use a progressive activation. See Chapter 7 of the SharePlex Administrator’s Guide for more information.
CHAPTER 1 Using SharePlex Commands
23
Warning! If your application uses NOWAIT locking on tables that will be activated in a replication configuration, it could fail if it attempts to obtain a lock on a row or object that is being activated.
Using live activation When you synchronize data with an Oracle hot backup and the reconcile command, you can take advantage of live configuration activation by using the [live] option with the activate config command. Activation with the [live] option allows users to access the tables while the activation is taking place, so you need not quiet the database. Successful live activation is dependent upon running the reconcile command after the target database has been recovered on the target system, following the instructions in the synchronization procedure you are using. Warning! Live activation requires that the applications have retry logic. NOWAIT locking on tables in the replication configuration may cause the application to fail if it attempts to obtain a lock on an object that is being activated.
What to expect during live activation During live activation, SharePlex creates asynchronous, parallel processing threads to activate multiple tables simultaneously, while keeping track of row chaining. Replication of each table begins as soon as its activation is complete. Should one or more table fail to activate, SharePlex continues with the activation of the other tables. During live activation, SharePlex locks the tables as needed — at the beginning of the activation to get read consistency, and at the completion of the activation. For this reason, if an application uses NOWAIT locking on tables in the replication configuration, it could fail if it attempts to obtain a lock on an object being activated.
Other considerations when using live activation • Do not perform DDL, including TRUNCATE, during live activation. DML changes are the only permissible changes during live activation.
• Do not use live activation to reactivate tables to which an Oracle partition has been added. Activate newly partitioned tables by using default activation.
24
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Controlling the number of activation threads Multi-threaded activation is intended for systems with multiple processors. The SP_OCF_THREAD_COUNT parameter (see page 235) controls the default number of analysis threads. You can change the default number of threads by issuing the set param command for SP_OCF_THREAD_COUNT (see page 156), or you can override the default by using the [threads=n] option of the activate config command. The more threads, the higher the load on the system. Generally, there is a point of diminishing returns when there are more than 5 threads, regardless of the hardware configuration. Therefore, it is recommended that you use from 3 to 5 threads.
Changing the PROCESSES parameter Configuration activation creates the following number of database log-ons (LDAs) per thread:
• For the standard activation process, there are three log-ons per thread. • For live activation, there are four log-ons per thread. Before you activate a configuration, you might need to change the PROCESSES parameter in the init.ora file to accommodate the activation log-ons.
• For Oracle, the PROCESSES parameter should be set to the highest number of users expected to log onto the database at any given time.
• For SharePlex, add to the Oracle value the number of log-ons that the activation threads will generate, plus three more.
Verifying the configuration Before you activate a configuration, use the verify config command to confirm that basic requirements for successful activation and replication have been satisfied. The command alerts you to potential problems that can cause the activation to fail. See page 224 for more information.
Viewing configuration activation status SharePlex activates objects according to their object ID, not their order in the configuration file, so there is no way to predict the order of activation. You can use the show activate command on the source system to view activation statistics (see page 166).
CHAPTER 1 Using SharePlex Commands
25
Viewing results of the activation Because SharePlex continues with activation whether or not individual tables fail to activate, it alerts you when tables fail to activate by displaying the following error message at the sp_ctrl prompt: “WARNING, not all objects activated successfully. Check activation log.”
To view the results of activation:
• Issue the show config command (see page 173) Or...
• View the SID_oconf##.log file (SID is the ORACLE_SID of the datasource for the configuration). SharePlex prints activation status and error messages in this file, which resides in the log sub-directory in the SharePlex variable-data directory. Note: The activation log file name is comprised of three (3) components: the Oracle SID, the activation process identifier (oconf), and a log number. There may be more than one log, each being differentiated from the others by the log number.
The following is an excerpt from a SID_oconf##.log log for default activation: oconf 08-07-08 16:17:03.297156 str=11.1.0.0.0, int=111 oconf 08-07-08 16:17:03.404378 oconf 08-07-08 16:17:03.445080 file oconf 08-07-08 16:17:03.445225 oconf 08-07-08 16:17:03.850244 oconf 08-07-08 16:17:03.884861 oconf 08-07-08 16:17:04.158338 oconf 08-07-08 16:17:04.244146 oconf 08-07-08 16:17:04.244387 oconf 08-07-08 16:17:06.370400 oconf 08-07-08 16:17:06.546159 ging enabled oconf 08-07-08 16:17:06.796741 oconf 08-07-08 16:17:06.796823 oconf 08-07-08 16:17:06.796853 lock on "QARUN"."DEMO_SRC" oconf 08-07-08 16:17:07.335588 tion oconf 08-07-08 16:17:12.575705
23372 1 Oracle compatible parameter 23372 1 Parsing the configuration file 23372 1 Completed parsing the configuration 23372 1 New activation id 1348 23372 1 Building object cache 23372 1 Oracle version 111 23372 1 Finished building object cache 23372 1 Comparing object caches 23372 1 Completed comparing object caches 23372 1 Oracle supplemental logging is on 23372 1 Activation id 1348, supplemental log23372 1 Placing items in replication 23372 1 "QARUN"."DEMO_SRC": NEW, Type is T, 23372 1 DetLock: Attempting to do a non-wait 23372 1 Completed placing items in replica23372 1 Activation complete
26
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
What to do if activation fails Many things can cause the activation of a table or the entire configuration to fail, such as the following:
• Locking: Default activation uses NOWAIT locking, and if a lock cannot be obtained, the activation fails. Locks are tolerated by live activation.
• Syntax error: If one or more components in the configuration file were entered incorrectly, activation of the affected objects fails If you did not issue the verify config command before you activated, run it now, and correct any problems that it finds. Then, try activating again. If the configuration still does not activate, see “Solving configuration problems” on page 301. . Authorization level: Administrator (1) Issued for: source system abort config, copy config, create config, deactivate Related commands: config, edit config, list config, purge config, remove config, rename config, show activate, show config, verify config, view config
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
activate config filename
[threads=n] [live]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to activate. Configuration names are case-sensitive. Example: sp_ctrl(sysA)> activate config sales
CHAPTER 1 Using SharePlex Commands
27
Command options OPTION
DESCRIPTION
live
Use this option to activate a configuration when users are accessing the tables. When you use this option, you must issue the reconcile command (see page 138) after the target database has been recovered, according to the instructions for the synchronization procedure you are using. When used, this option must appear after the [threads=n] option, but it must precede any other command options in the syntax. Example: sp_ctrl(sysA)> activate config sales threads=3 live
threads=n
Use this option to control the number of analysis threads that the activation process generates. This option overrides the default value set by the SP_OCF_THREAD_COUNT parameter (see page 235). Multi-threaded activation The range of valid values for n is 1 to 32, but it is recommended that you use no more than 5 threads because the benefits of using threads generally diminish beyond that point. SharePlex will not start more threads than the number of tables to be analyzed. When used, this option must appear after the required command arguments, and it must appear before the [live] option. Examples: sp_ctrl(sysA)> activate config sales threads=3 sp_ctrl(sysA)> activate config sales threads=3 live
28
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
orainfo Use the orainfo command to view the Oracle database informationthe including the SID. The following is an example of the display: sp_ctrl (alvspxl11:2101)> orainfo Oracle instance #1: Oracle SID w111a64f Oracle HOME /oracle/products/111 Oracle Version 111 Oracle instance #2: Oracle SID ora111 Oracle HOME /oracle/products/111 Oracle Version 111 Oracle instance #3: Oracle SID ora11132f Oracle HOME /oracle/products/111 Oracle Version 111
The following will be displayed if ora_setup was not run and/or the statusdb disappeared and/or the command is executed from a version of SPO that doesn't support it. sp_ctrl (alvspxl11:2101)> orainfo Oracle information not available
Authorization level: Issued for: Related commands:
Viewer (3) source or target system none
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
orainfo
available
CHAPTER 1 Using SharePlex Commands
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
29
30
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
authlevel Use the authlevel command to determine your authorization level for issuing SharePlex commands on a system. The following is an example of the display: User is a viewer (level=3)
Authorization level: Issued for: Related commands:
Viewer (3) source or target system none
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
authlevel
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
31
clear status Use the clear status command to remove old warning messages from the Status Database. To use this command: 1 Issue the show statusdb detail command (see page 205) to find out which messages can be cleared. Clearable messages have a Yes in the Clear column. 2 If you don’t want to clear all messages, make a note of the status ID of each one that
you want to clear. 3 Issue the clear status command for each status ID, or use the all argument to remove
all clearable messages at once. SharePlex puts a message in the Event Log identifying the messages that were cleared. This command clears messages from the Status Database for the default system. To clear messages from a Status Database on a different system, use the [on host] option.
clear status The Status Database shows a single message, and when cleared it is evident that this message can’t be cleared from the status database. Some message can’t be cleared.
Authorization level: Issued for: Related commands:
Operator (2) source or target system show statusdb
32
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
clear status {statusID | all}
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
statusID
The SharePlex-assigned ID of an individual message (obtained using the show statusdb command) that you want to remove. Example: sp_ctrl(sysA)> clear status 20
all
This argument removes all clearable messages. Example: sp_ctrl(sysA)> clear status all
CHAPTER 1 Using SharePlex Commands
33
compare config Use the compare config command to compare the data in all of the source tables in a configuration file to the data in the corresponding target tables. This command also provides repair options that apply the SQL statements needed to bring out-of-sync target rows back into synchronization with the source rows.
How to use the compare config command Use the compare config command in the following ways:
• On a routine basis to detect and correct hidden out-of-sync conditions in target tables before they become large problems that require the tables to be resynchronized.
• To determine the cause of a problem when SharePlex returns out-of-sync errors and then repair out-of-sync rows. Important! Before you begin using this command, please review all of this documentation. Improper use could result in lost target data and out-of-sync conditions.
Tip: To compare the contents of an individual source table to its target table, see “compare table” on page 55.
What the compare config command supports The compare config command detects out-of-sync conditions in target tables that are caused by DML operations. It detects:
• extra or missing rows. • rows whose values do not match. Those conditions typically are caused by user-initiated DML operations or by automatic processes such as triggers or cascading deletes. Out-of-sync conditions resulting from DML on target objects can go undetected until the Post process attempts to post a change to the affected rows. Important! The compare config command supports configs that employ Oracle wilcards; however, if the set of objects indicated by the wildcard specification includes objects that are not presently in replication, the compare command will only compare those objects currently in replication. Please refer to the “Specifying source tables using
34
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5 wildcards” section of the SharePlex Administrator’s Guide for information on employing Oracle wildcards in a configuration file.
What the compare config command does not support The compare config command does not detect out-of-sync conditions caused by DDL operations, including those that SharePlex supports. However, once you correct an outof-sync condition caused by DDL, you can use the compare config command with a repair option to resynchronize the data in the rows. Do not use the compare config command for:
• configurations that replicate sequences. • tables for which transformation is being used. • network configurations in which a pass-through server is used to pass data between the source and target servers. Such objects are skipped and an error is logged to the compare log. Important! Running DDL on a table while it is being compared will cause the compare process to fail with the following error: Oracle Error: ORA-01466: unable to read data - table definition has changed
Overview of compare config command options Used without options, the compare config command compares data values in all of the columns in the tables, including the keys. The following options are available to optimize and customize the comparison process. These options are described in more detail later in this documentation.
• Use the [repair] option to resynchronize the source and target tables after the comparison.
• Use the [key] option to compare only the key columns in source and target tables, instead of all of the columns.
• Use the [key-repair] option to compare the key columns in source and target tables and repair all of the columns in rows whose keys do not match.
• Use the [quickcompare] option to obtain a quick determination of the existance of out-of-sync rows without an indication of where the out-of-sync is located. This option may NOT be used in conjunction with any repair, key or where options. This
CHAPTER 1 Using SharePlex Commands
35
option does NOT support LONG or LOB columns. This option does NOT log any out-of-sync row information to the compare client SQL file. Note: The port and sshport options and the sp_deq_ip_mapping parameter are no longer needed with SharePlex 7.5 as long as both the source and all targets are 7.5 (or above). If, however, either the source or at least one target is a version lower than 7.5, these options may still be necessary. Please refer to your SharePlex documentation for that release on their use.
Overview of compare config processes The compare config command initiates a multi-threaded process to compare multiple tables concurrently, with no limit on the number of tables.
The following is the sequence of events and an illustration of the processes: 1 The sp_cop process spawns an sp_desvr (server) process on the source system. 2 The sp_desvr process returns control of the sp_ctrl interface to the user, and repli-
cation continues while the command’s processes are working. 3 The sp_desvr process sends a message through the SharePlex queues and initiates
processing threads on the target system, the number of which is based on the value set by the SP_DEQ_THREADS parameter (see page 282). The default number of threads is 2. 4 Each thread spawns an sp_declt (client) process. 5 The server and client processes establish direct communication with each other, and
the processing load is divided between the client processes.
36
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
The compare config command does not affect the source tables in any way. SharePlex logs into Oracle only to query for read consistency, and the locks on the source tables are brief. SharePlex briefly locks the target tables during the comparison, but users can continue accessing them with little or no awareness of the lock. When a [repair] option is used, target tables are locked when it is their turn to be repaired, and then the lock is released.
Running concurrent compare processes You can issue multiple compare config commands at a time, for example to compare subsets of the active configuration (see “Comparing subsets of a configuration” on page 46). There is a limit to the number of concurrent comparison processes that you can run. A maximum of 20 SharePlex processes can read from, and write to, the post queue at the same time, including the replication processes and the compare processes. There is no practical way to determine how many compare processes can be running without exceeding this limit. Therefore, it is recommended that you allow a maximum of five compare processes to run at any given time. An entry similar to the following in the Event Log indicates that the maximum number of queue readers and writers has been exceeded, and that the offending compare process failed: “Can not add DataEquator queue reader, tried for 300 seconds. Error: que_TOOMANYUSERS: User table is full.” An error most likely will occur when a repair option is used, because a repair accesses the queue much longer than a basic compare process.
Using the compare cancel id command The compare cancel id command is used to stop a running compare process. This command can be issued any time you are running a compare config or compare table operation. To stop a running compare operation, issue the following command: sp_ctrl(sysA)> compare cancel id PID
Identifying compare config processes Compare processes are identified in two ways.
CHAPTER 1 Using SharePlex Commands
37
Session ID Because multiple compare config commands can run concurrently, SharePlex keeps track of the processes for each one by assigning them a session ID number that corresponds to the operating-system-assigned process ID (PID) of the sp_desvr process. The session ID is reflected in the show compare command output and in the logs.
Process ID On UNIX systems, the operating-system PID of the sp_desvr and sp_declt processes are displayed by the status and lstatus commands, as shown in this illustration.
The compare server process (sp_desvr) on the source system shown with the status command
On Windows systems, each sp_desvr and sp_declt process has an associated sp_cop process. The lstatus and status commands display the PID of the sp_cop process, not the actual PID of the sp_desvr or sp_declt process.
Viewing compare config status and results The best way to view the status or results of one or more compare processes is to use the show compare command in sp_ctrl.
• The basic command displays the processing status of all compare config and compare table processes on a system.
• Additional command options display statistics for each table that was compared, as well as an option to view a compare report for each of the compared tables. The compare report contains the SQL statements required to bring a target table back into synchronization (or those that were applied by the repair process). It also can be configured with the SP_DEQ_LOG_ROWID parameter to show the row ID of each source row.
38
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
For more information about using the show compare command, see page 173. For more information about the SP_DEQ_LOG_ROWID parameter, see page 277.
You can view compare reports directly from the log sub-directory of the SharePlex variable-data directory on the target system. The compare report file naming convention is: sid_schema-table-sessionID.sql, where:
• • • •
sid is the ORACLE_SID of the associated Oracle instance. schema_name is the name of the target table’s schema. table_name is the name of the target table. sessionID is the SharePlex-assigned session identifier for the compare session.
Example compare report file name: j102a32f_SP_IOT-IOT_BASIC-21744.sql
Sample compare report file /* * Compare Report * * Session ID : 21744 * Schema : SP_IOT * Table : IOT_BASIC * Repair : Off * Target Route: alvlabl17@j102a32f * Key Compare : Off * Select Hint : * Log File : /splex/SharePlex-6.0.0.65/var10/log/j102a32f_SP_IOTIOT_BASIC-21744.sql * Date : Tue May 15 09:19:28 2007 * */ /* * Compare Results * * 440 source and 440 target rows compared successfully (L320). * No out-of-sync rows were found in this table. * * Inserts : 0 * Updates : 0 * Deletes : 0 * */
CHAPTER 1 Using SharePlex Commands
39
Viewing compare config logs SharePlex logs notices, warnings, and errors for each compare session in a log file in the log sub-directory of the SharePlex variable-data directory on both systems. There is a log file for the sp_desvr process on the source system, and there is a log for each associated sp_declt process on the target system. The file name differs depending on which process you are looking at. The file name for the sp_desvr process is SID_desvr-sessionID-log#.log, where:
• SID is the ORACLE_SID of the Oracle instance associated with the process. • sessionID is the SharePlex-assigned session identifier for the compare session. • log# is the log number in the series. The file name for the sp_declt process is SID_declt-schema-table-sessionID-log#.log, where:
• • • • •
SID is the ORACLE_SID of the Oracle instance associated with the process. schema is the name of the target table’s schema. table is the name of the target table. sessionID is the SharePlex-assigned session identifier for the compare session. log# is the log number in the series.
SharePlex creates logs in a circular fashion to control its disk usage. When the maximum log size is reached, as determined by an internal parameter, SharePlex generates another log file until the number of logs reaches an internal limit. At that point, the logs wrap (just like the Oracle redo logs wrap), and the oldest log is replaced with a new one. Subsequent logs wrap as well, maintaining the number of logs at or below the limit value. For the compare config command, there rarely is more than one log file. Example log file names: w102a64f_desvr-13942854-01.log a102a64f_declt-SP_DDL_ALL-QA_DDL_TAB_2-13942854-01.log
Sample sp_desvr log file The sp_desvr log contains log information for all tables affected by the compare config command. The following example has been truncated to show just the first table. FILE: /splex/SharePlex-6.0.0/var10/log/a102a64f_desvr-21744-01.log DATE: Tue May 15 10:07:57 2007 000: Read Buffer Size: 1048576 bytes ( 1 mbytes) 000: Debug flag: 0x00000000
40
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
000: 5460382473338/splex/SharePlex-6.0.0.65a102a64f/opt10/bin/sp_desvr 000: DEBUG:pthread stack size=4096, status=0 (main,L1158) 000: Notice: SP_DEQ_NLS_SELECTOR = 0 (DB) (de_trans_set_nls_lang,L1849) 000: Threads used: 2 000: Notice: ORACLE_HOME=/u01/app/oracle/product/10.2.0/db_2 (main,L1286:de_internal_getenv,L1439) 000: Notice: ORACLE_SID=a102a64f (main,L1287:de_internal_getenv,L1439) 000: OS Version : SunOS 5.10 Generic_118855-36 000: Machine : i86pc 000: Server Message: 0x0006 000: Server Message: OS Version : SunOS 5.10 Generic_118855-36 (LITTLE) 000: Server Message: Machine : i86pc 000: Server Message: SharePlex Version 6.0.0.115 000: Server Message: SharePlex Lib Version 6.0.0.115 000: Processing Hori. Partition statement: 000: sp_iot.IOT_INCLUDE_OVERFLOW sp_iot.IOT_INCLUDE_OVERFLOW !iot_include_overflow 000: Processing Vert. Partition statement: 000: sp_iot.IOT_BASIC (work_date, employee_no, dash, class_code, paycode, SHIFT_DIFFERENTIAL, HOURS) sp_iot.IOT_BASIC (work_date, employee_no, dash, class_code, paycode, SHIFT_DIFFERENTIAL, HOURS)
[email protected] 000: NOTE: pthread_self_id=1 (de_thrdmgr_main,L2263) 000: Notice: SP_DEQ_TIMEOUT set to 3600 000: COMPARE CURRENT STATUS:Tue May 15 10:07:58 2007 , Thread started (de_thrdmgr_main,L2264:de_log_line,L301) 000: NOTE: pthread_self_id=2 (de_thrdmgr_main,L2263) 000: Oracle Session Id = 327, Serial# = 30298 000: Notice: Job ID = 10036 (de_oci_getResultSeqNum,L1656) 000: Notice: DB NLS_LANG=AMERICAN_AMERICA.AL32UTF8 (de_trans_ora_logon,L988) 000: Oracle Session Id = 327, Serial# = 30303 000: Oracle Session Id = 307, Serial# = 40856 000: COMPARE CURRENT STATUS:Tue May 15 10:07:59 2007 , Thread started (de_thrdmgr_main,L2264:de_log_line,L301) 000: Oracle Session Id = 122, Serial# = 42017 000: Oracle Session Id = 326, Serial# = 23028 001: Oracle Database 10g Enterprise Edition Release 10.2.0.1.0 - Production With the Partitioning and Data Mining options 000: Notice: DB CSID (AL32UTF8,873) is set. (de_oci_coreSetCSIDs,L1253:de_oci_setCSIDs,L1427) 000: Notice: DB NCSID (AL16UTF16,2000) is set, NCHAR LEN=2 (de_oci_coreSetCSIDs,L1248:de_oci_setCSIDs,L1432) 000: Notice: DEQ CSID (JA16EUC,830) is set. (de_oci_coreSetCSIDs,L1253:de_oci_setCSIDs,L1451) 000: Notice: DEQ NCSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1456) 000: Notice: use SP_DEQ_CHARACTERSET id 830, encoded 830 (de_oci_determineFinalCSID,L1305) 000: Notice: use DB NCHAR CHARACTERSET id 2000 (de_oci_determineFinalCSID,L1358) 000: Notice: use NCHAR Character length = 2 (de_oci_determineFinalCSID,L1365) 001: Notice: Object ID of "SP_IOT"."IOT_BASIC" is 747414 001: Skip LOB column(s) : Off
CHAPTER 1 Using SharePlex Commands
41
001: Log source rowid : On 001: NOTE: rowid size = 4096 for IOT table (de_table_process_iot,L2496) 001: Table is veritcal partitioned 001: LONG column in VP table, swapping DASH with SUMMIT_WORK_ORDER_NO 001: LONG column in VP table, swapping CLASS_CODE with DASH 001: LONG column in VP table, swapping PAYCODE with CLASS_CODE 001: Notice: Object ID of "SP_IOT"."IOT_BASIC" is 747414 001: some nullable column(s) marked as key in object cache, use all column(s) as key instead (de_table_find_key_cols,L1000) 001: NOTE: Using all columns as key for table 747414 (de_table_mark_all_columns_as_key,L795) 001: Session ID : 21744 001: Source Data : a102a64f 001: Source Table: "SP_IOT"."IOT_BASIC" 001: Source Node : alvlabu18 001: Target Table: "SP_IOT"."IOT_BASIC" 001: Target Route: alvlabl17.quest.com@j102a32f 001: Target Node : alvlabl17.quest.com 001: Batch Size : 10000 rows 001: Repair : Off 001: Key Compare : Off 001: Port Number : 53441 001: Select Hint : 001: Order By : 001: COMPARE CURRENT STATUS:Tue May 15 10:07:59 2007 (elapsed 1.396424 seconds), ready to do non timed-wait table lock. (de_trans_get_read_consistent_view,L1430:de_log_line,L301) 001: COMPARE CURRENT STATUS:Tue May 15 10:07:59 2007 (elapsed 0.004113 seconds), got lock & ready to get consistent view. (de_trans_get_read_consistent_view,L1449:de_log_line,L301) 001: COMPARE CURRENT STATUS:Tue May 15 10:07:59 2007 (elapsed 0.000444 seconds), got consistent view. (de_trans_get_read_consistent_view,L1458:de_log_line,L301) 001: COMPARE CURRENT STATUS:Tue May 15 10:07:59 2007 (elapsed 0.000015 seconds), table unlocked (conn2) & ready to select count rows. (de_thrdmgr_sub_main,L1466:de_log_line,L301) 001: COMPARE CURRENT STATUS:Tue May 15 10:07:59 2007 (elapsed 0.007506 seconds), done counting rows & ready to insert compare marker. (de_thrdmgr_sub_main,L1471:de_log_line,L301)
42
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Sample sp_declt log file There is a sp_declt log file for each pair of tables compared with the compare config command. The following is a sample log. FILE: /splex/SharePlex-6.0.0/var10/log/j102a32f_declt-SP_IOT-IOT_BASIC-2174401.log DATE: Tue May 15 09:19:25 2007 000: Debug flag: 0x00000000 000: 3929275259 3314 /splex/SharePlex-6.0.0.65/opt10/bin/sp_declt 000: Notice: ORACLE_HOME=/u01/app/oracle/product/10.1.0/db_1 (main,L1710:de_internal_getenv,L1439) 000: Notice: ORACLE_SID=j102a32f (main,L1711:de_internal_getenv,L1439) 000: OS Version : Linux 2.6.9-11.EL #1 Fri May 20 18:17:57 EDT 2005 000: Machine : i686 000: Notice: SP_DEQ_NLS_SELECTOR = 0 (DB) (de_trans_set_nls_lang,L1849) 000: Oracle Session Id = 299, Serial# = 42075 000: Notice: DB NLS_LANG=JAPANESE_JAPAN.JA16EUC (de_trans_ora_logon,L988) 000: Oracle Session Id = 299, Serial# = 42077 000: Oracle Session Id = 317, Serial# = 1079 000: Oracle Database 10g Enterprise Edition Release 10.2.0.1.0 - Production With the Partitioning, OLAP and Data Mining options 000: Notice: DB CSID (JA16EUC,830) is set. (de_oci_coreSetCSIDs,L1253:de_oci_setCSIDs,L1427) 000: Notice: DB NCSID (AL16UTF16,2000) is set, NCHAR LEN=2 (de_oci_coreSetCSIDs,L1248:de_oci_setCSIDs,L1432) 000: Notice: OPO CSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1440) 000: Notice: OPO NCSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1445) 000: Notice: DEQ CSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1451) 000: Notice: DEQ NCSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1456) 000: Notice: use DB CHARACTERSET id 830 (de_oci_determineFinalCSID,L1350) 000: Notice: use DB NCHAR CHARACTERSET id 2000 (de_oci_determineFinalCSID,L1358) 000: Notice: use NCHAR Character length = 2 (de_oci_determineFinalCSID,L1365) 000: Client Message: 0x0006 000: Client Message: OS Version : Linux 2.6.9-11.EL #1 Fri May 20 18:17:57 EDT 2005 (LITTLE) 000: Client Message: Machine : i686 000: Client Message: JA16EUC 000: Client Message: AL16UTF16 000: Client Message: SharePlex Version 6.0.0.115 000: Client Message: SharePlex Lib Version 6.0.0.115 000: Server Message: 0x0006 000: Server Message: OS Version : SunOS 5.10 Generic_118855-36 (LITTLE) 000: Server Message: Machine : i86pc 000: Server Message: SharePlex Version 6.0.0.115 000: Server Message: SharePlex Lib Version 6.0.0.115 000: COMPARE CURRENT STATUS:Tue May 15 09:19:27 2007 , ready to do non timedwait table lock. (de_trans_get_read_consistent_view,L1430:de_log_line,L301)
CHAPTER 1 Using SharePlex Commands
43
000: COMPARE CURRENT STATUS:Tue May 15 09:19:27 2007 (elapsed 0.010074 seconds), got lock & ready to get consistent view. (de_trans_get_read_consistent_view,L1449:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:19:27 2007 (elapsed 0.007243 seconds), got consistent view. (de_trans_get_read_consistent_view,L1458:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:19:27 2007 (elapsed 0.000160 seconds), removed semaphore, poster lock file. & ready to select count rows (conn1). (main,L2083:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:19:28 2007 (elapsed 1.024283 seconds), done with row count. (main,L2087:de_log_line,L301) 000: Notice: Reducing batch from 10000 to 440 (main,L2158) 000: NOTE: use new numeric compare flag is ON 000: Key Compare : Off 000: Notice: client qualified rows count = 440 000: Notice: client total rows count = 440 000: Session ID : 21744 000: Source Table: "SP_IOT"."IOT_BASIC" 000: Source Node : alvlabu18.quest.com 000: Target Table: "SP_IOT"."IOT_BASIC" 000: Target Route2: alvlabl17@j102a32f 000: Batch Size : 440 rows 000: Repair : Off 000: Source Port : 53441 000: Select Hint : 000: sp_declt PID: 29949 000: Read Buffer Size : 1 mbytes 000: No new key column order, using default column order for SP_IOT.IOT_BASIC 000: running sql statement : (de_select_prepare_to_fetch,L1525) 000: select rowid,"WORK_DATE","EMPLOYEE_NO","DASH","CLASS_CODE","PAYCODE","SHIFT_DIFFERENTIAL","HOURS" from "SP_IOT"."IOT_BASIC" order by 2, 3, 4, 5, 6, 7, 8 000: COMPARE CURRENT STATUS:Tue May 15 09:19:28 2007 (elapsed 0.074330 seconds), ready to fetch first batch, including the order by sorting. (de_batch_setup,L1102:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:19:28 2007 (elapsed 0.007571 seconds), got first batch (de_batch_setup,L1117:de_log_line,L301) 000: SP_DEQ_PART_UPDATE : 0 000: Notice: Object ID of "SP_IOT"."IOT_BASIC" is 876751 000: Exiting without any errors 000: Status : In Sync
Removing old compare reports and logs To remove old compare reports and logs from a system, use the remove log compare command (see page 144).
44
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Repairing out-of-sync rows To repair out-of-sync rows found by a basic comparison (without the [key] option), use the [repair] option. The following summarizes your choices when deciding how and when to use the [repair] option.
• The recommended procedure is to run the compare config command without the [repair] option first, then view the results with the show compare command to find out if (or which) tables are out-of-sync and the possible cause. Unless the problem is corrected, replication probably will go out of synchronization again. After the problem is fixed, either re-issue the compare config command with the [repair] option or use the compare table command with the [repair] option for individual tables (see page 55). Or...
• You can run the compare config command with the [repair] option without doing a preliminary comparison. See “Solving synchronization problems” on page 311 for causes and solutions for out-ofsync conditions.
When to run the repair The best time to repair target tables depends on their size, the cause of the problem, the extent of out-of-sync rows, and how long you are willing to tolerate users being locked out. Before you initiate a repair, consider the following:
• Although users are not affected by locks when tables are compared, they are locked out of a target table for the duration of its repair process. For a small table, this might not be disruptive, but for a large table needing extensive repairs, the wait can be significant.
• Locks on a target table can impede the Post process if Post must wait for the repair to finish before it can apply changes to that table and move on to other tables. This can increase the latency of the target data and cause operations to accumulate in the post queue. (Note: If the objects Post needs to change are different than those being processed by the compare config command, the two processes can run simultaneously.)
• If you must repair a table immediately, but cannot tolerate locks or replication latency, you can use the [key-repair] option, keeping in mind that all of the out-ofsync rows might not be detected and repaired. For more information, see “Comparing only the key values” on page 47.
CHAPTER 1 Using SharePlex Commands
45
• If the repair can wait, you can correct the cause of the problem immediately, then do the repair during non-peak hours. Tip: You can make one or more copies of the active configuration, and then edit them to contain the smaller tables being replicated. These copies can be kept available for issuing global compares and repairs with the compare config command as needed. Larger tables can be compared and repaired on an individual basis using the compare table command when they are less in demand.
How repairs are made The [repair] option issues the following corrective SQL statements:
• If a row exists on the source side but not the target side, SharePlex issues an INSERT statement.
• If a row exists on the target side but not the source side, SharePlex issues a DELETE statement.
• If a target row differs from the source row, and the key columns match, SharePlex issues an UPDATE statement based on the source values.
• If you are using the [repair] option for a partitioned table, the default behavior of the repair process is to repair rows by using INSERTs and DELETEs only. Repairs requiring UPDATEs are converted to a DELETE followed by an INSERT to prevent errors should an UPDATE cause a row to change partitions and row movement is not enabled for the table. You can change the repair behavior so that SharePlex repairs partitioned tables by using INSERTs, UPDATEs, and DELETEs as appropriate. For more information, see the SP_DEQ_PART_TABLE_UPDATE parameter on page 280.
How repair errors are handled If SharePlex encounters an Oracle error when it applies a repair SQL statement, it stops the repair from that statement forward and commits only the previously applied valid statements. Thus, the table is partially repaired, but it still could be out of synchronization. The show compare command with the [detail] option alerts you to this situation. To determine where the error occurred and which rows were repaired successfully, view the compare report by issuing the show compare command with the [report] option. SharePlex prints the following error message in the compare report immediately after
46
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
the statement for which the error occurred, and it summarizes the repair results at the end of the report. /* * The following Oracle error occurred while repairing. * * * The SQL statement immediately above, and all the statements * following this message will not be applied. */
Comparisons when there are multiple target systems The compare config command compares each source table in a configuration to all of its target tables on all target systems. To limit a comparison to specific target tables or systems, you can make one or more subsets of the active configuration and list the tables and routes that you want to use.
Comparing subsets of a configuration You can compare subsets of an active configuration by making one or more copies of the configuration and running the compare config command for the copies. For example, you can create copies based on schemas or routes. Tables and routes in the subsets must also be contained in the active configuration. To compare a subset of a configuration, do the following without deactivating the active configuration: 1 Copy the active configuration with the copy config command.
sp_ctrl(sysA)> copy config filename to newname 2 Edit the copy with the edit config command to exclude tables or routes that you do
not want to compare. sp_ctrl(sysA)> edit config newname 3 Save the new configuration. 4 Repeat these steps for each subset configuration that you want to create. 5 Issue the compare config command for one or more configuration subsets, but do
not activate them, and do not deactivate the original configuration.
CHAPTER 1 Using SharePlex Commands
47
Comparing and repairing dissimilar source and target tables The compare config command can be used for target tables that have more columns than their source tables, but the command ignores target columns that are not contained in the source table. A repair does the following:
• An INSERT inserts values into target columns that have corresponding columns in the source table, but not into the extra columns. Columns with NOT NULL constraints but no default values cause Oracle errors. Default values are recommended for extra columns in target tables.
• An UPDATE resynchronizes values in target columns that have corresponding columns in the source table, but not the values in the extra columns.
• A DELETE is not affected by extra columns in the target table, because the compare table command selects rows based on column data in the matching columns.
Comparing only the key values For a faster comparison, you can use the [key] option to compare only the key columns in source and target rows instead of all of the columns. Use it for fast comparisons of large tables to ensure that the same rows exist in both databases. If key values match, the rows are considered synchronized. To restore synchronization to rows where key values do not match, use the [key-repair] option. This option compares a row’s key columns but repairs the values in all of the columns, based on the source table’s values. Use these options with caution and only as a first-level solution. They might not detect all of the out-of-sync conditions. Even though key values match, it is possible for values in non-key columns to be out-of-sync.
Comparing tables that have LONG columns SharePlex for Oracle has no size constraint when comparing tables with a LONG or LONG RAW column. Compare/Repair supports the maximum LONG column size, currently 2 GB, that Oracle can support.
48
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Comparing tables that have LOB columns SharePlex for Oracle command supports tables with LOB columns when the SP_DEQ_SKIP_LOB parameter is set to 0 when employing the compare config command. For more information about the SP_DEQ_SKIP_LOB parameter, see page 281.
To log row IDs for manual repair of LOBs When you need to know the source row ID in order to manually repair target LOB columns, set the SP_DEQ_LOG_ROWID parameter on the source system to 1. Enabling this parameter directs SharePlex to log the source row IDs for all rows that are inserted or updated in the target tables. For more information about the SP_DEQ_LOG_ROWID parameter, see page 277.
Using the compare config command with DDL replication When the compare process starts, it acquires a read-consistent view of the table, gets the table definition, and parses SQL to SELECT from the table. If the table definition is modified by executing DDL after the compare process determines the table definition and parses the SELECT SQL, then the following error will occur when compare tries to SELECT from the table: Oracle Error: ORA-01466: unable to read data - table definition has changed
Therefore, do not run DDL on a table while it is being compared.
Repairing columns that have UNIQUE constraints Columns that have a UNIQUE constraint can cause unique-constraint violation errors when you use a repair option. The following example illustrates why. This example shows source and target tables with two columns each. The first column is the primary key, and the second column has the UNIQUE constraint. Source Table
Target Table
111
ABC
111
XYZ
222
XYZ
222
ABC
When SharePlex attempts to repair the target table, the UNIQUE constraint on column 2 returns an error for the repair on row 1, because the value ABC already exists in row 2 of
CHAPTER 1 Using SharePlex Commands
49
the target table. The same thing happens when SharePlex updates row 2 of the target table, because the value XYZ already exists in row 1. The workarounds are:
• Disable UNIQUE constraints on the target tables before you run a compare config command with a repair option, then re-enable them afterward. Or ...
• Manually delete the target rows for which the unique constraint violations occurred, and then re-run the repair so that SharePlex inserts the rows with the correct data.
Using compare config with consolidated replication Do not use the compare config command when any of the source tables are part of a consolidated replication environment. The compare config command will cause unwanted deletion of target rows that do not exist in those source tables. As a workaround, create a subset of the configuration that excludes the tables involved in consolidated replication, and compare the subset configuration instead. You can use the compare table command to compare the tables that are involved in consolidated replication. See for more page 55 information.
Using compare config with partitioned replication When tables in a configuration use partitioned replication, the compare config command determines the rows and columns to compare by reading the configuration file and, for horizontally partitioned replication, the column conditions in the SHAREPLEX_PARTITION table.
• For vertically partitioned tables where source and target column names are different, the compare config command maps the source columns to the target columns.
• For horizontally partitioned replication, the compare config command reads the column conditions for the source table and selects rows for the source and target tables based on those conditions. Rows and columns that are excluded from replication are not compared or repaired.
50
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Using compare config with peer-to-peer replication To use the compare config command in a peer-to-peer replication environment, decide which system is the trusted source system — the one with the valid data — and which are the target, or secondary, systems containing data that will be repaired, if needed. Before you run the comparison, follow these steps: 1 Stop user access on the target systems and wait for replicated operations to post to
the source database. Users can continue to access the source database. 2 Issue the qstatus command on the source and target systems. (For more information about the qstatus command, see page 135). 3 When there are 10 or fewer messages in the queues, run the compare config com-
mand on the source system. 4 Do one of the following:
• For comparisons without a repair, you can permit user access to all databases after the sp_desvr and sp_declt processes have started.
• For comparisons with a repair, make the users wait until a table’s repair is finished before permitting access to that table.
Using compare config to fix Post reported out-of-syncs This option can only be employed after enabling and setting up Generic Conflict Resolution. See “Using generic conflict resolution” on page 206 in the Shareplex Administrator’s Guide. 1 Set-up Generic Conflict Resolution. 2
If you have not already done so, set the value of parameter SP_OPO_GENERIC_CR to 1, and stop and start the Post to activate this new parameter.
3
Run compare with the reported oos option.
Controlling the number of processing threads To take advantage of machines with multiple processors, you can set the number of compare processing threads on the source system with the SP_DEQ_THREADS parameter. The default number of threads is two threads, and the range of valid values is from one thread to 15.
CHAPTER 1 Using SharePlex Commands
51
With multi-threaded processing, there is additional load on the system. Regardless of the system configuration, there will be a point where additional threads provide no added benefit. Generally, two to five threads should be sufficient, but for machines with one processor, use a value of 1. For more information about the SP_DEQ_THREADS parameter, see page 282.
Controlling the batch size The default batch (block) size for comparisons is 10,000 rows. A larger or smaller batch size might be required for your comparisons, depending on the size and volume of your tables and your system resources. To change the batch size, change the value of the SP_DEQ_BATCHSIZE parameter. If the value of SP_DEQ_BATCHSIZE is larger than the number of rows in the source table being compared, SharePlex reduces the batch size to the number of rows in the table. This prevents SharePlex from allocating more space than necessary for the compare processes. For more information about this parameter, see page 276.
Other conditions and requirements for using compare config • All SharePlex processes (Capture, Read, Export, Import, Post) must be running when you issue the compare config command, and they must remain running throughout the compare and repair processes.
• The success of the compare config command depends on the activity on the source system. Because the command relies on the replication queues to spawn the sp_declt process on the target system, and because SharePlex forwards data (including the compare config command) in the order in which it is received, the compari-
son cannot start until all previous messages in the queues have been processed. If a delay causes the compare process to lose its read consistency, the command returns an error. To avoid errors, consider doing comparisons during non-peak hours.
• The tables that you want to compare must be currently replicating. • Large open transactions (without a COMMIT) on a source table prevent the compare process from obtaining the brief lock it needs to obtain read consistency. The command attempts the lock several times and then returns an error if it is unsuccessful. Make sure that transactions are committed before issuing a compare config command.
• The compare process skips tables for which a SharePlex key definition is defined. For more information about key definitions, see the SharePlex Administrator’s Guide.
52
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• Do not use the compare config command in a cascading replication environment. • Do not truncate a table that is being compared. The compare config command takes a snapshot of the source table when it starts, and if the table is truncated, the table view in the snapshot also is truncated. This can result in invalid out-of-sync rows being found on the target system.
• Make certain your applications use Oracle JDBC driver classes 8.0.5 or above. JDBC driver classes below version 8.0.5 permit improper date formats, which adversely affect sorts used by the compare processes. Authorization Level: Issued on: Related commands:
Operator (2) source system compare table, show compare, remove log compare
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
compare config filename
[key | key-repair] [quickcompare] [repair] [reported oos]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14. Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration file containing the tables to be compared. Configuration names are case-sensitive. Example: sp_ctrl(SysA)> compare config sales
CHAPTER 1 Using SharePlex Commands
53
Command options OPTION
DESCRIPTION
key
Use this option to compare (but not repair) only the PRIMARY or UNIQUE key columns. Use it for fast comparisons of large tables to verify that the same rows exist in both databases. Important: When key values match (so the rows are considered synchronized), but values in other columns do not, the tables remain out of synchronization. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Do not use this option to compare based on a SharePlex key definition. For more information about key definitions, see the SharePlex Administrator’s Guide. Do not use this option with the [repair] option. To base a comparison on key columns and then repair out-of-sync rows, use the [key-repair] option. Example: sp_ctrl(SysA)> compare config sales key
key-repair
Use this option to compare only the PRIMARY or UNIQUE key columns and, when keys do not match, repair all of the columns based on the source table’s values. Important: When key values match (so the rows are considered synchronized) and values in other columns do not (but are not repaired), the tables remain out of synchronization. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Do not use this option to compare based on a SharePlex key definition. For more information about key definitions, see the SharePlex Administrator’s Guide. To base a comparison on key columns without doing a repair, use the [key] option. Example: sp_ctrl(SysA)> compare config sales key-repair
quickcompare
Use this option to obtain a quick determination of the existance of out-ofsync rows without an indication of where the out-of-sync is located. This option may NOT be used in conjunction with any repair, key or where options. This option does NOT support LONG or LOB columns. This option does not log any out-of-sync row information to the compare client SQL file.
54
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
repair
Use this option to repair out-of-sync target tables. It repairs all of the columns in the out-of-sync rows, based on the source table’s values. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Do not use this option with the [key] option. Example: sp_ctrl(SysA)> compare config sales repair
reported oos
Use this option to repair rows reported out-of-sync by Post and recorded in the internal tables. This option can only be employed after enabling and setting up Generic Conflict Resolution. See “Using generic conflict resolution” on page 206 of the Shareplex Administrator’s Guide. When the reported oos option is specified in the command line, it will automatically default to the repair option. In addition, it will override the other compare options, such as key and key-repair. sp_ctrl(SysA)> compare config sales reported oos
CHAPTER 1 Using SharePlex Commands
55
compare table Use the compare table command to verify that a target table is in synchronization with its source table. This command also provides repair options that apply the SQL statements needed to bring out-of-sync target rows back into synchronization with the source rows.
How to use the compare table command Use the compare table command in the following ways:
• On a routine basis to detect and correct hidden out-of-sync conditions in target tables before they become large problems that require the tables to be resynchronized.
• To determine the cause of a problem when SharePlex returns out-of-sync errors and then repair out-of-sync rows. Important! Before you begin using this command, please review all of this documentation. Improper use could result in lost target data and out-of-sync conditions.
What the compare table command supports The compare table command detects out-of-sync conditions in a target table that are caused by DML operations. It detects:
• extra or missing rows • rows whose values do not match. Those conditions typically are caused by user-initiated DML operations or by automatic processes such as triggers or cascading deletes. Out-of-sync conditions resulting from DML on target objects can go undetected until the Post process attempts to post a change to the affected rows.
What the compare table command does not support The compare table command does not detect out-of-sync conditions caused by DDL operations, including those that SharePlex supports. However, once you correct an outof-sync condition caused by DDL, you can use the compare table command with a repair option to resynchronize the data in the rows.
56
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Do not use the compare table command to compare:
• replicated sequences. • tables for which transformation was used. • network configurations in which a pass-through server is used to pass data between the source and target servers. Such objects are skipped and an error is logged to the compare log. Important! Running DDL on a table while it is being compared will cause the compare process to fail with the following error: Oracle Error: ORA-01466: unable to read data - table definition has changed
Important! The compare table command does NOT support use of Oracle wilcards.
Overview of compare table command options Used without options, the compare table command compares data values in all of the columns, including the keys, and it detects missing or extra rows in the target table. The following options are available to optimize and customize the comparison process. These options are described in more detail later in this documentation.
• Use the [where “clause”] option to use a standard SQL WHERE clause to restrict the comparison to certain rows. This option is useful for focusing on specific records and in partitioned and consolidated replication, where source and target tables usually have different structures.
• Use the [sourcewhere “clause”] to use a standard SQL WHERE clause when there are one or more extra columns in the source table whose values make a row unique.
• Use the [targetwhere “clause”] to use a standard SQL WHERE clause when there are one or more extra columns in the target table whose values make a row unique. This option is useful in partitioned and consolidated replication.
• Use the [hint “hint”] option to use a standard Oracle hint to make the selection of rows more efficient — such as specifying an index.
• Use the [orderby “column_list”] option to specify columns for the compare table command’s ORDER BY clause, which helps when a table has no PRIMARY or UNIQUE NOT NULL key.
• Use the [repair] option to resynchronize the source and target tables after the comparison.
CHAPTER 1 Using SharePlex Commands
57
• Use the [key] option to compare only the key columns in source and target tables instead of all of the columns.
• Use the [key-repair] option to compare only the key columns and repair all of the columns in rows whose keys do not match.
• Use the [quickcompare] option to obtain a quick determination of the existance of out-of-sync rows without an indication of where the out-of-sync is located. This option may NOT be used in conjunction with any repair, key or where options. This option does NOT support LONG or LOB columns. This option does NOT log any out-of-sync row information to the compare client SQL file. Note: The port and sshport options and the sp_deq_ip_mapping parameter are no longer needed with SharePlex 7.5 as long as both the source and all targets are 7.5 (or above). If, however, either the source or at least one target is a version lower than 7.5, these options may still be necessary. Please refer to your SharePlex documentation for that release on their use.
Overview of compare table processes The compare table command initiates the following sequence of events: 1 The sp_cop process spawns a sp_desvr (server) process on the source system. 2 The sp_desvr process returns control and use of the sp_ctrl interface to the user,
and replication continues while the command’s processes are working. 3 The sp_desvr process sends a message through the SharePlex queues from Capture to Post and initiates a sp_declt (client) process on the target system. 4 The server and client processes establish direct communication with each other and
start processing. The compare table command does not affect the source table in any way. SharePlex logs into Oracle only to query for read consistency, and the lock on the source table is brief. SharePlex briefly locks the target table during the comparison, but users can continue accessing it with little or no awareness of the lock. When a [repair] option is used, the target table is locked for the duration of the repair, and then the lock is released.
58
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Comparing a partition (or sub-partition) To compare a partition (or a subpartition) use the following syntax. Please note that comparison of partitions (and subpartitions) is only supported with the compare table functionality. In the example that follows partition_name can be a partition or subpartition name. sp_ctrl(sysA)> compare table owner.source_table@partition_name to owner.target_table@partition_name target
[email protected]_SID
Comparing multiple tables You can compare more than one set of source and target tables at a time by issuing multiple compare table commands, either through sp_ctrl or in a script. As an alternative, you can compare all of the tables in a configuration by using the compare config command (see page 33). There is a limit to the number of concurrent comparison processes that you can run. A maximum of 20 SharePlex processes can read from, and write to, the post queue at the same time, including the replication processes and the compare processes. There is no practical way to determine how many compare processes can be running without exceeding this limit. Therefore, it is recommended that you allow a maximum of five compare processes to run at any given time, or use the compare config command to compare an entire configuration. An entry similar to the following in the Event Log indicates that the maximum number of queue readers and writers has been exceeded, and that the offending compare process failed: “Can not add DataEquator queue reader, tried for 300 seconds. Error: que_TOOMANYUSERS: User table is full.” An error most likely will occur when a repair option is used, because a repair accesses the queue much longer than a basic compare process. Tip: SharePlex provides the edit command for editing the previously issued command. This can reduce keystrokes when you issue another compare table command for the same datasource and target system. See page 107 for more information about the edit command. SharePlex also provides keyboard shortcuts for the edit command in the for of the up arrow ( ) and the forward slash ( / ) keys.
CHAPTER 1 Using SharePlex Commands
59
Stopping a running compare operation The compare cancel id command is used to stop a running compare process. This command can be issued any time you are running a compare config or compare table operation. To stop a running compare operation, issue the following command: sp_ctrl(sysA)> compare cancel id PID
Identifying compare table processes Compare processes are identified in two ways.
Session ID Because multiple compare table commands can run concurrently, SharePlex keeps track of the processes for each one by assigning them a session ID number that corresponds to the operating-system-assigned process ID (PID) of the sp_desvr process. The session ID is reflected in the show compare command output and in the logs.
Process ID On UNIX systems, the operating-system PID of the sp_desvr and sp_declt processes are displayed by the status and lstatus commands, as shown in this illustration.
The compare server process (sp_desvr) on the source system shown with the status command
On Windows systems, each sp_desvr and sp_declt process has an associated sp_cop process. The lstatus and status commands display the PID of the sp_cop process, not the actual PID of the sp_desvr or sp_declt process.
60
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Viewing compare table status and results The best way to view the status or results of one or more compare processes is to use the show compare command in sp_ctrl.
• The basic command displays the processing status of all compare table and compare config processes on a system.
• Additional command options display statistics for each table that was compared, as well as an option to view a compare report for compared tables. The compare report contains the SQL statements required to bring a target table back into synchronization (or those that were applied by the repair process). It also can be configured with the SP_DEQ_LOG_ROWID parameter to show the row ID of each source row. For more information about using the show compare command, see page 173. For more information about the SP_DEQ_LOG_ROWID parameter, see page 277.
You can view compare reports directly from the log sub-directory of the SharePlex variable-data directory on the target system. The compare report file naming convention is: schema_name-table_name-sessionID.sql, where:
• • • •
sid is the ORACLE_SID of the associated Oracle instance. schema_name is the name of the target table’s schema. table_name is the name of the target table. sessionID is the SharePlex-assigned session identifier.
Example compare report file name: a102a64f_SP_DDL_ALL-QA_DDL_TAB_2-13942854.sql
Sample compare report file /* * Compare Report * * Session ID : 13942854 * Schema : SP_DDL_ALL * Table : QA_DDL_TAB_2 * Repair : Off * Target Route: irvqasu18@a102a64f * Key Compare : Off * Select Hint : * Log File : /splex/SharePlex-6.0.0/var10/log/a102a64f_SP_DDL_ALLQA_DDL_TAB_2-13942854.sql * Date : Tue May 15 09:00:00 2007 * */
CHAPTER 1 Using SharePlex Commands
61
ALTER SESSION SET TIME_ZONE = 'GMT'; ALTER SESSION SET NLS_TIMESTAMP_FORMAT = 'YYYYMMDDHH24:MI:SSXFF'; ALTER SESSION SET NLS_TIMESTAMP_TZ_FORMAT = 'YYYYMMDDHH24:MI:SSXFF TZR'; /* source rowid='AADaTMAAdAAAABwAAC' */ insert into "SP_DDL_ALL"."QA_DDL_TAB_2" ("ID","ID1","COL1","COL2","COL3","COL4" ,"COL5") values ('4958425.89984097337629431660942456872878', '-3060909993.544176903814730142050084428617','..1139348109:894..', 'GwhUKLGqjrfYXeyLFvpr','1087710982.068300827002518333076710088939'); /* source rowid='AADaTMAAdAAAABjAAA' */ insert into "SP_DDL_ALL"."QA_DDL_TAB_2" ("ID","ID1","COL1","COL2","COL3","COL4" ,"COL5") values ('946606671.473204804683937834920622934129', '2478119329.970482066728242156633884054263','..2752924801:469..', 'NjITDXihdnJUkZqhhBHH','-4143277897.80978239547068277343072746155'); /* * NOTE: The source and target tables contain LOB and/or LONG columns. * The data for these columns maybe logged as '....' */ /* * Compare Results * * 2 source and 0 target rows compared successfully (L350). * 2 out-of-sync row(s) found in this table. * The SQL statements above are needed to bring this * table back in sync. * * To bring this table back in sync, run the compare * command again with the repair option. * See SharePlex documentation for more details. * * Inserts : 2 * Updates : 0 * Deletes : 0 * */
Viewing compare table logs SharePlex logs notices, warnings, and errors for each compare session in a log file in the log sub-directory of the SharePlex variable-data directory on both systems. There is a log file for the sp_desvr process on the source system, and there is a log for the associated sp_declt process on the target system. The file name differs depending on which process you are looking at. The file name for the sp_desvr process is SID_desvr-sessionID-log#.log, where:
• SID is the ORACLE_SID of the Oracle instance associated with the process.
62
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• sessionID is the SharePlex-assigned session identifier for the compare session. • log# is the log number in the series. The file name for the sp_declt process is SID_declt-schema-table-sessionID-log#.log, where:
• • • • •
SID is the ORACLE_SID of the Oracle instance associated with the process. schema is the name of the target table’s schema. table is the name of the target table. sessionID is the SharePlex-assigned session identifier for the compare session. log# is the log number in the series.
SharePlex creates logs in a circular fashion to control its disk usage. When the maximum log size is reached, as determined by an internal parameter, SharePlex generates another log file until the number of logs reaches an internal limit. At that point, the logs wrap (just like the Oracle redo logs wrap), and the oldest log is replaced with a new one. Subsequent logs also wrap, maintaining the number of logs at or below the limit value. For the compare table command, there is rarely more than one log file. Example log file names: ora920_desvr-6566-01.log
ora920_declt-KWONG-KCWTAB2-6566-01.log
Sample sp_desvr log file FILE: /splex/SharePlex-6.0.0/var10/log/w102a64f_desvr-13942854-01.log DATE: Tue May 15 08:59:54 2007 000: Read Buffer Size: 1048576 bytes ( 1 mbytes) 000: Debug flag: 0x00000000 000: 647125886 3338 /splex/SharePlex-6.0.0/opt10/bin/sp_desvr 000: DEBUG:pthread stack size=4096, status=0 (main,L1158) 000: Notice: SP_DEQ_NLS_SELECTOR = 0 (DB) (de_trans_set_nls_lang,L1840) 000: Threads used: 2 000: Notice: ORACLE_HOME=/oracle/products/102 (main,L1286:de_internal_getenv,L1438) 000: Notice: ORACLE_SID=w102a64f (main,L1287:de_internal_getenv,L1438) 000: OS Version : AIX 2 5 000: Machine : 0002813A4C00 000: Server Message: 0x0006 000: Server Message: OS Version : AIX 2 5 (BIG) 000: Server Message: Machine : 0002813A4C00 000: Server Message: SharePlex Version 6.0.0.86 000: Server Message: SharePlex Lib Version 6.0.0.86 000: The number of threads has been reduced to 1 by the validation process. 000: Notice: SP_DEQ_TIMEOUT set to 1800 000: NOTE: pthread_self_id=1 (de_thrdmgr_main,L2263)
CHAPTER 1 Using SharePlex Commands
63
000: COMPARE CURRENT STATUS:Tue May 15 08:59:54 2007 , Thread started (de_thrdmgr_main,L2264:de_log_line,L301) 000: Oracle Session Id = 1147, Serial# = 7521 000: Notice: Job ID = 6242 (de_oci_getResultSeqNum,L1656) 000: Notice: DB NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1 (de_trans_ora_logon,L979) 000: Oracle Session Id = 1147, Serial# = 7526 000: Oracle Session Id = 1172, Serial# = 35794 002: Oracle Database 10g Enterprise Edition Release 10.2.0.1.0 - 64bit Production With the Partitioning and Data Mining options 000: Notice: DB CSID (WE8ISO8859P1,31) is set. (de_oci_coreSetCSIDs,L1253:de_oci_setCSIDs,L1427) 000: Notice: DB NCSID (AL16UTF16,2000) is set, NCHAR LEN=2 (de_oci_coreSetCSIDs,L1248:de_oci_setCSIDs,L1432) 000: Notice: DEQ CSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1451) 000: Notice: DEQ NCSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1456) 000: Notice: use DB CHARACTERSET id 31 (de_oci_determineFinalCSID,L1350) 000: Notice: use DB NCHAR CHARACTERSET id 2000 (de_oci_determineFinalCSID,L1358) 000: Notice: use NCHAR Character length = 2 (de_oci_determineFinalCSID,L1365) 002: Notice: Object ID of "SP_DDL_ALL"."QA_DDL_TAB_2" is 893564 002: Skip LOB column(s) : Off 002: Log source rowid : On 002: Notice: Object ID of "SP_DDL_ALL"."QA_DDL_TAB_2" is 893564 002: Notice: Found primary key for table 893564 (de_table_find_primary_key:L521) 002: DEBUG: Read Key Order: key 0 = col 0 (ID) 002: Session ID : 13942854 002: Source Data : w102a64f 002: Source Table: "SP_DDL_ALL"."QA_DDL_TAB_2" 002: Source Node : irvlabu02.quest.com 002: Target Table: "SP_DDL_ALL"."QA_DDL_TAB_2" 002: Target Route: irvqasu18.quest.com@a102a64f 002: Target Node : irvqasu18.quest.com 002: Batch Size : 10000 rows 002: Repair : Off 002: Key Compare : Off 002: Port Number : 48973 002: Select Hint : 002: Order By : 002: COMPARE CURRENT STATUS:Tue May 15 08:59:55 2007 (elapsed 1.443046 seconds), ready to do timed-wait table lock. (de_trans_get_read_consistent_view,L1426:de_log_line,L301) 002: COMPARE CURRENT STATUS:Tue May 15 08:59:55 2007 (elapsed 0.008997 seconds), got lock & ready to get consistent view. (de_trans_get_read_consistent_view,L1440:de_log_line,L301) 002: COMPARE CURRENT STATUS:Tue May 15 08:59:55 2007 (elapsed 0.000428 seconds), got consistent view. (de_trans_get_read_consistent_view,L1449:de_log_line,L301)
64
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
002: COMPARE CURRENT STATUS:Tue May 15 08:59:55 2007 (elapsed 0.000026 seconds), table unlocked (conn2) & ready to select count rows. (de_thrdmgr_sub_main,L1466:de_log_line,L301) 002: COMPARE CURRENT STATUS:Tue May 15 08:59:55 2007 (elapsed 0.000679 seconds), done counting rows & ready to insert compare marker. (de_thrdmgr_sub_main,L1471:de_log_line,L301) 002: COMPARE CURRENT STATUS:Tue May 15 08:59:55 2007 (elapsed 0.031760 seconds), inserted compare marker & waiting for compare client to connect back, time out in 1800 seconds. (de_thrdmgr_sub_main,L1517:de_log_line,L301) 002: COMPARE CURRENT STATUS:Tue May 15 08:59:59 2007 (elapsed 4.000195 seconds), received a connection (de_thrdmgr_sub_main,L1567:de_log_line,L301) 002: connection matched, the message is for this thread, ready to receive test message. 002: Notice: source qualified row count = 2 002: Notice: source total row count = 2 002: Notice: Reset batch from 10000 to 2 (table qualified row count) 002: Entering de_msg_svr_preTableMessaging,L98 002: Exiting de_msg_svr_preTableMessaging,L141 002: Client Message: 0x0006 002: Client Message: 002: Client Message: OS Version : AIX 3 5 (BIG) 002: Client Message: Machine : 000CD72D4C00 002: Client Message: AL32UTF8 002: Client Message: AL16UTF16 002: Client Message: SharePlex Version 6.0.0.86 002: Client Message: SharePlex Lib Version 6.0.0.86 002: Notice: source is big endian (de_intenral_determineSwapByte,L1148) 002: Notice: target is big endian (de_intenral_determineSwapByte,L1159) 002: Notice: SP_DEQ_SWAP_BYTE is AUTO (de_intenral_determineSwapByte,L1168) 002: Notice: swap byte is OFF (de_intenral_determineSwapByte,L1200) 002: running sql statement : (de_select_prepare_to_fetch,L1524) 002: select rowid,"ID","ID1","COL2","COL3","COL4","COL5" 002: from "SP_DDL_ALL"."QA_DDL_TAB_2" order by 2 002: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.599445 seconds), ready to fetch first batch, including the order by sorting. (de_batch_setup,L1102:de_log_line,L301) 002: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.059216 seconds), got first batch (de_batch_setup,L1117:de_log_line,L301) 002: Status : Out Sync 002: Entering de_msg_svr_postCompareMessaging,L521 002: Exiting de_msg_svr_postCompareMessaging,L626 002: Compare SP_DDL_ALL.QA_DDL_TAB_2 to SP_DDL_ALL.QA_DDL_TAB_2 completed. 000: DEQ done reading. 000: Exiting....
CHAPTER 1 Using SharePlex Commands
65
Sample sp_declt log file FILE: /splex/SharePlex-6.0.0/var10/log/a102a64f_declt-SP_DDL_ALLQA_DDL_TAB_2-13942854-01.log DATE: Tue May 15 08:59:57 2007 000: Debug flag: 0x0c070800 000: 512458835 3314 /splex/SharePlex-6.0.0/opt10/bin/sp_declt 000: Notice: ORACLE_HOME=/oracle/products/102 (main,L1710:de_internal_getenv,L1438) 000: Notice: ORACLE_SID=a102a64f (main,L1711:de_internal_getenv,L1438) 000: OS Version : AIX 3 5 000: Machine : 000CD72D4C00 000: Notice: SP_DEQ_NLS_SELECTOR = 0 (DB) (de_trans_set_nls_lang,L1840) 000: Connected to Oracle 000: Oracle Session Id = 306, Serial# = 48168 000: Notice: DB NLS_LANG=AMERICAN_AMERICA.AL32UTF8 (de_trans_ora_logon,L979) 000: Connected to Oracle 000: Oracle Session Id = 306, Serial# = 48405 000: Connected to Oracle 000: Oracle Session Id = 310, Serial# = 9172 000: Oracle Database 10g Enterprise Edition Release 10.2.0.2.0 - 64bit Production With the Partitioning and Data Mining options 000: Notice: DB CSID (AL32UTF8,873) is set. (de_oci_coreSetCSIDs,L1253:de_oci_setCSIDs,L1427) 000: Notice: DB NCSID (AL16UTF16,2000) is set, NCHAR LEN=2 (de_oci_coreSetCSIDs,L1248:de_oci_setCSIDs,L1432) 000: Notice: OPO CSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1440) 000: Notice: OPO NCSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1445) 000: Notice: DEQ CSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1451) 000: Notice: DEQ NCSID is NA. (de_oci_coreSetCSIDs,L1261:de_oci_setCSIDs,L1456) 000: Notice: use DB CHARACTERSET id 873 (de_oci_determineFinalCSID,L1350) 000: Notice: use DB NCHAR CHARACTERSET id 2000 (de_oci_determineFinalCSID,L1358) 000: Notice: use NCHAR Character length = 2 (de_oci_determineFinalCSID,L1365) 000: In de_sock_connectToServerWithIP (L219) 000: eintr_count = 0, eisconn_count = 0, ealready_count = 0 000: Client Message: 0x0006 000: Client Message: OS Version : AIX 3 5 (BIG) 000: Client Message: Machine : 000CD72D4C00 000: Client Message: AL32UTF8 000: Client Message: AL16UTF16 000: Client Message: SharePlex Version 6.0.0.86 000: Client Message: SharePlex Lib Version 6.0.0.86 000: Server Message: 0x0006 000: Server Message: OS Version : AIX 2 5 (BIG) 000: Server Message: Machine : 0002813A4C00 000: Server Message: SharePlex Version 6.0.0.86 000: Server Message: SharePlex Lib Version 6.0.0.86
66
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
000: DEBUG: rowid_size=20, rowid_size_send=20 (sp_declt_process_iot,L1425) 000: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 , ready to do timed-wait table lock. (de_trans_get_read_consistent_view,L1426:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.020177 seconds), got lock & ready to get consistent view. (de_trans_get_read_consistent_view,L1440:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.000963 seconds), got consistent view. (de_trans_get_read_consistent_view,L1449:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.007507 seconds), removed semaphore, poster lock file. & ready to select count rows (conn1). (main,L2083:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.001428 seconds), done with row count. (main,L2087:de_log_line,L301) 000: Notice: Reducing batch from 10000 to 2 (main,L2158) 000: DEBUG: Key Order, Read 128 bytes, key_count=1 000: DEBUG: key_order[0] = column 0 (ID) 000: Key Compare : Off 000: Notice: client qualified rows count = 0 000: Notice: client total rows count = 0 000: Session ID : 13942854 000: Source Table: "SP_DDL_ALL"."QA_DDL_TAB_2" 000: Source Node : irvlabu02.quest.com 000: Target Table: "SP_DDL_ALL"."QA_DDL_TAB_2" 000: Target Route2: irvqasu18@a102a64f 000: Batch Size : 2 rows 000: Repair : Off 000: Source Port : 48973 000: Select Hint : 000: sp_declt PID: 30604 000: Read Buffer Size : 1 mbytes 000: running sql statement : (de_select_prepare_to_fetch,L1524) 000: select rowid,"ID","ID1","COL2","COL3","COL4","COL5" 000: from "SP_DDL_ALL"."QA_DDL_TAB_2" order by 2 000: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.459739 seconds), ready to fetch first batch, including the order by sorting. (de_batch_setup,L1102:de_log_line,L301) 000: COMPARE CURRENT STATUS:Tue May 15 09:00:00 2007 (elapsed 0.001399 seconds), got first batch (de_batch_setup,L1117:de_log_line,L301) 000: SP_DEQ_PART_UPDATE : 0 000: Notice: Object ID of "SP_DDL_ALL"."QA_DDL_TAB_2" is 604493 000: Exiting without any errors 000: DEBUG:schema=SP_DDL_ALL, table name=QA_DDL_TAB_2, column_count=6 (de_table_list_table_info,L3752) 000: DEBUG:colName=ID, column[0].number=1, column[0].type=2 (NUMBER), dsize=22, cform=0, csid=0 000: DEBUG:colName=ID1, column[1].number=2, column[1].type=2 (NUMBER), dsize=22, cform=0, csid=0 000: DEBUG:colName=COL1, column[2].number=3, column[2].type=8 (LONG), dsize=0, cform=256, csid=873 000: DEBUG:colName=COL2, column[3].number=4, column[3].type=1 (CHAR), dsize=20, cform=256, csid=873 000: DEBUG:colName=COL3, column[4].number=5, column[4].type=2 (NUMBER), dsize=22, cform=0, csid=0
CHAPTER 1 Using SharePlex Commands
67
000: DEBUG:colName=COL4, column[5].number=6, column[5].type=2 (NUMBER), dsize=22, cform=0, csid=0 000: DEBUG:colName=COL5, column[6].number=7, column[6].type=12 (DATE), dsize=7, cform=0, csid=0 000: Status : Out Sync 000: DEBUG:logoff from Oracle, pid 30604 (de_trans_ora_logoff,L1062)
Removing old compare reports and logs To remove old compare reports and logs from a system, use the remove log compare command (see page 144).
Using the [repair] option To repair out-of-sync rows found by a basic comparison (without the [key] option), use the [repair] option. The following summarizes your choices when deciding how and when to use the [repair] option.
• The recommended procedure is to run the compare table command without the [repair] option first, then view the results with the show compare command to find out if (or which) rows are out-of-sync and the possible cause. Unless the problem is corrected, replication probably will go out of synchronization again. After the problem is fixed, issue the compare table command again, this time with the [repair] option. Or...
• You can run the compare table command with the [repair] option without doing a preliminary comparison. See “Solving synchronization problems” on page 311 for causes and solutions for out-ofsync conditions.
When to run the repair The best time to repair a target table depends on its size, the cause of the problem, the extent of out-of-sync rows, and how long you are willing to tolerate users being locked out. Before you initiate a repair, consider the following:
• Although users are not affected by locks when tables are compared, they are locked out of the target table for the duration of its repair process. For a small table, this might not be disruptive, but for a large table needing extensive repairs, the wait can be significant.
68
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• Locks on a target table can impede the Post process if Post must wait for the repair to finish before it can apply changes to that table and move on to other tables. That can increase the latency of the target data and cause operations to accumulate in the post queue. (Note: If the objects that Post needs to change are different than those being processed by the compare table command, the two processes run simultaneously.)
• If you must repair a table immediately, but cannot tolerate locks or replication latency, you can use the [where “clause”] option to limit the command’s effect to certain rows. Or, you can use the [key-repair] option, keeping in mind that all of the out-of-sync rows might not be repaired.
• If the repair can wait, you can correct the cause of the problem immediately, then do the repair during non-peak hours.
How repairs are made The [repair] option issues the following corrective SQL statements:
• If a row exists on the source side but not the target side, SharePlex issues an INSERT statement.
• If a row exists on the target side but not the source side, SharePlex issues a DELETE statement.
• If a target row differs from the source row, and the key columns match, SharePlex issues an UPDATE statement based on the source values.
• If you are using the [repair] option for a partitioned table, the default behavior of the repair process is to repair rows by using INSERTs and DELETEs. Repairs requiring UPDATEs are converted to a DELETE followed by an INSERT to prevent errors should an UPDATE cause a row to change partitions when row movement is not enabled for the table. You can change the repair behavior so that SharePlex repairs partitioned tables by using INSERTs, UPDATEs, and DELETEs as appropriate. For more information, see the SP_DEQ_PART_TABLE_UPDATE parameter on page 280.
How repair errors are handled If there is an Oracle error during the application of a repair SQL statement, the repair stops from that statement forward, and only the previously applied valid statements are committed. Thus, the table is partially repaired, but it still could be out of synchronization. The show compare command with the [detail] option alerts you to this situation. To determine where the error occurred and which rows were repaired successfully, view the compare report by issuing the show compare command with the [report] option. SharePlex prints the following error message in the compare report immediately after
CHAPTER 1 Using SharePlex Commands
69
the statement for which the error occurred, and it summarizes the repair results at the end of the report. /* * The following Oracle error occurred while repairing. * * * The SQL statement immediately above, and all the statements * following this message will not be applied. */
Comparing only the key values For a faster comparison, you can use the [key] option to compare only the key columns of source and target tables instead of all of the columns. Use it for fast comparisons of large tables to ensure that the same rows exist in both objects. If key values match, the rows are considered synchronized. To restore synchronization to rows where key values do not match, use the [key-repair] option. This option compares a row’s key columns but repairs the values in all of the columns, based on the source table’s values. Use these options with caution and only as a first-level solution. They might not detect all of the out-of-sync conditions. Even though key values match, it is possible for values in non-key columns to be out of synchronization.
Comparing dissimilar source and target tables The compare table command ignores target columns that are not contained in the source table. A repair does the following:
• An INSERT inserts values into target columns that have corresponding columns in the source table, but not into the extra columns. Columns with NOT NULL constraints but no default values cause Oracle errors. Default values are recommended for extra columns in target tables.
• An UPDATE resynchronizes values in target columns that have corresponding columns in the source table, but not the values in the extra columns.
• A DELETE is not affected by extra columns in the target table, because the compare table command selects rows based on column data in the matching columns.
To include the extra columns in a comparison, see “Constraining row selection with a WHERE clause.”
70
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Constraining row selection with a WHERE clause The compare table command provides WHERE clause options to constrain row selection in the following situations:
• To speed processing when the tables are large and data synchronization is only critical for a subset of the records. You can compare the subset instead of all of the rows.
• To prevent deletion of records when there are more rows in the target table than in the source table, such as in a consolidated reporting environment. Using compare table without a WHERE clause for such tables causes a repair to delete the extra rows.
• To compare and repair dissimilar source and target tables, where extra columns in the target table contain values that make a row unique. A WHERE clause on the target system lets you include the extra columns in the comparison.
Using a global WHERE clause on the source and target systems When you can base the row selection on columns that exist in both the source and target table, use the [where “clause”] option. For example, the following table shows a consolidated reporting table that receives data from two regions. A WHERE clause can be constructed based on the REGION column to compare one region’s source table to the corresponding rows in the target table, and to ensure that the other region’s rows are not deleted.
Source table at each of two regional locations
Target table at the central datawarehouse location
Month
Year
Income
Region
Month
Year
Income
Region
1
04
n
n
1
04
100
1
2
04
n
n
2
04
120
1
3
04
n
n
3
04
300
1
1
04
200
2
2
04
120
2
3
04
300
2
Use the [where “clause”] option when the same columns can be used on the source and target systems to select rows for a comparison.
CHAPTER 1 Using SharePlex Commands
71
The WHERE clause can be refined further to compare subsets of rows from the source table to the correct rows in the target table, for example selecting based on the MONTH and REGION columns. Use the [where “clause”] option as follows:
• When source and target column names are identical, create a regular Oracle WHERE clause based on the columns you want to use for the sort. SharePlex creates identical WHERE clauses on both systems.
• When vertically partitioned replication is used for a source table and the corresponding target columns have different names, create a regular Oracle WHERE clause based on the source column names. SharePlex reads the configuration file and maps the source names to the target names to create a WHERE clause for the target table. As an alternative, you can use the [targetwhere “clause”] option to define the columns for row selection on the target system. For further instructions for using the [where “clause”] option, see the syntax description on page 79.
Using a source WHERE clause to compare dissimilar tables Use the [sourcewhere “clause”] option when a source table contains one or more extra columns that make records unique and you want to include those columns in the row selection criteria, such as the REGION column in the following table. Target table at the central data-warehouse location
Source table at each of two regional locations Month
Year
Income
Region
Month
Year
Income
1
04
n
n
1
04
100
2
04
n
n
2
04
120
3
04
n
n
3
04
300
1
04
200
2
04
120
3
04
300
72
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5 Use the [sourcewhere “clause”] option when extra columns exist in the source table but not in the target table and contain data that links records to the target rows.
Use the [sourcewhere “clause”] option only for the extra source columns. Because the [where “clause”] option creates a WHERE clause on the source and target systems, it works for the columns that are common to both tables. SharePlex combines both options to create the complete WHERE clause for the source table. For further instructions for using the [sourcewhere “clause”] option, see the syntax description on page 85.
Using a target WHERE clause to compare dissimilar tables Use the [targetwhere “clause”] option when a target table contains one or more extra columns that make records unique and you want to include those columns in the row selection criteria, such as the REGION column in the following table. Source table at each of two regional locations
Target table at the central datawarehouse location
Month
Year
Income
Month
Year
Income
Region
1
02
n
1
02
100
1
2
02
n
2
02
120
1
3
02
n
3
02
300
1
1
02
200
2
2
02
120
2
3
02
300
2
Use the [targetwhere “clause”] option when extra columns exist in the target table but not in the source table and contain data that links records to the source rows.
Use the [targetwhere “clause”] option only for the extra target columns. Because the [where “clause”] option creates a WHERE clause on the source and target systems, it works for the columns that are common to both tables. SharePlex combines both options to create the complete WHERE clause for the target table. For further instructions for using the [targetwhere “clause”] option, see the syntax description on page 86.
CHAPTER 1 Using SharePlex Commands
73
Important! When a target table has extra columns, use the [targetwhere “clause”] option to compare for UPDATEs and DELETEs only. The command cannot determine the correct values to INSERT into the extra target columns. Work around this issue by either setting a default value for the extra columns or by manually updating the inserted rows.
Using compare table with partitioned replication When issued for tables that are configured for partitioned replication, the compare table command determines the rows and columns to compare by reading the configuration file and, for horizontally partitioned replication, the column conditions in the SHAREPLEX_PARTITION table.
• For vertically partitioned tables where source and target column names are different, the compare table command maps the source columns to the target columns and constructs the correct WHERE clause for each table.
• For horizontally partitioned replication, the compare table command reads the column conditions for the source table and selects rows for the source and target tables based on those conditions. Rows and columns that are excluded from replication are not compared or repaired.
Using compare table with consolidated replication In consolidated replication, there are more rows in the central target table than there are in any given source table. Often, the target table has additional columns that are not contained in the source tables. To compare a source table against a consolidated target table, use a WHERE clause option to prevent unwanted row deletions and, if needed, to include the extra columns in the comparison criteria. For more information, see “Constraining row selection with a WHERE clause” on page 70.
Using compare table with peer-to-peer replication To use the compare table command in a peer-to-peer replication environment, decide which system is the trusted source system — the one with valid data — and which is the target, or secondary, system containing data that will be repaired, if needed. Before you run the comparison, follow these steps:
74
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
1 Stop user access on the target system and wait for replicated operations to post to the
source database. Users can continue to access the source database. 2 Issue the qstatus command on the source and target systems. (For more information about the qstatus command, see page 135). 3 When there are 10 or fewer messages in the queues, run the compare table com-
mand on the source system. 4 Do one of the following:
• For a comparison without a repair, you can permit user access to both databases after the sp_desvr and sp_declt processes have started.
• For a comparison with a repair, make the users wait until the target table’s repair is finished before permitting access to that table. Depending on the databases’ configuration and the way applications access them, you can use the [where “clause”] option to repair selected rows in a table without locking users out.
Using compare config to fix Post reported out-of-syncs This option can only be employed after enabling and setting up Generic Conflict Resolution. See “Using generic conflict resolution” on page 206 in the Shareplex Administrator’s Guide. 1 Set-up Generic Conflict Resolution. 2
If you have not already done so, set the value of parameter SP_OPO_GENERIC_CR to 1, and stop and start the Post to activate this new parameter.
3
Run compare with the reported oos option.
Comparing tables that have no keys or indices The compare table command issues a SELECT statement with an ORDER BY clause on the source and target systems. Having a primary key or a unique, non-null key and an index (preferably a unique index) on large source and target tables speeds the ordering process. SharePlex orders the rows by using the best available key columns, as determined by the order of priority listed below:
CHAPTER 1 Using SharePlex Commands
75
1 Primary key. 2 Unique key with the fewest columns, where at least one of the columns is NOT
NULL. 3 All columns (except LONG, LOB, and BFILE) up to a maximum of 255 col-
umns. This serves as a simulated unique key but makes sorting significantly slower. Note: Unique keys that allow NULL columns are not used, because they can cause the compare process to report that a table is out-of-synchronization when, in reality, all rows are synchronized. Instead, the command uses all of the columns.
Use the [orderby “column_list”] option in the following circumstances:
• when a table has no unique index (or when one cannot be found by SharePlex because it was not created with the UNIQUE keyword).
• when a table has no PRIMARY or UNIQUE key but you know one or more columns are unique (such as an employee ID number). Using the [orderby “column_list”] option speeds processing by avoiding the use of all of the columns for the sort. When this option is used, SharePlex prints a notice to the sp_desvr log on the source system that those columns were marked as key columns for the session.
Comparing tables that have LONG columns SharePlex compare/repair supports the maximum LONG column size, currently 2 GB, that Oracle can support.
Comparing tables that have LOB columns Beginning with SharePlex for Oracle version 5.0, the compare table command supports tables with LOB columns when the SP_DEQ_SKIP_LOB parameter is set to 0. For more information about the SP_DEQ_SKIP_LOB parameter, see page 281.
To log row IDs for manual repair of LOBs When you need to know the source row ID in order to manually repair target LOB columns, set the SP_DEQ_LOG_ROWID parameter on the source system to 1. Enabling this parameter directs SharePlex to log the source row IDs for all rows that are inserted or updated in the target table. For more information about the SP_DEQ_LOG_ROWID parameter, see page 277.
76
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Using the compare table command with DDL replication When the compare process starts, it acquires a read-consistent view of the table, gets the table definition, and parses SQL to SELECT from the table. If the table definition is modified by executing DDL after the compare process determines the table definition and parses the SELECT SQL, then the following error will occur when compare tries to SELECT from the table: Oracle Error: ORA-01466: unable to read data - table definition has changed
Therefore, do not run DDL on a table while it is being compared.
Repairing columns that have UNIQUE constraints Columns with a UNIQUE constraint can cause unique-constraint violation errors when you use a repair option. The following example illustrates why. This example shows source and target tables with two columns each. The first column is the primary key, and the second column has the UNIQUE constraint. Source Table
Target Table
111
ABC
111
XYZ
222
XYZ
222
ABC
When SharePlex attempts to repair the target table, the UNIQUE constraint on column 2 returns an error for the repair on row 1, because the value ABC already exists in row 2 of the target table. The same thing happens when SharePlex updates row 2 of the target table, because the value XYZ already exists in row 1. The workarounds are:
• Disable UNIQUE constraints on the target table before you run a compare table command with a repair option, then re-enable them afterward. Or ...
• Manually delete the target rows for which the unique constraint violations occurred, and then re-run the repair so that SharePlex inserts the rows with the correct data.
CHAPTER 1 Using SharePlex Commands
77
Controlling the batch size The default batch (block) size for comparisons is 10,000 rows. A larger or smaller batch size might be required for your comparisons, depending on the size and volume of your tables and your system resources. To change the batch size, change the value of the SP_DEQ_BATCHSIZE parameter. If the value of SP_DEQ_BATCHSIZE is larger than the number of rows in the source table being compared, SharePlex reduces the batch size to the number of rows in the table. This prevents SharePlex from allocating more space than necessary for the compare processes. For more information about this parameter, see page 276.
Using command strings longer than 255 characters When issuing the compare table command from the sp_ctrl command line, the total string for the compare table command, including the syntax and the WHERE and HINT strings, cannot exceed 255 characters. You can work around this operating-system imposed limitation by using the edit command on the source system. The edit command enables you to type the command string within a text file, and then it automatically executes the command. To run compare table with the edit command 1 If no compare commands were issued previously in the current session of sp_ctrl, type the words compare table at the prompt, then press Enter. Otherwise, skip this
step. (Ignore the online help or error that is displayed.) 2 At the sp_ctrl prompt, issue the edit command. This command opens a temporary
text file with the default SharePlex text editor. The first line should contain either the words compare table or the string of the previous command that was issued. sp_ctrl(sysA)> edit 3 In the text file, use the editor’s standard commands to edit out any unwanted characters and type the compare table command string. 4 Save and exit out of the file using the editor’s standard save command. The com-
mand executes.
78
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Other conditions and requirements for using compare table • All SharePlex processes (Capture, Read, Export, Import, Post) must be running when you issue the compare table command, and they must remain running throughout the compare and repair processes.
• The success of the compare table command depends on the activity on the source system. Because the command relies on the queues to spawn the sp_declt process on the target system, and because SharePlex forwards data (including the compare table command) in the order in which it is received, the comparison cannot start until all previous messages in the queues have been processed. If a delay causes the compare process to lose its read consistency, the command returns an error. To avoid errors, consider doing comparisons during non-peak hours.
• Large open transactions (without a COMMIT) on a source table prevent the compare process from obtaining the brief lock it needs to obtain read consistency. The command attempts the lock several times and then returns an error if it is unsuccessful. Make sure that transactions are committed before issuing a compare table command.
• The tables that you want to compare must be currently replicating. • Do not use the compare table command for tables for which a SharePlex key definition is defined. For more information about key definitions, see the SharePlex Administrator’s Guide.
• Do not truncate a table that is being compared. The compare table command takes a snapshot of the source table when it starts, and if the table is truncated, the table view in the snapshot is also truncated. This can result in invalid out-of-sync rows being found on the target.
• Do not use the compare table command in a cascading replication environment. • Make certain your applications use Oracle JDBC driver classes 8.0.5 or above. JDBC driver classes below version 8.0.5 permit improper date formats, which adversely affect sorts used by the compare processes. Authorization Level: Issued on: Related commands:
Operator (2) source system compare config, show compare, remove log compare
CHAPTER 1 Using SharePlex Commands
79
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
compare table owner.source_table to owner.target_table target
[email protected]_SID
[for datasource] [hint “hint”] [key | key-repair] [orderby “column_list”] [quickcompare] [repair] [reported oos] [where “clause”] [targetwhere “clause”]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
compare table owner.source_table to owner.target_table target target_host @o.target_SID
Use the basic command to compare a designated pair of source and target tables. This command compares all of the source columns with all of the target columns, for all of the rows in the tables. • compare table is a required part of the syntax. • owner.source_table is the owner name and table name of the source table. Separate the owner and table names with a dot (.), but no spaces. Use double quotes to enforce case-sensitivity or spaces within a name, for example “HR”.emp. • to is a required part of the syntax. • owner.target_table is the owner name and table name of the target table. Use the same syntax rules as those of the source owner and table. • target is a required part of the syntax. •
[email protected]_SID is the routing map that directs SharePlex where to find the target table. The target host variable is the name of the target system and target_SID is the ORACLE_SID of the target instance. The ORACLE_SID is not case-sensitive. Allow no spaces between components of the routing map. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected]
80
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options OPTION
DESCRIPTION
for datasource
Use this option to specify the datasource of the source table to be compared. Use it only when replication is active for more than one Oracle instance on a source system. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source instance. The ORACLE_SID is case-sensitive and must be typed as it appears in the oratab file, V$PARAMETER table, or Windows Registry. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] for o.oraA sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] repair for o.oraA
hint “hint”
Use this option to include an Oracle hint in the command’s SELECT statement. The hint is used on the source and target systems. • hint is a required part of the syntax. • “hint” must be a standard Oracle hint, and the entire hint must be enclosed within double quotes as shown in the examples below. Do not include the leading /*+ and trailing */ in the hint string. SharePlex puts those in when it creates the SELECT statement. The hint string cannot be longer than 2000 characters. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] repair where “file >001005” hint “emp(salary)” sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] repair hint “emp(salary)” where “file >001005” Note: To run the compare table command from the UNIX command line (non-interactively), all strings within quotes must have an extra set of escaped double quotes — quotes preceded by a backslash (\), as in the following example: /productdir/bin/sp_ctrl compare table scott.emp to scott.emp target
[email protected] repair hint “\“emp(salary)\””
CHAPTER 1 Using SharePlex Commands
81
Command options (continued) OPTION
DESCRIPTION
key
Use this option for fast comparisons (but not repairs) of large tables to verify that the same rows exist in both objects. Use it in one of the following ways: • To compare only the PRIMARY or UNIQUE key columns without repairing out-of-sync rows. Or... • If the tables have no keys, to compare columns specified with the [orderby “column_list”] option without repairing out-of-sync rows. Important: When keys or the orderby values match (so the rows are considered synchronized), but values in other columns do not, the tables remain out of synchronization. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Do not use this option to base a comparison on a SharePlex key definition. For more information about key definitions, see the SharePlex Administrator’s Guide. Do not use this option with the [repair] option. To base a comparison on key columns and then repair out-of-sync rows, use the [key-repair] option. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] key
82
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
key-repair
Use this option for fast comparisons and repairs of large tables to verify that the same rows exist in both databases. Use it in one of the following ways: • To compare only the PRIMARY or UNIQUE key columns and, when keys do not match, repair all of the columns based on the source table’s values. Or... • If the tables have no keys, to compare columns specified in the [orderby “column_list”] option and, when values do not match, repair all of the columns based on the source table’s values. Important: When the keys or the orderby values match (so the rows are considered synchronized) but values in other columns do not (and are not repaired), the tables remain out of synchronization. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Do not use this option to base a comparison on a SharePlex key definition. For more information about key definitions, see the SharePlex Administrator’s Guide. To base a comparison on key columns, without repairing out-of-sync rows, use the [key] option. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] key-repair
CHAPTER 1 Using SharePlex Commands
83
Command options (continued) OPTION
DESCRIPTION
orderby “column_list”
Use this option to specify columns for the command’s ORDER BY clause. • orderby is a required part of the syntax. • “column_list” contains the names of the columns on which you want the sort to be based. Separate each column name with a comma, but allow no spaces in the string unless a column’s name includes spaces. The string itself must be enclosed within double quotes, as shown in the examples below. The sort is performed in ascending order, regardless of how the columns are listed in the string. Column names are not case-sensitive. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] repair where “file >001005” orderby “Last Name,Division” Note: To run the compare table command from the UNIX command line (non-interactively), all strings within quotes must have an extra set of escaped double quotes — quotes preceded by a backslash (\), as in the following example: /productdir/bin/sp_ctrl compare table scott.emp to scott.emp target
[email protected] repair orderby “\“Last Name,Division\””
quickcompare
Use this option to obtain a quick determination of the existance of out-ofsync rows without an indication of where the out-of-sync is located. This option may NOT be used in conjunction with any repair, key or where options. This option does NOT support LONG or LOB columns. This option does not log any out-of-sync row information to the compare client SQL file.
repair
Use this option to repair out-of-sync target tables. It repairs all of the columns in the out-of-sync rows, based on the source table’s values. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Do not use this option with the [key] option. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] repair sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] where “file >001005” repair
84
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
reported oos
Use this option to repair rows reported out-of-sync by Post and recorded in the internal tables. This option can only be employed after enabling and setting up Generic Conflict Resolution. See “Using generic conflict resolution” on page 206 of the Shareplex Administrator’s Guide. When the reported oos option is specified in the command line, it will automatically default to the repair option. In addition, it will override the other compare options, such as key and key-repair. sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] reported oos
where “clause”
Use this option to compare specific rows of the source and target tables. • where is a required part of the syntax. • “clause” defines a WHERE clause for the rows to be compared. SharePlex uses the WHERE clause in its SELECT statement on both the source and target systems. Use any standard SQL WHERE clause that does not include subqueries, and enclose it within double quotes as shown in the examples below. Table names must be in the format of owner.table, for example scott.emp. Use double quotes to enforce casesensitivity or spaces within a table name. Dates in the WHERE clause must be in the format of 'YYYYSMMDDHH24MISS'. To convert a date to that format, use the Oracle TO_DATE function. For example if Column 1 is a DATE column, the WHERE clause c1 > '10-SEP-2001' will not work, but c1 > to_date('10SEP-2001', 'DD-MON-YYYY') will. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Example: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] repair where “file >001005” sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] where “file >001005” repair Note: To run the compare table command from the UNIX command line (non-interactively), all strings within quotes must have an extra set of escaped double quotes — quotes preceded by a backslash (\), as in the following example: /productdir/bin/sp_ctrl compare table scott.emp to scott.emp target
[email protected] repair where “\“file >001005\””
CHAPTER 1 Using SharePlex Commands
85
Command options (continued) OPTION
DESCRIPTION
sourcewhere “clause”
Use this option to base the comparison on one or more source columns when those columns do not exist in the target table. • sourcewhere is a required part of the syntax. • “clause” defines a WHERE clause for selecting rows from the source table. Use any standard SQL WHERE clause that does not include subqueries, and enclose it within double quotes as shown in the examples below. Table names must be in the format of owner.table, for example scott.emp. Use double quotes to enforce case-sensitivity or spaces within a name. • Dates in the source WHERE clause must be in the format of 'YYYYSMMDDHH24MISS'. To convert a date to that format, use the Oracle TO_DATE function. For example, if Column 1 in the source table is a DATE column, the source WHERE clause c1 > '10-SEP2003' will not work, but c1 > to_date('10-SEP-2003', 'DD-MON-YYYY') will. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Example #1: sp_ctrl(sysA)> compare table scott.emp to scott.emp target
[email protected] repair sourcewhere “file >001005” sp_ctrl(sysA)> compare table scott.emp to scott.emp target
[email protected] sourcewhere “file >001005” repair Example #2: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] sourcewhere “deptno = 200” where “mgr = ‘SMITH’” repair In the second example, the source and target machines use different WHERE clauses. Only the source is using the source WHERE clause, “deptno = 200”, while both the source and target are using the WHERE clause “mgr = ‘SMITH’”. Note: To run the compare table command from the UNIX command line
(non-interactively), all strings within quotes must have an extra set of escaped double quotes — quotes preceded by a backslash (\), as in the following example: sp_ctrl> compare table scott.emp to scott.emp target
[email protected] repair sourcewhere “\“file >001005\””
86
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
targetwhere “clause”
Use this option to base the comparison on one or more target columns when those columns do not exist in the source table. • targetwhere is a required part of the syntax. • “clause” defines a WHERE clause for selecting rows from the target table. Use any standard SQL WHERE clause that does not include subqueries, and enclose it within double quotes as shown in the examples below. Table names must be in the format of owner.table, for example scott.emp. Use double quotes to enforce case-sensitivity or spaces within a name. • Dates in the target WHERE clause must be in the format of 'YYYYSMMDDHH24MISS'. To convert a date to that format, use the Oracle TO_DATE function. For example, if Column 1 in the target table is a DATE column, the target WHERE clause c1 > '10-SEP-2001' will not work, but c1 > to_date('10-SEP-2001', 'DD-MON-YYYY') will. When used, this option must appear after the command’s required arguments, but it can appear in any order with other options. Example #1: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] repair targetwhere “file >001005” sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] targetwhere “file >001005” repair Example #2: sp_ctrl(SysA)> compare table scott.emp to scott.emp target
[email protected] where “deptno = 200” targetwhere “mgr = ‘SMITH’” repair In the second example, the source and target machines use different WHERE clauses. The source and target are using the WHERE clause, “deptno = 200”, while only the target is using the WHERE clause “mgr = ‘SMITH’”. Note: To run the compare table command from the UNIX command line
(non-interactively), all strings within quotes must have an extra set of escaped double quotes — quotes preceded by a backslash (\), as in the following example: /productdir/bin/sp_ctrl compare table scott.emp to scott.emp target
[email protected] repair targetwhere “\“file >001005\””
CHAPTER 1 Using SharePlex Commands
87
copy/append The copy/append command uses the Oracle Export/Import utility to allow users to setup replication and/or (re)synchronize individual tables already in replication. Users may copy/append individual tables to a single target, specify multiple targets, or all targets in the replication configuration. Important! This command invokes Export with CONSISTENT=Y. This requires an adequately sized RBS to avoid an ORA-01555 error. If you encounter this error, please refer to the Knowledge Base solution, SOL48063.
Important! This command cannot be used in a bi-directional or HA environment without additional steps. Please refer to the Knowledge Base solution, SOL48020.
The copy command Use the copy command to synchronize or instantiate a table (or tables) from one host to any other host when the user wants the target table truncated prior to synchronizing data.
The append command Use the append command to synchronize or instantiate a table (or tables) from one host to any other host when the user does not want the target table truncated prior to synchronizing data. Note: The difference between the copy and append commands is that the copy command employs a TRUNCATE prior to synchronizing table data.
When to use the copy/append command Use the copy/append command in the following ways:
• To migrate a database. • To sync a table that the Compare/Repair process is unable to repair. • Place a table into replication while instantiating it.
88
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Important! Before you begin using this command, please review all of this documentation. Improper use could result in lost data and out-of-sync conditions.
What the copy/append command supports The copy/append command supports the following:
• Objects supported by the copy/append command are those objects supported by Oracle’s Import/Export utility.
• Copying from a lower version of Oracle to a higher version of Oracle, or between the same versions of Oracle.
• The copy/append of objects in a synchronization routing file that are included as a result of Oracle wildcard specification.
• The use of Oracle wildcard specification in command line syntax.
What the copy/append command does not support The copy/append command does not support:
• Copying from a higher version of Oracle to a lower version of Oracle. • Copying from a table to a view. • UDTs or VARRAYs if the UDT or VARRAY type was not created on the target database using Oracle's Import/Export utility or Oracle's hot backup. This is a limitation in Oracle's import/export facility.
• Tables in replication that are horizontally or vertically partitioned. • Sequences. • Tables for which transformation is being used, unless the transformation is being applied on the target, as well.
• Network configurations in which a pass-through server is used to pass data between the source and target servers.
• • • • •
Column mapping. Subset of columns. Specifying a subset of rows within a table. Indexes, constraints, triggers, and grants options. Direct load.
CHAPTER 1 Using SharePlex Commands
89
• The append command does not support Oracle partitions. (Only the copy command supports Oracle partitions.) Important! The copy/append command supports Oracle wildcards; however, if the set of objects indicated by the wildcard specification includes objects that are not presently in replication, the copy/append command will only act on those objects currently in replication.
Important! If the force option is employed and all the target information is specified, the tables in replication will be copied statically, as is the current behavior.
Overview of copy/append command options The following options are available to optimize and customize the copy/append command. These options are described in more detail later in this documentation.
• Use the [force] option to synchronize individual tables not in replication.
The launcher process The launcher process must be running on the target system(s) prior to executing the copy/append command. To start the launcher process the user must execute the following command on each of the target systems: sp_ctrl(sysB)> start launcher While the launcher process is running the show launcher command may be used to view process details. When the user has completed synchronization the launcher may be stopped on the target system(s). To stop the launcher process the user must execute the following command on each of the target systems: sp_ctrl(sysB)> stop launcher
Overview of copy/append process The copy/append command initiates a process to synchronize individual tables between individual hosts.
90
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
The following is the sequence of events that illustrates simple synchronization process activity: 1 Log onto the target system and issue the start launcher command from sp_ctrl. 2
When the copy/append command is issued from a sp_ctrl session the sp_cnc spawns sp_sync_svr on the source system.
3
The sp_sync_svr connects to the target system and starts the sp_sync_clnt on the target system.
4
The sp_sync_svr sends the sp_syn_clnt a table list to verify information on the target table. a) If the object is being copied (versus an append) the target table is truncated.
5
For each object under copy the sp_sync_svr starts up an Oracle export process.
6
If the object under copy is in replication sp_sync_svr must wait for sp_sync_clnt to indicate that the Post process is ready.
7
The sp_sync_clnt process starts an Oracle import process for each of the objects that the sp_sync_svr process opened an Oracle export process for.
8
The sp_sync_svr process transfers data to the sp_sync_clnt process until the copy is complete.
9
If the object under copy is in replication the Post process re-initiates and resumes it’s posting activities.
10 Log onto the target system and issue the stop launcher command from sp_ctrl.
Running concurrent copy processes You can issue multiple copy/append commands at a time. Users should note that while the copy process is in progress the Post process stops all replication.
Identifying synchronization processes The synchronization processes are not listed in the sp_ctrl console as they are not started by sp_cop process. To identify the process use your operating system to locate the executables.
• sp_sync_svr
CHAPTER 1 Using SharePlex Commands
91
• sp_sync_clnt • sp_sync_lstnr • sp_sync_launcher
Tuning parameters for the synchronization The following is a list of parameters associated with synchronization using the copy/ append command. These parameters are all live and take effect the next time the command is issued.
• SP_OSY_COMPRESSION: This parameter adjusts the data compression from off (0) to full (9). The default integer value is set to six (6).
• SP_OSY_EXP_BUFFER_SIZE: This parameter adjusts the amount of data that is buffered before being sent to the target system. The default integer value is 1024 Kilobytes.
• SP_OSY_IMP_BUFFER_SIZE: This parameter adjusts the amount of data that is buffered before being applied on the target system. The default integer value is 1024 Kilobytes.
• SP_OSY_LOCK_TIMEOUT: This parameter set the number of seconds that the synchronization process will wait to obtain a table lock. The default integer value is 2 seconds.
• SP_OSY_PORT: This parameter sets the port number for the synchronization process. The default integer value is set to port number 2501.
• SP_OSY_POST_TIMEOUT: This parameter sets the number of seconds that the synchronization process will wait for the Post process to be ready and the synchronization to begin. The default integer value is set to 1800 seconds (30 minutes).
• SP_OSY_TCP_TIMEOUT: This parameter sets the number of seconds for the IPC time-out. The default integer value is set to 10 seconds.
• SP_OSY_THREADS: This parameter sets the number of synchronization processing threads. This thread parameter only affects a partitioned table. The default integer value is set to 5 threads. It has a maximum value of 32 threads. Note: For more information on each of the parameters associated with synchronization using copy/append please refer to each individual parameter in the “SharePlex Parameters” section of this guide.
92
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Viewing copy status The best way to view the status of one or more copy/append commands is to use the copy status command or the append status command. The basic command displays the results of all copy/append processes on a system. The basic command displays the status of all copy/append jobs currently running on the system, and the most recently executed copy/append if it isn’t included in the currently running list. The best way to view the results of one or more copy/append commands is to use the report command with the copy option in sp_ctrl. For more information about using the report command, see page 148.
In the example text that follows, the copy/append command was issued against a table not in replication. The copy status that follows displays basic information about the table and the status of the procedure. sp_ctrl (alvlabl17:8708)> copy sp_iot.SYNC_iot_BASIC to sp_iot.SYNC_iot_BASIC for o.w920a32f at
[email protected] force copy started; job id 111 sp_ctrl (alvlabl17:8708)> copy status 111 for o.w920a32f Job ID Host Started Job Type Status ID
: 111 alvlabl17.quest.com 17-MAR-08 13:59:28 Copy Done
: : : :
Tablename
Total Rows %Comp Status
Status Time Total Time
----- ---------------------- ---------- ----- -------- ----------- ---------1
"SP_IOT"."SYNC_IOT_BASIC"
3720
100 Done
N/A
0:08
Using a synchronization routing file The synchronization routing file is very similar in structure to a configuration file used for activation, in that the file contents have the same formatting requirements. The difference between the two files is that some tables or objects in a configuration file may not be supported by the synchronization process and therefore should not be included in a synchronization routing file. For example, horizontally or vertically partitioned tables are not supported by the synchronization process and should not be included in a synchronization routing file.
CHAPTER 1 Using SharePlex Commands
93
Use of Oracle wildacrds in synchronization routing files is supported. The application of Oracle wildcards in a synchronization routing file is the same as in a config file. For information on using Oracle wildcards in this context, please refer to the “Specifying source tables using wildcards” section of the SharePlex Administrator’s Guide.
Example routing file Datasource:o.s_sid1 s_user0.sync_multi_trgt s_user0.sync_multi_trgt s_user0.sync_multi_trgt
d_user0.sync_multi_trgt d_user0.sync_multi_trgt d_user0.sync_multi_trgt_bu
[email protected]_sid1
[email protected]_sid1
[email protected]_sid2
Note: When using the copy/append command for a group of tables all the tables must be in replication or all the tables must not be in replication. If you have a combination of tables in replication and tables not in replication the user must create a separate synchronization routing file for each group and a separate synchronization process be started with each file.
Tip: The copy/append command copies tables in random order and does not take into account referential integrity. Therefore, we recommend that users copy/append only one table at a time, or limit the copy/append to a very small number of tables.
Copying dissimilar source and target tables The structure of the source and target table(s) should be identical, with the exception that the source tables may contain less columns than the target tables. The copy/append command should not be used for source tables that contain more columns than their corresponding target tables.
Using copy with partitioned replication When tables in a configuration use partitioned replication:
• The copy/append command will support the copying of individual tables and individual partitioned tables, but not individual partitions.
• Data is never copied to an individual partition, even when the target object specified is a partition.
• Specifying a partition as a target is not supported.
94
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• The synchronization of data, for both, copy and append, is always done on the base table and never the partition.
• The copy/append command does not support vertically or horizontally partitioned tables currently in replication.
Controlling the number of processing threads To take advantage of machines with multiple processors, you can set the number of copy/append processing threads on the source system using the SP_OSY_THREADS parameter. This thread parameter only affects a partitioned table. The default value of this parameter is set to five (5) threads, and the range of valid values is from one (1) to ten (32) threads. Please note that synchronization process is single threaded when the tables are in replication. Multi-threaded processing only comes into play with tables that are not in replication. For more information on the SP_OSY_THREADS parameter please refer this parameter in the “SharePlex Parameters” section of this guide.
Using Oracle wildcards in command line syntax Oracle wildcards may be employed when specifying the source_table portion of the copy/append command. Additionally, you may use not notation to exclude specific objects. You may specify all the tables in a specific schema using the following: sp_ctrl (irvspxu14:8567)> copy scott.%
In the above example, all objects under the scott schema will be copied, provided the objects are currently in replication. You can also set exclusions using the following: sp_ctrl (irvspxu14:8567)> copy scott.% not (%"foo"%)
In the above example, all objects under the scott schema, except objects whose name contain “foo”, will be copied, provided the objects are currently in replication. Tip: To gain a better understanding of how to employ Oracle wildcards please refer to the “Specifying source tables using wildcards” section of the SharePlex Administrator’s Guide.
CHAPTER 1 Using SharePlex Commands
95
Other considerations for using copy/append • When using the copy/append command to migrate a database, operations issued against the table before the copy/append begins are ignored by the Post process.
• When using the copy/append command to sync a table that is out-of-sync or when using the copy/append command to place a table into replication while instantiating it the Post process will pause if data for that table is found in the incoming stream. The Post process will resume when the copy/append command is complete. This does not apply to a table that is being added to replication through a new route.
• The copy/append command can only operate on one table at a time if the tables are currently in replication.
• When using the copy/append command for a table not in a known replication route the user must employ the force option. To employ copy/append on objects not in replication the user must employ the force option.
• All SharePlex processes (Capture, Read, Export, Import, Post) must be running when you issue the copy/append command, and they must remain running throughout the processes.
• Do not use the copy/append command in a cascading replication environment. • Tables with foreign keys should have those keys disabled and then re-enabled. • Table indexes, constraints, triggers, and grants must be (re)enabled after the synchronization completes, as these options are not supported.
• When objects are in replication copy/append does not require locks or synchronization between the source table and target table since it is assumed that the source and target table will not undergo changes while the copy/append command is being executed.
• When a config file is specified, which contains multiple objects, the source and target schema name can only be different if all of the target objects have the same schema name.
• The copy/append command will only be able to copy or append data between two objects on the same database if the objects reside in different schemas.
• Activating a new config while the copy/append process is running may cause the synchronization process to fail. Note: The syntax for the copy and append commands are exactly the same. The examples that appear below utilize the copy command, but the append command can be invoked by simply substituting append for copy.
96
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Authorization Level: Issued on: Related commands:
Operator (2) source system report
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
copy {source_owner}.{source_table}
[not ({list of exceptions])] [to {target_owner}.{target_table} [.partition}]] [at {target_host}@[{target_sid}] [for {o.source_sid}] [force] [status]
available
append {source_owner}.{source_table}
[not ({list of exceptions])] [to {target_owner}.{target_table} [.partition}]] [at {target_host}@[{target_sid}]] [for {o.source_sid}] [force] [status]
available
copy using filename
[for {o.source_sid}] [force]
available
append using filename
[for {o.source_sid}] [force]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
{source_owner}. {source_table}
Specifies the source owner and source table name.
filename
The name of the synchronization routing file containing the tables to be synchronized. File names are case-sensitive. Example: sp_ctrl(SysA)> copy using sync_file_2.txt sp_ctrl(sysA)> append using sync_file_2.txt
CHAPTER 1 Using SharePlex Commands
97
Command options OPTION
DESCRIPTION
{source_owner}.{source_t This option sets the source table routing map option that directs SharePlex able} where to find the table for synchronization. When used without a target route this option assumes that the table for synchronization is in replication and that the synchronization target is the same as the replication target. Allow no spaces between components of the routing map. Examples: sp_ctrl(SysA)> copy s_user1.sync_single_tbl sp_ctrl(sysA)> append s_user1.sync_single_tbl [to This option sets the target table routing map option that directs SharePlex {target_owner}.{target_tabl where to find the target table for synchronization. This option must be used e} [.partition}]] in conjunction with the above source routing option. When used this option does not assume that the table for synchronization is in replication, however, if the table is not in replication this option must be used in conjunction with the at routing map option below. Allow no spaces between components of the routing map. Examples: sp_ctrl(SysA)> copy s_user1.sync_single_tbl to d_user1.sync_single_tbl sp_ctrl(SysA)> append s_user1.sync_single_tbl to d_user1.sync_single_tbl [at {target_host}@ [{target_sid}]]
This options sets the target system routing map option that directs SharePlex where to find the target system for the table intended for synchronization. This option must be used in conjunction with the above source table and target table routing map options. This option does not assume that the table for synchronization is in replication. Allow no spaces between components of the routing map. Examples: sp_ctrl(SysA)> copy s_user1.sync_single_tbl to d_user1.sync_single_tbl@
[email protected]_sid1 sp_ctrl(SysA)> append s_user1.sync_single_tbl to d_user1.sync_single_tbl@
[email protected]_sid1
[for {o.source_sid}]
This option is used for employing the copy command when there is no active config, or if there is more than one active config. In either case, the source SID must be specified using the for option. Examples: sp_ctrl(SysA)> copy s_user1.sync_single_tbl for o.source_sid1 sp_ctrl(SysA)> append s_user1.sync_single_tbl for o.source_sid1
98
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
[force]
Use this option when tables intended for synchronization are not in replication. Or when the table route does not match an existing or known route. Examples: sp_ctrl(SysA)> copy s_user1.sync_single_tbl for o.source_sid1 force sp_ctrl(SysA)> append s_user1.sync_single_tbl for o.source_sid1 force
[status]
Displays status history for previous copy/append commands. sp_ctrl(SysA)> copy status sp_ctrl(SysA)> append status
CHAPTER 1 Using SharePlex Commands
99
copy config Use the copy config command to copy a configuration file and save the copy under a different file name. Copying the configuration allows you to:
• save a replica for backup purposes. • use the copy as the basis for composing a new configuration using the edit config command (see page 110).
• change an active configuration. SharePlex does not allow you to edit an active configuration. You make your changes to the copy with the edit config command while replication under the current configuration continues, and you activate the new configuration when you are ready. This command copies the configuration to the same source system as the original configuration. To copy a configuration file to a different system, you can transfer the file via tape, CD, or FTP. To see a list of configurations on a system, use the list config command (see page 122). To view the contents of a configuration, use the view config (page 227) command. Authorization level: Issued for: Related commands:
Operator (2) source system activate config, create config, edit config, list config, remove config, rename config, show config, verify config view config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
copy config filename to newname
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
100
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments ARGUMENT
DESCRIPTION
filename to newname
• filename is the name of the configuration that you want to copy. Configuration names are case-sensitive. • to is a required part of the syntax. • newname is the name you are giving to the copy. It must be unique among configurations on the system. Example: sp_ctrl(sysA)> copy config sales to sales2
CHAPTER 1 Using SharePlex Commands
101
create config Use the create config command to create a new configuration file. This command runs the SharePlex default text editor and opens a new file. To create a configuration, follow the instructions in Chapter 5 of the SharePlex Administrator’s Guide. If you attempt to give a new configuration the same name as an existing configuration, SharePlex returns this error message “The parameter for create config must be a new filename.” As an alternative to creating a configuration, you can use the copy config command (see page 99) to duplicate an existing configuration and then use the edit config command to edit the copy (see page 110). Authorization level: Issued for: Related commands:
Operator (2) source system activate config, copy config, edit config, list config, remove config, show config, verify config, view config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
create config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to create. Configuration names are case-sensitive. The name must be unique among configurations on the system. Example: sp_ctrl(sysA> create config sales
102
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
deactivate config Use the deactivate config command to gracefully terminate replication for an active configuration. This command stops all Capture activity for the configuration, posts all data currently in the queues, and removes the associated SharePlex processes and queues. The deactivate config command does not remove a configuration from the system, but only stops replication of its objects until you activate it again. When you deactivate a configuration, it can cause the target data to go out of synchronization if users continue making changes to the configured source objects. Deactivating one configuration on a system does not deactivate other active configurations on the same system.
Deactivating when multiple configurations are active When replicating from multiple instances (datasources) on the same source system, use the deactivate config command only if you have named (separate) export queues in each configuration that separate the data streams of those instances. Normally, the data from all replicated instances accumulates in one export queue. When you issue the deactivate config command, it deletes all the data in the export queue (along with the queue itself), including data for configuration(s) you might not want to deactivate. See Chapter 5 of the SharePlex Administrator’s Guide for instructions on creating a configuration using named export queues. Tip: To save time when activating a configuration that is only slightly different than the active one, you do not need to deactivate the active one first. While it is still active, you can copy the active configuration with the copy config command (page 99). Change the copy with the edit config command (page 110), and then activate the copy (page 22). Using this method saves time because SharePlex will not re-analyze the objects that are common to both configurations. SharePlex will only analyze the new objects. (If you deactivate the first configuration before activating the copy, SharePlex will analyze all of the objects. This process takes longer.) Be sure that the first config has completed the activation process before activating the copy.
Authorization level: Issued for: Related commands:
Administrator (1) source system abort config, list config, purge config, remove config, view config
CHAPTER 1 Using SharePlex Commands
103
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
deactivate config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to deactivate. Configuration names are case-sensitive. Example: sp_ctrl(sysA)> deactivate config sales
104
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
delete queue Use the delete queue command to delete a SharePlex queue. When a system fails, one or more SharePlex queues can become corrupted, and there will be errors reading from them or writing to them. The purge config and abort config commands cannot be used to restore corrupted queues because they rely on code sent through the queues. The damaged queue must be removed and rebuilt. The delete queue command removes a corrupted queue, including any associated subqueues. The process that writes to that queue rebuilds it when replication resumes, replacing the data that was in the queue but not yet processed. Before using the delete queue command, stop the processes that writes to the queue and those that read it.
• To delete a capture queue, stop Capture and Read. • To delete an export queue, stop Read and Export. • To delete a post queue, stop Import and Post. After deleting a queue, delete all subsequent queues to ensure that all other possible points of corruption are eliminated.
• After deleting a capture queue, delete the export queue, then the post queue. • After deleting an export queue, delete the corresponding post queue. • After deleting a post queue, no other action is required. After deleting the queues, TRUNCATE the SHAREPLEX_TRANS table in the SharePlex schema in the target database. Otherwise, SharePlex could undertake a recovery process and generate recovery notices in the Event Log. SharePlex is designed to recover from a system failure and will interpret the queue deletions as such. Note: The delete queue command will fail if there are messages in backlog.
Authorization level: Issued for: Related commands:
Operator (2) source or target system
CHAPTER 1 Using SharePlex Commands
105
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
delete queue {datasource:C | queuename:X | queuename:P for datasourcedatadest}
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
datasource:C
Use this option to delete a capture queue. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • :C is a required part of the syntax. It indicates that the queue is a capture queue. The C must be capitalized. Example: sp_ctrl(sysA)> delete queue o.oraA:C In this example, the capture queue for Oracle instance oraA is being deleted.
queuename:X
Use this option to delete an export queue. • queuename is the name of the export queue. Use the source system name if the queue is a default export queue, or use the userdefined name if the queue is a named queue. • :X is a required part of the syntax. It indicates that the queue is an export queue. The X must be capitalized. Example: sp_ctrl(sysA)> delete queue sysA:X In this example, the default export queue sysA is being deleted. Example: sp_ctrl(sysA)> delete queue West:X In this example, the named export queue West is being deleted.
106
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments ARGUMENT
DESCRIPTION
queuename:P for datasourcedatadest
Use this option to delete a post queue. • queuename is the name of the post queue. Use the source system name if the queue is a default post queue, or use the user-defined name if the queue is a named queue. • :P is a required part of the syntax. It indicates that the queue is a post queue. The P must be capitalized. • for is a required part of the syntax. It directs the command to affect the post queue for a certain data flow. There can be multiple post queues on a target system, depending on how replication is configured. • datasource-datadest represents the data flow for which you want to delete the post queue. For datasource, use o. followed by the source ORACLE_SID. For datadest, use o. followed by the target ORACLE_SID. Example: sp_ctrl(sysA)> delete queue sysA:P for o.oraA-o.oraB In this example, the default post queue sysA for data being replicated from Oracle instance oraA to target instance oraB is being deleted. Example: sp_ctrl(sysA)> delete queue Sales:P for o.oraA-o.oraB In this example, the named post queue Sales for data being replicated from Oracle instance oraA to target instance oraB is being deleted.
CHAPTER 1 Using SharePlex Commands
107
edit Use the edit command in the following ways:
• to make changes to a SharePlex command that you previously issued. This saves time when you need to issue a command again, but with slightly different syntax, or if you need to correct a syntax mistake.
• to execute commands that contain more than 255 characters, which is an operatingsystem imposed limitation. The edit command opens a temporary text file in the default text editor from within the sp_ctrl interface. You enter the command in the file, and it automatically executes when you save the file. To use the edit command 1 If no commands were issued previously in the current session of sp_ctrl, type the first word of the command at the sp_ctrl prompt, then press Enter. Otherwise, skip
this step. (Ignore the online help or error that is displayed.) 2 At the sp_ctrl prompt, issue the edit command to open a temporary text file.
sp_ctrl(sysA)> edit 3 In the text file, use the editor’s standard commands to edit out any unwanted charac-
ters and type the command string. 4 Save and exit out of the file using the editor’s standard save command. The com-
mand executes immediately Tip: SharePlex provides keyboard shortcuts for the edit command in the for of the up arrow ( ) and the forward slash ( / ) keys.
108
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
CHAPTER 1 Using SharePlex Commands
Authorization level: Issued for: Related commands:
The user must have the previous command’s authorization level or higher. The system affected by the previous command none
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
edit | ed
not available
†
109
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
110
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
edit config Use the edit config command to modify an inactive configuration file. This command opens the configuration in SharePlex’s default text editor. Modify and save the configuration using the tools provided by the editor. You cannot directly edit an active configuration. You can copy an active configuration with the copy config command (see page 99), and then edit the copy with the edit config command. When you activate the copy, the original configuration deactivates. Note: To view a list of configurations on a system, use the list config command (see page 122). To view the contents of a configuration, use the view config command (see page 227).
Authorization level: Issued for: Related commands:
Operator (2) source system activate config, copy config, create config, list config, remove config, rename config, verify config, view config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
edit config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to edit. Configuration names are case-sensitive. Example: sp_ctrl(sysA)> edit config sales
CHAPTER 1 Using SharePlex Commands
111
exit Use the exit command to close the current session of sp_ctrl. Closing sp_ctrl does not shut down replication; all replication processes continue without interruption unless they have been stopped by a user. This command merely discontinues your session with sp_ctrl on that system. To run sp_ctrl again, change to the directory containing the SharePlex binaries and enter the ./sp_ctrl command (for UNIX systems) or double-click the sp_ctrl shortcut (Windows systems). There are no [on host] options for the exit command. It must be issued on the system where you want to stop running sp_ctrl. This command is the same as the quit command (see page 137). Authorization level: Issued for: Related commands:
Viewer (3) source or target system quit
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
exit | e
not available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
112
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
expand Use the expand command to expand a wildcard specification and display it to the screen. This is particularly useful if you are unsure of what wildcard specification will produce the specific list of tables you want to replicate using Oracle wildcard specification in the SharePlex configuration file. For more information on how to use Oracle wildards in the config file, see “Specifying source tables using wildcards” in the SharePlex Administrator’s Guide. Authorization level: Issued on: Related commands:
Viewer (3) source system create config, edit config, show config, verify config
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
expand filespec
[not ({list of exclusions})] [for o.{source_sid}] [on host]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filespec
This argument specifies the wildcarded Oracle object (including schema owner) that the command will execute against. Without the for datasource option it assumes that the schema and objects are in replication and are contained within the active configuration. Example: sp_ctrl(sysA)> expand scott.% In this example, the result will display all objects in the scott schema.
CHAPTER 1 Using SharePlex Commands
113
Command options OPTION
DESCRIPTION
not ({list of exclusions})
This option, referred to a not notation, list specific exclusions from the wildcarded schema and objects. Example: sp_ctrl(sysA)> expand scott.% for o.oraA not (%”foo”%) In this example, the result will display all objects in the scott schema from the oraA instance, except anything that contains “foo” in the object name. Please note that in this example, foo, is encased by quotation marks and as a result is case sensitive.
for o.{source_sid}
This command option is used when there is no active config and specifies the Oracle instance against which the command will be executed. Example: sp_ctrl(sysA)> expand scott.% for o.oraA In this example, the result will display all objects in the “scott” schema from the oraA instance.
on host
This option executes the command on the designated remote system. Example: sp_ctrl(sysA)> expan scott.% for o.oraB on sysB In this example, the result will display all objects in the “scott” schema from the oraB instance on sysB.
114
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
flush Use the flush command to stop the Post process at a certain point. It puts a marker in the data stream and automatically stops the Post process at the marker point. You can issue this command at a certain time or date – when month-end reports need to be generated, for example – and the data on the target system will reflect what was on the source system at the time the command was issued. When you are performing backups, or when following certain documented SharePlex procedures, you issue the flush command after you stop user access on the source system to ensure that the last transaction gets posted to the target database before Post is stopped.
Starting Post again Changes generated after the flush command accumulate in the queues and are applied to the target instance after you start Post again. Post remains stopped until the start post command is issued. Post keeps a record of where it stopped and resumes posting from that point to maintain synchronization. Important! If users continue making changes on the source system while Post is stopped, data will accumulate in the post queue and possibly consume all available disk space. Remember to start Post as soon as permissible.
Authorization level: Issued on: Related commands:
Operator (2) source system stop
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
flush datasource
[to host] [queue queuename] [to host queue queuename] [to host@target_SID] [to host@target_SID queue queuename]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
115
Required arguments ARGUMENT
DESCRIPTION
datasource
This argument specifies the source data that the command will affect. Without additional options, it flushes the data through all queues on all target systems and stops Post. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. Example: sp_ctrl(sysA)> flush o.oraA In this example, the data for instance oraA is flushed to all target systems.
Command options OPTION
DESCRIPTION
to host
This option flushes all of the data replicating to a designated target system. Replication to other target systems is unaffected. Example: sp_ctrl(sysA)> flush o.oraA to sysB In this example, the data is flushed from sysA to sysB.
queue queuename
This option flushes data for a designated post queue. It flushes data flowing through all queues of that name on all target systems. This option is most useful when there are named post queues. Example: sp_ctrl(sysA)> flush o.oraA queue sales In this example, the data is flushed for post queue sales on all target systems that have a post queue of that name.
to host queue queuename
This option flushes data for a designated post queue on a designated target system. Other post queues on that and other target systems are unaffected. Example: sp_ctrl(sysA)> flush o.oraA to sysB queue sales In this example, the data is flushed for post queue sales on sysB.
116
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
to host@datadest
This option flushes data to a designated target instance on a designated target system. It does not affect: • other target instances on that system. • other target instances with the same ORACLE_SID on other target systems In the syntax: • host is the target system’s name. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target instance. Example: sp_ctrl(sysA)> flush o.oraA to
[email protected] In this example, the data is flushed to instance oraB on sysB.
to host@datadest queue queuename
This option flushes data for a designated post queue and target instance on a designated target system. It does not affect: • other post queues for that instance or any other target instance on that system. • other post queues on any other target system. In the syntax: • host is the target system’s name. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target instance. • queuename is the name of the post queue. Example: sp_ctrl(sysA)> flush o.oraA to
[email protected] queue sales In this example, the data is flushed for post queue sales for target instance oraB on sysB.
CHAPTER 1 Using SharePlex Commands
117
help Use the help command to get help for SharePlex commands while working within sp_ctrl.
• Using this command without any options produces a list of SharePlex command groups.
• Additional options enable you to drill down through each group to get help for a specific command. There are no [on host] options for this command. Authorization level: Issued for: Related commands:
Viewer (3) source or target system usage
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
help
{groupname} {commandname}
not available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
118
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options OPTION
DESCRIPTION
groupname
Displays the commands within each group for which specific help can be obtained. Valid values are: config connect info maint misc param properties queues run sync For a list of commands within each group, see “SharePlex commands at a glance” on page 5. Example: sp_ctrl(sysA)> help run Control processes abort service - Stop one or all replication processes immediately. shutdown - Shut down SharePlex. start - Restart one or all stopped replication processes. startup - Start SharePlex if sp_cop was started with -s option. stop - Stop one or all replication processes gracefully.
commandname
This option provides help for a designated command. Example: sp_ctrl(sysA)> help start Restart a SharePlex process that was stopped with a "stop" or "abort service" command.
CHAPTER 1 Using SharePlex Commands
119
host Use the host command to establish a default system for sp_ctrl. A default machine enables you to enter a series of commands without using the [on host] option for each one. The TCP/IP connection to the default system remains active until you exit sp_ctrl or issue another host command. The default system name is displayed as part of the sp_ctrl prompt as shown below: sp_ctrl(hostname)>.
The default system can be the machine where you are running sp_ctrl or any other system to which that machine can connect through TCP/IP. To issue a command for a system other than the default, use the command’s [on host] option to temporarily connect to the alternate system. When the command finishes, it returns you to the default sp_ctrl connection. The host command can only be issued from within sp_ctrl at the sp_ctrl prompt. Tip: To set a default port number for an sp_ctrl session, use the port command (see page 131).
Authorization level: Issued for: Related commands:
Viewer (3) source or target system port
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
host hostname
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
120
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments ARGUMENT
DESCRIPTION
hostname
The name of the machine that you want to establish as the default. This name must reside in your system’s /etc/hosts file (UNIX) or hosts file (Windows). Example: sp_ctrl(sysA)> host sysB
CHAPTER 1 Using SharePlex Commands
121
hostinfo Use the hostinfo command to view information about a system’s hardware, including the operating system, machine name, OS version and revision. This is an example of the command’s output: HP-UX sys1 B.11 A 9000/861
Authorization level: Issued for: Related commands:
Viewer (3) source or target system none
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
hostinfo
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
122
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
list config Use the list config command to view a list of all active and inactive configurations on a source system. The command displays the following information:
• File Name: The name of the configuration, the time and date that it was modified, and the size of the file.
• State: Whether the configuration is active or inactive. Active means the configuration file is currently involved in replication. Inactive means the configuration is not currently involved in replication.
• Datasource: The Oracle instance containing the objects being replicated by the configuration.
• Internal Name: The name of the internal copy of the active configuration. This is the file that SharePlex actually replicates from. Its name is displayed under the State heading wherever there is an active configuration.
CHAPTER 1 Using SharePlex Commands
Authorization level: Issued for: Related commands:
Viewer (3) source system view config, show config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
list config
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
123
124
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
list param Use the list param command to display SharePlex tuning parameters. Without options, the command displays the basic (user configurable) parameters and their current settings. Options are available for displaying:
• all SharePlex parameters, including those that should not be changed by a SharePlex user (internal parameters).
• only the basic and internal parameters whose settings have been changed from their default values. (These settings are recorded in the SharePlex paramdb file.)
• either of the preceding options filtered according to the SharePlex module. Parameters are grouped by module, each module representing a functional component of the software. The following table lists the modules that contain user-configurable parameters (which can be changed without guidance from Quest). SharePlex parameter modules Module
Naming convention
Function controlled
capture
SP_OCT
Capture process
compare
SP_DEQ
compare commands
config
SP_OCF
configuration activation process
cop
SP_COP
sp_cop
export
SP_XPT
Export process
import
SP_IMP
Import process
logging
SP_SLG
the SNMP feature
post
SP_OPO
Post process
queue
SP_QUE
the SharePlex queues
read
SP_ORD
Read process
reconcile
SP_RCL
the reconcile command
stats
SP_SHS
the shared memory for statistics
SP_OSY
the SYNC family of commands, e.g. copy/ append
SP_SYS
system-related items
sync system
CHAPTER 1 Using SharePlex Commands
125
Each list param display provides the parameter’s:
• Name • Actual Value: the parameter’s current setting and its default value, if different. • Units: the parameter’s unit of measurement, such as seconds, kilobytes, or operations.
• Set-At point: the point where the parameter becomes active when you issue the set param command (see page 156), either immediately after the parameter is set, after the affected process is restarted, or after sp_cop is restarted.
SharePlex parameter “set-at” points This display, obtained using the list param command, shows the three possible “set-at” points for SharePlex parameters: Live, Restart Process, and Restart Cop.
See Chapter 2 for more information about SharePlex parameters.
Authorization level: Issued for: Related commands:
Viewer (3) source or target system set param, reset param
126
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SYNTAX BASIC COMMAND
COMMAND OPTIONS
list param
[basic | all | modified]
†
[ON HOST] OPTIONS†
[module]
available
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
basic
This option displays parameters that can be set by users without guidance from a Quest support engineer or technical specialist. Example: sp_ctrl(sysA)> list param basic
all
This option displays all of the SharePlex parameters, including basic (user-configurable) parameters and internal parameters (whose settings you should not change without guidance from Quest). Example: sp_ctrl(sysA)> list param all
modified
This option lists the user-configurable and internal parameters that have been modified from their default values. Example: sp_ctrl(sysA)> list param modified
module
This option constrains the output to parameters for a specific module.
• module is one of the module names listed on page 124. This option, if used, must appear after the list param [all | modified] syntax. Example: sp_ctrl> list param all post In this example, SharePlex displays all parameters for the Post process.
CHAPTER 1 Using SharePlex Commands
127
lstatus Use the lstatus command to view detailed information about the status of replication on a source or target system. This command is the most comprehensive information command in sp_ctrl. To view a brief status of replication, use the status command (see page 216). The lstatus command displays:
• • • • • • • •
The status of the replication processes, including their associated queues. The operating system process ID of each process. When the process started. The machine where the process is running. The number of messages (SQL or SharePlex operations) in the queues and their age. Whether the machine is a source or target system. Events that took place since sp_cop started. A list of active configurations.
The lstatus command also provides information about the queues, including:
• Type: The kind of queue that it is (capture queue, export queue, post queue). • Queue name: The name of the queue, either a default name or the user-assigned name of a named queue.
128
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• # Messages: The number of messages in the queue. A message approximately corresponds to a SQL operation, but there can be multiple messages for one operation on a LONG or LOB column. Conversely, there could be one message for numerous operations in an array insert.
• Size: The current size of the queue. This varies with the amount of data. For more information, see “Understanding the SharePlex queues” on page 129
• Age: The time difference between when the oldest and newest messages in the queue were written to that queue.
• Oldest Msg Time: The date and time the oldest message entered the queue. • Newest Msg Time: The date and time the newest message entered the queue. The lstatus command also provides other information, such as how the system is being used, its configuration activity, and errors that occurred. .
Understanding the SharePlex queues The following will help you understand the statistics for the SharePlex queues
CHAPTER 1 Using SharePlex Commands
129
Queue size Although SharePlex uses memory for the queues, the data is periodically written to disk as part of the checkpoint recovery system. The default size for SharePlex queue files is 8 MB. However, queue files are sparse files, meaning that from a system standpoint the file size is 8 MB, but the filesystem might only allocate part of the file for data written to the queues. That is why the qstatus command can show a queue size of less than 8 MB, but what you see with qstatus is NOT the true indication of the actual file size. To predict disk space usage for the queue files, use the information from qstatus and not the filesystem.
Number of queues It is normal for the capture and export queues to have fewer queue files than the post queue. Data that resides in one queue file on the source system is separated into multiple sub-queue files on the target system, each approximately corresponding to a user session on the source system.
Names of queues Queue names are case-sensitive on all platforms. The following explains the naming conventions for SharePlex queues.
• Default capture queues are identified by their datasource, which is expressed as o.SourceSID, for example o.ora64.
• Default export queues are identified by the source system's name, for example SysA. • Default post queues are identified by the name of the source system appended with datasource-datadestination, where datasource is o.sourceSid and datadestination is o.targetSID, for example lajolla (o.ora10a-o.ora10b).
• Named export and post queues are identified by their user-assigned names, not the default name. For more information about named queues, see the SharePlex Administrator’s Guide.
Authorization level: Issued for: Related commands:
Viewer (3) source or target system qstatus, show, show statusdb, status
130
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
lstatus
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
131
port Use the port command to connect from sp_ctrl to an instance of sp_cop that is running on a TCP/IP port number other than the default. The default port number for sp_cop is either 2100 (the default port in the param-defaults file when SharePlex was installed) or a user-defined port in the paramdb file that was set with the SP_COP_TPORT and SP_COP_UPORT parameters (see page 269). All commands issued during the current session of sp_ctrl will affect the sp_cop running on the specified port until the sp_ctrl session is terminated. A new session of sp_ctrl connects to the default port number or the one in the paramdb.
When to use the port command When you are running one instance of sp_cop, using the port command is unnecessary. On startup, sp_ctrl determines the port number by first checking the paramdb for a user-defined port and, if none exists, defaulting to port 2100. Use the port command when you are running multiple instances of sp_cop on dedicated ports (such as in consolidated replication) and default ports for them were not set with the SP_COP_TPORT and SP_COP_UPORT parameters. To issue commands for multiple sp_cop instances, open a session of sp_ctrl for each one, and use the port command to set a port for each session. SharePlex notifies you as follows if the port command is required when you start sp_ctrl: “Your tcp port is not set properly or 'sp_cop' is not running.”
The warning indicates that sp_cop is not running or that it is running on a different port than the default. The port command cannot be issued from a remote machine, so there are no [on host] options. Authorization level: Issued for: Related commands:
Viewer (3) source or target system host
132
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
port number
not available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
number
The port number you want to use. There must be a space between port and the port number. Example: sp_ctrl> port 2200
CHAPTER 1 Using SharePlex Commands
133
purge config Use the purge config command to remove the data from all queues associated with a configuration without removing the queues themselves or deactivating the configuration. Avoiding a deactivation avoids the need for SharePlex to recalculate the configuration data. This saves time when the tables are large and numerous, enabling replication can start sooner. Issue the purge config command on the source system to affect the source system and all target systems in the configured routes. Should any SharePlex process stop prior to or during the purge config activity, the command also stops working. When the process starts again, the command resumes working. Thus, purge config works even when the network is temporarily unavailable — the command remains in the queues until the connection is restored.
Cautions for using the purge config command • Do not activate a configuration and then follow the activate config command with a purge config command. You might be purging more than just queued data, including the configuration information that controls replication, thus rendering the activation invalid.
• When there are multiple active configurations on the same source system, use the purge config command only if there are named export queues that separate the replication streams for each one. Without named export queues, SharePlex funnels all replicated data through one export queue, and a purge config command for one configuration deletes the data for all of them. To create named queues, see Chapter 5 of the SharePlex Administrator’s Guide.
Authorization level: Issued for: Related commands:
Administrator (1) source system abort config, deactivate config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
purge config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
134
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to purge. Configuration names are case-sensitive. Example: sp_ctrl(sysA)> purge config sales
CHAPTER 1 Using SharePlex Commands
135
qstatus Use the qstatus command to view statistics for the capture, post, and export queues on any system. It displays the number of messages in each queue, their age, and the current size of the queue. Typically, a message approximately corresponds to a SQL operation, but there can be multiple messages for one operation on a LONG or LOB column, and there could be just one record for numerous operations of an array insert. A message also can be an internal SharePlex operation. Use the qstatus command to:
• determine if there is data still waiting to be read by a replication process or posted to the target database.
• estimate the speed at which SharePlex is processing by analyzing the rate at which messages accumulate.
• view the size of the queues to ensure that they do not exceed available disk space. • verify that all of the queues are empty when that is required for certain operational procedures or when you need to shut down replication for system maintenance, upgrades, and other administrative tasks.
• determine if there is user activity on a target system that can cause data to go out of synchronization. For more information about the SharePlex queues, refer to “Understanding the SharePlex queues” on page 128.
136
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
qstatus This command displays the status of all queues on a system.
sp_ctrl (bonzai:8800)> qstatus Queues Statistics for bonzai Name: o.a920a32a (Capture queue) Number of messages: (Age 2,3 44 Backlog (messages): 44 (Age
1
4
Name: bonzai (Export queue) Number of messages: 53158 (Age Backlog (messages): 0 (Age
5
0 min; Size 0 min) 163 min; Size 0 min)
Name: lajolla (o.a10a32a - o.a920a32a) (Post queue) Number of messages: 741 (Age 0 min; Size Backlog (messages): 644 (Age 0 min)
6
2 mb)
61 mb)
13 mb)
1 There are 44 messages in the Capture queue and 53,158 messages in the Export queue awaiting transport to this machine's target system(s). The size of this queue is 61 MB. 2 The number of messages in a queue reflects the messages that have been read by the next Share Plex process, as well as those that have not been read. As part of its checkpoint recovery system SharePlex retains copies of messages that were sent to the next process. These messages are deleted when receipt by that process is acknowledged. 3 The Backlog field indicates the number of messages yet to be read by the next SharePlex process. 4 The Age field is the difference in time between when the oldest and newest messages in the queue were written to the queue. 5 The presence of a Post queue indicates that this system is also used as a target system. A config uration with a queue name of lajolla is currently replicating data, as indicated by the messages in the Post queue. 6 The Size field indicates the true size of a queue. For more information about queue size, see “Understanding the SharePlex queues” on page 128.
Authorization level: Issued for: Related commands:
Viewer (3) source or target system lstatus, show
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
qstatus
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
137
quit Use the quit command to close the current session of sp_ctrl. Closing sp_ctrl does not shut down replication; all replication processes continue without interruption unless they have been stopped by a user. This command merely discontinues your session with sp_ctrl on that system. To run sp_ctrl again, change to the directory containing the SharePlex binaries and enter the ./sp_ctrl command (for UNIX systems) or double-click the sp_ctrl shortcut (Windows systems). There are no [on host] options for the quit command. It must be issued on the system where you want to stop running sp_ctrl. This command is the same as the exit command (see page 111). Authorization level: Viewer (3) Issued for: source or target system Related commands: exit SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
quit | q
not available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
138
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
reconcile Use the reconcile command as part of a procedure to synchronize source and target data with minimal interruption to the database users. Initial synchronization procedures are in Chapter 7 of the SharePlex Administrator’s Guide, and resynchronization procedures are in Chapter 1 of this guide. The reconcile command coordinates the results of ongoing replication with a hot copy of the source data that is applied to the target system by an Oracle hot-backup. After the target instance has been recovered and opened, the reconcile function compares the replicated changes in the post queue with the state of the target instance after the recovery process. It differentiates between the transactions that were applied during recovery from those that have not yet been applied (still waiting in the post queue), and it only posts the non-duplicated changes so that both systems are synchronized. The reconcile process
Use the basic command with one of the command options to reconcile data after an Oracle hot backup or to reconcile data in a peer-to-peer replication environment. Although the reconcile command is designed for use in high-volume environments, it can be used in low-volume environments with an understanding that the reconcile process can, in some circumstances, seem to stall. This happens because the reconcile command depends on data continuing to arrive from the source system. If there is no replication activity on the source system after the hot backup or copy, the reconcile process waits until source activity resumes.
CHAPTER 1 Using SharePlex Commands
139
Considerations when using the reconcile command Do not use the reconcile command unless you are following specific procedures in the SharePlex documentation or from another authorized source. For any given procedure, there are steps that must be followed in sequence to successfully restore replication after the backup or copy. Authorization level: Issued for: Related commands:
Administrator (1) target system flush
SYNTAX: BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
reconcile queue queuename for datasource-datadest
[seq sequence_number] [scn scn_number] [to flush]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
queue
queue is a required part of the command.
queuename
The post queue on the target system that you want to reconcile. Valid values are: • the name of the source system if using default queues • the name of the queue if using named queues When using named post queues, issue the reconcile command for each one. To determine the queue name, issue the qstatus command in sp_ctrl. Queue names are case-sensitive on all platforms.
140
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments (continued) ARGUMENT
DESCRIPTION
for datasource-datadest
• for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target instance. Example: sp_ctrl (sysB)> reconcile queue SysA for o.oraA-o.oraB In this example, the data is reconciled for default post queue o.oraA-o.oraB, which is the data stream replicating from source instance oraA to target instance oraB.
Command options OPTION
DESCRIPTION
seq sequence_number
Use this option when an Oracle hot backup is used in the synchronization procedure. It directs SharePlex to reconcile to the end of the same log that Oracle uses for its recovery. • seq is a required part of the syntax. • sequence_number is the sequence number of the log to which Oracle recovers. The syntax must appear after the syntax for the basic command. Do not use this option with the [to flush] option. Example: sp_ctrl (sysB)> reconcile queue SysA for o.oraA-o.oraB seq 1234 In this example, the data is reconciled for default post queue o.oraAo.oraB to the end of Oracle log number 1234.
scn scn_number
Use this option when an Oracle hot backup is used in the synchronization procedure. It directs SharePlex to reconcile to a specific Oracle System Change Number (SCN). • scn is a required part of the syntax. • scn_number is the SCN to which Oracle recovers. The syntax must appear after the syntax for the basic command. Do not use this option with the [to flush] option. Example: sp_ctrl (sysB)> reconcile queue SysA for o.oraA-o.oraB scn 0123456789 In this example, the data is reconciled for default post queue o.oraAo.oraB to the Oracle SCN 0123456789.
CHAPTER 1 Using SharePlex Commands
141
Command options (continued) OPTION
DESCRIPTION
to flush
Use this option to reconcile to a flush marker that is established with the flush command. Use it for synchronizing multiple databases in a peer-to-peer replication environment. The syntax must appear after the syntax for the basic command. Do not use this option with the [seq sequence_number] option. Example: sp_ctrl (sysA)> reconcile queue SysA for o.oraA-o.oraB to flush In this example, the data is reconciled for default post queue o.oraAo.oraB to the marker point established by the SharePlex flush command.
142
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
redo Use the redo command to execute the previous command again without having to retype it. This command is useful when you are making frequent status checks with the information commands, for example using the qstatus command to monitor changes in queue volume. This command only can be issued from within sp_ctrl; it cannot be issued directly from the operating system’s command line. There are no [on host] options for this command. SharePlex also provides keyboard short-cuts that perform the same task as the redo command. Invoking the forward slash or the up arrow while in sp_ctrl will execute the previous command. Authorization level: Issued for: Related commands:
To “redo” the previous command, the user must have that command’s authorization level or higher. The system affected by the previous command. none
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
redo | / | r
not available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
143
remove config Use the remove config command to permanently delete a configuration file from the system. This command does not prompt for confirmation, and removing a configuration file cannot be undone. You cannot remove an active configuration. To remove an active configuration, deactivate it first. Tip: You might be able to recover an accidentally deleted configuration if that configuration was previously active and you did not run ora_cleansp since it was activated. To recover the configuration, view the Event Log to determine the activation ID for that configuration file, then look in the save sub-directory of the SharePlex variable-data directory for a .conf.actid file, where actid is the activation ID you got from the Event Log.
Authorization level: Issued for: Related commands:
Operator (2) source system deactivate config, list config, show config, view config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
remove config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to remove. Configuration names are case-sensitive. Example: sp_ctrl(sysA)> remove config sales
144
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
remove log compare Use the remove log compare command to remove compare reports and compare logs generated by the compare config and compare table commands. These files reside in the log sub-directory of the SharePlex variable-data directory and can be removed when no longer needed. This command does not permit removing files selectively, such as only removing the logs but retaining the report(s).
Removing logs for the compare config command For the compare config command, the following are removed:
• The sp_desvr log on the source system. • The compare reports on all target systems in the configuration file. There is one report for each target table that was compared.
• The log for each sp_declt process on all target systems in the configuration file. There is a log for each processing thread that was generated on each system.
Removing logs for the compare table command For the compare table command, the following are removed:
• The sp_desvr log on the source system. • The compare report and the sp_declt log on the target system. For more information about the compare commands, see “compare config” on page 33 and “compare table” on page 55.
Using required arguments Arguments are available to remove files for:
• • • •
all completed compare processes a specific table a specific datasource a specific compare session ID
CHAPTER 1 Using SharePlex Commands
Authorization level: Issued for: Related commands:
145
Viewer (3) source system compare, show compare
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
remove log compare {id id_number | all | table owner.table_name}
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
id id_number
Use this option to remove the compare report(s) and log files for a specific compare session. • id is a required part of the syntax. Type a space after it. • id_number is the session ID number of the compare session whose files you want to remove. The session ID is the same as the operating system process ID number (PID) of the sp_desvr process on the source system. It appears within the name of the compare report and the logs, for example: scott-emp-12345.sql (compare report) oraA_desvr-12345-01.log oraA_declt-12345-01.log (logs) To determine the session ID, issue the basic show compare command, and look in the ID column. For more information about show compare, see page 173. Example: sp_ctrl(sysB)> remove log compare id 12345
all
Use this option to remove the compare reports and logs generated by all compare sessions that initiated on the source system where you are running the remove log compare all command. Any sp_declt logs that belong to compare sessions initiated on other source systems are not affected. Example: sp_ctrl(sysB)> remove log compare all
146
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments (continued) ARGUMENT
DESCRIPTION
table owner.table_name
Use this option to remove the compare reports and logs for all compare processes that originated on the local system for a specific table. • table is a required part of the syntax. Type a space after it. • owner.table_name is the owner and name of the source table whose files you want to remove. Example: sp_ctrl(sysA)> remove log compare table scott.emp In this example, the command removes the compare reports and logs for all comparisons issued for scott.emp.
CHAPTER 1 Using SharePlex Commands
147
rename config Use the rename config command to give a configuration file a different name. Use a name that is unique among the configuration files on the system. You cannot rename an active configuration. To rename an active configuration, deactivate it first. Authorization level: Issued for: Related commands:
Operator (2) source system copy config, edit config, list config, view config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
rename config filename to newname
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename to newname
• filename is the name of the configuration that you want to rename. Configuration names are case-sensitive. • to is a required part of the syntax. • newname is the new name you are giving the configuration. Example: sp_ctrl(sysA)> rename config sales to sales2
148
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
report Use this command to display the copy/append history for a table. Authorization level: Issued for: Related commands:
Viewer (3) source system copy/append
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
report
{source_owner}.{source_table} [copy] | [append] [toeditor] [for {o.source_sid}]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
{source_owner}. {source_table}
Specifies the source owner and source table name.
Command options OPTION
DESCRIPTION
{source_owner}.{source_t This option sets the source table for the synchronization report. Allow no able} spaces between components of the source owner and table name. Examples: sp_ctrl(SysA)> report s_user1.sync_single_tbl [copy] | [append]
This option returns results specific to either copy or append. Examples: sp_ctrl(SysA)> report copy s_user1.sync_single_tbl sp_ctrl(SysA)> report append s_user1.sync_single_tbl
CHAPTER 1 Using SharePlex Commands
149
Command options (continued) OPTION
DESCRIPTION
[toeditor]
This options sets the target Examples: sp_ctrl(SysA)> report s_user1.sync_single_tbl toeditor sp_ctrl(SysA)> report copy s_user1.sync_single_tbl toeditor
[for {o.source_sid}]
This option is used for specifying results specific to the provided source SID. Examples: sp_ctrl(SysA)> report s_user1.sync_single_tbl for o.source_sid1 sp_ctrl(SysA)> report copy s_user1.sync_single_tbl for o.source_sid1
150
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
reset param Use the reset param command to restore a parameter to its default value. The change takes effect based on the parameter’s set-at point:
• For a set-at point of Live, the change takes effect immediately. • For a set-at point of Restart Process, the change takes effect the next time the affected SharePlex process is started.
• For a set-at point of Restart Cop, the change takes effect the next time sp_cop is started (do not reboot the system).
Using command options The following are guidelines for resetting SharePlex parameters.
• To reset a parameter that was set with the set param command on a global basis (without process-specific options), use the reset param command without options. (See page 156 for more information about the set param command.)
• To reset a parameter that has a process-specific value (set with one of the set param process-specific options), use one of the reset param process-specific options. Process-specific options can be used for parameters in the following modules: Module
Naming convention
Function controlled
export
SP_XPT
Export process
import
SP_IMP
Import process
capture
SP_OCT
Capture process
post
SP_OPO
Post process
read
SP_ORD
Read process
Note: If the reset param command is issued for a process-specific parameter but there is no corresponding process-specific value for the parameter in the paramdb, SharePlex generates an error in the Event Log.
CHAPTER 1 Using SharePlex Commands
151
Viewing current parameter settings To view the names of SharePlex parameters, their values and set-at points, and whether or not process-specific values are in effect, use the list param command, as shown in the following example which shows both a global value for the Export process and a process-specific value for Export to sysB. Parameter Name
Actual Value
Units
Set At
---------------------------
-------------------
-------
--------------
SP_XPT_SO_SNDBUF
0
bytes
Restart Process
SP_XPT_SO_SNDBUF
1024
bytes
Restart Process
To sysB.ABC.com Default Value:
0
For more information about the list param command, see page 124.
Authorization level: Issued for: Related commands:
Administrator (1) source or target system list param, set param
SYNTAX BASIC COMMAND
PROCESS-SPECIFIC OPTIONS
[ON HOST] OPTIONS†
reset param paramname
[to host] [from host] [for datasource] [for datasource-datadest] [queue queuename]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
152
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments ARGUMENT
DESCRIPTION
paramname
The name of the parameter that you want to restore to its default value. This argument is not case-sensitive. Example: sp_ctrl(sysA)> reset param SP_XPT_SO_SNDBUF This resets the parameter for all Export processes on the system.
Process-specific command options OPTION
DESCRIPTION
to host
This option resets an Export parameter (SP_XPT_) for the Export processes to a designated target system. To restrict the command’s effect to the Export process associated with a named export queue, follow this option with the [queue queuename] option. Example: sp_ctrl(sysA)> reset param sp_xpt_so_sndbuf to sysB In this example, the parameter is reset for Export to sysB, but other Export processes are not affected.
from host
This option resets an Import parameter (SP_IMP_) for the Import processes from a designated source system. To restrict the command’s effect to the Import process associated with a named export queue, follow this option with the [queue queuename] option. Example: sp_ctrl(sysD)> reset param sp_imp_wcmt_msgcnt from sysC In this example, the parameter is reset for Import from sys C, but other Import processes are not affected.
for datasource
This option resets a Capture or Read parameter (SP_OCT_ or SP_ORD_) for a designated source Oracle instance. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source instance. Example: sp_ctrl(sysA)> reset param sp_oct_replicate_dload for o.oraA In this example, the parameter is reset for the Capture process for instance oraA, but other Capture processes are not affected.
CHAPTER 1 Using SharePlex Commands
153
Process-specific command options (continued) OPTION
DESCRIPTION
for datasource-datadest
This option resets a Post parameter (SP_OPO_) for all Post processes posting data from one database to another. To restrict the command’s effect to the Post process associated with a named post queue, follow this option with the [queue queuename] option. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target instance. Example: sp_ctrl(sysC)> reset param sp_opo_cont_on_err for o.oraA-o.oraC In this example, the parameter is reset for the Post process for instance oraA replicating to oraC, but other Post processes are not affected.
queue queuename
This option resets a parameter for an Export, Import or Post process associated with a designated named queue. Example: sp_ctrl(sysA)> reset param sp_opo_poster_delay queue QA In this example, the parameter is reset for the Post process associated with named post queue QA, but other Post processes are not affected.
154
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
set log Use the set log command to set the default parameters for the show log command. This command sets defaults for
• the maximum number of lines to extract from the log. • the maximum number of lines to display at once on the screen. • the direction in which you want to view the entries (newest to oldest, or oldest to newest). You can set any, or all, of those parameters at once with this command. There are no [on host] options for this command. For more information about the show log command, see page 187.
Authorization level: Issued for: Related commands:
Viewer (3) source or target system show log, view log options
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
set log {maxlines=number | lpp=number | reverse | forward}
not available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
maxlines=number
Use this option to set the default for the maximum number of lines of a log that the show log command displays. This option can be used alone or in combination with any other set log command options. Examples: sp_ctrl(sysA)> set log maxlines=50 sp_ctrl(sysA)> set log maxlines=50 lpp=34 reverse
CHAPTER 1 Using SharePlex Commands
155
Required arguments (continued) ARGUMENT
DESCRIPTION
lpp=number
Use this option to set the default for the number of lines per screen for the show log command. This option can be used alone or in combination with any other set log command options. Examples: sp_ctrl(sysA)> set log lpp=34 sp_ctrl(sysA)> set log maxlines=50 lpp=34 reverse
reverse
Use this option to start the show log output with the most recent entries. This option can be used alone or in combination with any other set log command options. Examples: sp_ctrl(sysA)> set log reverse sp_ctrl(sysA)> set log maxlines=50 lpp=34 reverse
forward
Use this option to start the show log output with the oldest entries. This option can be used alone or in combination with any other set log command options. Examples: sp_ctrl(sysA)> set log forward sp_ctrl(sysA)> set log maxlines=50 lpp=34 forward
156
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
set param Use the set param command to change the value of a SharePlex parameter. The new setting takes effect based on the parameter’s set-at point:
• For a set-at point of Live, the change takes effect immediately. • For a set-at point of Restart Process, the change takes effect the next time the affected SharePlex process is started.
• For a set-at point of Restart Cop, the change takes effect the next time that sp_cop is started. Do not reboot the system.
Changing a parameter from its default value When you change a parameter from its default value, SharePlex records the change in the paramdb file, where all user-defined parameter values are stored. Default values are stored in the param-defaults file. The default settings of most SharePlex parameters are adequate for most replication operations, but some can be changed by an authorized SharePlex user when necessary. Those parameters are viewed with the list param basic command. See Chapter 2 for information about user-configurable parameters. The rest of the parameters are considered non-user-changeable. They are viewed with the list param all command. Do not change those parameters without the supervision of Quest’s Development or Technical Support team, or unless you are following a documented procedure in a SharePlex guide. Unless you are familiar with those parameters, changing them could adversely affect replication.
Using command options The following explains how to use the set param command options.
• The basic set param command (without options) sets a parameter on a global basis for an instance of sp_cop. For example, the following command sets the parameter for all of the Export processes spawned by one instance of sp_cop. sp_ctrl(sysA)> set param SP_XPT_SO_SNDBUF 1024
CHAPTER 1 Using SharePlex Commands
157
• Parameters for the following replication processes can be process-specific, which enables you to set different values for the same parameter to accommodate multiple instances of a process running from one instance of sp_cop. Module
Naming convention
Function controlled
export
SP_XPT
Export process
import
SP_IMP
Import process
capture
SP_OCT
Capture process
post
SP_OPO
Post process
read
SP_ORD
Read process
You can use a process-specific value in conjunction with a global value for the same parameter. For example, you could set SP_XPT_SO_SNDBUF globally for all Export processes except the one transmitting to SysC; for that one you could set a different value by using the [to host value] process-specific option.
Viewing current parameter settings To view the names of SharePlex parameters, their values and set-at points, and whether or not process-specific values are in effect, use the list param command, as shown in the following example which shows both a global value for the Export process and a process-specific value for Export to sysB. Parameter Name
Actual Value
Units
Set At
---------------------------
-------------------
-------
--------------
SP_XPT_SO_SNDBUF
0
bytes
Restart Process
SP_XPT_SO_SNDBUF
1024
bytes
Restart Process
To sysB.ABC.com Default Value:
0
For more information about the list param command, see page 124.
158
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Changing a parameter back to its default value To change the value of a parameter back to its default value, use the reset param command (see page 150). Authorization level: Issued for: Related commands:
Administrator (1) source or target system list param, reset param
SYNTAX FOR GLOBAL SETTINGS BASIC COMMAND
[ON HOST] OPTIONS†
set param paramname value
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
SYNTAX FOR PROCESS-SPECIFIC SETTINGS BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
set param {paramname to host value | paramname from host value | paramname for datasource value | paramname for datasource-datadest value}
[queue queuename]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments for global settings ARGUMENT
DESCRIPTION
paramname value
• paramname is the name of the parameter that you want to set. This argument is not case-sensitive. • value is the new value for the parameter. Example: sp_ctrl(sysA)> set param SP_XPT_SO_SNDBUF 1024 In this example, the parameter is set globally for all Export processes on the system.
CHAPTER 1 Using SharePlex Commands
159
Required arguments for process-specific settings OPTION
DESCRIPTION
to host value
This option sets an Export parameter (SP_XPT_) for all Export processes to a designated target system. To constrain the change to an Export process associated with a named export queue, use this option with the [queue queuename] option. • host is the target system’s name. • value is the new value for the parameter. Example: sp_ctrl(sysA)> set param sp_xpt_so_sndbuf to sysB 1024 In this example, the parameter is set for Export to sysB, but Export processes to other target systems are not affected.
from host value
This option sets an Import parameter (SP_IMP_) for all Import processes from a designated source system. To constrain the change to an Import process associated with a named export queue, use this option with the [queue queuename] option. • host is the source system’s name. • value is the new value for the parameter. Example: sp_ctrl(sysD)> set param sp_imp_wcmt_msgcnt from sysC 10000 In this example, the parameter is set for Import from sys C, but Import processes from other source systems are not affected.
for datasource value
This option sets a Capture or Read parameter (SP_OCT_ or SP_ORD_) for a designated datasource. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • value is the new parameter value. Example: sp_ctrl(sysA)> set param sp_oct_replicate_dload for o.oraA 1 In this example, the parameter is set for Capture for instance oraA, but other Capture processes for the same instance of sp_cop are not affected.
160
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Required arguments for process-specific settings (continued) OPTION
DESCRIPTION
for datasource-datadest value
This option sets a Post parameter (SP_OPO_) for all Post processes posting data from one database to another. To constrain the change to a Post process associated with a named post queue, use this option with the [queue queuename] option. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target Oracle instance. • value is the new parameter value. Example: sp_ctrl(sysC)> set param sp_opo_cont_on_err for o.oraA-o.oraC 1 In this example, the parameter is set for the Post process for instance oraA replicating to oraC, but other Post processes are not affected.
CHAPTER 1 Using SharePlex Commands
Process-specific command options OPTION
DESCRIPTION
queue queuename
This option restricts the command’s effect to an Export, Import or Post process associated with a named queue. • queuename is the named queue’s name. When used, the queue queuename option must appear after the required and optional syntax, but before the new value, as shown below: Example 1: Export process sp_ctrl(sysA)> set param sp_xpt_so_sndbuf queue QA to sysB 1024 In this example, the parameter is set for the Export process associated with named export queue QA, but other Export processes are not affected. Example 2: Import process sp_ctrl(sysD)> set param sp_imp_wcmt_msgcnt from sysC queue QA 10000 In this example, the parameter is set for the Import process associated with named export queue QA, but other Import processes are not affected. Example 3: Post process sp_ctrl(sysC)> set param sp_opo_cont_on_err queue QA for o.oraA-o.oraC 1 In this example, the parameter is set for the Post process associated with named post queue QA for replication between oraA and oraC, but other Post processes are not affected. Example 4: Post process sp_ctrl(sysC)> set param sp_opo_cont_on_err queue QA 1 In this example, the parameter is set for the Post process associated with named post queue QA, but other Post processes are not affected.
161
162
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
show Use the show command to view the replication processes for an instance of sp_cop and the path the data is taking.
The following describes each column in the show command display:
Process The Process column shows the SharePlex replication processes (services) spawned by the instance of sp_cop to which the current sp_ctrl session is connected. The command does not show the command and control process (sp_cnc) or any compare processes that are running.
• If there are named export queues, there are multiple Export or Import processes, depending on whether it is a source or target sp_cop.
• If there are named post queues, there are multiple Post processes, one for each queue.
• The Post process is labeled MTPost. • For an instance of sp_cop running peer-to-peer replication, or for those that serve as both source and target sp_cop instances, all SharePlex replication processes are present.
Source The Source column shows the source of the data being processed by a SharePlex process. A source can be one of the following:
• For a Capture or Read process: the datasource (the source Oracle instance). • For an Export process: the name of the associated export queue. Default export queues bear the name of the source system. Named export queues bear their userassigned names, for example exptq1.
CHAPTER 1 Using SharePlex Commands
163
• For an Import process: the name of the associated default export queue (for example, sysA), or the name of the associated named export queue, such as exptq1.
• For a Post process: There can be one of several displays for the source of a Post process, depending on the replication configuration: --When there is a default export queue and a default post queue, the Post source is the short name of the associated post queue. The short name consists of the datasource and the source system’s name, in the format of o.ora10-elliot. --When there is a named export queue (which automatically creates a named post queue on the target system) the Post source consists of the datasource and the named export queue’s name, in the format of o.ora10-exptq1. --When there is a default export queue and a named post queue, the Post source consists of the datasource and the named post queue’s name, for example o.ora10postq1. See “show command example 1” and “show command example 2” for an illustration of this naming convention.
Target The Target column shows the destination, or target, of the data being processed by a SharePlex process. A target can be one of the following:
• For a Capture or Read process: There is no target to show for these processes. The data captured by the Capture process and routed by the Read process can be routed to one or many destinations.
• For an Export process: the name of the target system. • For an Import process: the name of the target system. • For a Post process: the target Oracle instance.
State The State column shows the status of each process:
• • • •
running idle (waiting for data to process) stopped by a user stopped because of an error.
PID This column lists the process ID number for each process.
164
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
show command example 1 named export queues In this example, the configuration on source system elliot employs named export queues. A named export queue spawns its own export and import process, a named post queue, and an associated Post process, as shown on target system maui.
show command example 2 named post queues In this example, the configuration on source system elliot replicating to target system maui employs named post queues and default export queues.
CHAPTER 1 Using SharePlex Commands
show command example 3 peer-to-peer replication In this example, the configurations on systems elliot and maui are part of a peer-to-peer replication configuration. In this scenario, all SharePlex processes are present on both systems. This configuration uses default export and post queues.
Authorization level: Issued for: Related commands:
Viewer (3) source or target system lstatus, qstatus, status
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
show
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
165
166
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
show activate Use the show activate command to view the status of activation activity on a source system. Concurrent activations for different datasources are displayed in the order that they started.
The command displays:
• The configuration’s name, datasource, and activation ID number, and the date and time it was activated.
• The number of tables that SharePlex is processing concurrently. This value depends on either the default number of threads for the activate config command (based on the value of the SP_OCF_THREAD_COUNT parameter) or that command’s [threads=n] option, if used. See “activate config” on page 22 for more information about multi-threaded activation.
• The number of tables in the processing batch whose activations completed successfully.
• The number of tables in the processing batch whose activations failed. • The names of the tables in the processing batch that are still being processed. • The tables for which SharePlex is waiting to receive a lock. The value is shown next to the name of the table in the list of tables still being processed.
CHAPTER 1 Using SharePlex Commands
167
The following are possible notice messages: Message
Reason
No current activation process. Activation is already finished. Use the show config command to view the active configuration.
The activation is finished.
No current activation process. Activation is already finished.
The activate config command was never issued
No tables to activate.
This message is generated when an active configuration is reactivated without being changed first. The show activate command generates output only when you activate the following: • a new configuration. • an edited configuration that contains new objects.
The show activate command remains in control of the sp_ctrl prompt until the entire activation is finished. To issue other commands in sp_ctrl while activation is in process, open another session of sp_ctrl. Authorization level: Issued for: Related commands:
Viewer (3) source system activate config, show config, view config
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
show activate
[for datasource]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
168
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options OPTION
DESCRIPTION
for datasource
Use this option to show activation for a specific Oracle instance when replication is active for multiple instances on a system. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. The default show activate behavior without this option is to show the activation processes for all active configurations. Example: sp_ctrl(sysA)> show activate for o.oraA
CHAPTER 1 Using SharePlex Commands
169
show capture Use the show capture command to view statistics for the Capture process.
• To view the state of the Capture process and a summary of the operations captured, use the show capture command without any options.
• To view detailed statistics, use the show capture command with the [detail] option. The statistics can help you tune Capture’s performance and diagnose problems.
• To filter the output based on the datasource (when there are multiple replicating Oracle instances), use the [for datasource] option. sp_ctrl (irvqasu21:2100)> show capture detail Host: irvqasu21 Operations Source Status Captured Since ---------- --------------- ---------- -----------------o.w920a32f Running 34324 14-Nov-07 15:19:23 Oracle current redo log : 1460 Capture current redo log : 1460 Capture log offset : 110489912 Last redo record processed: Operation on "SP_LOB_16K"."QA_LOB_REG_TAB_PART_8" at 11/14/07 15:22:06 Capture state Activation id Error count Operations captured Transactions captured
: : : : :
Processing 239 0 34324 3
Concurrent sessions HWM concurrent sessions Checkpoints performed Total operations processed Total transactions completed Total Kbytes read
: : : : : :
1 3 9 90642 507 732239
Redo Redo Redo Redo
: : : :
132002 310896 168422 AABaROAAWAAAAN1AAX
records records records records
in progress processed ignored - last HRID
170
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Understanding the detailed statistics The following points explain the statistics shown with the [detail] option.
• Oracle current redo log: The sequence number of the redo log to which Oracle is writing.
• Capture current redo log: The sequence number of the redo log that Capture is reading.
• Capture log offset: The location in the redo log of the record being processed by Capture.
• Last redo record processed: The record being processed by Capture or the last one processed if Capture is not currently replicating data.
• Capture state: The state of the process. There are three possible results. --INITIALIZING: Capture is starting up. --WAITING: Capture is reading the redo log and waiting for records that need to be replicated. --PROCESSING: Capture is processing a redo log record for replication.
• Activation ID: The internal identifying number of the configuration activation, which identifies the associated processes and queues.
• Error count: The number of records that were skipped due to Oracle errors since Capture started. Data from skipped records is not reflected in the target database.
• Operations captured: The number of redo records that Capture successfully processed for replication since it started.
• Transactions captured: The number of committed Oracle transactions whose operations Capture successfully replicated since it started.
• Concurrent sessions: The number of Oracle sessions being processed at the same time.
• HWM concurrent sessions: The largest number of concurrent Oracle sessions since Capture started.
• Checkpoints performed: The number of checkpoints to save the state of Capture since Capture started. Frequent checkpointing generates additional overhead on the system, but infrequent checkpoints cause SharePlex to recover less quickly from a system or instance failure. By default, Capture checkpoints every 20,000 seconds, but it can be adjusted with the SP_OCT_CHECKPOINT_FREQ parameter.
• Total operations processed: The number of all Oracle operations and SharePlex internal operations processed by Capture since it started, including records captured for replication and records for objects not in the configuration.
CHAPTER 1 Using SharePlex Commands
171
• Total transactions completed: The number of committed Oracle transactions processed by Capture since it started, including transactions captured for replication and transactions for objects not in the replication configuration.
• Redo records in progress: The number of records that Capture is processing. • Redo records processed: The total number of redo records processed. • Redo records ignored: The number of records that Capture ignored because they are not associated with objects in the configuration.
• Redo records - last HRID: The head row ID value for the last chained row processed by Capture. Note: The show capture detail output for RAC systems will vary slightly from what is described here. The information is essentially the same, but is necessarily presented differently.
Authorization level Issued for: Related commands:
Viewer (3) source system show export, show import, show post, show read
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
show capture
[detail] [for datasource]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
detail
This option displays detailed statistics for the Capture process. Example: sp_ctrl(sysA)> show capture detail
172
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
for datasource
This option shows Capture statistics only for a specific datasource. Other replicating datasources are unaffected. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. Example: sp_ctrl(sysA)> show capture for o.oraA In this example, Capture is shown on sysA only for instance oraA.
CHAPTER 1 Using SharePlex Commands
173
show compare Use the show compare command to obtain statistics about compare processes initiated by the compare config and compare table commands. The show compare command provides options to:
• view a list of compare processes running on a system. • view detailed statistics for one or more compare processes, or for a specific pair of source-target tables.
• view the compare report for one or more compared tables. For more information about the compare config command, see page 33. For more information about the compare table command, see page 55.
Viewing a list of compare processes Without additional options, the show compare command shows all current and completed compare processes that were issued on a source machine. It displays:
• the session ID number and the table extension number, which is appended to the session ID number as shown in the first column of the illustration on page 174. The table extension correlates to the order in which SharePlex lists the table in its internal database. When you use the compare config command, each table has its own extension number, but all tables share one session ID, because one compare config command compares them all. As long as the configuration is active, a table retains the same extension number throughout multiple compare sessions.
• the source table name(s). • the state of the process: either Error, Out Sync (out of sync), In Sync, Running, or Repaired.
• the time that the compare process started (if still running) or the time the process finished and generated a compare report (if the process is complete).
174
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
When you run one compare process for all tables in a configuration, each table has a unique ID number consisting of the main session ID plus an appended extension number.
Viewing detailed process statistics You can use the show compare command to view detailed statistics about one or more compare processes.
• Use the [detail] option to view statistics for all compare processes on the system. • Use the [table tablename] option to view statistics for all of the compare processes for a specific table, both active and inactive.
• Use the [id id_number] option to view statistics for a specific compare process or for a specific table within a configuration comparison.
• Use the [for datasource] option with the [detail] option to view statistics for compare processes for tables in a specific Oracle instance.
Statistics for active compare processes When a compare process is running, show compare compiles run-time statistics as shown in the following example.
CHAPTER 1 Using SharePlex Commands
175
ID Tablename Since Repair -------- ------------------------------ ------------------ -----23324 scott.T_HFL_3 16-Jan-01 13:45:57 On Source table Target table Target route Where clause Select hint Compare state Processed (%) Inserts needed Updates needed Deletes needed
: : : : : : : : : :
SCOTT.T_HFL_3 SCOTT.T_DEST_3 ted@ora920 Comparing 1.9 % 1 0 3
Details for an active compare process. There are four possible Compare States, depending on whether or not the repair option was used: • Comparing • Initializing for Repair • Repairing • Completed
The show compare process does not refresh the output for active comparisons on a real-time basis. To view the progress of a compare process, issue the show compare command again.
Statistics for completed compare processes For completed compare processes, show compare extracts the heading and summary information from the compare reports on the target system, as shown in the following examples.
ID Tablename Since Repair -------- -------------------------- ------------------ -----22504 SCOTT.T_HFL_4 15-Jan-01 15:27:14 Off Source table Source node Target table Target route Where clause Select hint * * * * * * * *
: : : : : :
SCOTT.T_HFL_4 ted SCOTT.T_DEST_4 ted@ora920
Compare Results 256 row comparisons completed successfully. 207 out-of-sync rows found in this table. Inserts : 104 Deletes : 103 Updates : 0
Details for a completed compare without the repair option. This provides information about the operations required to repair this table.
176
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
ID Tablename Since Repair -------- -------------------------------- ------------------ -----25034 SCOTT.T_HFL_10 16-Jan-01 10:17:48 On Source table Source node Target table Target route Where clause Select hint * * * * * * * *
: : : : : :
SCOTT.T_HFL_10 ted SCOTT.T_DEST_10 ted@ora920
Compare Results 397 row comparisons completed successfully.* 168 out-of-sync rows found and repaired.
Details for a completed compare with the repair option. This provides information about how the out-of-sync condition was repaired.
Inserts : 83 Deletes : 85 Updates : 0
*Note: The number of row comparisons reported by show compare equals the actual row count in the table only when the tables are in sync. When SharePlex does a repair on out-of-sync tables, the compare count is the total of the comparisons for both the compare process and the repair process (which are executed in separate passes). The number of row comparisons also is affected by the distribution of the out-of-sync rows. If outof-sync rows are dispersed among other, synchronized rows, more comparisons are generated than if the out-of-sync rows were grouped together at the end of the table. The number of comparisons, therefore, is a measure of the processing done by the compare config or compare table command.
Because the statistics from the compare report are obtained from the target machine, an error (“Could not obtain statistics from the target machine.”) is generated if communication cannot be made with that machine.
Viewing the compare report Every completed compare process generates a compare report for each table that was compared. The report shows detailed statistics and the SQL statements required to repair the table (or those that were applied by the repair process). If there were processing errors, the report contains references to the sp_desvr and sp_declt log files for further information. To view compare reports, use the show compare command with the [report] option in one of the following ways:
CHAPTER 1 Using SharePlex Commands
177
• To view reports for all completed compare processes, use the [report] option with no other options.
• To view a report for a specific table, use the [report] option with the [table tablename] option. This displays reports for all active and completed compare processes for that table.
• To view report(s) for a specific compare process, or for a specific table within a configuration comparison, use the [report] option with the [id id_number] option. This specifies the process or table by its session ID number (see “Identifying compare table processes” on page 59). SharePlex displays the session ID in the ID column when you issue the basic show compare or show compare for datasource command.
• To view reports for compare processes for a specific Oracle instance, use the [for datasource] option with the [report] option. This shows the reports for all tables in that instance for which a compare config or compare table command was issued. The following is an example of a compare report for a successful compare process that used the repair option: /* * Compare Report * * Session ID : 24269 * Schema : scott * Table : DEST1 * Repair : On * Where Clause: c1 >0 * Select Hint : * Log File : /splexdata/scott/var/log/sid_scott-DEST1-24269.sql * Date : Wed Aug 23 13:40:33 2001 * */ delete from “scott”.”DEST1” where rowid = 'AAAOzrAAHAAAAIIAAT'; insert into “scott”.”DEST1” (“C1”,”C2”,”C3”) values ('-20715242643699','V', 'C '); insert into “scott”.”DEST1” (“C1”,”C2”,”C3”) values ('18888226709999',NULL,NULL); delete from “scott”.”DEST1” where rowid = 'AAAOzrAALAAAAAyAAm'; delete from “scott”.”DEST1” where rowid = 'AAAOzrAAHAAAAIJAAo'; insert into “scott”.”DEST1” (“C1”,”C2”,”C3”) values ('-23354.22275999','V', 'C '); delete from “scott”.”DEST1” where rowid = 'AAAOzrAAHAAAAIGAAM'; insert into “scott”.”DEST1” (“C1”,”C2”,”C3”) values ('12294.14776999','VVVVVV', NULL); insert into “scott”.”DEST1” (“C1”,”C2”,”C3”) values ('15105.40969999', 'VVVVVVVVVVVVVVVVV','CCCCCCCCCC '); delete from “scott”.”DEST1” where rowid = 'AAAOzrAAHAAAAISAAG';
178
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
delete from “scott”.”DEST1” where rowid = 'AAAOzrAAHAAAAIQAAw'; delete from “scott”.”DEST1” where rowid = 'AAAOzrAALAAAAA3AAd'; insert into “scott”.”DEST1” (“C1”,”C2”,”C3”) values ('53282644125246', 'VVVVVVVVVVVVVV','CCCCCCC '); /* * Compare Results * * 1416 row comparisons completed successfully. * 13 out-of-sync rows found and repaired. * The table is now in sync. * The SQL statements above were applied to bring this * table back in sync. * * Inserts : 6 * Deletes : 7 * Updates : 0 * */ Note: For partitioned tables, the default behavior of the repair function is to convert each UPDATE to a DELETE followed by an INSERT to allow for possible row movement between partitions. Therefore, you will not see UPDATE statements in the report for those tables, but only INSERTS and DELETEs. If the SP_DEQ_PART_TABLE_UPDATE parameter (see page 280) is set to 1, however, the repair uses UPDATEs where appropriate, and then you will see UPDATE statements as well as INSERTs and DELETEs.
Because the number and length of SQL statements can be large, there is a limit to how many statements can be displayed with the [report] option. When the limit is reached, the following notice refers you to the report file itself, which resides in the log subdirectory of the SharePlex variable-data directory. To view the entire report see the following file on the target machine /splex/current/var8/log/ora920_SCOTT-T_DEST_7-14294.sql
Applying the SQL statements manually The SQL statements in the compare report can be applied manually to the target table if there have been no changes to the source table since the comparison was run. However, that is not the recommended procedure. The recommended procedure is to issue the compare config or compare table command with a repair option. If you do apply the statement(s) manually, and if the string data has an ampersand (&) character, you must issue the set define off command in SQL*Plus to turn off the special meaning of the ampersand so that Oracle does not interpret it as a variable.
CHAPTER 1 Using SharePlex Commands
179
Removing old compare reports SharePlex extracts the show compare statistics for completed compare processes from the compare reports. To prevent old compare processes from being displayed, you can either delete their report files from the log sub-directory, or use the remove log compare command in sp_ctrl (see page 144). After the reports are removed, the following notice appears when you issue the show compare command, unless you first run a comparison. No active or completed comparisons to show. Either the command never was issued, or the compare reports and log files necessary to provide this information have been removed from the system.
Authorization level: Issued for: Related commands:
Viewer (3) source system compare config, compare table, remove log compare
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
show compare
[detail | report] [table owner.table_name | id id_number] [for datasource]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
detail
Use this option to view detailed statistics and results for all current and complete compare processes, including those for which a repair was executed. It does not display the SQL statements needed to repair the tables (or the ones that were used, if a repair was performed). Example: sp_ctrl(sysA)> show compare detail
180
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
report
Use this option to view compare reports for all completed compare processes, including those for which a repair was executed. This option shows the SQL statements that are needed to repair the table (or that were used if a repair was performed). Example: sp_ctrl(sysA)> show compare report
table owner.tablename
Use this option to restrict the output to the compare processes for a specific table. • table is a required part of the syntax. • owner.tablename is the owner and name of the source table for which you want to view compare statistics. When used without additional options, the default behavior of this option is to display detailed statistics. When used with the [report] option, it shows the compare report. This option can appear in any order after the basic command. Examples: sp_ctrl(sysA)> show compare table scott.emp sp_ctrl(sysA)> show compare table scott.emp report
id id_number
Use this option to restrict the output to a specific compare session. • id is a required part of the syntax. • id_number is the session ID of the compare process that you want to view. This number is the same as the process ID number (PID) of the sp_desvr process on the source system. When used without additional options, the default behavior of this option is to display detailed statistics. When used with the [report] option, it shows the compare report. To use this option for a specific table that was part of the comparison of an entire configuration, use the session ID number appended with the table’s extension, for example 22504.5. This option can appear in any order after the basic command. Examples: sp_ctrl(sysA)> show compare id 25034 sp_ctrl(sysA)> show compare id 25034.8 sp_ctrl(sysA)> show compare id 25034 report
CHAPTER 1 Using SharePlex Commands
181
Command options (continued) OPTION
DESCRIPTION
for datasource
Use this option to restrict the output to the compare processes for a specific Oracle instance. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. The SID is case-sensitive and must appear as it does in the oratab file, V$PARAMETER table, or Windows Registry. This option can be used with other command options to filter their output for a specific Oracle instance. This option can appear in any order after the basic command. Examples: sp_ctrl(sysA)> show compare for o.oraA sp_ctrl(sysA)> show compare detail for o.oraA sp_ctrl(sysA)> show compare report for o.oraA
182
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
show config Use the show config command to display statistics for the active configuration. For example: sp_ctrl (irvspxu14:8567)> show config Materialized Views Replicating: “SCOTT”.”V5_ROWID” Tables Replicating with Key: “SCOTT”.”S1TEST2”
KEY: KC
“SCOTT”.”S2TEST2”
KEY: KC
“SCOTT”.”T1TEST2”
KEY: KC
“SCOTT”.”T2TEST2”
KEY: KC
Tables Replicating with no Key: “TED”.”DEMO_SRC” “TED”.”DEMO_DEST” “SCOTT”.”FOOS” filename : allscott Datasource : o.ora920 Activated : 29-Jan-09 10:11:41 Actid : 1810 Total Objects : 160 Total Objects Replicating : 160 Total Objects Not Replicating : 0 View config summary in /splex/rr/svn/var92/log/ora920_config_log
The following is displayed if this command is executed before Capture is up: sp_ctrl (irvspxu14:8567)> show config Capture is not yet replicating the most recent activation Re-issue this command when capture’s replication is current
Show Config provides the following statistics:
• Config: The configuration name. • Datasource: The Oracle instance containing the objects being replicated.
CHAPTER 1 Using SharePlex Commands
183
• Activated: The date and time that the configuration was activated. • Actid: The activation ID number for the configuration (mostly for use by Quest Technical Support).
• Total Objects: The number of objects in the configuration file. • Total Objects Replicating: The number of objects in the configuration that are replicating.
• Total Objects Not Replicating: The number of objects in the configuration for which activation failed, and therefore are not replicating.
• List of the tables in replication and having a primary or unique key, in replication and having no key, and not in replication For more information about the objects in the configuration, view the SID_config_log, where SID is the ORACLE_SID of the instance. SharePlex prints activation results and error messages in this file, which resides in the log sub-directory of the SharePlex variable-data directory. An example of the log file follows: File Name Datasource Activated Actid
:wild :ora920 :29-Jan-09 10:11:41 :1810
Total Objects :9 Total Objects Replicating :9 Total Objects Not Replicating :0 Objects Replicating: "SCOTT"."SRC_TEST1" "SCOTT"."SRC_TEST2" "SCOTT"."SS2_TEST1" "SCOTT"."SRC_TEST3" "SCOTT"."SRC_TEST4" "SCOTT"."SS2_TEST2" "SCOTT"."SRC_TEST5" "SCOTT"."SRC_TEST6" "SCOTT"."SS2_TEST3" Objects Not Replicating:
184
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Note: It may take a few seconds or longer to display the statistics.
Authorization level: Issued for: Related commands:
Viewer (3) source system activate config, show activate, view config, verify config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
show config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration for which you want to view statistics. Configuration names are case-sensitive. Example: sp_ctrl(sysA)> show config sales
CHAPTER 1 Using SharePlex Commands
185
show export Use the show export command to view statistics about the Export process. This command keeps a record of the number of messages* sent to target systems by all Export processes on the local machine. The message count begins over again whenever Export stops and starts again.
Authorization level: Issued for: Related commands:
Viewer (3) source system show capture, show import, show post, show read
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
show export
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14. Usage: show export [queue quename] [to host] [on host]
* Typically, a message approximately corresponds to a SQL operation, but there can be multiple messages for one operation on a LONG or LOB column, and there could be one record for numerous operations in an array insert. A message also can be an internal SharePlex operation.
186
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
show import Use the show import command to view statistics about the Import process. This command keeps a record of the number of messages* received from source systems by all Import processes on the local machine. The message count begins over again whenever Import stops and starts again.
Authorization level: Issued for: Related commands:
Viewer (3) source system show capture, show export, show post, show read
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
show import
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14. Usage: show import [queue quename] [from host] [on host]
* Typically, a message approximately corresponds to a SQL operation, but there can be multiple messages for one operation on a LONG or LOB column, and there could be one record for numerous operations in an array insert. A message also can be an internal SharePlex operation.
CHAPTER 1 Using SharePlex Commands
187
show log Use the show log command to view the SharePlex Event log or user issued commands through the sp_ctrl interface, instead of opening the log file directly through the operating system. This command can be used for logs smaller than 2 MB in size; otherwise, view the log directly through the filesystem. The default command used without any options displays 60 lines from the Event Log at 15 lines per page on the screen, starting with the oldest entry.
• To view the current show log default parameters, use the view log options command (see page 228).
• To change the defaults, use the set log command (see page 154). To override the set log defaults, you can use optional syntax to:
• • • • •
set the order of entries the number of lines extracted from the log the number of lines on the screen. filter entries by keyword view the user issued commands instead of the full Event Log.
show log reverse This example shows one of the options of the show log command — viewing the Event Log beginning with the most recent entry.
188
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Authorization level: Issued for: Related commands:
Viewer (3) source or target system set log, view log options
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
show log
[event | command | trace | post | capture | read] [maxlines=number] [lpp=number] [reverse] [forward] [filter=keyword]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
event
Use this option to display the Event Log. This option, if used, must appear in the syntax before any other option. It cannot be used with the [command] option. Example: sp_ctrl(sysA)> show log event
command
Use this option to view the user issued commands. This option, if used, must appear in the syntax before any other option. It cannot be used with the [event] option. Example: sp_ctrl(sysA)> show log command
post for DataDst queue Queue Use this option to view the Post Log. This option must specify the data Name destination and the queue name. Example: sp_ctrl(sysA)> show log post for DataDst queue Queue Name sp_ctrl(sysA)> show log post for o.a102a64f queue irvqasu21
CHAPTER 1 Using SharePlex Commands
189
Command options (continued) OPTION
DESCRIPTION
capture for DataSrc
Use this option to view the Capture Log. This option must specify the data source. Example: sp_ctrl(sysA)> show log capture for o.a920a64a
read for DataSrc
Use this option to view the Read Log. This option must specify the data source. Example: sp_ctrl(sysA)> show log read for o.a920a64a
maxlines=number
Use this option to specify the maximum number of lines to extract from the log. Without this option, show log defaults to 60 lines or the value set with the set log command. Example: sp_ctrl(sysA)> show log maxlines=50
lpp=number
Use this option to customize the output to fit your monitor screen. It specifies the number of lines to display on your screen. Without this option, show log defaults to 15 lines or the value set with the set log command. Example: sp_ctrl(sysA)> show log lpp=34
reverse
Use this option to order the display starting with the most recent entry. Without this option, show log defaults to the forward direction or the value set with the set log command. Example: sp_ctrl(sysA)> show log reverse
forward
Use this option to order the display starting with the oldest entry. Without this option, show log defaults to the forward direction or the value set with the set log command. Example: sp_ctrl(sysA)> show log forward
190
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
filter=keyword
Use this option to filter log entries based on a keyword. There are two ways to use this option: • To view only those lines containing the keyword, type filter=keyword • To exclude lines containing the keyword, precede the keyword with an exclamation point (!), as in filter=!keyword The keyword cannot contain blanks. Examples: sp_ctrl(sysA)> show log filter=compare The preceding example extracts only the compare related messages from the Event Log. Notice 08-07-08 22:47:21.906001 96492 1 User command: qarun remove log compare all (from irvqasu21.quest.com)
sp_ctrl(sysA)> show log filter=!Notice The preceding example excludes all Notice entries from the Event Log but shows all other types of entries. Info 08-07-08 22:47:19.642379 96490 1 Command server launched, pid = 96490 (connecting from irvqasu21.quest.com) Info 08-07-08 22:47:20.825598 96492 1 Command server launched, pid = 96492 (connecting from irvqasu21.quest.com) Info 08-07-08 22:47:22.334040 23710 1 Command server launched, pid = 23710 (connecting from irvqasl03.quest.com) Info 08-07-08 22:47:23.969925 125996 1 Compare server launched, pid = 125996 Info 08-07-08 22:47:24.632481 125996 1 Compare server completed
Note: To obtain the DataSrc, DataDst, and Queue Name use the lstatus command and refer to the Queues sub-section. For more information on the lstatus command see “lstatus” on page 127.
CHAPTER 1 Using SharePlex Commands
191
show post Use the show post command to view statistics for the Post process. This command provides options for viewing global statistics for the Post process as a whole, as well as options for viewing statistics for individual processing threads. For more information about the Post process, see Chapter 6 of the SharePlex Administrator’s Guide.
Viewing global Post statistics The following are options for viewing global Post statistics.
• To determine the state of the Post process and the number of messages* posted since it started, use the show post command without additional options. sp_ctrl (irvqasu21:9765)> show post Host : irvqasu21.quest.com Source : o.a920a32a Queue : irvqasl20 Operations Target Status Posted Since Total Backlog ---------- --------------- ---------- ------------------ ---------- --------o.a102a64f Running 3203 15-May-07 14:03:22 47 0 Last operation posted: Redo log: 6726 Log offset: 84637788 COMMIT "SP_IOT"."QA_IOT_TAB_9" at 15-May-07 14:08:53
• To view detailed global statistics for the Post process, use the show post command with the [detail] option. That option shows the most recent SQL statement processed, as well as other statistics that can help you assess Post’s performance, decide whether tuning parameters need to be adjusted, and detect problems or bottlenecks.
* Typically, a message approximately corresponds to a SQL operation, but there can be multiple messages for one operation on a LONG or LOB column, and there could be one record for numerous operations in an array insert. A message also can be an internal SharePlex operation.
192
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
The show post detail shows an aggregate of statistics for all of the Post processing threads, with statistics for the most recently processed SQL statement. sp_ctrl (irvqasu21:9765)> show post detail Host : irvqasu21.quest.com Source : o.a920a32a Queue : irvqasl20 Operations Target Status Posted Since Total Backlog ---------- --------------- ---------- ------------------ ---------- --------o.a102a64f Running 3203 15-May-07 14:03:22 47 0 Last operation posted: Redo log: 6726 Log offset: 84637788 COMMIT "SP_IOT"."QA_IOT_TAB_9" at 15-May-07 14:08:53 Post state Activation Id Current transaction Id ID of blocking transaction Number of open transactions Number of messages read released
: : : : : :
Waiting 301 2 0 1 42986
Number of threads
: 2
Operations posted Transactions posted
: 3203 : 115
Insert operations Update operations Delete operations
: 2023 : 84 : 63
Key cache hit count SQL cache hit count
: 0 : 84 %
• To filter the output for a specific post queue or datasource (useful when you have multiple replicating data streams), use the [queue queuename] or [for datasourcedatadest] option.
Viewing statistics for SQL threads The following are options for viewing statistics for the processing threads within the Post process.
CHAPTER 1 Using SharePlex Commands
193
• To view basic statistics for the processing threads, use the [threads] option. It displays the status of the main Post thread and the SQL threads. The main thread always is thread number 1. sp_ctrl (irvqasu15:9765)> show post threads Thread -----1 772
Type ------Main Session
Status Instance Session Msgs waiting Last oper processed ------- -------- ------- ------------ ------------------Waiting Wait 0 2 0 15-May-07 14:13:14
For each SQL thread, show post threads provides the corresponding session number and message backlog, as well as the timestamp for the last operation processed. The main thread has no session number or related statistics, because it is not a SQL thread that posts data.
• To view detailed processing statistics for a specific thread or session, use the [thread=n] or [session=n] option, where n is the thread or session number shown in the show post threads display. Both options provide identical output. sp_ctrl (irvqasu21:9765)> show post thread=772 Host : irvqasu21.quest.com Source : o.a920a32a Queue : irvqasl20 Operations Target Status Posted Since Total Backlog ---------- --------------- ---------- ------------------ ---------- --------o.a102a64f Running 282 15-May-07 14:10:37 70 68 Last operation posted: Redo log: 6727 Log offset: 2242868 ALTER TABLE "SP_IOT"."QA_IOT_TAB_10" at 15-May-07 14:13:14 Thread state Thread type Thread number Instance id Session / subqueue id Messages waiting in thread queue Transaction state
: : : : : : :
Active Session 772 0 2 0 Open
Operations posted Transactions posted
: 282 : 3
Insert operations Update operations Delete operations
: 17 : 0 : 0
Key cache hit count SQL cache hit count
: 0 : 0 %
194
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Note: When you issue show post thread=1, it displays the following message: Thread 1 does not exist.
• To filter the output for a specific post queue or datasource (useful when you have multiple replicating data streams), use the [queue queuename] or [for datasourcedatadest] option.
Explanation of show post statistics Global statistics The following explains the statistics shown with show post. Some appear only for the [detail] option while others appear only for the [thread=n] or [session=n] options.
• Host: The name of the local machine (target system). • Source: The source of the data being processed by Post, expressed as o.SID, where SID is the ORACLE_SID of the source database.
• Queue: The Post queue for this Post process. For a default Post queue, it is the name of the source system. For a named queue, it is the user-defined name.
• Target: The target Oracle instance for the data being processed by Post, expressed as o.SID, where SID is the ORACLE_SID of the target database.
• Status: The status of the Post process (or a specified thread). Possible states are: --WAITING --RUNNING --STOPPED --STOPPED BY USER --ABORTED --STOPPED DUE TO ERROR.
• Operations posted: The number of Oracle and SharePlex internal operations that Post (or a specified thread) processed since it was started.
• Since: The time that Post (or a specified thread) started. • Total: The number of messages that have yet to be read-released. This number corresponds to the 'Number of messages' returned from running qstatus.
• Backlog: The number of messages that are waiting in the queue to be processed by Post (or a specified thread).
CHAPTER 1 Using SharePlex Commands
195
• Last operation posted: The operation being posted to the target database if Post (or a specified thread) is active, or the last operation posted if it is inactive. An operation can be one of the following: --INSERT --UPDATE --DELETE --TRUNCATE --COMMIT --DDL statement --INSERT_MULTIPLE or DELETE_MULTIPLE (array operations). --SharePlex internal operation. Associated with this statistic are the following fields that describe the operation: --The owner and name of the table or sequence. --The time the operation took place. --Redo log: The sequence number of the redo log containing the record that Post (or a specified thread) is processing. --Log offset: The location of the record in the redo log.
• Post state (or thread state): The state of the process. It can be one of the following: --WAITING: Post (or a thread) is waiting for messages to process. --APPLY CHANGES: the transaction is uncommitted but the data is being applied to the database while a copy is retained in the post queue in case of a ROLLBACK. --COMMIT TRANSACTION: the transaction was completed on the source system with a COMMIT, so it is being committed to the target database. --SKIP RECORDS FOR ROLLBACK: the transaction is being rolled back and will not be applied to the target database. --RECOVERY: Post is in a crash-recovery mode.
• Activation ID: The current configuration’s activation ID number. • Current transaction ID: The SharePlex transaction ID of the transaction being processed. SharePlex creates internal transaction ID numbers for Oracle transactions.
• ID of blocking transaction: The transaction ID of a transaction that is blocking another transaction.
• Number of open transaction(s): The number of concurrent transactions that Post is processing. This field helps you determine when to stop and start the Post process to re-initialize the SQL Cache parameter. For example, if the SQL Cache size needs to be reduced to accommodate more transactions, this field can confirm whether or not
196
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
the number of concurrent transactions is decreasing. If it is, this is probably a good time to stop and start Post to bring the SQL Cache size back to its original state. For more information about the SQL Cache, refer to page 224 in the SharePlex Administration Guide.
• Number of threads: The number of processing threads, including the main and timekeeper threads.
• Number of messages read released: The difference between the number of operations posted and the actual number of operations removed from the queue. This field is used mainly by Quest Technical Support staff when Post is stalled.
• Operations posted: The number of SQL operations posted to the database, whether or not the COMMIT has been received.
• Transactions posted: The number of committed user transactions that Post (or a specified thread) posted to the database since it was started.
• Insert operations: The number of INSERT statements processed by Post (or a specified thread) since it was started.
• Update operations: The number of UPDATE statements processed by Post (or a specified thread) since it was started.
• Delete operations: The number of DELETE statements processed by Post (or a specified thread) since it was started.
• Key cache hit count: The number of times that the SharePlex internal key cache was used by the Post process (or a specified thread) to generate UPDATE statements. SharePlex uses the key cache to post data to the target instance quickly.
• SQL cache hit count: The ratio of the total number of messages that were executed without parsing and binding divided by the total number of INSERT, UPDATE and DELETE operations. For more information on the SQL Cache feature of SharePlex, see Chapter 6 of the SharePlex Administrator’s Guide.
Thread statistics When you issue show post with the [thread=n] or [session=n] option, the following statistics appear in combination with certain global statistics previously described.
• Thread state: The thread state • Thread type: The thread type, whether the main processing thread or a SQL processing thread. The SQL threads are the threads that process the data. Generally, there is one thread per user session on the source system, but threads can process multiple sessions if the number of threads exceeds 64.
• Thread number: The number assigned by the main Post thread to the SQL thread.
CHAPTER 1 Using SharePlex Commands
197
• Session/subqueue id: The Post subqueue from which the thread is processing data. Each subqueue corresponds to a user session on the source system.
• Messages waiting in thread queue: The number of messages in the thread’s waiting queue that need to be processed.
• Transaction state: The state of the transaction containing the operation being posted, either OPEN or COMMIT. Authorization level: Issued for: Related commands:
Viewer (3) target system show capture, show read, show export, show import
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
show post
[detail] [queue queuename] [for datasource-datadest] [threads] [thread=n] [session=n]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
detail
This option displays detailed statistics for the Post process. Example: sp_ctrl(sysB)> show post detail
198
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options (continued) OPTION
DESCRIPTION
queue queuename
This option filters the show post display for a specific post queue. • queue is a required part of the syntax. • queuename is the post queue for which you want to see Post statistics. Valid values are: --the name of the source system if using default queues. --the user-defined queue name, if using named queues. If you are unsure what the queue name is, issue the qstatus command. Queue names are case-sensitive on all platforms. This option can appear in any order with other options. Example: sp_ctrl(sysB)> show post queue sysA
for datasource-datadest
This option filters the show post display for a specific data stream. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target Oracle instance. This option can appear in any order with other options. Example: sp_ctrl(sysB)> show post for o.oraA-o.oraB
threads
This option displays a list of, and statistics for, all of the threads spawned by the Post process. This option can appear in any order with other options. Example: sp_ctrl(sysB)> show post threads
thread=n
This option displays detailed statistics for a SQL processing thread. • thread= is a required part of the syntax. • n is any thread number displayed with the show post threads command. Leave no space between any of the components. This option can appear in any order with other options. Example: sp_ctrl(sysB)> show post thread=1234
CHAPTER 1 Using SharePlex Commands
199
Command options (continued) OPTION
DESCRIPTION
session=n
This option displays detailed statistics for a user session. • session= is a required part of the syntax. • n is any session number displayed with the show post threads command. Leave no space between any of the components. This option can appear in any order with any other option. Example: sp_ctrl(sysB)> show post session=1234
200
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
show read Use the show read command to view statistics about the Read process. The following are options for viewing Read statistics.
• To view the status of the Read process since it started, use the show read command without any options.
• To view detailed statistics, use show read with the [detail] option. That option shows Read’s progress and can help you fine-tune performance and pinpoint problems when problem solving.
show read detail These are the Read statistics that SharePlex displays when you issue the show read detail command.
• To filter the output based on the datasource (useful when you have multiple replicating Oracle instances), use the [for datasource] option.
CHAPTER 1 Using SharePlex Commands
201
Explanation of statistics: • Last operation forwarded: The most recent operation that Read sent to the export queue, or the last operation it sent if Read is inactive. An operation can be one of the following: --INSERT --UPDATE --DELETE --TRUNCATE --COMMIT --DDL statement --INSERT_MULTIPLE or DELETE_MULTIPLE (array operations). --SharePlex internal operation. Associated with this statistic are the following fields that describe the operation: --The owner and name of the table or sequence. --The time the operation took place. --Redo log: The sequence number of the redo log containing the record that Read is currently processing. --Log offset: The location of the record in the redo log.
• Read state: One of the following possible states: --IDLE: Read is waiting to collect and process the next batch of records from the capture queue. If Read is idle too long, it could mean that Capture is running behind or that it is idle because there is no new data in the capture queue. If that is not the case, and you want to reduce the latency of the Read process, you can adjust the SP_ORD_DELAY_RECORDS parameter (see page 247) to have Read collect and process records faster. --PASS1: Read is in the first phase of processing the data and packaging it for routing. --PASS2: Read is in its second phase of processing. The Read State field is useful if Read appears to be taking too long to process an operation.
• Activation ID: The internal identifying number of the configuration activation, which identifies the associated processes and queues.
• Operations forwarded: The number of Oracle and internal SharePlex operations sent by Read to the export queue since it started.
202
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• Transactions forwarded: The number of committed transactions sent by Read to the export queue since it started. Comparing this value with the value for the operations forwarded indicates whether the transactions tend to be small or large. You can use that information to determine why Read appears to be falling behind and why the queues are not emptying (large transactions without a COMMIT).
• Cursor cache hit count: The number of times Read used a cached cursor. • Cursor cache miss count: The number of times Read could not use a cached cursor. • Number of open cursors: The number of open cursors reserved by Read to access Oracle if necessary. Authorization level: Issued for: Related commands:
Viewer (3) source system show capture, show export, show import, show post
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
show read
[detail] [for datasource]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
detail
This option displays detailed statistics for the Read process. Example: sp_ctrl(sysA)> show read detail
for datasource
This option shows Read statistics for a specific datasource. It does not show other replicating datasources. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. Example: sp_ctrl(sysA)> show read for o.oraA In this example, Read is shown on sysA only for instance oraA.
CHAPTER 1 Using SharePlex Commands
203
show sql Use the show sql command to view the SQL statement being written by the Post process to post data to the target database. If the post queue is empty, or if Post is not processing a statement, the show sql command shows the most recent SQL statement processed. Use this command when you think replication is taking too long, or when Post stops on an error. Knowing which SQL statement is at fault can help you determine what is wrong and whether or not further action is required. For tips on resolving Post problems and other replication problems, see Chapter 1. The following is an example of the show sql display: sp_ctrl (tustin:8852)> show sql Last SQL statement of queue tustin and instance o.ora920-0.ora920 on tustin insert into “KWONG”.”KCWTAB2” (“C1”,”C2”) values (:V001,:V002)
Issue this command for the target system. Authorization level: Issued for: Related commands:
Viewer (3) target system none
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
show sql
[queue queuename] [for datasource-datadest] [thread=n] [session=n]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
204
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options OPTION
DESCRIPTION
queue queuename
Use this option to show the SQL statement for a specific named queue. • queue is a required part of the syntax. • queuename is the name of the queue. If you are unsure what the queue name is, issue the qstatus command. Queue names are case-sensitive on all platforms. Example: sp_ctrl(sysA)> show sql queue q1
for datasource-datadest
Use this option to show the SQL for a specific replication stream when you are replicating to or from more than one Oracle instance. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target Oracle instance. Example: sp_ctrl(sysA)> show sql for o.oraA-o.oraB
thread=n
Use this option to show the SQL for a post processing thread. • thread= is a required part of the syntax. • n is a thread number displayed with the show post threads command. Leave no spaces between the components. This option can appear in any order with other options. Example: sp_ctrl(sysB)> show sql thread=1234
session=n
Use this option to show the SQL for a user session. • session= is a required part of the syntax. • n is a session number displayed with the show post threads command. Leave no space between the components. This option can appear in any order with other options. Example: sp_ctrl(sysB)> show sql session=1234
CHAPTER 1 Using SharePlex Commands
205
show statusdb Use the show statusdb command to view the Status Database. Each machine involved in replication has its own Status Database that contains records of key replication events, including those that did not generate an error message or warning at the user interface. This information can alert you to potential problems and help you resolve existing ones. The show statusdb display includes the following information:
• Level: whether the entry is there only for information purposes or whether it is the result of an error or warning condition.
• Details: the reason for the event.
When appropriate, the Status Database refers you to the Event Log if there is more information about an entry. See Chapter 1 for more information about the Event Log and for explanations of common error messages. Authorization level: Issued for: Related commands:
Viewer (3) source or target system status, lstatus
206
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
show statusdb
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
detail
This option displays a higher level of detail for the Status Database. Example: sp_ctrl(sysB)> show statusdb detail
CHAPTER 1 Using SharePlex Commands
207
show sync The show sync command shows any out-of-sync issues that Post may have encountered. The information is extracted from the Status Database. For each out-of-sync object, the command displays:
• Count: the number of statements that failed • Detail: contains the table name, queue name, date and time To see which SQL statement caused the error, view the SID_errlog.sql log file. The Event Log also will contain a record of the problem. For more information about these logs, see Chapter 1. If nothing is out of synchronization when you issue the show sync command, you will be returned to the sp_crtl prompt. Issue this command for the target system.
Authorization level: Issued for: Related commands:
Viewer (3) target system show statusdb
208
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
BASIC COMMAND
[ON HOST] OPTIONS†
show sync
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
209
shutdown Use the shutdown command to shut down replication. Upon completion of the shutdown command, SharePlex shuts down sp_ctrl automatically.
Shutting down gracefully The basic shutdown command shuts down sp_cop (the SharePlex service on Windows systems) and all other SharePlex processes gracefully, saving the state of each process, performing a checkpoint to disk, read-releasing buffered data, and cleaning up child processes. Data in the queues remains safely in place, ready for processing when an authorized user starts sp_cop again.
Shutting down forcefully The shutdown command with the [force] option kills the SharePlex processes immediately, whether or not the normal shutdown procedures were completed. SharePlex recovers from a forced shutdown when you start sp_cop, but replication processing resumes from a previous save point, which means startup can be slightly longer. Use the [force] option only if you tried to shut down SharePlex gracefully, but child processes remained running. You can verify whether SharePlex processes are still running by issuing the ps -ef | grep sp_ command in the UNIX shell or by viewing the Processes tab in Windows Task Manager. Warning! If you shut down replication and users continue changing the objects in the active configuration(s), it is possible for the Oracle redo logs to wrap before SharePlex starts again. If the delay is long and the archive logs become unavailable, you will need to re-synchronize the data. The redo logs should be large and numerous enough to accommodate the time SharePlex will be shut down. For more information about proper sizing of the redo logs for replication, see Chapter 4 of the SharePlex Administrator’s Guide.
Authorization level: Issued for: Related commands:
Administrator (1) source or target system startup
210
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
shutdown
[force]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Command options OPTION
DESCRIPTION
force
This option shuts down all replication processes, including sp_cop, immediately, whether or not they have finished reading from or writing to a queue. Use this option if the default shutdown command fails or you cannot wait for a graceful shutdown. Example: sp_ctrl(sysA)> shutdown force
CHAPTER 1 Using SharePlex Commands
211
start Use the start command to start a replication process after it was stopped using the stop or abort [service] command, or after Post was stopped by the flush command. Authorization level: Issued for: Related commands:
Operator (2); Administer (1) required for Capture source or target system stop
SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
start service
[to host] [from host] [for datasource] [for datasource-datadest] [queue queuename]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
service
The SharePlex process you want to start. Valid values are: • Capture • Read • Export • Import • Post Example: sp_ctrl(sysA)> start export
212
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options OPTION
DESCRIPTION
to host
This option starts Export to a designated target system only. • to is a required part of the syntax. • host is the name of the target system. Example: sp_ctrl(sysA)> start export to sysB In this example, Export is started from sysA to sysB.
from host
This option starts Import from a designated source system only. • from is a required part of the syntax. • host is the name of the source system. Example: sp_ctrl(sysD)> start import from sysA In this example, Import is started on sysD from sysA.
for datasource
This option starts Capture or Read for a designated Oracle instance. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. Example: sp_ctrl(sysA)> start read for o.oraA In this example, Read is started on sysA for instance oraA.
for datasource-datadest
This option starts Post for a designated source SID-target SID data stream only. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target Oracle instance. Example: sp_ctrl(sysC)> start post for o.oraA-o.oraC In this example, Post is started on sysC for instance oraA replicating to oraC.
CHAPTER 1 Using SharePlex Commands
213
Command options (continued) OPTION
DESCRIPTION
queue queuename
This option starts the Export, Import or Post process associated with a designated named queue. • queue is a required part of the syntax. • queuename is the named of the queue as written in the configuration file. Example: sp_ctrl(sysA)> start export queue QA In this example, Export of data through named export queue QA is started on sysA.
214
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
startup Use the startup command to start replication only if sp_cop was started using the [–s] option on a UNIX machine. When there is an active configuration, replication normally starts automatically when you start sp_cop from the UNIX command line. But when the [–s] option is used at startup, the replication processes (Capture, Read, Export, Import, Post) remain in an idle state, which you can see when you issue the status command as shown in the following example.
When sp_cop is started with the [–s] option, you cannot start processes individually with the start command. You must start them all with the startup command. All of the processes will start unless they were stopped with the stop command prior to shutting down sp_cop.
CHAPTER 1 Using SharePlex Commands
215
For more information about starting SharePlex with the [-s] option, see Chapter 3 of the SharePlex Administrator’s Guide.
Authorization level: Issued for: Related commands:
Administrator (1) source or target system shutdown
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
startup
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
216
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
status Use the status command to view a summary of the status of replication on a system, to ensure that processes are running and to check for errors, warnings or notices. For a more detailed status report, use the lstatus command (see page 127). The status display shows:
• Process: The name of the process. • State: The status of each process, either running, idle, stopped due to error, or stopped by user
• PID: The operating-system process ID number of the process • Running Since: The date and time that the process was started • Other information: such as how the system is being used, if there is an active configuration on the system, and if replication errors occurred.
status This screen shows that all SharePlex processes are running normally. In this example, the system summary indicates that there are queue problems, that an error occurred, and that a configuration was activated. The target system is also named in the display: lajolla. There are warning conditions on the target machine also.
CHAPTER 1 Using SharePlex Commands
SharePlex updates the status display at intervals determined by the SP_COP_IDLETIME parameter (see page 267). Authorization level: Issued for: Related commands:
Viewer (3) source or target system lstatus, qstatus, show, show statusdb
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
status
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
217
218
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
stop Use the stop command to stop a SharePlex replication process gracefully, allowing it to finish reading from, or writing to, its associated queues. When you stop a replication process, data accumulates safely in the queues. A process stopped with the stop command remains stopped even when SharePlex is shut down and restarted. It can only be started with the start command (see page 211). When the process starts again, it resumes processing at the point where stopped, so the data remains synchronized. Note: The stop command differs from the abort service command in that it stops a replication process after the process has finished reading from, or writing to, its associated queue. The abort service command immediately terminates the process, whether or not the process is processing data.
Stopping the Capture process Be careful when you stop the Capture process. The source and target data can go out of synchronization if:
• users continue changing the source data while Capture is stopped. and...
• the Oracle redo logs wrap during that time. and...
• the archive logs become unavailable.
Stopping Post at a specific point in time Use one of the [at sourcetime] options to control when the Post process stops. Either of those options automatically stops Post when it receives the first message stamped with a designated time, or time and date. Subsequent messages accumulate in the post queue until Post is restarted. You can use an [at sourcetime] option when a job is scheduled on the source system, and you want to be certain that the operations were successful there before they are applied to the target database. Set the option to stop Post just before the job is scheduled to run.
CHAPTER 1 Using SharePlex Commands
219
You also can use this option when you are running reports on the target system and do not want Post operations competing for overhead. Because SharePlex is not synchronous, the actual time on the target system when Post stops probably will be later than the operation’s timestamp. The timing depends on how long it takes to post preceding messages in the queue. Authorization level: Issued for:
Operator (2); Administrator (1) required to stop Capture • stop for Capture, Read and Export is issued for the source system.
• stop for Import and Post is issued for the target system. abort service, start
Related commands: SYNTAX BASIC COMMAND
COMMAND OPTIONS
[ON HOST] OPTIONS†
stop service
[to host] [from host] [for datasource] [for datasource-datadest] [queue queuename] [at sourcetime hh:mm:ss] [at sourcetime mm/dd/yyyy hh:mm:ss]
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
service
The SharePlex process you want to stop. Valid values are: • Capture
• • • •
Read Export Import Post
Example: sp_ctrl(sysA)> stop export
220
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command options OPTION
DESCRIPTION
to host
This option stops Export to a designated target system, while allowing Export to other systems to continue. • to is a required part of the syntax. • host is the name of the target system. Example: sp_ctrl(sysA)> stop export to sysB In this example, Export is stopped from sysA to sysB, but Export from sysA to other target systems continues.
from host
This option stops Import from a designated source system, while allowing Import from other systems to continue. • from is a required part of the syntax. • host is the name of the source system. Example: sp_ctrl(sysD)> stop import from sysC In this example, Import from sys C is stopped on sysD, but Import on sysD from other systems continues.
for datasource
This option stops Capture or Read for a designated Oracle instance, while data from other Oracle instances on the same system continues replicating. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. Example: sp_ctrl(sysA)> stop read for o.oraA In this example, Read is stopped on sysA for instance oraA, but other Read processes for other instances on sysA continue processing.
for datasource-datadest
This option stops Post for a designated source SID-target SID data stream, without affecting other Post activities. • for is a required part of the syntax. • datasource is expressed as o.SID, where SID is the ORACLE_SID of the source Oracle instance. • datadest is expressed as o.SID, where SID is the ORACLE_SID of the target Oracle instance. Example: sp_ctrl(sysC)> stop post for o.oraA-o.oraC In this example, Post is stopped on sysC for instance oraA replicating to oraC, but other Post processes on sysC continue posting.
CHAPTER 1 Using SharePlex Commands
221
Command options (continued) OPTION
DESCRIPTION
queue queuename
This option stops the Export, Import or Post process associated with a named queue. Replication through other named queues continues unaffected. • queue is a required part of the syntax. • queuename is the user-defined name of the queue, as shown in the configuration file. Example: sp_ctrl(sysA)> stop export queue QA In this example, Export of data through named export queue QA is stopped on sysA, but Export continues for data assigned to all other named queues.
at sourcetime hh:mm:ss
This option stops the Post process when it receives the first message stamped with the designated time. Subsequent messages accumulate in the post queue until Post is restarted. • at sourcetime is a required part of the syntax. • hh:mm:ss is the time stamp at which Post stops, which must be specified using a 24-hour clock. Pad single-digit components with a zero (0). Allow no spaces. Example: sp_ctrl(sysC)> stop post at sourcetime 24:00:00 In this example, Post stops on sysC when it receives the first message with the timestamp of midnight.
at sourcetime mm/dd/yyyy hh:mm:ss
This option stops the Post process when it receives the first message stamped with the designated time and date. It has the same purpose and functionality as stop post at sourcetime hh:mm:ss, with an added date option. • at sourcetime is a required part of the syntax. • mm/dd/yyyy is the date on which you want Post to stop at the designated time. The date component must precede the time component in the syntax. The year must include all four digits. Pad single-digit components with a zero (0). Allow no spaces. Separate this component from the time component with a space. • hh:mm:ss is the time stamp at which Post stops, which must be specified using a 24-hour clock. Pad single-digit components with a zero (0). Example: sp_ctrl(sysC)> stop post at sourcetime 01/31/2002 24:00:00 In this example, Post stops on sysC when it receives the first message stamped midnight, January 31, 2002.
222
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
truncate log Use the truncate log command to truncate (remove all data from) the Event Log and trace log files in the log sub-directory in the SharePlex variable-data directory. These logs accumulate data and eventually can consume a large amount of disk space. The truncate log command allows you to truncate the logs after the data has outlived its usefulness. This command does not affect replication. You can issue it while replication is active and data is in the queues.
Truncating logs when sp_eventmon is running When 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. Important! The truncate log command deletes all entries from the logs. Quest Technical Support refers to the information in the logs when you make a support call, so try to retain the data as long as possible.
Authorization level: Issued for: Related commands:
Administrator (1) source or target system none
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
truncate log
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
223
usage Use the usage command to view the syntax for a SharePlex command. You can enter the entire command or just the first few keywords. For example, type usage compare to view syntax for both the compare config and compare table commands. To view syntax plus an explanation of a command or group of commands, use the help command (see page 117). There are no [on host] options for this command. Authorization level: Issued for: Related commands:
Viewer (3) source or target system help
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
usage commandname
not available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
commandname
The command for which you want to view the syntax. Example: sp_ctrl(sysA)> usage stop
224
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
verify config The verify config command is intended for use as a preventive measure to avoid certain activation and replication problems. It is intended to be used to test activation to ensure that it will complete successfully. The verify config command verifies tables and sequences only. This command can be used to:
• • • • • •
verify the syntax of a config file. report an error if the source object is not a table or sequence. report if a hostname specified in a route is unreachable. report if there are duplicate specification for a single object. report if a table specification will be skipped and the reason why view a listed of qualifying objects included under wildcard specifications.
What the verify config command does not support The verify config command does not:
• verify activation time. • verify target objects or the target SID.
Verifying added or changed objects in an active configuration To verify objects that you want to add to an active configuration or objects that you want to change (such as routing changes), it is suggested that you copy and modify the active configuration and then run the verify command against that copy.
Using with partitioned replication You can use the verify config command for configurations containing tables that use partitioned replication. While SharePlex supports the use of verify config with partitioned replication, it does not include any additional functionality for verifying partitions or their definition.
CHAPTER 1 Using SharePlex Commands
225
Viewing the results of the verification The verify config command retains control of the sp_ctrl interface until the verification is completed. The command will read the entire config file, logging errors and duplicates, and expanding objects falling under wildcards. The results of the verify are displayed to the screen within sp_ctrl. If you would like to view detailed results you may:
• issue the verify config command in sp_ctrl using the detail option • navigate to the results file directly using the path displayed to the screen after issuing the verify config command. Authorization level: Issued for: Related commands:
Viewer (3) source system activate config, copy config, create config, edit config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
verify config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
filename is the name of the configuration to be verified.
Command options OPTION
DESCRIPTION
detail
This option will display a greater level of detail to the screen. Example: sp_ctrl(sysA)> verify config local_wild detail In this example, the local_wild config will be verified and the results will be displayed with a higher level of detail.
226
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
version Use the version command to view the version number of the SharePlex software on a system. Authorization level: Issued for: Related commands:
Viewer (3) source or target system none
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
version
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
CHAPTER 1 Using SharePlex Commands
227
view config Use the view config command to view the contents of an active or inactive configuration file from within the sp_ctrl interface. Use it when:
• you suspect that an incorrectly written configuration could be causing activation or replication problems.
• you want to know which objects are being replicated and how the routes are configured. Note: To edit a configuration, use the edit config command (see page 110). You cannot edit an active configuration. To change an active configuration, copy it with the copy config command (see page 99) and then edit the copy.
Authorization level: Issued for: Related commands:
Viewer (3) source system activate config, copy config, deactivate config, edit config, list config, remove config, rename config, verify config
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
view config filename
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
Required arguments ARGUMENT
DESCRIPTION
filename
The name of the configuration that you want to view. Configuration names are case-sensitive. Example: sp_ctrl(sysB)> view config sales
228
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
view log options Use the view log options command to view the default values for the show log command (see page 187). Example display: sp_ctrl(sysA)> view log options Log current display options: direction = reverse maxlines = 50 lpp = 30
These parameters can be changed with the set log command (see page 154), or with options within the show log command itself.
Authorization level: Issued for: Related commands:
Viewer (3) source or target system set log, show log
SYNTAX BASIC COMMAND
[ON HOST] OPTIONS†
view log options
available
†
The [on host] options enable issuing of remote commands. For more information about these options, see page 14.
2 SharePlex Parameters This chapter reviews the most commonly used SharePlex parameters and how to set and activate them. Contents About SharePlex parameters Where parameter information is stored Setting and activating parameters Viewing a list of SharePlex parameters Parameter categories Descriptions of user-configurable SharePlex parameters
230
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
About SharePlex parameters SharePlex parameters control and tune various aspects of replication. SharePlex is designed to operate optimally with the default settings. In general, you should not change a parameter’s value except in the following circumstances:
• your replication strategy requires it. • you are following a documented SharePlex procedure. • you are instructed to do so by Quest Technical Support. When needed, a SharePlex Administrator can change certain parameters that are designated user-configurable. Descriptions of user-configurable parameters begin on page 234.
Where parameter information is stored There are two files for SharePlex parameters:
• The param-defaults file stores default settings that were set by Quest developers for optimal replication performance under most conditions. The param-defaults file resides in the data sub-directory of the SharePlex product directory. The data in this file does not change unless a new version of SharePlex is installed. Never edit this file. To change a parameter’s value, see “Setting and activating parameters.”
• The paramdb file stores user-defined parameter settings — values that were changed from their defaults by a SharePlex Administrator using the set param command. Also stored in this file are the SharePlex license key for the local system, the SharePlex Oracle user, and the SharePlex user’s password. The paramdb resides in the data sub-directory of the SharePlex variable-data directory. It starts out empty, and as SharePlex Administrators change parameter values, those values are added to it. User-defined parameter values override SharePlex default values when SharePlex is running. All of the settings in the paramdb file remain intact when a new version of SharePlex is installed.
Setting and activating parameters A SharePlex Administrator (member of the SharePlex Admin group) is the only user authorized to make parameter changes. To determine the correct format and range for a parameter’s value, look up the parameter’s description in the reference guide beginning
CHAPTER 2 SharePlex Parameters
231
on page 235. Parameters for the Capture, Read, Export, Import, and Post processes can be set on a per-process basis when there are multiple instances of a process for an instance of SharePlex. Parameters can be set in the following ways:
• With the set param command through the sp_ctrl interface. This is the preferred method because the new value remains intact no matter how many times replication stops and starts.
• As environment variables on UNIX systems prior to starting sp_cop. The new value remains in effect only for that session of sp_cop.
• By editing the paramdb directly. This is the least desirable method, because it is easy to make mistakes that can severely affect replication. Important! The password for the SharePlex user in Oracle is encrypted, and it cannot be changed using the set param command or by editing the paramdb. The best way to change the password is to run the ora_chpwd program. For more information, see Chapter 11 of the SharePlex Administrator’s Guide.
Setting SharePlex parameters through sp_ctrl The recommended way to change a SharePlex parameter is to use the set param command in sp_ctrl. This command establishes an accurate entry in the paramdb, ensuring that the setting remains in effect whenever sp_cop is started or shut down. Using sp_ctrl is the only way to ensure that process-specific parameter settings are entered into the paramdb correctly. To restore a parameter’s setting to its default value, use the reset param command. For more information about the set param and reset param commands, see their alphabetical listings in Chapter 1.
Setting SharePlex parameters as environment variables On a UNIX system, a SharePlex parameter can be set as an environment variable. The environment variable overrides the setting in the paramdb or param-defaults files, but only for the session of sp_cop for which it was set. If you shut down sp_cop and restart it without re-setting the environment variable, SharePlex uses the paramdb setting (if available) or the default setting in the param-defaults file.
232
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Note: On Windows systems, SharePlex environment variables must be set through the Windows Registry. See the SharePlex Administrator’s Guide for more information.
To set a SharePlex parameter as an environment variable on a UNIX system, use one of the following commands. Set the environment variable before starting sp_cop or, if sp_cop is running, restart sp_cop for the new setting to take effect. ksh shell: $ export parameter_name=value csh shell: $ setenv parameter_name value Because of the temporary nature of environment variables, avoid using them if possible; instead make your changes with the set param command. When you rely on environment variables, especially when there are multiple users of SharePlex, you incur the risk of someone forgetting to set them (or using an incorrect value) when they restart sp_cop. That can have a significant, negative impact on replication and can result in the need to resynchronize the data.
Setting SharePlex parameters by editing the paramdb The paramdb can be edited in an ASCII text editor to change parameter settings, but that should only be done by an experienced SharePlex Administrator. It is easy to make mistakes when editing the file outside the sp_ctrl interface, and they can severely affect replication. Only edit parameters that are listed in this documentation. If you edit the paramdb, save a copy of the original paramdb file first, as a backup. To edit the paramdb file To edit the paramdb file, open it in the text editor and use the editor’s tools to make changes. You can add comments as needed, preceding each comment line with a pound (#) symbol and ending it by pressing Enter.
• If a parameter was previously changed from its default, there is an entry for it in the file. Change the current value in the file to the new one.
• If this is the first time a parameter’s value is being changed, create an entry for it on a new line. Carefully follow the format requirements set forth in the file’s header. Enter the parameter’s name, then a space, then the value.
CHAPTER 2 SharePlex Parameters
233
Depending on which parameters you changed, you might need to restart the affected replication process(es) or sp_cop. The following is an example of a paramdb opened in the vi text editor.
FIGURE 1: The paramdb opened in vi
Viewing a list of SharePlex parameters Use the list param command in sp_ctrl to view user-configurable SharePlex parameters. It displays parameter names, current settings, default values (if the parameter has been changed), and set-at points. The set-at point indicates when changes to a parameter will take effect. Possible set-at points are:
• Live means a change takes effect immediately. • Restart Process means a change takes effect after the affected SharePlex process is restarted.
• Restart Cop means a change takes effect after sp_cop is restarted. Additional options are available for viewing:
• all SharePlex parameters. • only parameters whose values have changed. • parameters relating to a specific SharePlex module. For more information about the list param command, see page 124.
234
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Parameter categories SharePlex parameters are grouped according to modules that control different functions of the software. Modules with parameters that SharePlex users can change are listed in the following table. You can view a list of parameters for any module by issuing the list param module command, where module is the module’s name. SharePlex parameter modules Module
Naming convention
Function controlled
capture
SP_OCT
Capture process
compare
SP_DEQ
compare commands
config
SP_OCF
configuration activation process
cop
SP_COP
sp_cop
export
SP_XPT
Export process
import
SP_IMP
Import process
logging
SP_SLG
the SNMP feature
post
SP_OPO
Post process
queue
SP_QUE
the SharePlex queues
read
SP_ORD
Read process
reconcile
SP_RCL
the reconcile command
stats
SP_SHS
the shared memory for statistics
SP_OSY
the SYNC family of commands, e.g. copy/ append
SP_SYS
system-related items
sync system
Descriptions of user-configurable SharePlex parameters This section describes the user-configurable SharePlex parameters. Parameters not documented in this chapter are internal parameters that should only be modified under guidance of a Quest developer or Technical Support representative. Parameters are grouped as follows:
• Configuration parameters, page 235
CHAPTER 2 SharePlex Parameters
• • • • • • • • • • •
235
Capture parameters, page 236 Read parameters, page 246 Export parameters, page 253 Import parameters, page 255 Post parameters, page 256 sp_cop parameters, page 267
Queue parameters, page 269 SNMP parameters, page 272 System parameters, page 273 Compare command parameters, page 276 Synchronization (copy/append) command parameters, page 282
Configuration activation parameters SP_OCF_LOCK_WAIT_TIME This parameter tells SharePlex how long to wait before failing activation on a particular table. Since the table must be locked for activation, the logic is to retry the lock for a designated period of time, and this designated period of time is controlled by the SP_OCF_LOCK_WAIT_TIME parameter. Default: 5 minutes Range of valid values: Any positive integer Takes effect: for the next activation
SP_OCF_THREAD_COUNT This parameter controls the default number of threads that SharePlex generates during configuration activation. It might be necessary to experiment with the number of threads to determine the optimal performance level. As an example, for a 32-CPU machine with a large disk array, 10 or more threads could show improved performance. The value for the thread count is independent of the number of tables to be analyzed.Default: 3 threads Range of valid values: 1 to 32 Takes effect: immediately
236
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Capture parameters SP_OCT_ARCH_LOC This parameter defines the path to the archive logs. When the redo logs wrap, SharePlex looks for the archive log in Oracle’s archive log list. If SharePlex cannot find the archive log there, it looks in the directory or directories specified by this parameter. The default is the /home directory. If the path for the archive logs is different, specify the correct full path name with this parameter. You can specify more than one directory path if you separate them with semicolons (;) as shown in the following example: sp_ctrl> set param SP_OCT_ARCH_LOC /disk1/log;/disk2/log In this example, Capture will search under both /disk1/log and /disk2/log paths to find the logs. To specify the directory path for SharePlex for RAC, use the following: sp_ctrl> set param SP_OCT_ARCH_LOC !;;;; Note that the non-RAC format for path names allows a list of directory path names separated by a semicolon. The list can be any length desired up to the limit of 1023 bytes. However, the RAC format, which is !; followed by a list of sid;pathname pairs, does not allow the pathname to be a list of path names as the non-RAC format does. Each SID must be followed by exactly one directory pathname. If you want to specify more than one pathname for a single instance SID, you must put in two pairs of entries in which each of the entries has the same SID. Thus, you cannot specify !;sid1;path1;path2;path3;sid2;path4 Rather, the proper format for the preceding example is !;sid1;path1;sid1;path2;sid1;path3;sid2;path4 Default: empty string Range of valid values: full directory path to the restored archive logs Takes effect: immediately
SP_OCT_ARCH_LOC_FIRST This parameter allows the user to change to order of the process by which SharePlex determines the location of the archive logs. SharePlex normally seraches for the archive logs location in the following manner:
CHAPTER 2 SharePlex Parameters
237
1 Online logs 2 Archive logs – using Oracle specified locations 3 Archive logs using the customer specified location SP_OCT_ARCH_LOC
When employed, this parameter effectively switches the order of the steps, using the information in Step 3 prior to the Oracle specified locations of Step 2. Note: This parameter must be used in conjunction with the SP_OCT_ARCH_LOC
parameter. Default: 0 (off) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OCT_AUTOADD_ENABLE If this parameter is set, Capture will automatically add a table to replication when it is created if the name of the new table matches a wildcard specification in the active config. Default: 1 (on) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OCT_CK_LOC_FIRST This parameter causes the Capture process to first search for an archived redo log in the location specified by SP_OCT_ARCH_LOC. If SP_OCT_ARCH_LOC is an empty string, Capture will first search in the Archive Log Destination as configured in Oracle. Default: 0 (off) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OCT_ASM_SID This parameter identifies the ASM module’s Oracle SID. This parameter is only installed if, during ora_setup on ASM supported platforms, the user opts to enable support for ASM. Default: none, value recommended during ora_setup (SID must be preceded by the plus (+) sign) Takes effect: upon restart of the Capture process
238
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_OCT_ASM_SUPPORT This parameter enables and disables support for redo and archive logs on ASM supported platforms. This parameter is only installed if, during ora_setup on ASM supported platforms, the user opts to enable support for ASM. Default: 1
(on)
Takes effect: upon restart of the Capture process
SP_OCT_CHECKPOINT_LOG Sometimes, the Capture process does not checkpoint on a regular basis. Checkpointing saves the state of the process in case it is needed for recovery. If the Capture process terminates for some reason and the redo logs wrap, SharePlex attempts to recover to a checkpoint that no longer exists. SP_OCT_CHECKPOINT_LOG ensures that the checkpointing occurs before the logs switch. The checkpoint is triggered when Capture lags a specified number of logs behind Oracle. For example, with the default of 2, Capture does a checkpoint when it falls 2 or more logs behind Oracle. The range of permissible values for this parameter is from 2 (the default) to a value equal to the number of logs you are using. A value of 0 disables this feature. This parameter is useful in environments where frequent log switches can cause a switch to occur before SharePlex’s internal checkpoint mechanism can be triggered. Default: 2 logs Range of valid values: 2 to the number of redo logs Takes effect: immediately
SP_OCT_CHECKPOINT_TIME This parameter works in conjunction with the SP_OCT_CHECKPOINT_FREQ parameter. It defines the time delay, in seconds, before the Capture process checkpoints. If the value set for this parameter is reached before the value set for SP_OCT_CHECKPOINT_FREQ, it triggers the checkpoint. (Checkpointing saves the state of the process in case it is needed for failure recovery.) Default: 120 seconds Range of valid values: any positive integer Takes effect: immediately
CHAPTER 2 SharePlex Parameters
239
SP_OCT_DATA_OBJ_CACHE_SIZE This parameter specifies the number of entries/elements used in the Data Object ID to Table Object ID mapping cache. For certain operations, such as DLOADs or LOB data, the redo-record for such operations contains only the Data Object ID. The Capture process needs to map the Data Object ID to the Table Object ID to see if the operation is of interest. The Data Object ID to Table Object ID cache provides a look-up solution; otherwise, the Capture processmust query Oracle to map the Data Object ID to Table Object ID. Default: 50 Range of valid values: any positive integer Takes effect: immediately
SP_OCT_DATE_ MSG This parameter can be set so that the Capture process prints a warning message to the Event Log and the Capture Log when it detects an invalid date column. A setting of 0 disables it, and a setting of 1 activates it. The error message generated by Capture is: Invalid DATE format detected in record with rowid=rowid, on obj object_id. See capture log for detail.
Default: 0 (do not print messages) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OCT_DDL_LOGGING This parameter controls the Capture logging levels for DDL activity. The logging of DDLs to the DDL log is not dependent upon the SP_OCT_REPLICATE_ALL_DDL setting. Even when SP_OCT_REPLICATE_ALL_DDL is 0, turning off 9i+ DDL replication, the DDL can still be logged. The following settings are available: 0 = no logging, 1 = replicated DDL only 2 = all DDL Default: 2 Range of valid values: 0, 1, 2 Takes effect: immediately
240
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_OCT_DEF_ Date and Time Parameters The following parameters can be set so that SharePlex corrects the format of dates and times if they were incorrectly entered by a user or application and bypassed the database’s validity check. These parameters take effect as soon as they are activated. SP_OCT_DEF_MONTH SP_OCT_DEF_DAY SP_OCT_DEF_YEAR SP_OCT_DEF_HOUR SP_OCT_DEF_MIN SP_OCT_DEF_SEC
range of values is from 1 - 12 range of values is from 1 - 31 range of values is from 1987 - 9999 range of values is from 0 - 23 range of values is from 0 - 59 range of values is from 0 – 59
SP_OCT_DENIED_USER This parameter can be used to specify an Oracle 10g+ userid for which all DML and DDL transactions should be ignored or filtered by the Capture process. Important! Ignoring transactions on the source machine may lead to an out-of-sync condition. Important! SharePlex does not verify that the specified userid exists.
Default: 0x00000000 Range of valid values: integers (any valid Oracle userid) Takes effect: immediately
SP_OCT_LOB_BUFFER_SIZE This parameter controls the size of Capture’s LOB buffers, which must be maintained until Capture can assemble the related transaction information. If SharePlex is unable to determine the transaction, it uses a special sub-queue outside of the ones containing the transactions. The headers for these sub-queues require more shared memory, which can require an increase in the SP_OCT_LOB_BUFFER_SIZE parameter. The larger the LOB buffers, the more likely that system memory will run out, preventing buffering for subsequent LOB operations until memory becomes available again. Therefore, you might need to increase the SP_QUE_Q_SHMSIZE parameter (see page 270) in conjunction with increasing the SP_OCT_LOB_BUFFER_SIZE parameter. Generally, only the LOB data for VARRAYs is buffered, so this parameter generally only impacts transactions involving VARRAYs. Default: 5 MB of memory per LOB
CHAPTER 2 SharePlex Parameters
241
Range of valid values: any positive integer Takes effect: when Capture is restarted
SP_OCT_LOG_MEMBER The SP_OCT_LOG_MEMBER parameter is used to augment queries of the data dictionary to specify archive log locations. You can use this parameter to specify exactly what log file you want to operate on. You can specify a mapped file path by using sp_ctrl, as in the following example: set param SP_OCT_LOG_MEMBER C:\Oracle\SID\archive\% Default: % (percent symbol) Range of valid values: any correctly formed file name specification with wildcard characters Takes effect: when Capture is restarted
SP_OCT_LOG_READ_SIZE The Capture process reads multiple redo-log file blocks in one pass. This parameter controls the number of blocks read at a time, enabling you to adjust the value according to the system’s configuration and whether or not Capture is falling behind the pace of Oracle’s processing. Keep in mind that when the value is higher than necessary, it incurs more system overhead. Default value: 64 blocks Range of valid values: any positive integer Takes effect: when Capture is restarted
SP_OCT_LOGWRAP_RESTART This parameter defines how long Capture waits before it restarts after encountering either of the following problems:
• A log wrap because a log file no longer exists. When Capture detects a log wrap and the archive logs are not available, Capture stops. It waits a certain amount of time and then starts again. If the archive logs have not been restored, Capture waits and then stops again, continuing this process until the logs are restored. Capture writes the following message to Event Log. “10727 - Possible log wrap at activation act_id, log sequence number seq#, offset offset#” Or...
242
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• SharePlex is denied permission to open a redo log. If someone changes permission, denying SharePlex the ability to read the redo logs, Capture stops for the time specified by this parameter and then tries to read the log again. Capture continues in this manner until the problem is resolved. Default: 300 seconds Range of valid values: any positive integer Takes effect: immediately
SP_OCT_OLOG_DELAY This parameter controls the amount of microseconds capture's redo log reader spends sleeping when it has detected that there is no more data to read. This parameter essentially comes into play only when capture is idle. When busy capture essentially won't be sleeping since there are records to read. Default: 10000 (microseconds) Range of valid values: any positive integer Takes effect: when Capture is restarted
SP_OCT_OLOG_NO_DATA_DELAY This parameter controls the length of time that the log reader will sleep before a retry when there is no data to process. Default: 10000 (microseconds) Range of valid values: any positive integer Takes effect: when Read is restarted
SP_OCT_OLOG_REOPEN This parameter controls whether or not the Capture process will close and re-open the online redo log when it reaches the end of the file. If this parameter is enabled, the user may control the length of time that the Capture process will wait before retry by employing the SP_OCT_OLOG_NO_DATA_DELAY parameter. Default: 1 (off) Range of valid values: 0 or 1 (flag) Takes effect: when Read is restarted
SP_OCT_OPS_LOGREADER_DELAY This parameter controls the log reader delay time before retry when it encounters no_data.
CHAPTER 2 SharePlex Parameters
243
Default: 50000 (microseconds) Range of valid values: any positive integer Takes effect: when Capture is restarted
SP_OCT_OPS_LOGREADER_RETRY This parameter controls the number of times the log reader will retry when it encounters no_data. Default: 3 Range of valid values: any positive integer Takes effect: when Capture is restarted
SP_OCT_OPS_NO_DATA_DELAY This parameter controls the length of the sleep that is enforced per node when no data is encountered in the sequencer. Default: 5 (deciseconds) Range of valid values: any positive integer Takes effect: when Read is restarted
SP_OCT_REPLICATE_DDL For objects in replication, this parameter enables you to selectively turn on or off the replication of ALTER TABLE DDL and TRUNCATE TABLE DDL. At the default of 3, all ALTER TABLE DDL and TRUNCATE TABLE DDL performed against a table is replicated. Other options constrain replication to ALTER TABLE DDL only or TRUNCATE TABLE DDL only. You may also disable the replication of both. The replication of DDL may also be impacted through the use of the SP_OCT_REPLICATE_ALL_DDL parameter. Note: Partition object DDL is not replicated when the SP_OCT_REPLICATE_DDL and SP_OCT_REPLICATE_ALL_DDL parameters are both disabled, i.e., when both are set to zero (0).
Default: 3 (replicate DDL and TRUNCATE) Range of valid values: 0 (disable replication of both ALTER and TRUNCATE) 1 (enable ALTER replication only) 2 (enable TRUNCATE replication only) 3 (enable replication of DDL and TRUNCATE) Takes effect: immediately
244
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_OCT_REPLICATE_ALL_DDL For object not in replication, this parameter enables you to turn on or off the replication of DDL. Enabling this parameter requires identical source and target databases in order for DDL to execute successfully on the target system. SharePlex replicates all supported DDL for all schema objects and accounts, so those components must exist in the target database for the operations to succeed. If your environment meets this requirement, you can enable this parameter. To configure the Post process to stop for errors encountered when applying replicated DDL operations to the target database, set the SP_OPO_STOP_ON_DDL_ERR parameter (see page 266). If you are replicating the creation of package or stored procedures, the name of the objects in the body of the package or stored procedure should be fully qualified since other users or schemas may execute this package or stored procedure. For a list of operations supported by SharePlex, see the Release Notes that correspond to your version of SharePlex. Default: 0 (off) Range of valid values: 0 or 1 (flag) Takes effect: immediately Note: Partition object DDL is not replicated when the SP_OCT_REPLICATE_DDL and SP_OCT_REPLICATE_ALL_DDL parameters are both disabled, i.e., when both are set to zero (0).
SP_OCT_REPLICATE_DLOAD This parameter controls whether or not SQL*Loader direct-path loads are replicated. The default setting of 1 enables direct-path load replication. SharePlex supports replication for non-parallel loads only (PARALLEL=FALSE). The database must be in archive mode, and table logging must be enabled. To disable replication of direct-path loads, change this parameter to 0. Default: 1 (replicate direct-path loads) Range of valid values: 0 or 1 (flag) Takes effect: immediately
CHAPTER 2 SharePlex Parameters
245
SP_OCT_REPLICATE_POSTER This parameter controls whether or not the Capture process on a system replicates data posted by the Post process on that system. Leave this parameter at the default setting of 0, which tells Capture to ignore Post activities on the same system. When establishing certain replication configurations — primarily cascading replication — you might be instructed to set this parameter to 1, which causes Capture to replicate posted changes. Default: 0 (do not replicate Post transactions) Range of valid values: 0 or 1 (flag) Takes effect: when Capture is restarted
SP_OCT_REQUIRED_DATA_IS_LOGGED This parameter enables the Capture process to gather additional information to improve rollback handling. With rollback handling, the Read process will require more resources to accomplish and improve performance in return. If system resources are scarce and the systems experiences lots of rollbacks, to lower the Read process resource consumption, you can disable this parameter. This parameter is enabled by default. Default: 1 (on) Range of valid values: 0 or 1 (flag) Takes effect: when Capture is restarted
SP_OCT_TARGET_COMPATIBILITY SharePlex contains enhancements, features, or functionality that are not always compatible with previous versions. Use of this parameter enables users to replicate from higher version SharePlex source sytems to lower version target systems. When replicating to a lower version of SharePlex, to maintain compatibility with previous releases and allow for smoother migrations and upgrades, this parameter should be left at its default value. When replicating between same versions, set this parameter to the value that most closely matches the installed SharePlex version on your source and target systems. Default: 7.0 Range of valid values: 6.0, 6.1, or 7.0 Takes effect: when Capture is restarted
SP_OCT_USE_SUPP_KEYS Use this parameter to tell SharePlex to use the columns set by Oracle's supplemental logging as the key columns when a row is updated or deleted.
246
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
In a typical replication scheme, SharePlex chooses a set of key columns for poster to use when poster updates or deletes a row. When Oracle's PK/UK supplemental logging is enabled, Oracle logs key columns for each update. These key columns may not always match what SharePlex chose as its keys which causes unnecessary work for the Reader process. Setting this parameter overrides the default behavior of SharePlex, allowing us to be more efficient and faster. Default: 0 (Disabled) Range of valid values: 0 or 1 (Enabled) Takes effect: when Capture is restarted
Read parameters SP_ORD_BATCH_ENABLE This parameter controls the enabling of the Batch Processing functionality. By default it is enabled. This allows the Read process to combine multiple identical records into a single record, or into a batch, for processing by the Post process. Default: 1 (on) Range of valid values: 0 or 1 (flag) Takes effect: when Read is restarted
SP_ORD_BATCH_MAX This parameter controls the maximum number of concurrent batch transactions. Default: 50 (transactions) Range of valid values: any integer between (and including) 5 and 250 Takes effect: when Read is restarted
SP_ORD_BATCH_MATCH_MIN This parameter controls the minimum number of matched operations before processing a batch. Default: 2 Range of valid values: any positive integer Takes effect: when Read is restarted
CHAPTER 2 SharePlex Parameters
247
SP_ORD_CDA_LIMIT This parameter controls the number of cursors cached by each login of the Read process. You might need to increase its value if replication starts falling behind Oracle activity on the source system. An initial setting of 15 cursors is recommended if you have a large number of tables in replication. Default: 5 cursors Range of valid values: any positive integer Takes effect: when Read is restarted
SP_ORD_DATE_ MSG This parameter can be set so that the Read process prints a warning message to the Event Log and the Read log when it detects an invalid date column. A setting of 0 disables the parameter, and a setting of 1 activates it. The error message generated by Read is: An oerr#1801 has occurred on record with rowid rowid, on object object_id. Rec skipped. It is usually caused by invalid column data of type DATE. Creating a unique index that doesn't include column of type DATE and reactivating same configuration may solve the problem.
Default: 0 (do not print warning message) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_ORD_DEBUG_OBJECT This parameter turns on the debug messages when the incoming message has the same object_id as the setting of SP_ORD_DEBUG_OBJECT. It selectively turns on the debug messages based on the object_id, and these debug messages are logged in the reader debug logs (ODR). Since SP_ORD_DEBUG_OBJECT is a debug parameter, it can affect reader performance. Default: 0 Range of valid values: valid source machine Oracle OBJECT_ID’s Takes effect: Immediately
SP_ORD_DELAY_RECORDS The Read process processes records in batches. The size of the batches depends on the number of records in the capture queue. If the number of records is large, Read ignores the value of this parameter, and the batches are kept as small as possible. If Read is keeping pace with Capture, the size of the batch is approximately the value set by this parameter.
248
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Set this parameter low if SharePlex is generating rollback segment too old messages in the Event Log. It instructs SharePlex to pass the data along sooner. This parameter is of use particularly in e-commerce situations where only minimal latency can be tolerated. Warning! Use this parameter with caution, because reducing the number of records increases the I/O that SharePlex must perform, which increases system overhead. It can also negatively impact smooth interaction between SharePlex processes.
Default: 200 records Range of valid values: any positive integer Takes effect: Immediately
SP_ORD_FIRST_FIND This parameter controls how the Read process checks column conditions to determine whether or not a replicated row change satisfies them.
• At the default of 1, when a row change satisfies a column condition, SharePlex does not check any other column conditions to see if that row chaynge also satisfies any of them.
• At a value of 0, SharePlex sends the data to all target systems where the column conditions are satisfied. For more information about horizontal partitioning, see Chapter 5 of the SharePlex Administrator’s Guide. Default: 1 (on) Range of valid values: 0 or 1 (flag) Takes effect: when Read is restarted
SP_ORD_HP_HASH This parameter controls the number of slots in the hash table sued for Horizontal Partitioning. By default this parameter is set to 16 slots to minimize memory usage (usage is the number of slots x 32 bytes for every transaction with an insert). If the user’s system does a lot of insert operations followed by updates (in the same transaction) on a horizontally partitioned table then SharePlex will use this hash table a lot and this value may need to be increased for performance. Additionally, if the user system has a lot of long transactions with inserts on tables with horizontal partitioning the value of this parameter might need to be increased. Default: 16 slots Range of valid values: any positive integer
CHAPTER 2 SharePlex Parameters
249
Takes effect: when Read is restarted
SP_ORD_HP_IN_SYNC This parameter is used for horizontally partitioned replication to ensure that data is replicated properly when a value for a column in a column condition changes so that the row no longer satisfies the condition. It enables SharePlex to automatically correct the following:
• UPDATEs that cause a row to meet a different column condition than the one created for that row, sending the changes to a different location. An example would be an UPDATE to a row for which the column condition is region=East that changes the value of the region column to WEST. Such operations will fail because the original INSERT statement for that row was replicated to the original location (the Eastern region), so the row does not exist in the new location (the Western region) when Post attempts the update there.
• UPDATEs that cause a row to meet a column condition (and be replicated) when the row was not supposed to be replicated. An example would be when the region column is updated from the value of HEADQUARTERS (for which a row is not replicated) to the value of WEST. Such operations will fail because the original INSERT statement for that row (into the headquarters system) was not replicated to the Western region’s system, so Post cannot perform the update there.
• UPDATEs that cause a row to no longer meet any column condition. An example would be when the region column is updated from the value of WEST to the value of HEADQUARTERS. The original INSERT statement was replicated to the Western region’s system, but the update to the new value is not replicated, because the new value does not meet a column condition (headquarters data is not shared). The rows are now out of synchronization, but there are no errors. When this parameter is enabled, SharePlex automatically corrects rows for which UPDATEs cause the preceding conditions. SharePlex converts the UPDATE to a DELETE and, if needed, an INSERT. To convert an UPDATE statement (which normally only uses the changed columns and the key) to an INSERT statement, SharePlex needs values for all of the columns. Enabling SP_ORD_HP_IN_SYNC directs SharePlex to send all of the columns in a row to the Post process when there is an UPDATE to a table using horizontally partitioned replication, so that an INSERT can be constructed. Set this parameter on the source system before you activate the configuration. If replication is active, set the parameter and then reactivate the configuration so that SharePlex can rebuild its object cache. The reactivation will be fast because the objects are not analyzed for chained rows.
250
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
If you know that the columns in column conditions for tables using horizontally partitioned replication will never change, leave this parameter set to 0, because using it incurs processing overhead. Default: 0 (off) Range of valid values: 0 or 1 (flag) Takes effect: when Read is restarted
SP_ORD_LDA_ARRAY_SIZE This parameter controls the number of logins made to the database for read consistency. If the Read process slows down, try increasing the value of this parameter. The maximum setting is determined by the MAX_PROCESSES parameter in the init_ora file. Default: 5 logins Range of valid values: any positive integer Takes effect: when Read is restarted
SP_ORD_MSGS_CK_FREQ and SP_ORD_RCM_SKIP_RATIO These parameters work together, so if one of them is set its default value of 0, then the other parameter, if set to a number other than 0, does not work. Both parameters support the automated process in which the Read process detects that too much time is being taken to process its queries, by checking the ratio of disk gets per executed queries. Once Read makes this determination, it gets rid of its existing read consistent views and replaces it with a new view. The ORD_MSGS_CK_FREQ parameter is the frequency that the Read process checks if the ratio has been surpassed. For example, if you set this parameter to 100, the Read process will check every 100 queries to see if the ratio is still good. The recommended setting is 1,000 queries. The ORD_RCM_SKIP_RATIO parameter specifies the number (the ratio of disk gets to executed queries) that when reached, causes the read consistent view to be replaced. The most sensitive setting is 1, which means one disk get per one executed query. The recommended setting is 2. To turn off these parameters, set one of them to 0, which disables the other parameter. Default for SP_ORD_MSGS_CK_FREQ: 1,000 Range of valid values for SP_ORD_MSGS_CK_FREQ: 0 to 100,000 Default for SP_ORD_RCM_SKIP_RATIO 2
CHAPTER 2 SharePlex Parameters
251
Range of valid values for SP_ORD_RCM_SKIP_RATIO: 0 to 1000 (not recommended to set this greater than 5) Takes effect: Immediately
SP_ORD_NLS_LANG SharePlex expects the default character set for the database to be US7ASCII, but it is designed to detect the database’s setting, if different, and automatically use the correct character set. Therefore, in most situations, you should not need to change this parameter. Change this parameter only if it becomes necessary to override SharePlex to ensure that a certain character set is used for a database. You can set different character sets for individual databases with this parameter, and you can specify all of the sets with the same set param command if you use the following format: sp_ctrl(sysA)> set param SP_ORD_NLS_LANG SID_1,LANGUAGE_TERRITORY.CHARACTERSET1/ SID_2,LANGUAGE_TERRITORY.CHARACTERSET2 Separate each database’s Oracle_SID and character set with a comma (,) and separate each SID-character set combination with a slash (/). Leave no spaces between any components. Example: ora10a,AMERICAN_AMERICA.WE8ISO8859P1/ora10b,AMERICAN_AMERICA.UTF8
This parameter is for use on the source system. To set the character set on the target system, use the SP_OPO_NLS_LANG parameter (see page 261). Note: This parameter only enables SharePlex to recognize the database character set. SharePlex does not convert data from one character set to another.
Default: None; a character set must be specified to make the parameter active. Range of valid values: any valid ORACLE_SID and character set in the required format Takes effect: when Read is restarted
SP_ORD_RCM_SKIP_RATIO Refer to the SP_ORD_MSGS_CK_FREQ and SP_ORD_RCM_SKIP_RATIO parameter, as these two parameters work together.
252
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_ORD_RMSG_LIMIT This parameter controls the frequency of the checkpoints performed by the Read process when it reads messages from the capture queue and determines the key values. A checkpoint saves the capture queue to a cache file, commits the outgoing queue messages (being passed to the export queue), and does a read release (delete) on the heldover records in the capture queue that have already been received by the export queue. The higher the value of this parameter, the more records will be held in memory before the checkpoint is triggered. A very high value causes less I/O on the system and faster processing — but at the expense of increased memory usage and a longer recovery time should something unforeseen cause the Read process stop. A low value increases I/O, which increases the recovery speed but reduces throughput speed. The default value of 1,000 records should establish a reasonable balance between the need for speed and the conservation of memory and process recovery, but you can adjust this parameter to suit your processing requirements. Adjustment options range from checkpointing after every record to holding as many records as the system and its memory can accommodate. Default: 1,000 records Range of valid values: any positive integer within system limitations Takes effect: immediately
SP_ORD_SEND_DDL_TO_FIRST This parameter allows the user to specify which route to send the DDL that is not associated with a TABLE or SEQUECE in replication. If this parameter is set, then the first line in the active config that includes a route specification will be used to determine the route for this DDL. For instance, if the following example were your active config, all DDL that is not associated with a TABLE or SEQUENCE in replication would be sent to sysmm:
[email protected]: Datasource: o.dbprod SCOTT.EMP SCOTT.FOO
SCOTT.EMP SCOTT.FOO
sysmm:
[email protected] sysmm:
[email protected]
Alternately, the route for this DDL may be explicitely stated, as appears in the following example: Datasource: o.dbprod #Route for non-table/sequence DDL ! sysmm:
[email protected]
CHAPTER 2 SharePlex Parameters
SCOTT.EMP SCOTT.FOO
SCOTT.EMP SCOTT.FOO
253
sysmm:
[email protected] sysmm:
[email protected]
Default: 1 (on) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_ORD_SKIP_OBJECT This parameter prevents replicating DML and DDL operations for an object, based on the source table’s Oracle object ID. This parameter causes the Read process to throw away messages for the object specified. The Capture process will still read the messages and put them in the Capture Queue, from here the Read process will retrieve them and throw them away. Default: none Range of valid values: any valid Oracle Object ID Takes effect: when Read is restarted
Export parameters SP_XPT_ALTERNATE_HOST This parameter provides an alternate target IP address when you need to connect to a different target machine. The SP_XPT_ALTERNATE_HOST parameter allows you to change your target host without shutting down your active configuration and thus losing your data. The parameter can be used any time you want to change your target from the one specified in the current active configuration file. For example, if you are having difficulties with your predefined target host, you can set the parameter to the IP address of your alternate target machine, stop the Export process and then restart it. Default: None Takes effect: After restarting Export
SP_XPT_PORT_OVERRIDE This parameter works in conjunction with the SP_XPT_USE_LOCALHOST parameter to enable SharePlex to send data through a secure tunnel port created with SSH® Secure ShellTM software. This parameter sets the local connection, which overrides the default SharePlex port. From that port number, the SSH daemon directs the connection to a different system (the SharePlex target machine) using another port number and the SSH data encryption.
254
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Default: 0 (disabled) Range of valid values: 0 or any positive integer Takes effect: when Export is restarted
SP_XPT_SO_SNDBUF This parameter tunes the TCP/IP window size on the source machine. It works in conjunction with the SP_COP_SO_RCVBUF parameter (see page 268) on the target machine to establish the size of a packet sent across the network. SharePlex references both parameters when TCP/IP sockets are created at the startup of sp_cop and the Export process. If SharePlex is replicating across a WAN and the export queue is continually backlogged, try adjusting both parameters. SP_XPT_SO_SNDBUF must be set equal to or greater than the value of SP_COP_SO_RCVBUF, in multiples of 1024 bytes. To size the parameters, determine the ping time between the source and target machines, then use the following formula for both parameters: param_value / ping_time = bytes per second For example, if ping time is 200 milliseconds, and the value for the two parameters is 64K, SharePlex will send five 64K-packets every second, totaling 320K per second. Unless you observe a bandwidth problem, Quest recommends leaving both parameters set to their defaults, which use the system's setting. To change SP_XPT_SO_SNDBUF, set it on the source system, then stop and start Export on that system. If transfer still is slow, try increasing the SP_IMP_WCMT_MSGCNT and SP_IMP_WCMT_TIMEOUT parameters (see page 255) on the target system. Set SP_IMP_WCMT_MSGCNT to at least 10,000. Default: 0 (default is set by the operating system) Range of valid values: positive integers, in bytes, using multiples of 1024. Maximum is set by the operating system. Takes effect: when Export is restarted
SP_XPT_USE_LOCALHOST This parameter enables SharePlex to send data through a secure tunnel port created with SSH® Secure ShellTM software. The Export process reads this parameter before making a TCP connection. If the parameter is enabled, the Export process connects to the local host through a local port number, where the SSH daemon directs the connection to a different system (the SharePlex target machine) using another port number and the SSH data encryption.
CHAPTER 2 SharePlex Parameters
255
Default: 0 (disabled) Range of valid values: 0 or 1 (flag) Takes effect: when Export is restarted
Import parameters SP_IMP_WCMT_MSGCNT This parameter works in conjunction with the SP_IMP_WCMT_TIMEOUT parameter. It defines the number of messages that are processed before the Import process checkpoints. Checkpointing saves the state of the process in case it is needed for failure recovery. When Import checkpoints, it triggers the Export process to perform its own checkpoint. If the value for this parameter is reached before the value set for SP_IMP_WCMT_TIMEOUT, it triggers the checkpoint. In a WAN environment, you can increase this parameter to as many as 10,000 messages, with the understanding that increasing the message interval between checkpoints can negatively affect SharePlex's fault tolerance. If you are using SharePlex in an environment where the network continually fails, you can decrease this parameter. Default: 10,000 messages Range of valid values: any positive integer Takes effect: immediately
SP_IMP_WCMT_TIMEOUT This parameter works in conjunction with the SP_IMP_WCMT_MSGCNT parameter. It defines the number of seconds that pass before the Import process checkpoints. Checkpointing saves the state of the process in case it is needed for failure recovery. When Import checkpoints, it triggers the Export process to perform its own checkpoint. If the value for this parameter is reached before the value set for SP_IMP_WCMT_MSGCNT, it triggers the checkpoint. Default: 30 seconds Range of valid values: any positive integer Takes effect: immediately
256
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Post parameters SP_OPO_CHARACTERSET This parameter controls how SharePlex tells Oracle about data encoding for CHAR, VARCHAR2 and CLOB columns. By default this parameter is not set. If it is not set, SharePlex notifies Oracle that the data encoding is the character set of the source database. If this parameter is set, then SharePlex notifies Oracle that the data is encoded in the character set you specify. Oracle bypasses data conversion if it believes that the data is encoded in the database character set. Thus setting this parameter to the character set of the target database bypasses the Oracle data conversion process. If the character sets on the source and target database are identical, then the default setting for this parameter is appropriate. If the source and target database character sets are not identical, then you should consider setting this parameter depending on your needs for data conversion. There are two different forms of settings for this parameter: 1 VALUE 2 SID1,VALUE1/SID2,VALUE2/...
Example sp_ctrl(sysA)> set param SP_OPO_CHARACTERSET SID_A,characterset1/ SID2,characterset2 Separate the ORACLE_SID and character set for each database with a comma (,) and separate each SID-character set combination with a slash (/). Leave no spaces between any components. Default: not set Range: set or not set Takes effect: when Post is restarted
CHAPTER 2 SharePlex Parameters
257
SP_OPO_CONT_ON_ERR This parameter controls whether or not Post stops when it encounters Oracle errors that can be corrected. When this flag is set to the default of 0, Post stops for all Oracle errors except the following: Default errors for which Post will not stop unique key violation operation interrupted no data found no such table invalid number non-numeric in date invalid rowid invalid hex number
insert null into not-null cannot update not-null to null Year must be between -4713 and +9999 check constraint violated packet writer failure sequence not found resource busy with nowait Oracle internal error
To add errors for which Post will not stop You can direct SharePlex to ignore additional Oracle errors and continue posting. Follow these instructions to add the errors to the oramsglist file on the target system, and then change the SP_OPO_CONT_ON_ERR setting to 1. 1 Stop Post.
sp_ctrl(sysB)> stop post 2 On the target system, change directories to the data sub-directory of the SharePlex
variable-data directory. 3 Using any ASCII text editor, open the oramsglist file in the data sub-directory.
258
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
4 Increase the number on the first line by the number of Oracle errors you are adding.
This number tells SharePlex how many error messages are in the file. The following is an example file:
FIGURE 2: Example oramsglist file: The number on the first line must be equal to the number of errors listed in the file. For each error you add to the file, increase that number by one. In this example, there are 19 errors listed in the file, errors for which SharePlex will not stop.
5 Starting at the end of the file, add the number of each Oracle error, one per line as
shown in Figure 2. The messages need not be in numerical order. 6 Save and close the file using the text editor’s standard commands. 7 Change the value of SP_OPO_CONT_ON_ERR setting to 1.
sp_ctrl(sysB)> set param SP_OPO_CONT_ON_ERR 1 8 Start Post.
sp_ctrl(sysB)> start post From now on, the Oracle errors that you listed will be recorded by SharePlex in the Event Log, but Post will not stop when they are encountered. SharePlex will log the errors and the offending SQL statements in the SID_errlog.sql log file.
CHAPTER 2 SharePlex Parameters
259
Warning! Use caution when setting this parameter to 1. Your data could become very out-of-sync without your knowing it. It is recommended that you enable this parameter only if your target instance must be as up-to-date as possible and you can tolerate some out-of-sync data. If you direct Post to ignore Oracle error messages, you should check the SID_errlog.sql log frequently to see if there were errors that could cause replication problems.
Default: 0 (stop on Oracle errors) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OPO_DISABLE_OBJECT_NUM This parameter prevents Post from posting replicated DML and DDL operations for one or more tables, based on the source tables’ Oracle object IDs. You can set this parameter if a source tables’ data is invalid or corrupted, or for any other reason that you do not want operations for the table(s) to be reflected in the target database(s). Setting this parameter prevents further replication activity on the target table(s) until you have time to resynchronize the data and reactivate the configuration file. The Post process discards all replicated messages for these tables from the post queue, and the messages do not accumulate in the queue. Use the parameter with caution. If it is enabled and DDL or DML is executed for the source table(s), the target data will be out of date because the changes are not posted. If there are dependencies on the table(s), such as a foreign key in other tables outside the replication configuration, disabling posting will prevent the dependencies from being satisfied. SP_OPO_DISABLE_OBJECT_NUM is disabled by default. To enable it, issue the set param command on the target system using the object IDs of the source tables as the value, as shown in the following example. sp_ctrl(sysB)> set param SP_OPO_DISABLE_OBJECT_NUM 12345, 23456 Invalid object IDs will be ignored. If you do not use quotes, there must be no spaces in between the object ids (e.g. set param SP_OPO_DISABLE_OBJECT_NUM 498438,1000,497109). If you do use quotes, spaces must be used (e.g. set param SP_OPO_DISABLE_OBJECT_NUM "498438, 1000, 497109") When you are ready to begin posting to the target table again, set SP_OPO_DISABLE_OBJECT_NUM to 0.
260
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Default: 0 (off) Range of valid values: valid Oracle Object IDs separated by commas Takes effect: when Post is restarted
SP_OPO_HINTS_LIMIT This parameter controls the maximum number of hints (table/index combinations) that can be listed in the hints file. Use hints only if you see that Post is doing full table scans on tables where there are defined indices. Using a large number of hints can reduce the performance of the Post process. See Chapter 6 of the SharePlex Administrator’s Guide for more information about the hints feature. Default: 100 hints Range of valid values: any positive integer Takes effect: when Post is restarted
SP_OPO_MAX_CDA This parameter is for the SQL cache module and controls the max number of cursor caches that a session can concurrently open. This number must be smaller than the Oracle setting for OPEN_CURSORS in v$parameter view. It is only be used when SP_OPO_SQL_CACHE_DISABLE is set to zero (0). Default: 50 Range of valid values: any positive integer Takes effect: when Post is restarted
SP_OPO_MAX_OEXN_TIME This parameter controls the maximum duration, in seconds, that a SQL thread may spend in a call to OCIStmtExecute ( ) before the timekeeper thread defaults to a deadlocked position and forces the Multi-threaded Post process to exit. Default: 180 [seconds] Range of valid values: any positive integer Takes effect: when Post is restarted
SP_OPO_MAX_ROLLBACK_MESSAGES This parameter is the maximum number of messages to which the backward count is incremented. The main thread scans forward and counts the backward messages. Once the backward count reaches the maximum number set for this parameter, the main thread resolves the rollback. When the rollback is resolved, the main thread resumes dispatching messages. If there are more backward messages, the main thread again
CHAPTER 2 SharePlex Parameters
261
scans forward in the subqueue. The next group of 10,000 backward messages (if the value for the parameter is set to 10,000) is then resolved, using the same procedure. Default: 10,000 messages Range of valid values: 11 - 1,000,000 Takes effect: when Post is restarted.
SP_OPO_NCHAR_CHARACTERSET This parameter controls how SharePlex tells Oracle about data encoding for NCHAR, NVARCHAR2 and NCLOB columns. These columns are encoded in the database NCHAR character sets as opposed to the database character set. By default this parameter is not set. If this parameter is not set, SharePlex notifies Oracle that the data encoding is the NCHAR character set of the source database. If this parameter is set, then SharePlex notifies Oracle that the data is encoded in the character set you specify. There are two different forms of settings for this parameter: 1 VALUE 2 SID1,VALUE1/SID2,VALUE2/...
Example sp_ctrl(sysA)> set param SP_OPO_NCHAR_CHARACTERSET SID_A,characterset1/ SID2,characterset2 Separate the ORACLE_SID and character set for each database with a comma (,) and separate each SID-character set combination with a slash (/). Leave no spaces between any components. Default: not set Range: set or not set Takes effect: when Post is restarted
SP_OPO_NLS_LANG SharePlex expects the default character set for the database to be US7ASCII, but it is designed to detect the database’s setting, if different, and automatically use the correct character set. Therefore, in most situations, you should not need to change this parameter. Change this parameter only if it becomes necessary to override SharePlex to ensure that a certain character set is used for a database.
262
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
You can set different character sets for individual databases with this parameter, and you can specify all of the sets with the same set param command if you use the following format: sp_ctrl(sysB)> set param SP_OPO_NLS_LANG SID_1,LANGUAGE_TERRITORY.CHARACTERSET1/ SID_2,LANGUAGE_TERRITORY.CHARACTERSET2 Separate the ORACLE_SID and character set for each database with a comma (,) and separate each SID-character set combination with a slash (/). Leave no spaces between any components. Example: ora10a,AMERICAN_AMERICA.WE8ISO8859P1/ora10b,AMERICAN_AMERICA.UTF8
This parameter is for use on the target system. To set the character set on the source system, use the SP_ORD_NLS_LANG parameter (see page 251). Note: This parameter only enables SharePlex to recognize the database character set. SharePlex does not convert data from one character set to another.
Default: None; a character set must be specified to make the parameter active. Range of valid values: any valid ORACLE_SID and character set in the required format Takes effect: when Post is restarted
SP_OPO_OBJID_DEBUG This parameter allows debugging for one specific object, such as a table, for Post. The SP_OPO_OBJID_DEBUG parameter is typically used for debugging out-of-syncs, and may or may not be used in conjunction with SP_ORD_DEBUG_OBJECT, the debugging parameter for the Read process. To use the SP_OPO_OBJID_DEBUG parameter, set its value on the target system to the value of the object ID for the object from the source database. Default: 0 Range of valid values: Any number greater than or equal to 0 Takes effect: immediately
SP_OPO_OUT_OF_SYNC_SUSPEND This parameter controls what SharePlex does when it encounters an out-of-sync condition.
• The default value of 0 directs the Post process not to stop processing when it encounters an out-of-sync condition. Post logs the SQL statement and data for the out-of-
CHAPTER 2 SharePlex Parameters
263
sync operation to the SID_errlog.sql log file in the log sub-directory of the variabledata directory on the target system. Post continues posting other valid operations to keep the target database as synchronized with the source database as possible.
• To direct Post to stop posting when it encounters an out-of-sync condition, change the value of this parameter to 1. Post will log the offending statement and stop. When you enable this parameter, check the status of the replication processes frequently. Stopping Post causes latency between source and target databases, and it causes data to accumulate in the replication queues, which could cause them to exceed available disk space. SharePlex provides several sp_ctrl commands for checking replication status (see Chapter 1), and it provides tools for unattended SharePlex monitoring (see the SharePlex Administrator’s Guide). Default: 0 (do not stop for out-of-sync conditions) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OPO_POSTER_DELAY This parameter controls the amount of time that the Post process delays before it posts records to the target instance. Normally, Post applies the changes immediately to minimize latency between the source and target systems, but you can delay posting for up to 5 days (7200 minutes). Delaying posting helps protect the data against accidental loss caused by unwanted deletes or object drops on the source system. The delay gives you enough time to detect the mistake and retrieve the data from the target instance before the mistake is replicated. Running “what-if” analyses is another reason you could change the default of this parameter. Having the target database behind in time enables you to validate predictive modeling compared to the real thing. The delay caused by SP_OPO_POSTER_DELAY is measured from the time the message first appears in the redo logs. Things to consider when using this parameter include the following: 1 Make certain that there is enough disk space for the data to collect in the post queue
for the designated time interval until it is applied to the database. 2 To determine when to start posting based on the parameter’s setting, SharePlex com-
pares the target system’s current timestamp with the time that a record enters the redo log on the source system. Those machines could be in different locations, perhaps thousands of miles from each other. Consider any difference between time zones, and add that to the delay time.
264
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
For example, there is an 18-hour time difference between Los Angeles, California, U.S.A., and Sydney, Australia. To delay posting for five hours, you would need to set SP_OPO_POSTER_DELAY to 23 hours (1380 minutes) to account for the desired five-hour delay plus the 18-hour time difference. Also consider whether or not a location observes Daylight Savings Time, which could change the time difference between two locations. The way that Daylight Savings Time is observed varies among, and even within, nations that use it. 3 Do not use this parameter going back in time, for example when a source system is in
Sydney and a target system is in Los Angeles. To SharePlex, this as a negative time difference when the time stamps on each system are compared. For example, 2:00 in the morning on April 2 in Sydney is 8:00 in the morning on April 1 in Los Angeles. The parameter does not accommodate settings of less than 0. Default: 0 minutes Range of valid values: 0 to 7200 minutes Takes effect: immediately
SP_OPO_PRB_MISMATCH_SUSPEND This parameter, when set to 1, will cause poster to stop when there is a mismatch on a partial rollback. This allows the problem to be investigated and resolved before poster moves on. Default: 0 (off) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OPO_READRELEASE_INTERVAL This parameter controls how often Post read/releases. Normally, Post performs a 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 smaller transactions, this causes excessive I/O on the target system and slows Post. If most transactions are small, you can set this parameter so that Post read/releases after a certain number of messages instead of after every COMMIT. When you set a read/release interval, be aware that if new data does not follow a committed transaction (for example, if it was the last transaction of the day or there is no more user activity), Post processes the COMMIT and waits a certain amount of time, which is controlled by the internal SP_OPO_IDLE_LOGOUT parameter. If no data
CHAPTER 2 SharePlex Parameters
265
arrives, Post performs the read/release even though the SP_OPO_READRELEASE_INTERVAL interval is not satisfied. The number of messages in the post queue reduces to 0, indicating that Post is finished processing all messages from the queue. Note: Because the Post process has multiple threads, the number of messages is associated with each thread instead of the queue. Thus, the read/release interval can be longer than expected, and you might need to lower the default value.
Default: 1,000 Range of valid values: any positive integer Takes effect: immediately
SP_OPO_RETRIES_MAX This parameter controls the number of times that the Post process attempts to post a SQL statement that failed the first time. Post is programmed to retry certain failed operations when there is the possibility that they will succeed with another attempt. The main operations that Post will retry are TNS write failures, connection failures, or locks on tables when Post needs to apply a TRUNCATE. Post waits for a time interval specified by the SP_OPO_RETRY_DELAY_TIME parameter, and then it tries the operation again. When it reaches the value set by that parameter, it stops trying. If the Post process is set to continue on error (SP_SYS_SUSPEND_ON_ERROR=0) or if the error message is listed in the oramsglist file, the Post process will move-on to the next transaction. In all other cases, the Post process will stop after it reaches the maximum number of retires. To increase the likelihood that the failed operations are successful, you can increase the SP_OPO_RETRIES_MAX parameter so that Post tries the operation more times. At the same time, increase the SP_OPO_RETRY_DELAY_TIME parameter to increase the time interval between the attempts. That will give the lock or other blocking operation enough time between Post’s attempts to be resolved; otherwise, the retries might be too close together to be effective. Warning! Reducing this parameter can cause the data to accumulate in the queues, possibly causing them to exceed the available disk space.
Default: 10 times Range of valid values: 0 or any positive integer Takes effect: immediately
266
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_OPO_SQL_CACHE_DISABLE This parameter enables or disables the SQL Cache feature. By default, SQL Cache is on, and this parameter is set to 0. A setting of 1 disables SQL caching. If you disable SQL caching, SharePlex prints the following message to the Event Log: SQL Cache disabled. For more information about SQL Cache, see Chapter 6 of the SharePlex Administrator’s Guide. Default: 0 (on) Range of valid values: 0 or 1 (flag) Takes effect: when Post is restarted
SP_OPO_STOP_ON_DDL_ERR This parameter controls whether or not the Post process stops when there is an error applying DDL that is replicated between Oracle 9i+ databases. The default of 1 directs Post to stop for errors. An error usually indicates that the source component for which the DDL was executed does not exist in the target database, indicating the likelihood that subsequent DML changes will also fail. Stopping Post prevents the DML failures and enables you to correct the problem to keep the databases synchronized. DDL replication between Oracle 9i+ databases is enabled with the SP_OCT_REPLICATE_ALL_DDL parameter (see page 244). Default: 1 (on) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_OPO_THREADS_MAX This parameter is used primarily in testing to view the behavior of a SQL thread when it is handling several subqueues. The minimum number of threads is four, which enables the Post process to create the main thread, the timekeeper thread, the signal waiter thread, and one SQL thread. Default: 64 threads Range of valid values: 4 threads (minimum) to 128 threads (maximum) Takes effect: When the Post process is restarted
SP_OPO_USE_VARNUM Use a varnum to enter numbers into the database. Allows non-standard high precision values to be entered into a number column in the database. Default: 0 (Off)
CHAPTER 2 SharePlex Parameters
267
Range of valid values: 0 or 1 (flag) Takes effect: when Post is restarted
SP_OPO_WAIT_MSG_DELAY This parameter controls how long Post waits before generating a message indicating that it is killing old or stalled Oracle sessions. Those messages occur at the startup of Post. Default: 300 seconds Range of valid values: any positive integer up to 86400 Takes effect: when Post is restarted
sp_cop parameters SP_COP_IDLETIME This parameter determines the time interval during which sp_cop is inactive. The purpose of idle time is to conserve a machine's resources. In general, sp_cop should not be idle for long, because it plays a central role in replication. This parameter enables you to increase the idle time if sp_cop is using too much CPU time for overhead activities. A recommended value is 600 seconds to reduce the overhead. Default: 300 seconds Range of valid values: any positive integer Takes effect: immediately
SP_COP_SCAN _TIMEOUT This parameter sets the initial time interval sp_cop uses to scan its services table to determine if a process needs to be stopped or restarted. As SharePlex continues to run, the interval might change, depending upon the history of each process. Default: 300 seconds Range of valid values: any positive integer Takes effect: immediately
268
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_COP_SO_RCVBUF This parameter tunes the TCP/IP window size on the target machine. It works in conjunction with the SP_XPT_SO_SNDBUF parameter (see page 254) on the source machine to establish the size of a packet sent across the network. SharePlex references both parameters when TCP/IP sockets are created at the startup of sp_cop and the Export process. If SharePlex is replicating across a WAN and the export queue is continually backlogged, try adjusting both parameters. SP_COP_SO_RCVBUF must be set equal to or greater than the value of SP_XPT_SO_SNDBUF, in multiples of 1024 bytes. To size the parameters, determine the ping time between the source and target machines, then use the following formula for both parameters: param_value / ping_time = bytes per second For example, if ping time is 200 milliseconds, and the value for the two parameters is 64K, SharePlex sends five 64K-packets every second, totaling 320K per second. Unless you observe a bandwidth problem, Quest recommends leaving both parameters set to their defaults, which use the system's setting. To change SP_COP_SO_RCVBUF, set it on the target system, then stop and start sp_cop on that system. If transfer still is slow, try increasing the SP_IMP_WCMT_MSGCNT and SP_IMP_WCMT_TIMEOUT parameters (see page 255) on the target system. Set SP_IMP_WCMT_MSGCNT to at least 10,000. Default: 0 (default is set by the operating system) Range of valid values: positive integers, in bytes, using multiples of 1024. Maximum is set by the operating system. Takes effect: when SharePlex is restarted
SP_COP_TPORT This parameter sets the TCP/IP port number for TCP/IP communications among SharePlex sp_cop processes. All sp_cop processes replicating among each other must use the same TCP/IP port number. The default setting for SP_COP_TPORT is 2100; however, you may set a different port number during installation. After installation you may set a different port number by using the set port command. Thereafter, sp_cop uses the new port number. Default: 2100 Range of valid values: any positive integer Takes effect: when SharePlex is restarted
CHAPTER 2 SharePlex Parameters
269
SP_COP_UPORT This parameter sets the UDP port number for communication among SharePlex sp_cop processes. All sp_cop processes replicating among each other must use the same UDP port number. The default setting for SP_COP_UPORT is 2100; however, you may set a different port number during installation. After installation you may set a different port number by using the set port command. Thereafter, sp_cop uses the new port number. SharePlex only uses the UDP port for hello and are-you-alive messages, and it actually uses RMP through UDP. All other communication is through TCP. Default: 2100 Range of valid values: any positive integer Takes effect: when SharePlex is restarted
Queue parameters SP_QUE_MAX_QUEUES This parameter determines the maximum number of queues. Default: 25 Range of valid values: 9 - 254 Takes effect: When sp_cop is restarted
SP_QUE_POST_SHMSIZE This parameter determines the specific shared-memory size for the post queue. The SP_QUE_POST_SHMSIZE parameter is one of two parameters that have replaced the SP_QUE_SHMSIZE parameter, which has been retired in SharePlex version 5.0. Note that the default value for SP_QUE_SHMSIZE was 33554432, and since that was the amount of shared memory shared by all of the queues and each queue now has its own shared-memory segment, overall shared memory usage might increase. In addition, the queue code takes the existing value of SP_QUE_SHMSIZE and converts it to appropriate values for SP_QUE_POST_SHMSIZE and SP_QUE_Q_SHMSIZE. Warning! Increasing this parameter might require an increase in the maximum shared memory segment size in your system settings.
Default: 33554432 bytes Range of valid values: greater than 8388607 Takes effect: When sp_cop is restarted
270
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_QUE_Q_SHMSIZE This parameter determines the specific shared-memory size for the capture and export queues. Default: 8388608 bytes Range of valid values: 8388608 to no maximum Takes effect: When sp_cop is restarted
SP_QUE_SHMDBUF This parameter controls the shared-memory buffer size, which determines how much information the SharePlex processes read from, or write to, the queues at one time. The buffer is part of the SharePlex checkpoint recovery process that facilitates fast, safe, asynchronous transport of data. The default setting is an optimal value and should not be changed without the guidance of a Quest Technical Support representative or documented SharePlex procedure. However, it is acceptable to change this parameter if the majority of transactions are large. Try an initial setting of 65536. All values set for this parameter must be a power of 2. Warning! Increasing this parameter to a value greater than 64k might require an increase in the maximum shared memory segment size in your system settings.
Default: 32,768 bytes Range of valid values: any positive integer in powers of 2 Takes effect: when SharePlex is restarted
SP_QUE_SYNC SP_QUE_SYNC instructs the queue module to verify that the writes of queue data to disk have been written to the disk media before returning. This is not the standard disk write model in UNIX. In the default OS disk I/O procedure, disk writes are written to an internal OS buffer cache and then are written to disk later. This action distributes the overhead of writing to disk so processes do not have to wait for the data to be written to disk. When the data blocks are written to the buffer cache, the applications accessing the data cannot distinguish the data written to the buffer cache from data written to disk. Unlike the Oracle COMMIT, all processes that have access to the file also have access to the data in the buffer cache. If a system crash should occur between the time the data blocks are written to the buffer cache and to the physical media, any data not written to the media is at risk for being lost upon the system recovery.
CHAPTER 2 SharePlex Parameters
271
The SP_QUE_SYNC parameter is implemented as follows: SP_QUE_SYNC=0 The OS default case described in the second paragraph is the disk write algorithm used for the SharePlex queue data. SP_QUE_SYNC=1 Setting SP_QUE_SYNC to 1 causes the O_SYNC flag to be set upon opening each queue data and header file. This flag tells the OS not to return a write call until the data has been successfully written to disk. Without the sync flag ("normal" I/O), space would be allocated for the file data but the file data might not be written due to a system crash, cluster failover, or other critical problem that causes the OS to stop executing. SP_QUE_SYNC=2 (SharePlex default setting) Setting the SP_QUE_SYNC parameter to 2 does not turn on the O_SYNC flag. Instead, normal writes are done until a queue write COMMIT is called. As part of the write COMMIT, the queue module executes the system call fsync on each queue data file and then on the queue header files. This eliminates redundant sync operations on data that may be rewritten later by a later write COMMIT. Impact of setting SP_QUE_SYNC Setting SP_QUE_SYNC to a value that causes disk writes to complete before returning might have an impact on SharePlex performance and may slightly increase I/O processing for non-SharePlex processes. The amount of overhead is dependent upon the amount of data in the queue, the filesystem types, and the types of disk drive and disk controller in use. Default: 2 Range of valid values: 0 - 2 Takes effect: When SharePlex is restarted
Statistics (Shared Memory) parameters SharePlex maintains certain system information in a shared-memory segment that is separate from the shared memory segment used by the queues. This allows SharePlex to display process status statistics through sp_ctrl.
272
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
LOG Parameters SP_SLG_LOG_MAXSIZE This parameter controls the size of the SharePlex Event and Trace logs. You can set it based on the amount of available disk space to ensure that the logs do not consume too much space. Before writing to a log, SharePlex checks the log’s size. If the size is larger than the value of this parameter, SharePlex truncates the log before writing to it. The default log size is 500 MB. Before increasing this parameter, make certain that you have enough disk space to accommodate the new file size. Default: 500 MB Range of valid values: 1 to 2048 MB in increments of 1 MB Takes effect: when SharePlex is restarted
SNMP parameters SharePlex provides agent support for Simple Network Management Protocol, but does not provide an SNMP signal daemon (SNMP manager) to intercept the traps. Use the SharePlex SNMP feature only if you have a Network Management Station (NMS) to manage SNMP signals. The following parameters configure the SharePlex SNMP agent. _SNMP_ACTIVE — This parameter is a flag that enables or disables SNMP support. Default: 0 (off) Range of valid values: 0 or 1 (on) Takes effect: when SharePlex is restarted The following parameters configure the agent to communicate with the NMS. They must contain a value if the _SNMP_ACTIVE parameter is enabled. All take effect when SharePlex is restarted. _SNMP_HOST — The system (host) to which the traps will be sent _SNMP_COMMUNITY — The community to which the traps will be sent _SNMP_MJR_ERRNUM — The major error number to be used by the traps _SNMP_MNR_ERRNUM — The minor error number to be used by the traps The following parameters encompass all of the replication events for which you can configure SharePlex to send SNMP traps. All are flags. A setting of 0 disables the parameter’s functionality (meaning that SharePlex does not send a trap for the event); a
CHAPTER 2 SharePlex Parameters
273
setting of 1 enables it (SharePlex sends a trap). You can enable any or all of them. All take effect when SharePlex is restarted. _SNMP_INT_ERROR — SharePlex logic errors and errors that cause processes to exit _SNMP_SYS_ERROR — System-related errors encountered by SharePlex _SNMP_ERROR — Other SharePlex errors _SNMP_OUT_OF_SYNC — When replication is out of synchronization _SNMP_STARTUP — When SharePlex starts up _SNMP_SHUTDOWN — When SharePlex shuts down _SNMP_LAUNCH — When a SharePlex process starts _SNMP_EXIT — When a SharePlex process stops
System parameters SP_SYS_HOST_NAME This parameter is for use in environments where one SharePlex variable-data directory is shared among multiple nodes, such as clusters and systems with alternate network interfaces. It provides SharePlex the correct logical host name (global cluster package name) when any of its processes issues a name lookup, superseding the local system name. The name set with this parameter enables SharePlex to migrate properly during failover.
• Set SP_SYS_HOST_NAME on the primary node and all secondary (adoptive) nodes before you activate the configuration, and configure it into the package that fails over.
• Set this parameter in the .profiles file on UNIX systems and in the Windows Registry on Windows systems.
• On UNIX systems, set this parameter through sp_ctrl in the paramdb of the shared variable-data directory. Setting SP_SYS_HOST_NAME through sp_ctrl sets it permanently in the variable-data directory, which is part of the failover, and it ensures that the package name exports before sp_cop starts when you are ready to begin replication.
• Set SP_SYS_HOST_NAME only on machines within the cluster. When you issue sp_ctrl commands from a system affecting a clustered machine, use the name set with SP_SYS_HOST_NAME as the host in the [on host] option, or set it as the default for sp_ctrl by using the host command (see page 119).
274
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Complete instructions for using this parameter on clustered systems are in the SharePlex Installation and Demonstration Guide. Default: none Range of valid values: the character string of the package name Takes effect: when SharePlex is restarted
SP_SYS_IN_SYNC This parameter controls the way that SharePlex replicates tables that have key columns where a NULL value is allowed.
• When this parameter is set to the default of 0 (off), SharePlex uses the key to locate rows on the target system, whether or not any of those columns contain NULLs. This can cause an out-of-sync condition for UPDATEs and DELETEs if the key for a row contains NULLs. The row’s uniqueness cannot be assured, and it is possible for SharePlex to change the wrong row on the target system.
• When this parameter is set to 1 (on), it directs SharePlex to use the key, but only if there are no NULLs in the row’s key. If the key contains a NULL value, SharePlex uses all of the columns in the row as a simulated key to ensure that it locates the correct target row. If you know that the keys in your application will never contain NULLs (although NULLs were declared), leave this parameter off, because it incurs more overhead with the added logic that it uses. Set this parameter on the source system, and set it before you activate the configuration. Default: 0 (off) Range of valid values: 0 or 1 (flag) Takes effect: when Capture and Read are restarted
SP_SYS_JOB_HISTORY_RETENTION This parameter defines how many days information about past jobs will be kept for the copy status and/or copy report (append status and/or append report )commnds to display. Default: 90 days Range of valid values: 0 or any positive integer Takes effect: immediately
CHAPTER 2 SharePlex Parameters
275
SP_SYS_SUSPEND_ON_ERROR This parameter controls whether or not the Capture or Post process stops when it encounters a system or internal SharePlex error. The default of 1 directs the process to stop when there is an error. A setting of 0 directs the process to continue but generate a message in the Event Log. Important! If Capture is stopped for too long, it can lose pace with Oracle, and the redo logs can wrap. If that happens, Capture reads the archive logs, but if the archive logs become unavailable, you will need to resynchronize the data.
Default: 1 (stop on errors) Range of valid values: 0 or 1 (flag) Takes effect: immediately
SP_SYS_VAR_FULL This parameter sets a threshold for available space on the disk where the SharePlex variable-data directory is installed. It prevents the queues from exceeding available disk space. If an operation being processed by Capture, Read or Import will cause available disk space to drop below the value set for this parameter, the process stops. Processing resumes when available disk space reaches the threshold set with the SP_SYS_VAR_OK parameter. Default: 30 MB Range of valid values: any positive integer greater than the value of SP_SYS_VAR_OK Takes effect: immediately
SP_SYS_VAR_OK This parameter sets the amount of available disk space at which Capture, Read or Import resumes processing after it stopped because the value for SP_SYS_VAR_FULL was reached. Default: 50 MB Range of valid values: any positive integer Takes effect: immediately
276
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Compare command parameters SP_DEQ_BATCHSIZE This parameter controls the batch size that SharePlex uses for the compare/repair function when the compare config or compare table command is issued. The batch size controls the number of rows that SharePlex selects at once for comparison. Larger batch sizes increase processing speed but require more memory. Memory usage also depends on the number and size of the columns in the table(s) being compared, and the number of compare processes running at the same time. If the SP_DEQ_BATCHSIZE parameter is larger than the number of rows in the source table being compared, SharePlex reduces the batch size to the number of rows in the table. That prevents SharePlex from allocating more space than it needs for the compare processes. As you gain experience with the compare commands, you might find a more optimal setting for this parameter. Default: 10,000 rows Range of valid values: 1 to 32,767 rows (up to the max number of rows in the table) Takes effect: Immediately available for the next comparison
SP_DEQ_CHARACTERSET This parameter selects the character set for the CHAR, VARCHAR2, and CLOB datatypes from the target machine for Compare to use. Note that you set the SP_DEQ_CHARACTERSET parameter on the source machine using the value for the target NLS_CHARACTERSET. Default: none Range of valid values: See paragraph above Takes effect: immediately available for the next comparison
SP_DEQ_CONFIG_LINE_SIZE This paramater controls the buffer size when the config file contains line(s) that are longer than 2048 characters. (In general, users should not see lines greater than 2048 characters.) Default: 2048 Range of valid values: any integer between 1024 and 35000 Takes effect: immediately available for the next comparison
CHAPTER 2 SharePlex Parameters
277
SP_DEQ_IGNORE_ORACLE_ERROR_NUM This parameter allows the user to specify an Oracle Error Number to ignore. The specified errror number will be ignored up to 500 times. This parameter is mainly for debugging purposes and should not be use with the repair or repair1 option. Default: 0 (none) Range of valid values: Any valid Oracle Error Number, e.g. 1406 Takes effect: immediately available for the next comparison
SP_DEQ_IP_MAPPING This parameter maps the IP addresses when Network Address Translation (NAT) is implemented between the source and target systems. When NAT is implemented, the target IP address on the source machine (for example, 192.168.32.10) and the IP address on the target machine (for example, 213.18.123.103) can be different, which can cause confusion when the compare config and compare table commands are issued. When you set the parameter SP_DEQ_IP_MAPPING on the target machine, the IP address 192.168.32.10 is considered equivalent to the IP address 213.18.123.103, thus allowing Post to process the compare message and the compare sp_declt client process to finish the Compare process. Set the SP_DEQ_IP_MAPPING parameter on the target system as in the following example: sp_ctrl> set param SP_DEQ_IP_MAPPING "192.168.32.10:213.18.123.103" Note: Use the appropriate IP addresses for your source and target machines. The IP addresses listed above are only an example.
In addition, the SP_DEQ_IP_MAPPING parameter accepts multiple mappings, separated by a comma, as in the following example: sp_ctrl> set param SP_DEQ_IP_MAPPING "192.168.32.10:213.18.123.103,10.2.3.4:50.64.70.88" Default: None Takes effect: When the next compare command is issued
SP_DEQ_LOG_ROWID This parameter directs SharePlex to log the Oracle row ID of each source row that is inserted or updated by a compare config or compare table repair process.
278
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SharePlex writes the out-of-sync source rowID to the compare report, which is a file in the format of sid_schema-table-sessionID.sql in the log sub-directory of the SharePlex variable-data directory on the target system. You can view the compare report from sp_ctrl with the show compare command. This parameter is disabled by default because it incurs extra overhead to send each row ID to the target system, especially when tables are large, and a source row ID generally is not needed to make repairs. Set this parameter on the source system. Default: 0 (do not log source row ID) Range of valid values: 0 or 1 (flag) Takes effect: immediately available for the next comparison
SP_DEQ_NCHAR_CHARACTERSET This parameter selects the character set on the target machine for Compare to use for the NCHAR, NVARCHAR2 and NCLOB datatypes. Note that you set the SP_DEQ_NCHAR_CHARACTERSET parameter on the source machine using the value for the target NLS_NCHAR_CHARACTERSET. Default: no Range of valid values: none Takes effect: immediately available for the next comparison
SP_DEQ_NEW_NUM_COMPARE This parameter is used to control the use of an alternate numeric compare method for the numeric key column(s). This alternate numeric compare method will avoid larger numeric data rounding off issues. When this parameter is turned on the Compare process will use the actual string data instead of converting the data and then comparing. Default: 0 (off) Range of valid values: 0 or 1 (flag) Takes effect: immediately available for the next comparison
SP_DEQ_NLS_LANG This parameter for Compare is the same as the SP_OPO_NLS_LANG and SP_ORD_NLS LANG parameters for Post and Read, respectively.
CHAPTER 2 SharePlex Parameters
279
SharePlex expects the default character set for the database to be US7ASCII, but it is designed to detect the database's setting, if different, and automatically use the correct character set. Therefore, in most situations, you should not need to change this parameter. Change this parameter only if it becomes necessary to override SharePlex to ensure that a certain character set is used for a database. You can set different character sets for individual databases with this parameter, and you can specify all of the sets with the same set param command, if you use the following format: sp_ctrl(system:port)> set param SP_DEQ_NLS_LANG SID1,CHARACTERSET1/ SID2,CHARACTERSET2 Separate each database Oracle_SID and character set with a comma (,) and separate each SID-character set combination with a slash (/). Leave no spaces between any components. Example: ora10a,WE8ISO8859P1/ora10b,UTF8 Note: This parameter only enables the SharePlex Compare process to recognize the database character set. SharePlex does not convert data from one character set to another.
Default: None; a character set must be specified to make the parameter active. Range of valid values: Any valid ORACLE_SID and character set Takes effect: immediately available for the next comparison
SP_DEQ_NLS_LANG_SELECTOR This parameter selects the language for Compare to use on both source & target databases. There are four settings: 0 - the default setting, Compare uses the current language for the database. 1 - Compare uses the settings for the SP_ORD_NLS LANG (on source machine) and SP_OPO_NLS_LANG (on target machine) parameters 2 - user determines the language to be used 3 - the SP_DEQ_NLS_LANG_SELECTOR parameter is not set (is not used) Set this parameter on the source or target system. Default: 0 Range of valid values: 0 - 3 Takes effect: immediately available for the next comparison
280
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_DEQ_PART_TABLE_UPDATE This parameter affects the repair behavior of the compare table and compare config commands when they are issued for partitioned target tables.
• When this parameter is set to the default of 0, partitioned target tables are repaired using INSERTs and DELETEs only. Repairs requiring UPDATEs are converted to a DELETE followed by an INSERT to prevent errors when an UPDATE could cause a row to change partitions and row movement is not enabled for the table.
• When this parameter is set to 1, partitioned tables are repaired using INSERTs, UPDATEs, and DELETEs as appropriate. Use this mode only when you know UPDATEs will not result in a row changing partitions in the target table or when row movement is enabled for the target table. Set this parameter on the target system. Default: 0 (do not repair with UPDATEs) Range of valid values: 0 or 1 (flag) Takes effect: immediately available for the next comparison
SP_DEQ_READ_BUFFER_SIZE This parameter applies only to LOB and LONG columns during a compare/repair operation. It adjusts the size of the buffer that holds the fetched LOB or LONG data when those columns are being compared and repaired. The value of the parameter should be adjusted based on the available system memory and data size. Default: 1 MB Range of valid values: any integer between 1 and 100 (values in MB) Takes effect: Immediately available for the next comparison
SP_DEQ_RESULTS_RETENTION Using this parameter, the user can specify the number of days that results from Compare or from SYNC will be kept in the SHAREPLEX_DATAEQUATOR_RESULTS table. NOTE: The Compare and SYNC processes can only cleanup this table when they are running. If you have not run these the results in the table could be older than that specified in this parameter. Note: The Compare and SYNC processes can only cleanup the SHAREPLEX_DATAEQUATOR_RESULTS table when they are running. If you have not run these process recently the results in the table could be older than what is specified in this parameter.
CHAPTER 2 SharePlex Parameters
281
Default: 90 Range of valid values: any integer (no limit) Takes effect: Immediately available for the next comparison
SP_DEQ_REUSE_CONFIG This parameter conrols when the Compare Server will parse the config file and generate a compare internal config file that includes additional information, such as horizontal partition replication conditions, etc. Because the config file parsing process can take some time to complete, if the config has a large number of entries, by default this parameter is set to 1. In this case, the Compare Server will only parse the config file once per activation. Default: 1 (on) Range of valid values: 0 or 1 (flag) Takes effect: Immediately available for the next comparison
SP_DEQ_ROW_LOCK_THRESHOLD Compare/Repair utilizes this threshold to determine if, when utilizing the “where”, “sourcewhere” and/or “targetwhere” option, the row count is sufficiently low enough to merit use of row level locking instead of table level locking. If the percentage of qualified rows is less than or equal to this parameter value Compare/Repair will use row level locking. Default: 10% Range of valid values: 0 to 100% Takes effect: Immediately available for the next comparison
SP_DEQ_SKIP_LOB This parameter directs the behavior of the compare config and compare table commands with respect to tables containing LOB columns.
• When the parameter is set to the default of 0, the compare processes compare and repair tables with LOBs.
• When the parameter is set to 1, tables with LOBs are processed, but only non-LOB columns are compared and repaired. The LOB columns are ignored. See “SP_DEQ_LOG_ROWID” on page 277. Set this parameter on the source system.
282
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Default: 0 Range of valid values: 0 or 1 (flag) Takes effect: Immediately available for the next comparison
SP_DEQ_THREADS This parameter controls the number of processing threads used by the compare config command on the source system. Each thread creates a sp_declt process on the target machine. The default of 2 threads has proven to be the best number for UP machines, but you might obtain performance improvements with up to 15 threads. Too many threads causes diminishing benefits. The value for the thread count is independent of the number of tables to be compared, and SharePlex will not generate more threads than there are tables to be compared. If the machine has only one processor, set this parameter to a value of 1. Set this parameter before you issue the compare config command. Default: 2 threads Range of valid values: 1 to 15 Takes effect: immediately available for the next comparison
SP_DEQ_TIMEOUT This parameter controls the connection time out for the compare config and compare table commands. Because the sp_desvr process relies on the replication queues to instantiate the sp_declt process(es) on the target system, the sp_declt process cannot start until all previous messages in the queues have been processed. If the delay is longer than the time out specified with this parameter, sp_desvr exits and returns an error. If you know the queues are more than 30 minutes backlogged, you can increase this parameter as needed. Default: 1800 seconds (30 minutes) Range of valid values: 121 seconds or greater Takes effect: immediately available for the next comparison
Sync process parameters SP_OSY_COMPRESSION This parameter adjusts the data compression level from off (0) to full (9).
CHAPTER 2 SharePlex Parameters
283
Default: 6 Range of valid values: 0 to 9 (9 being the highest level of compression) Takes effect: immediately available for the next sync
SP_OSY_LOCK_TIMEOUT This parameter set the number of seconds that the synchronization process will wait to obtain a table lock. Default: 2 Range of valid values: 0 to 900 Takes effect: immediately available for the next sync
SP_OSY_POST_TIMEOUT This parameter sets the number of seconds that the synchronization process will wait for the Post process to be ready and the synchronization to begin. Default: 1800 Range of valid values: 0 to 36000 (seconds) Takes effect: immediately available for the next sync
SP_OSY_TCP_TIMEOUT This parameter sets the number of seconds for the IPC time-out. Default: 10 Range of valid values: 0 to 6000 (seconds) Takes effect: immediately available for the next sync
SP_OSY_THREADS This parameter sets the number of pairs of synchronization processing threads, export/ import, between the source and target systems. This parameter is utilized by SharePlex sync processes, e.g. the copy/append commands. Default: 5 Range of valid values: 1 to 10 Takes effect: immediately available for the next sync
284
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
3 Preventing and Solving Replication Problems This chapter contains solutions to many of the common questions and problems that can arise during replication, and it also suggests preventive measures for avoiding problems. The chapter is divided into several parts to make it easier to locate information. Contents Tools for preventing and solving problems Solving Oracle Setup problems Solving configuration problems Solving synchronization problems Solving replication problems Solving other problems How to get help
286
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Part 1: Tools for preventing and solving problems This part of the chapter reviews the tools available for preventing replication problems and diagnosing problems on your own.
Viewing the Status Database The Status Database contains a summary of what is reported in the Event Log, including events that did not generate a message or warning at the sp_ctrl user interface. It can expose potential problems and help you resolve existing ones. Each event’s description includes the reason and the number of times that the event occurred. If additional details are available, the Status Database refers you to the Event Log. Check the Status Database frequently by issuing the show statusdb command in sp_ctrl (see page 205).
Viewing the Event Log Each instance of SharePlex has a SharePlex Event Log, which is an ASCII file named event_log located in the log sub-directory of the SharePlex variable-data directory. The Event Log provides a perpetual step-by-step record of the replication process, listing the activity as a series of events. When there are replication problems and you cannot determine the cause, the Event Log can help you replay the sequence of events that led up to the problem. Frequently, the Status Database will refer you to the Event Log for a more detailed explanation of a warning, notice or event. Examples of replication events include:
• • • • •
The startup or stopping of sp_cop or a replication process The implementation of a user command such as activate config Oracle errors The failure of a connection or SharePlex process The execution of a utility such as ora_cleansp
CHAPTER 3 Preventing and Solving Replication Problems
287
• The login or logout of a user To view the Event Log, you can use the following:
• the show log command in sp_ctrl (see page 187). • the UNIX more or tail commands from the UNIX command line prompt. • WordPad or another ASCII text program on Windows systems. In addition to helping you diagnose problems on your own, the Event Log is an indispensable tool used by Quest Technical Support when you place a support call. Each entry in the Event Log includes the following critical information:
• The date and time of the event. • A description of the event and any related messages (error or non-error). • The event’s process ID number, if it is associated with a SharePlex process.
Viewing the user issued commands User issued commands are recorded in the Event Log. The user issued commands are recorded for every SharePlex command issued for that instance of SharePlex. It is useful when something has affected replication and you want to see if one or more commands caused it. For example, if Post is not running, you may have seen in the Status Database that it was stopped by a user. You can review the user issued commands to see who issued the command, which system it was issued for, the date and time it was issued, and the command syntax that was used. To view the user issued commands, you can use the following:
• the show log command in sp_ctrl (see page 187). • the UNIX more or tail commands from the UNIX command line prompt to view the event_log file.
• WordPad or another ASCII text program on Windows systems to view the event_log file. Note: A user issued command appears in the Event Log as a “Notice”.
288
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Example: Notice 08-07-02 16:13:24.641582 23696 1 User command: rragland activate config 1route (from irvspxu14) Notice 08-07-02 16:14:24.641582 23696 1 User command: rragland stop export (from irvspxu14) Notice 08-07-02 16:14:26.881325 23696 1 User command: rragland start export (from irvspxu14)
Viewing the other log files The process logs When a SharePlex process is unable to process a record, it logs the record to an associated log file in the log sub-directory of the SharePlex variable-data directory. In addition, it logs the error to the Event Log. The process logs are primarily used by Quest Technical Support when you are asked to turn on debugging. The log file names are constructed in the following manner:
• The first name component is either the source ORACLE_SID, for Capture or Read, or the target ORACLE_SID, for Post and the reconcile function, followed by an underscore (_ ). • The second component is the short name for the module (ocap, ord, opo, rcl). • The third component is the file number (01, 02, 03). • The fourth component is the .log extension. Examples: ora10_ocap01.log
ora10_ord01.log
ora10_opo01.log
ora10_rcl01.log
To permit continuous debug logging while controlling its disk usage, SharePlex generates the logs in a circular fashion, similar to the way in which Oracle generates redo logs. The default behavior for the process logs is that when a log file reaches 50 MB in size, SharePlex generates another log file. When the second log reaches 50 MB in size, SharePlex generates another one of the same size, continuing in this fashion for a total of 3 logs (per process). When 3 logs fill up, the logging mechanism wraps and replaces the oldest log with a new one. It continues this process in groups of 3. The numbering begins with 1. If a process is stopped and then restarted, the logging begins at the next number. For example, if Post is logging to ora10_opo01.log, and you stop and restart it, then the new Post process uses log ora10_opo02.log. When logs are
CHAPTER 3 Preventing and Solving Replication Problems
289
created up to, and including, log ora10_opo03.log, the series wraps and starts overwriting ora10_opso01.log. The size and number of the log files can be adjusted depending on your environment, but your Technical Support representative will advise you if that is necessary and will provide instructions for doing so. To view a process log, you can use the following:
• the UNIX more or tail commands from the UNIX command line prompt. • WordPad or another ASCII text program on Windows systems.
The activation log When you activate a configuration, it generates a log named SID_oconf##.log in the log sub-directory that provides the results of the activation. (SID is the ORACLE_SID for the source instance.) To view the activation log, you can use the following:
• the UNIX more or tail commands from the UNIX command line prompt. • WordPad or another ASCII text program on Windows systems.
The compare/repair log The compare config and compare table commands log errors, messages and warnings to the log sub-directory under either the sp_desrvr or sp_declt process name. For more information about viewing these logs, see “compare config” on page 33 and “compare table” on page 55.
The error log When the Post process detects that source and target tables are out of synchronization, it logs the first 100 SQL statements for the out-of-sync transactions to an error file named SID_errlog.sql, where SID is the ORACLE_SID of 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 the target tables if the condition is not too severe, after first correcting the cause of the problem. For more information about this log, see page 324.
290
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Viewing and terminating SharePlex processes Viewing and terminating processes on UNIX systems On UNIX systems, you can use the ps -ef | grep sp_ command to display all of the major and background SharePlex processes that are running.
sp_cop process This shows that the sp_cop process (PID1576) spawned: • the Command and Control process (PID5835) • the Capture process (PID5856) • the Read process (PID5857) • the Export process (PID5875) Note that each child process bears the same -u identifier as its parent, making it easier to identify related processes when multiple sessions of sp_cop are running. sp_cop
FIGURE 3: Sample display using ps -ef | grep sp_: This command issued in System V produces a basic UNIX display of all the SharePlex processes that are running, including background processes with which users do not interact. This command in other UNIX versions returns similar information. It returns, from left to right: • • • • • • • •
the user ID the process ID number of the process the process ID of the parent process that spawned the process how long the process has been running the start time of the process the terminal on which the process is running the amount of CPU time the process has consumed the command that started the process
CHAPTER 3 Preventing and Solving Replication Problems
291
To kill any of those processes, use the UNIX kill or kill -9 command. $ kill PID Or... $ kill -9 PID
Viewing SharePlex processes on Windows systems You can view the SharePlex processes on Windows systems in the following ways:
• from the Command Prompt console using the tlist program provided with the SharePlex software (also available in the Microsoft Windows Resource Kit).
• from the Windows Task Manager or the DTaskmgr utility provided with SharePlex. • from the Task Manager in the SpClient or SpUtils utilities.
Terminating SharePlex processes on Windows systems You cannot terminate SharePlex processes through the Windows Task Manager. The NuTCRACKER environment controls the SharePlex processes, so you need to run DTaskmgr, a special version of the Task Manager with special privileges that is provided with the SharePlex software. To determine which process to kill, see “How to identify Sp_Copsrv.exe processes on Windows systems” on page 25 in the SharePlex Administrator’s Guide. You can terminate SharePlex processes on Windows systems using the following tools:
• • • • •
SpClient SpUtils DTaskmgr KillSharePlex.bat Kill
Terminating processes with SpClient or SpUtils The fastest and easiest way to kill a SharePlex process is to launch DTaskmgr from either the SpClient or SpUtils utility. Those utilities run a filtered DTaskmgr that shows only the SharePlex processes. SpClient can be used on a local or remote system, but SpUtils can be used only on the local system. For more information about these utilities, see Chapter 12 of the SharePlex Administrator’s Guide.
292
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Terminating processes with DTaskmgr DTaskmgr can be run directly from its location in the SharePlex product directory. When run this way, it displays all of the processes on the system, including processes for other applications. 1
Double-click the DTaskmgr icon in the bin sub-directory of the SharePlex product directory, or run it from the Start menu by navigating to its location in the SharePlex programs group.
2 Click the Processes tab.
FIGURE 4: Viewing SharePlex processes with DTaskmgr
3 Highlight the SharePlex process that you want to terminate. 4 Click End Process. A warning message prompts for confirmation of your intent to
kill the process. 5 Click Yes to terminate the process.
CHAPTER 3 Preventing and Solving Replication Problems
293
Terminating processes with KillSharePlex.bat KillSharePlex.bat is a batch file that terminates all SharePlex processes at once, without displaying them. There is no user interface; the program works in the background without prompts or confirmation when it is finished. To run KillSharePlex.bat, doubleclick its icon in the bin sub-directory of the SharePlex product directory.
Terminating processes with kill DTaskmgr does not work if Windows Terminal Server is installed. In that case, use the kill program provided with SharePlex in the bin sub-directory of the SharePlex product
directory. (This command also is available in the Windows Resource Kit from Microsoft). 1 From the Start menu, select Run. 2 In the Open text box, type the characters cmd to open the Windows Command
Prompt. 3 At the prompt, change directories to the bin sub-directory of the SharePlex product
directory. 4 Type the tlist command and then press Enter. A list of processes is displayed. 5 At the command prompt, type kill followed by either the Process ID number or name
of the process you want to kill. You can terminate any SharePlex process in this manner. Most SharePlex processes begin with Sp_. To view all of them, look in the bin sub-directory in the SharePlex product directory.
294
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
FIGURE 5:This shows the use of the tlist command followed by the kill command.
If a process survives the kill command, try the /F option with the kill command to force the termination.
Using the status and lstatus commands to view status Issue the status, qstatus, and lstatus commands frequently to check the state of replication.
• Use the status command to view a summary of the status of replication on a system, to ensure that processes are running and to check for errors, warnings or notices.
• Use the lstatus command to view detailed information about the status of replication on a source or target system. This command is the most comprehensive information command in sp_ctrl. It provides process status, qstatus, and information about the active configuration and key events that occurred.
CHAPTER 3 Preventing and Solving Replication Problems
295
• Use the qstatus command to view statistics for the capture, post, and export queues on any system. It displays the number of messages in each queue, their age, and the current size of the queue. For more information about those commands, see the alphabetical reference section of Chapter 1.
Using the verify config command to test a configuration Before activating a configuration, run the verify config command. This command checks for common conditions that can cause activation to fail for individual objects or the entire configuration. Unless you are using live activation, configuration activation interrupts user activity, so you want the impact to be minimal by ensuring that activation succeeds the first time. This command also checks for conditions that can cause replication errors. For more information about verify config, see page 224.
Using the compare commands to verify synchronization The compare config and compare table commands in sp_ctrl compare and repair target tables that are out of synchronization with their source tables. For more information, see the alphabetical listings for these commands in Chapter 1.
Changing the IP address on the target machine When replicating, it has become fairly common to change the IP address of the target machine(s). However, when you change the IP address, you must clean up the old activation, resynchronize and reactivate your configuration(s). You can use the following procedure to set the export parameter SP_XPT_ALTERNATE_HOST to point to a different target machine. This procedure for changing the target IP address can be used in all configurations for switching the target IP address.
On the source machine 1 Stop the Export process. 2 Set the parameter SP_XPT_ALTERNATE_HOST IP address.
296
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
This parameter must be set for only those Export processes exporting to the machine whose IP address has changed. If replicating to more than one target, refer to the set param command on page 156 of the SharePlex Reference Guide for more information on setting parameters for specific processes. 3 Start the Export process.
On the target machine 4 Start sp_cop on the target machine on the right IP address, using the parameter
SP_SYS_HOST_NAME if necessary. Refer to page 273 of the SharePlex Reference Guide for more information on using this parameter. 5 Rename object cache files if necessary. The last few lines in the event log will con-
tain errors similar to the following: Error 08-06-12 13:20:17.089485 2480 1 sp_opst_mt(osp) (for o.vega817-o.vega817 queue vega) 17000 - error opening file /splex/scott/qview/var8/state/ 0x0a01014c+PP+vega+sp_opst_mt+o.vega817-o.vega817objcache_sp_opst_mt.11: No such file or directory. Look in the directory indicated (the vardir/state directory) and look for any files that are almost the same name and where only the first 10 characters of the name are different. That is, the above error may be generated for a file in that directory named: 0x0a010166+PP+vega+sp_opst_mt+o.vega817-o.vega817objcache_sp_opst_mt.11 To fix post's problem rename the file to match the name printed in the event log. For instance, mv 0x0a010166+PP+vega+sp_opst_mt+o.vega817-o.vega817objcache_sp_opst_mt.11 0x0a01014c+PP+vega+sp_opst_mt+o.vega817-o.vega817objcache_sp_opst_mt.11 6 Start the Post process.
Getting syntax help for commands To get a fast online explanation of a SharePlex command and its correct syntax, use the help command in sp_ctrl. To view just the correct syntax, use the usage command. See Chapter 1 for more information about these commands.
CHAPTER 3 Preventing and Solving Replication Problems
297
Monitoring replication to detect and prevent problems SharePlex provides the following means for detecting problems with replication.
Using the information commands in sp_ctrl SharePlex provides the following sp_ctrl commands for viewing brief and detailed information about the state of configuration activation and the SharePlex processes and queues when problem solving. See the alphabetical reference in Chapter 1 for detailed descriptions of these commands. Command
Auth. Level
lstatus
3
Displays detailed information about the state of SharePlex replication.
qstatus
3
Displays the state of the capture, export and post queues.
show
3
Displays the source and destination of the data being processed by each replication process on a system, and displays the status of each process.
show activate
3
Displays the status of all configuration activation activity on a source system.
show capture
3
Displays brief or detailed statistics for the Capture process for use in tuning and problem solving.
show compare
3
Displays the results of the compare config and compare table commands.
show config
3
Displays properties of the active configuration.
show export
3
Displays the number of messages sent to the target system(s).
show import
3
Displays the number of messages received from the source system(s).
show log
3
Displays the Event Log, Command Log, Verify Log, Trace Log, or a process log.
3
Displays brief or detailed statistics for the Post process for use in tuning and problem solving.
Description
298
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Command
Auth. Level
show read
3
Displays brief or detailed statistics for the Read process for use in tuning and problem solving.
show sql
3
Displays the current or last SQL statement processed by the Post process.
show statusdb
3
Displays the Status Database, which contains records of important replication events.
show sync
3
Displays information about out-of-sync conditions.
status
3
Displays an overview of the state of SharePlex replication.
Description
Using monitoring scripts SharePlex provides utility scripts for unattended monitoring of key aspects of replication, with e-mail alert capability. These scripts reduce the need to check the Status Database and Event Log for certain conditions, or to make frequent status checks with sp_ctrl commands. See Chapter 9 of the SharePlex Administrator’s Guide for more information about these scripts.
Using SNMP monitoring SharePlex supports agent monitoring for sending SNMP traps for certain replication events. If you have SNMP established with a Network Management Station (NMS) to manage SNMP signals, you can use SNMP for SharePlex. For more information, see Chapter 9 of the SharePlex Administrator’s Guide.
CHAPTER 3 Preventing and Solving Replication Problems
299
Part 2: Solving Oracle Setup problems This part of the chapter helps you diagnose problems that might occur when you run the Oracle setup program (ora_setup on UNIX systems or OraSetup on Windows systems). The Oracle setup program establishes an Oracle account for SharePlex and installs the SharePlex objects in the SharePlex schema.
Incorrect ORACLE_SID and/or ORACLE_HOME If ora_setup failed or if SharePlex cannot interact with Oracle, you might have specified the wrong ORACLE_SID and/or ORACLE_HOME for the Oracle instance. On UNIX and Windows systems, SharePlex uses the ORACLE_SID to identify the instance where the source data resides. On UNIX systems, SharePlex references the ORACLE_HOME to locate the Oracle shared libraries.
Methods for determining the ORACLE_SID You can view the ORACLE_SID in a few different ways.
• On UNIX and Windows systems, you can query the V$PARAMETER table through SQL*Plus. SQL> select name, value from V$parameter where name = ‘db_name’;
• On a UNIX system, you can view the oratab file. HP-UX and IBM AIX systems $ cd /etc $ more oratab You will see a display similar to this: ora10:/qa/oracle/ora10/product In this example, ora10 is the ORACLE_SID and /qa/oracle/ora10/ product is the ORACLE_HOME directory.
Sun Solaris systems On the Solaris platform, the oratab file is typically located in the var/ opt/oracle directory. Sometimes there is an oratab file in the /etc directory as well. If there is an oratab file in the /etc directory, remove, rename or relocate it to prevent problems for SharePlex.
300
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• On Windows systems, you can view the Windows Registry under HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE. After you determine the correct ORACLE_SID (and ORACLE_HOME, if using UNIX), try running ora_setup again
More than one oratab file (Sun Solaris) On Solaris systems, the oratab file is typically located in the /var/opt/oracle directory, but because other UNIX platforms store the oratab file in the /etc directory, there could be a second oratab in the /etc directory. If that is true, either move, rename or delete it, and then try running ora_setup again.
Asterisk as the ORACLE_SID entry Sometimes, the oratab file on a UNIX system has an * (asterisk) symbol instead of a value for the ORACLE_SID of the instance that will be replicated. An asterisk can cause ora_setup to fail. Ensure that a valid ORACLE_SID is in the oratab file, and then try running ora_setup again.
Legacy /etc/logingroups file (HP systems) Sometimes there is an /etc/logingroups file on an HP system. This file existed on HPUX systems prior to the adaptation of POSIX standards. To allow backward compatibility, HP-UX gives priority to /etc/logingroups, and uses the /etc/group file only if /etc/ logingroups does not exist. That can interfere with ora_setup and replication, because SharePlex installs groups into the /etc/group file. To resolve the problem, edit the /etc/ group file to make its entries identical to those in the /etc/logingroups file, then delete the etc/logingroups file.
CHAPTER 3 Preventing and Solving Replication Problems
301
Part 3: Solving configuration problems This part of the chapter reviews many common problems and solutions encountered during configuration activation. Tip: Many configuration problems can be prevented by using the verify config command in sp_ctrl before you activate a configuration or reactivate one containing new or changed objects. The verify config command reviews the configuration to help ensure that basic requirements for activation and replication have been satisfied. See Chapter 1 for more information about this and other SharePlex commands.
SharePlex cannot locate the configuration If SharePlex cannot locate the configuration that you want to activate, verify the directory where it resides. Configurations must reside in the config sub-directory of the SharePlex variable-data directory for SharePlex to find them. If you used the config.sql or build_config.sql script to create the configuration and the working directory was not the config sub-directory, the configuration was put in whatever working directory you were using. Locate the configuration and move it to the config sub-directory. When you create a configuration through sp_ctrl using the create config command, SharePlex automatically puts the configuration file in the config sub-directory. If you used that command and SharePlex still cannot find the file, check to see if someone moved or deleted the file. If you issue a configuration command, such as edit config filename, and you get an error on the file name, perhaps you typed it incorrectly. SharePlex configuration names are case-sensitive. CONFIG_1 is not the same as Config_1 or config_1. If you are confident that you entered the correct name, then the configuration file has been moved or deleted.
A configuration will not activate If SharePlex cannot activate one or more tables when default or live activation is used, it will continue to activate the other ones and display the names of the ones that failed in the SID_oconf##.log file or in the show activate command display. However, there are
302
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
several things can cause the entire activation of a configuration to fail. Common error messages for configuration activation problems are: Bad configuration file The Oracle sid SID specified in the config file is invalid. The following are causes and solutions for activation failures.
Reasons for complete activation failure The following are reasons for a complete activation failure.
Locks on tables If users are accessing any table in the configuration during default activation, or if a table is locked for any other reason, the entire activation will fail. Users can access tables only during live activation.
Invalid datasource or datasource syntax errors If SharePlex cannot find the source instance for the ORACLE_SID specified on the o.datasource line of the configuration, activation fails. Make sure the correct ORACLE_SID is used, and spell it the way it appears in the oratab file (UNIX), the Registry (Windows), or V$PARAMETER table (both platforms). In a SharePlex configuration, the ORACLE_SID is case sensitive. The spelling case (upper versus lower case or mixed case) for the ORACLE_SID in datasource:o.SID must be identical to the spelling in those locations.
Syntax errors Syntax is critical in SharePlex configurations. The following can cause activation failures:
• Syntax errors on individual lines of a configuration: These cause activation of the affected tables to fail. If a syntax error occurs throughout the file, such as omitting owner names, then the whole activation fails.
• Any syntax that is incorrect in an entry in the SHAREPLEX_PARTITION table when horizontally partitioned replication is being used. In addition, duplicate entries in the configuration will cause double posting. For help with configuration syntax, see Chapter 5 of the SharePlex Administrator’s Guide.
CHAPTER 3 Preventing and Solving Replication Problems
303
Oracle interaction problems If you receive the following error when you attempt to activate a configuration: “The Oracle sid ora10 specified in the config file is invalid,” and you know the SID is valid, it could be one of two things:
• Oracle setup (ora_setup on UNIX systems; OraSetup on Windows systems) was not run on the source system after you installed (or re-installed) SharePlex. Or...
• If this is a UNIX system, the oratab file is not where SharePlex expects it to be. To verify that ora_setup was run If ora_setup was not run, it means that an Oracle account was not established for SharePlex, so the activation process cannot log into Oracle. To determine whether or not ora_setup was performed, do any of the following:
• View the SP_ORD_LOGIN_ and SP_ORD_OWNER_ parameters. These are the internal SharePlex parameters for the SharePlex Oracle user and password. If there are values for these parameters, ora_setup was run. The password is encrypted. To view the parameters, issue the following command in sp_ctrl: sp_ctrl(sysA)> list param read Oracle Reader parameters: Parameter Name -----------------------------SP_ORD_CDA_LIMIT SP_ORD_DATE_MSG SP_ORD_DEBUG SP_ORD_DEBUG_FLAG SP_ORD_DELAY_RECORDS SP_ORD_DELAY_TIME SP_ORD_LDA_ARRAY_SIZE SP_ORD_LOG_FILESIZE SP_ORD_LOG_NUMFILES SP_ORD_LOGIN_O.ORA10 Default Value: SP_ORD_OWNER_O.ORA10 Default Value:
Actual Value ---------------------------5 0 0x00000000 0x00000000 200 3 5 50000000 3 4e9ad19fed4910ea81 judyd
Units Set At ------- -----cdas Restart Live bitflag Live bitflag Live records Live seconds Live logins Restart bytes Restart number Restart Unknown Unknown
• Query the database for tables beginning with "SHAREPLEX_." They are installed during ora_setup, so if they exist in the database, ora_setup was run. These tables are critical for activation and replication.
• Query the DBA_USERS view in the database to see if an Oracle account was established for SharePlex.
304
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
If the SharePlex tables and account do not exist, shut down SharePlex and follow the instructions for running ora_setup in the SharePlex Administrator’s Guide. To verify the oratab file SharePlex obtains its Oracle environment information from the oratab file on UNIX systems. SharePlex expects the oratab file to be in the /etc directory on HP-UX, IBM AIX systems, and in /var/opt/oracle on Sun Solaris systems. If the oratab file is in a different location, or if it contains an invalid ORACLE_SID, SharePlex generates an error during activation (“The Oracle sid ora10 specified in the config file is invalid”). On Sun systems, there sometimes are oratab files in the /etc directory as well as the /var/opt/oracle directory. Rename or delete all other oratab files except for the one in /var/opt/oracle.
Oracle password problems If there is an Oracle account and schema for SharePlex, but SharePlex is having trouble accessing Oracle, check to see if someone changed the password for SharePlex. If that is true, the SharePlex parameter database must be updated to reflect the new login information.
• To update the login information on a UNIX system, see either “Changing the SharePlex password on UNIX systems” or “Changing the SharePlex user (or user and password) on UNIX systems” in the SharePlex Administrator’s Guide, depending on how you want to update the SharePlex account.
• To update the login on Windows systems, shut down the SharePlex service, run OraSetup, then start SharePlex again. See “Running OraSetup on Windows systems” on
page 402 in the SharePlex Administrator’s Guide for instructions.
Insufficient DML locks If there are not enough DML locks for the source instance, activation will fail. Set the value to at least the current value plus the number of tables in the configuration. If you think you will add more tables to the configuration later, add extra locks.
Insufficient PROCESSES setting If Oracle Error 20 (ORA-00020 maximum number of processes (string) exceeded) is the cause of an activation failure, it is because Oracle ran out of resources on the source system to allow one or more threads to log on. You can resolve the problem by increasing the PROCESSES parameter in Oracle or by decreasing the number of activation threads you are using. The errors in the Event Log will look similar to the following:
CHAPTER 3 Preventing and Solving Replication Problems
305
Error 08-06-12 13:20:17.089485 2369 1 sp_tconf(rom) (for o.ora10 queue *) 1 - Error logging onto database 20 Error 08-06-12 13:20:17.641582 2369 1 Config compilation completed: datasrc - o.ora10; file - config_01192001 Error 08-06-12 13:20:17.641582 2369 1 Bad config file: file config_01192001; Error - Failed to build rowmap, sp_tconf exit. Error 08-06-12 13:20:17.881325 2369 1 Process exited sp_tconf (for o.ora10 queue *) [pid = 14083] - exit(1)
Inability to access the SYS tables SharePlex must be able to access the Data Dictionary in order to activate a configuration. If the activation process cannot access the SYS tables, you will see Event Log entries similar to the following, indicating Oracle error 00942. Error 08-06-12 13:20:17.089485 sp_tconf (for o.UALDEVA queue *) GetObjectNumAndType failed. Owner SPADMIN name DEMO_SRC rc 942 Error 08-06-12 13:20:17.641582 sp_tconf (for o.UALDEVA queue *) FindObjNumAndType failed on object SPADMIN.DEMO_SRC: ORA-00942: table or view does not exist. Error 08-06-12 13:20:17.881325 Bad config file: file - demo.UALDEVA; Failed to find object SPADMIN.DEMO_SRC due to ORA-00942: table or view does not exist. sp_tconf exit.
Check the O7_DICTIONARY_ACCESSIBILITY Oracle init.ora parameter and make sure it is set to TRUE. (This is the default.) The database must be restarted if the parameter is changed.
Deactivation followed too closely by activation In rare cases, if you activate a configuration too soon after a deactivation, the activation fails. Before you activate a new configuration, wait until you see the following message in the Event Log: Notice: sp_ordr (for o.ora10 queue o.ora10) Deactivated.
Non alphanumeric characters in the routing map Characters such as the dollar sign ($) can cause configuration activation to fail. Limit machine names and ORACLE_SIDs to letters and numbers. A dot (.), plus sign (+), and asterisk (*) are valid syntax components in a routing map when used to denote the target instance (o.), multiple target systems in a compound routing map (
[email protected] +
[email protected]), and named queues (sysA:QueueA*
[email protected]).
306
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Reasons individual objects fail to activate The following are reasons why individual objects fail to activate.
Locks on source tables If users are accessing a source table in the configuration during default activation, or if it is locked for any other reason, the activation for that table will fail. Tables can only be accessed during live activation.
Invalid objects Make sure you are attempting to replicate only objects supported by SharePlex. A list of supported and non-supported objects begins on page 54 in the SharePlex Administrator’s Guide.
Invalid target systems Verify that all target systems specified in the configuration are accessible through the replication network, and that their names are spelled correctly.
Syntax errors and misspelled words A misplaced space, a misspelled word, or a missing component causes activation of that table to fail. Examples are a missing .o in the routing path, a missing or misspelled owner name, or the lack of double quote marks around case-sensitive owners or table names. For help with configuration syntax, see Chapter 5 of the SharePlex Administrator’s Guide.
Activation takes too long The following can slow activation down significantly:
Locks on source tables If source tables are being accessed by users during live activation, SharePlex might have to wait to obtain the locks it needs in order to analyze them. SharePlex locks each table at a few stages during activation, and if a user already locked the table, SharePlex must wait until the lock is removed before it can continue the activation. This delays activation and replication of those tables.
CHAPTER 3 Preventing and Solving Replication Problems
307
Use the show activate command to view the activation status of each table. If SharePlex is waiting for a lock on a table, the command output displays a message alerting you. See Chapter 1 for more information about show activate and other SharePlex commands.
Explanation of configuration command errors The following are common error messages that you might encounter when executing configuration commands. Explanation of configuration error messages ACTIVATE CONFIG error messages
What to do
No datasource keyword at the beginning of the configuration file.
Make sure “datasource:” and “o.” were typed directly preceding the source ORACLE_SID on the first line, with no space between any of the items.
The data source name in the config file must be preceded by “o.”
The datasource specification in the configuration file must begin with “o.”.
The Oracle sid SID specified in the config file is invalid.
Check the oratab file (UNIX), the Registry (Windows), or V$PARAMETER table (both platforms) to make sure you specified the correct ORACLE_SID for the source instance. The SID is case-sensitive. If, for example, it is in upper case in those locations, it should be upper case in the configuration file.
Objectname may not be replicated because it's neither a table or a sequence. Sp_conf exit.
The object is probably one of the types of objects that SharePlex does not replicate. If that is not the cause, make sure the object owners and names are spelled correctly, including the spelling case if the item is case-sensitive.
line n, source object name (T_HFL_1) not of form OWNER.TABLE
See if the owner name is missing from one or more objects. The correct form is ownername.objectname.
308
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Explanation of configuration error messages (continued) syntax error in line n.
Review the syntax, making sure each component is on the correct line, and that no component is missing. Remember to list both the source and target objects, even if they have the same name. To enforce case-sensitivity, enclose the owner or table name within double quotes.
line n, bad routing spec (o.ora10)
Make sure the routing map is written correctly, for example
[email protected]. Note: SharePlex does not support system names that contain non-alphanumeric characters, such as an underscore ( _ ) or a dot (.).
File does not exist.
Make sure you correctly entered the name of the configuration you want to activate, including the case of the spelling. Configuration names are case-sensitive. To see a list of configurations on a system, use the list config command (see page 122).
sp_conf: oracle configuration failed
Verify that all required components have been specified correctly.
Attempt to run sp_conf when sp_conf is already active
SharePlex is indicating that the configuration is already in the process of being activated.
Login parameters not set in paramdb for database o.ora10
This indicates that ora_setup was not run for the source instance. The ora_setup program establishes SharePlex as an Oracle user and provides the privileges it needs to analyze objects for activation and perform the replication functions. It also creates the SharePlex internal tables that are vital to activation and replication. For more information about ora_setup, see the SharePlex Administrator’s Guide.
Currently involved in transaction.
Verify that no other process has locked the configured tables, such as users performing DML. SharePlex needs to lock those tables during activation and cannot do so when they are already locked.
WARNING, not all objects activated successfully. Check activation log.
If an activation succeeds, but one or more tables fails, SharePlex displays this message. To view the objects that failed to activate, look in the SID_oconf##.log log file, which resides in the log sub-directory in the SharePlex variable-data directory.
CHAPTER 3 Preventing and Solving Replication Problems
309
Explanation of configuration error messages (continued) CREATE CONFIG error messages
What to do
The parameter for ‘create config’ must be a new file name. or... Destination file exists file must not exist prior to operation.
The name you are giving this configuration already exists for another file. Use a different name. To see a list of configurations on a system, use the list config command (see page 122).
Couldn’t fork editor. or… Editor execution failed.
SharePlex failed to open the default text editor. Make sure the editor still exists on the system. The default editor that SharePlex uses is vi on UNIX systems and WordPad on Windows systems. To change the default text editor, see the SharePlex Administrator’s Guide.
COPY CONFIG error messages Destination file exists file must not exist prior to operation.
What to do The name you are giving this configuration already exists for another file. Use a different name. To see a list of configurations on a system, use the list config command (see page 122).
EDIT CONFIG error messages
What to do
Problems in reading or writing file used in edit -- command aborted.
Review the syntax of the configuration being edited to make sure it is correct; or check to see that the file is not corrupted.
Edit config file is not allowed for an active config file.
SharePlex does not allow editing of an active configuration. To make changes to entries in an active configuration, or to add objects, copy the configuration using the copy config command in sp_ctrl, then edit the copy using the edit config command. Activate the new configuration when you are ready. SharePlex only analyzes added and changed objects.
310
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Explanation of configuration error messages (continued) RENAME CONFIG error messages Destination file exists file must not exist prior to operation.
DEACTIVATE CONFIG error messages Deactivate/flush a nonactive datasource
What to do The new name you are giving this configuration already exists for another file. Use a different name. To see a list of configurations on a system, use the list config command (see page 122). What to do You are attempting to deactivate a configuration that is not active. To see a list of configurations on a system, and verify which ones are active, use the list config command (see page 122).
GENERAL configuration error messages
What to do
Invalid file name passed to command. or… File does not exist.
You could have misspelled the configuration name or used the wrong case. Verify the name and spelling, including the case, and enter it again. To see a list of configurations on a system, use the list config command (see page 122).
File access denied check file permissions.
You are not authorized to issue the command. To view a command’s authorization level, see its alphabetical listing in Chapter 1. To view your authorization level (according to the SharePlex user group to which you were assigned), use the authlevel command in sp_ctrl (see page 30).
CHAPTER 3 Preventing and Solving Replication Problems
311
Part 4: Solving synchronization problems This part of the chapter reviews the causes and solutions for common synchronization problems. If you try these solutions and are still having problems, contact Quest Technical Support. See “How to get help” on page 370 for more information.
How SharePlex reports out-of-sync conditions For all objects except those involved in transformation, SharePlex verifies that the source and target data are synchronized before posting the replicated data to the target instance.* When SharePlex determines that source and target data are different, it generates error conditions but continues to post the other data so that synchronization can be maintained for all other rows and tables. For more information about how SharePlex verifies synchronization, see “Understanding synchronization” on page 69 in the SharePlex Administrator’s Guide. Tip: You can change Post’s behavior to stop processing altogether when it detects an out-of-sync condition by changing the SP_OPO_OUT_OF_SYNC_SUSPEND parameter. See Chapter 2 for more information about SharePlex parameters.
When an out-of-sync condition occurs, the Post process logs a message in the Status Database (viewed with the show statusdb or show sync command in sp_ctrl and also to the Event Log (viewed using the show log command or by opening the file through the filesystem). Use these commands frequently to monitor for out-of-sync errors. The following is an example of how SharePlex reports an out-of-sync condition. sp_ctrl (irvspxu14:8567)> show sync Out Of Sync Status Database irvspxu14 Count Details ----- --------------------------------------------------------------------------------
* Synchronization is not verified when transformation is in use because transformation changes the target data, so the before and after images cannot be compared. Even if they could be compared, SharePlex could not do it because the transformation routine posts the data, not SharePlex.
312
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
3 Table "SCOTT"."TG_TEST1" out of sync for queue irvspxu14 since 16-Jun08 17:06:33 3 Table "SCOTT"."TG_TEST2" out of sync for queue irvspxu14 since 17-Jun08 15:47:58 1 Table "SCOTT"."TG_TEST3" out of sync for queue irvspxu14 since 17-Jun08 15:52:03
When data goes out of synchronization, SharePlex logs the offending SQL statements (the ones that should have been applied but failed) to the SID_errlog.sql file in the log sub-directory of the SharePlex variable-data directory. See page 324 for more information about this file. Important! If you see an out-of-sync message in the Status Database and in the Event Log, but there is no record in the SID_errlog.sql file for the transaction, do not ignore those messages. They could be associated with a ROLLBACK. Regardless of whether or not a transaction is rolled back, SharePlex still compares the pre-images of the source and target rows. If they are different, that indicates that the data is out of synchronization. Only when a transaction is committed on the source but fails on the target does SharePlex log it to the SID_errlog.sql file, to give you a record of the statement that should have been applied as a tool for problem solving and for manually applying the statement if appropriate. Rolled back statements are cancelled operations, and therefore not logged on the target.
Find and correct the problem before you resynchronize! If data is out-of-synchronization, determine why it happened before you resynchronize the data. Otherwise, the problem can repeat itself and result in more data going out of synchronization. Stop the Post process to prevent further errors, but do not stop Post if it could cause a backlog in the post queue with the potential to exceed free disk space. Even though the affected object(s) can become further out-of-sync, there is a procedure in the SharePlex Reference Guide for resynchronizing them. Meanwhile, SharePlex can continue to keep the unaffected objects synchronized. To determine the cause of the out-of-sync problem, view the Status Database and the Event Log. Once you correct the problem, routinely monitor replication for anything unusual. This can help you prevent small problems from becoming big ones.
CHAPTER 3 Preventing and Solving Replication Problems
313
How to detect and correct common out-of-sync conditions. The following are common ways in which data goes out of synchronization. In most cases, SharePlex detects out-of-sync conditions and returns an error message, but there are some situations where an out-of-sync condition is hidden, and SharePlex will not return an error.
Duplicate entries in the configuration file SharePlex activates configurations that contain duplicate entries, such as two entries with identical routes, but replication for that object returns out-of-sync errors. To find and eliminate duplicates, follow these steps: 1 Suspend all user access to the tables. 2 Open the configuration file in an ASCII text editor and search for the out-of-sync
tables to locate duplicates. Duplicates have the same source and target objects with identical routing maps. 3 If there are duplicates, run sp_ctrl on the source system and issue the copy config
command to copy the configuration. Do not deactivate the active configuration. The current activation continues replicating the tables that are synchronized. sp_ctrl(sysA)> copy config filename to newname 4 From sp_ctrl, issue the edit config command to open the copy in the text editor.
sp_ctrl(sysA)> edit config newname 5 Remove the duplicate entries, then save and close the file, but do not activate it. 6 Resynchronize the affected tables using one of the procedures outlined in “How to
resynchronize objects” on page 324. 7 From sp_ctrl, activate the new configuration. The activation should be brief because
SharePlex only has to analyze the changed tables. sp_ctrl(sysA)> activate config newname 8 Allow users to access the tables again.
314
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Inadequate or non-existing conflict resolution routines Conflict resolution procedures are required when users make DML changes to multiple databases that are being replicated to each other. This is known as peer-to-peer replication. SharePlex uses the conflict resolution procedures to determine which operation to post when the same data change is received from different systems, for example an UPDATE to the same row. To implement peer-to-peer replication, follow the instructions on page 193 in the SharePlex Administrator’s Guide.
Missing archive logs If the redo logs wrap before Capture can process the data it needs, the data can go out of synchronization if archived logging has been disabled or if the archive logs needed by Capture have been removed. (Normally, Capture would access the archive logs and continue replicating.)
• If archiving is not enabled, there are no archive logs for SharePlex to read. Data lost after the log wrap cannot be recovered. Enable archived logging, and resynchronize the data. Capture will not start until you do so.
• If SharePlex is several hundred logs behind, consider resynchronizing the data instead of restoring the logs. It might take less time than Capture would take to process the missing records from the archive logs. In addition, it eliminates the possibility that the capture queue could exceed free disk space while processing the archive logs. You can base your decision on the size of the redo logs and the number of tables being replicated, both of which determine how much information Capture must process. Also take into consideration how much latency the target data's users can tolerate.
• If archived logging is enabled (so that the required data is available) but the logs were removed, copy the appropriate archive logs back to the archived-log directory on the source system, or use the SP_OCT_ARCH_LOC parameter to point SharePlex to their location. (See page 236).
To restore the archive logs If you decide to restore the archive logs to resume replication, use the following procedure to determine the required archive logs. 1 Determine the sequence number that Capture needs to resume processing from. Cap-
ture stops when it encounters a log wrap and prints a message to the Event Log (event_log) containing the redo log sequence number it needs. You also can find out
CHAPTER 3 Preventing and Solving Replication Problems
315
this number by querying the SHAREPLEX_ACTID table and looking at the SEQNO column, as shown in the following example: SQL> select * from splex.shareplex_actid; ACTID SEQNO OFFSET AB_FLAG QUE_SEQ_NO_1 QUE_SEQ_NO_2 COMMAND ------ ------ ---------- -------- ------------ ------------- ---------14 114 9757200 0 672101000 0 2 Query the Oracle V$LOG_HISTORY table to find out when that sequence number
was archived, then copy the logs from that point forward to the source system. SQL> select * from V$LOG_HISTORY; RECID STAMP NEXT_CHANGE#
THREAD# SEQUENCE# FIRST_CHANGE# FIRST_TIM
------ ---------- ---------- ---------- ------------- --------- ----------111 402941650 2729548
1
111
2729501 14-JUL-00
112 402941737 2729633
1
112
2729548 14-JUL-00
113 402941930 2781791
1
113
2729633 14-JUL-00
114 402942019 2836155
1
114
2781791 14-JUL-00
115 402942106 2890539
1
115
2836155 14-JUL-00
3 See Chapter 4 of the SharePlex Administrator’s Guide for instructions for increasing
the size and number of the redo logs to prevent this from happening again.
Triggers on target objects If triggers fire on target objects, they cause the data to go out of synchronization. To determine if triggers are enabled on the target system, query the database. SQL> select * from user_triggers where table_owner=’owner’ and table_name=’name’;
316
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
If triggers have fired on the target system, the objects changed by the triggers are out of synchronization and must be resynchronized. See “How to resynchronize objects” on page 324 for instructions.
To disable the effects of triggers To disable the effects of triggers on target objects after the data is resynchronized, you can either:
• run the sp_add_trigger.sql wrapper script, which directs triggers to ignore the SharePlex Oracle user. Or...
• disable the triggers if they are not needed. See Chapter 4 of the SharePlex Administrator’s Guide for more information about configuring triggers for replication.
Cascading deletes on target objects Cascading deletes (ON DELETE CASCADE integrity constraint) on target objects cause replication to go out of synchronization because Post attempts to post the same DELETEs twice on the target, once when the constraints activate as the parent DELETE arrives from the source, and again as the replicated child (dependent) DELETEs arrive from the source. A message like this appears in the Event Log: 06/20/00 19:32 Error: sp_opst_mt.exe (for o.orcl-o.orcl queue ircfi06) 15033 - Failed to execute SQL on table: pub.EVENTS: ORA-02291: integrity constraint (.) violated - parent key not found. Note: ON DELETE CASCADE constraints report an out-of-sync condition that is not true. In SharePlex terminology, this is known as a “false out-of-sync”. The show sync command shows the table as out-of-sync whereas compare repair shows the table to be in sync.
Query dba_constraints to see if there are foreign key constraints on target tables. SQL> select * from dba_constraints where table_owner='owner' and table_name='name'; You can:
• Disable the ON DELETE CASCADE constraints, then re-synchronize the data. See “How to resynchronize objects” on page 324 for instructions.
CHAPTER 3 Preventing and Solving Replication Problems
317
Note that because SharePlex issued a duplicate DELETE, the database is still in synch. Use the compare table command to verify that the table is still in synch. If it is, you do not need to resynchronize the table. Or...
• Incorporate the cascading delete functionality into triggers, then run the sp_add_trigger.sql script to prevent the triggers from firing for the SharePlex user. For more information, see Chapter 12 of the SharePlex Administrator’s Guide.
LONG columns If a table has no primary or unique key, SharePlex builds a simulated key based on all of the columns except the LONG and LOB columns. It uses the simulated key to locate the target row to change. Synchronization problems occur when the LONG columns in the target rows contain unique values, but non-LONG columns in one row have the same values as those of another row. This results in multiple rows meeting the criteria for the simulated key. SharePlex could apply the UPDATE or DELETE to the wrong row without the error being detected, causing the table to go out of synchronization without an error message. If you can create a key from columns that ensure uniqueness on the target table(s), you can avoid this kind of out-of-sync condition. After you create the key, resynchronize and re-activate those objects so that SharePlex can update its object cache. If adding a primary or unique key is not possible (such as when packaged applications are in use), uniqueness of rows on the target system cannot be ensured.
Changes to keys If tables use sequences as keys, and a key value changed, check to see if it resulted in duplicity on the target system. If the new value already existed as a key in another row on the target system, it probably caused SharePlex to return a unique-key constraint violation and out-of-sync error. This can happen when you update values using an x +n formula, where n is an incremental increase. It is possible that one of the x +n values will equal an existing value. For more information about keys and replication, see Chapter 4 of the SharePlex Administrator’s Guide.
318
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
DDL changes SharePlex replicates some, but not all, DDL. For a list of supported DDLplease refer to the Release Notes that correspond to your version of SharePlex. Any of the following can cause replication to go out of synchronization. For future DDL changes, see the procedures recommended in Chapter 11 of the SharePlex Administrator’s Guide.
Configuration not reactivated after DDL changes If non-replicated DDL changes were made to the source objects and their associated target objects, it requires a configuration reactivation. SharePlex must re-analyze the objects to incorporate the changes. For example, if you reorganize a table, the object ID changes, and SharePlex needs to know the new one. To resolve the problem 1 Stop user access to the out-of-sync objects. 2 Resynchronize the affected objects. 3 Reactivate the configuration on the source system. 4 Allow users to access the objects again.
Supported DDL performed manually on the source and target systems If DDL that SharePlex supports was performed on the source system, and those same changes were performed on the target system, the tables are out-of-synchronization because SharePlex expects to perform the DDL. To restore synchronization 1 Stop the Post process (it might already be stopped).
sp_ctrl(sysB)> stop post 2 Alter the target table to undo the DDL changes. 3 Start Post and let SharePlex post the replicated DDL (which is still in the post
queue). sp_ctrl(sysB)> start post
CHAPTER 3 Preventing and Solving Replication Problems
319
DDL performed only on the target system If DDL was performed on the target system, but not on the source system, the source and target objects are no longer identical, so the data is out of synchronization. If the DDL is of a type supported by SharePlex, do the following: To restore synchronization 1 Stop the Post process.
sp_ctrl(sysB)> stop post 2 Alter the target table to undo the DDL. 3 Apply the DDL on the source system. 4 Start Post and let SharePlex post the replicated DDL (which is still in the post
queue). sp_ctrl(sysB)> start post If the DDL is of a type not supported by SharePlex, you need to resynchronize the objects. See “How to resynchronize objects” on page 324.
Non-supported DDL performed only on the source system If DDL that SharePlex does not support was performed on the source system, but not on the target system, the data is out of synchronization, and a resynchronization of those objects is required after the DDL is applied to the target objects. See “How to resynchronize objects” on page 324. For a current list of support and non-supported operations please refer to the Release Notes that correspond to your version of SharePlex. These are available from Quest Support at the SupportLink web site: http://support.quest.com.
Changes to column conditions in horizontally partitioned replication UPDATEs to columns in column conditions for horizontally partitioned replication can cause out-of-sync conditions. This happens in the following cases.
Row no longer satisfies the column condition If a column condition value is updated and the new value no longer satisfies the rowselection criteria, SharePlex performs the operation, but subsequent operations on that
320
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
row are not replicated. The tables are out of synchronization, but there are no errors from Post alerting you to it. For example: Column condition is “C1=A and C2=B”. 1 INSERT a row into the database. C1 and C2 values satisfy the column condition, so
the row is replicated to the target system. C1
C2
C3
C4
A
B
1
2
2 UPDATE ...set C1=B WHERE C1=A and C2=B 3 The change is replicated. Now the row does not satisfy the column condition, and
subsequent changes to data in the row are not replicated. C1
C2
C3
C4
B
B
1
2
Row that did not satisfy column condition now does If a row that does not satisfy the column condition is updated to satisfy the condition, subsequent operations on that row return out-of-sync errors. The reason is that the row was not replicated to the target system when it was inserted into the source database (it did not satisfy the column condition), but when it is updated to satisfy the condition, SharePlex replicates it. However, since the row never existed in the target database, Post cannot locate it, and it returns an error. For example: Column condition is “C1=A and C2=B”. 1 INSERT a row into the database. C1 and C2 values do not satisfy the column condi-
tion, so the row is not replicated to the target system. C1
C2
C3
C4
B
B
1
2
2 UPDATE ...set C1=A WHERE C1=B and C2=B 3 Now the row satisfies the column condition, so SharePlex replicates it, but Post can-
not locate the corresponding row on the target (it was never there) and returns an outof-sync error.
CHAPTER 3 Preventing and Solving Replication Problems
321
Resolving the out-of-sync condition Depending on the nature of the column conditions, you can use the compare table command to resynchronize rows that were affected by such changes. To avoid out-of-sync conditions when using horizontally partitioned replication, the columns used for a column condition should contain values that will not change (such as PRIMARY or UNIQUE key columns), since those values determine whether or not a row is replicated. If there will be updates to values of columns in column conditions, you can set the SP_ORD_HP_IN_SYNC parameter to detect the results of those updates and compensate for them. For more information about this parameter, see page 249.
Not re-activating after configuration changes If a table was added to the configuration, but the configuration was not reactivated, operations on that table are not being replicated. Resynchronize the affected tables, then reactivate the configuration so that SharePlex can update its object cache. For instructions on adding tables to active configurations, see Chapter 7 of the SharePlex Administrator’s Guide.
Incorrect running of ora_cleansp If ora_cleansp was run on some, but not all, systems associated with an active configuration, SharePlex perceives an out-of-sync condition. To determine whether or not ora_cleansp was run on all systems, or to see if the configuration was activated before ora_cleansp was completed on all systems, view the user issued commands in the Event Log on each system. The log tells you if and when ora_cleansp was run on each system. It also tells you if and when the configuration was activated. You can compare the times for those events to determine what happened. If ora_cleansp was not completed on all replication systems for this configuration, run it on all systems. Because ora_cleansp removes replication queues and processes and deactivates the configuration, you must perform initial synchronization again. See Chapter 7 of the SharePlex Administrator’s Guide for instructions on synchronizing data.
322
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Incorrect resynchronization procedure If resynchronization was performed for any objects, make sure it was done properly. Resynchronizing is different than initial synchronization if users were accessing the tables. Try resynchronizing according to the directions in “How to resynchronize objects” on page 324.
Lack of disk space Data goes out of synchronization if user transactions continue when SharePlex does not have enough room to accommodate them in the queues. This can happen if:
• the network or target system was unavailable and too much data accumulated in the export queue.
• the target Oracle instance was unavailable and too much data accumulated in the Post queue.
• the redo logs wrapped and Capture lost pace with Oracle as it processed the archive logs, causing data to accumulate in the capture queue.
• a SharePlex process was stopped, but not restarted. • the flush command was issued, but Post was not started again. If a queue disk runs out of disk space, you may see messages similar to this in the Event Log: 11/22/07 14:14 System call error: No space left on device bu_wt.write [sp_mport(que)/1937472] 11/22/07 14:14 System call error: No space left on device bu_rls.bu_wt [sp_mport(que)/1937472] 11/22/07 14:14 Error: que_BUFWRTERR: Error writing buffer to file que_writecommit(irvspxuz+P+o.a920a64z-o.a102a64z) [sp_mport(rim)/1937472] 11/22/07 14:14 Error: sp_mport: rim_writecommit failed 30 - exiting [sp_mport/ 1937472] 11/22/07 14:14 Process exited sp_mport (from irvspxuz.domain.com queue irvspxuz) [pid = 1937472] - exit(1)
If a queue disk is almost out of free space, you might be able to add disk space without having to resynchronize the data. Follow these steps: 1 Stop SharePlex on the affected system. 2 Add more disk space. 3 Start SharePlex.
CHAPTER 3 Preventing and Solving Replication Problems
323
4 View the Event Log and look for the messages queue recovery started and queue recovery complete.
• If both messages are there, SharePlex resumes processing where it stopped. If it does, SharePlex has recovered. However, if your applications are generating high volumes of transactions, there are probably numerous messages backlogged in the queues that must be processed and posted using standard SQL. Depending on the nature of the transactions, how well the target database and the Post process are tuned, and your tolerance for latency, it might be more practical to resynchronize the data instead of waiting for replication to regain parity with Oracle's processing.
• If one or more queues is corrupted, the Event Log records a message like this: Bad header magic... or peekahead failure. Or, you will see the message queue recovery started, but you will not see the queue recovery complete message that signifies successful queue recovery. In this case, you must run ora_cleansp to restore
replication to an initial state after you add disk space, then resynchronize and reactivate. Use the following procedure.
To restore synchronization 1 Run ora_cleansp to restore the variable-data directory and SharePlex tables. See
Chapter 12 of the SharePlex Administrator’s Guide for instructions. 2 If necessary, refer to the guidelines in “Disk space for queue files” on page 106 of the
SharePlex Administrator’s Guide for assistance with determining the space requirements for the queue files. 3 Synchronize the data using your method of choice and reactivate the configuration.
See Chapter 7 of the SharePlex Administrator’s Guide for instructions. 4 You can prevent this problem from re-occurring by using the SharePlex monitoring
utilities to start unattended monitoring of key replication events, including queue volume alerts. See Chapter 9 of the SharePlex Administrator’s Guide for more information.
System crash If the source or target system fails, SharePlex stores the data in the queues and resumes replication when the system has been recovered. If either system panics, however, the SharePlex queues can be corrupted, and data in them can be lost. This requires a resynchronization. To avoid queue corruption during system panic, you can also use the
324
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
parameter SP_QUE_SYNC. See “SP_QUE_SYNC” on page 270 in the SharePlex Reference Guide for more information.
How to resynchronize objects The following instructions help you decide how to resynchronize out-of-sync objects.
• If only a few tables are out of synchronization, and they are not large, you can use the compare table command in sp_ctrl to see how many rows are out-of-sync in each one. If the number of out-of-sync rows is small, you can run the compare table command again with the [repair] option to resynchronize them. For more information, see page 55.
• As an alternative to the compare table command, you can manually patch the tables after the cause of the problem is corrected, using the SQL statement(s) logged in the SID_errlog.sql file. Instructions are in the following section entitled “Manually patching out-of-sync tables.”
• If the number of out-of-sync objects is large, it might take less time to re-synchronize the databases than it will to use the compare table or compare config command or repair them manually. You can resynchronize by: --copying the tables (see page 324). --using the transportable tablespace feature (Oracle 9i and later) (see page 326). --using an Oracle hot backup with the reconcile command (see page 327).
Manually patching out-of-sync tables It is sometimes possible to manually repair out-of-sync tables if the number of synchronization errors is small. When the Post process detects that source and target tables are out-of-sync, it posts the synchronized transactions normally, but it logs the SQL statement and data for the out-of-sync transactions to an error file called SID_errlog.sql. (SID is the ORACLE_SID for the target instance.) The file entries look similar to this example: -- Host (irvlabua) Sid (al920u64) -- session 2, 1 error ---- [1] Tue Dec 11 13:31:32 2007 -- redolog seq#/offset 26622/26980368
CHAPTER 3 Preventing and Solving Replication Problems
325
-- redolog timestamp 641050290 (12/11/07 13:31:30) -- original rowid AAE0m8AAWAAAAFEAAA -- -- NOT FOUND delete from “SP_5”.”QA_LOB_DISABLE_INROW” t where rownum = 1 and “KEY”='01'; SharePlex creates this file in the log sub-directory of the variable-data directory on the
target system when a synchronization error occurs. Try manually applying those SQL statements to the target table. Since you are bypassing Post’s comparison process, the operations should succeed. Follow these steps: 1 Stop user access to the affected source table. 2 On the target system, open the SID_errlog.sql file. 3 Using SQL*Plus, manually apply the logged SQL statement(s) to the target table.
The SQL statement should succeed assuming the structure of the table has not changed.
Restoring synchronization by copying the source tables This procedure restores synchronization to out-of-sync target objects by applying a copy of the source objects. You only need to resynchronize the objects that are out of synchronization, so users can continue accessing all other objects. 1 Make sure sp_cop is running on the source and target systems. 2 [IF NECESSARY] On the target system, issue the show sync command to identify the
tables that are out of synchronization. This tells you the name of the tables that are out of sync. sp_ctrl(sysB)> show sync 3 On the source system, stop activity for the out-of-sync tables. 4 On the source system, issue the flush command in sp_ctrl. For datasource, substitute
o. followed by the ORACLE_SID of the source instance. sp_ctrl(sysA)> flush o.datasource 5 On the source system, copy the tables. 6 On the source system, allow users back onto the source tables.
326
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
7 On the target system, verify that the Post process has stopped. Keep issuing the
command until it shows that Post has stopped. sp_ctrl(sysB)> status 8 On the target system, restore the tables. 9 On the target system, address all triggers, referential integrity constraints and check
constraints according to the requirements of your replication strategy. See “Shared Semaphore Segment Resources” on page 73 of the SharePlex Administrator’s Guide for more information. 10 On the target system, clear the out-of-sync messages from the Status Database. 1 Determine each message’s status ID number by viewing the Status Database.
sp_ctrl(sysB)> show statusdb detail 2 Clear each message with the following command.
sp_ctrl(sysB)> clear status statusID 11 On the target system, start the Post process.
sp_ctrl(sysB)> start post [for datasource-datadest]
Resynchronizing using Oracle’s transportable tablespace feature (Oracle 9i and later) The transportable tablespace feature enables you to quickly resynchronize numerous out-of-sync objects with minimal downtime. To use the transportable tablespace feature, follow the instructions in the Oracle documentation for generating a tablespace set, moving the tablespace set to the target database, and plugging the set into the database. The following instructions contain steps only for using this feature to resynchronize data. It assumes familiarity with using the transportable tablespace feature. 1 On the source system, set the source tablespace to READ ONLY (alter tablespace
TRANS read only;). 2 On the source system, issue the flush command in sp_ctrl. For datasource, substitute
o. followed by the ORACLE_SID of the source instance. sp_ctrl(sysA)> flush o.datasource 3 Export the metadata to an export file according to Oracle’s instructions.
CHAPTER 3 Preventing and Solving Replication Problems
327
4 When the export is finished, copy the datafiles to a secondary location on the source
system. This minimizes the impact on the source database of copying the files to the target system. 5 On the source system, set the source tablespace(s) back to read/write mode (alter
Tablespace TRANS read write;) 6 On the target system, drop the existing datafiles and tablespaces from the target
database so that the copied files can be applied. 7 Copy the files from the secondary location on the source system to the target sys-
tem. 8 On the target system, use the Oracle import utility to import the metadata and the
tablespace definitions. 9 On the target system, set the tablespace(s) to read/write mode. Note: SharePlex must be the only user permitted to have write access to the target
tables, unless you are using peer-to-peer replication. 10 On the target system, start the Post process.
sp_ctrl(sysB)> start post
Resynchronization using an Oracle hot backup on an active database When you use an Oracle hot backup, live activation, and the reconcile command to resynchronize a target instance, users can continue to access the production data while the backup is made and applied.
Cautions To resynchronize centralized reporting, such as a data warehouse, you cannot use a hot backup from all source systems. One backup would override the data from the previous one. You can use a hot backup of one of the source instances to establish the target instance, and then use another method such as export/import or transportable tablespaces to copy the objects from the other instances. To resynchronize peer-to-peer replication, you must quiet all of the secondary source systems for the duration of this procedure. Move all users to the primary system, and
328
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
then follow the procedure. After the procedure has been performed on all of the secondary systems, users can resume activity on them.
To resynchronize with a hot backup 1 On the target system, stop the Post process. This allows the replicated data to accu-
mulate in the post queue until the target instance has been recovered and reconciled. sp_ctrl(sysB)> stop post 2 Run the Oracle hot backup on the source system. 3 Change to the bin sub-directory of the SharePlex product directory, and start sp_ctrl
on the source and target systems. 4 Verify that sp_cop, sp_ctrl and all SharePlex processes (Capture, Read, Export,
Import, Post) are running on both the source and target systems. sp_ctrl(sysA)> status sp_ctrl(sysB)> status 5 Switch log files on the source system. A To recover the database to a sequence number, make a note of the highest
archive-log sequence number. svrmgrl> alter system switch logfile; B To recover the database to a Oracle System Change Number (SCN), pick an
SCN to recover to on the target database. 6 Recover the target database from the hot backup: A If recovering to a sequence number, recover the database from the hot backup
using the UNTIL CANCEL option in the RECOVER clause, and cancel the recovery after Oracle has fully applied the log from step 5. B If recovering to a SCN, recover the database from the hot backup using the
UNTIL CHANGE option in the RECOVER clause, and cancel the recovery after Oracle has applied the logs matching the SCN from step 9. 7 Open the database with the RESETLOGS option. 8 On the target system, issue the reconcile command. If you are using named post queues, issue the command for each one. Issue the qstatus command if you are
unsure of the queue name.
CHAPTER 3 Preventing and Solving Replication Problems
329
A If recovering to a sequence number, substitute the sequence number of the log
that you noted in step 5. sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest seq sequence_number For example: if you are replicating from instance oraA on SysA to oraA on SysB, the syntax would be: sp_ctrl(sysB)> reconcile queue SysA for o.oraA-o.oraA seq 1234 B If recovering to a SCN, substitute the SCN that you noted in step 5.
sp_ctrl(sysB)> reconcile queue queuename for datasource-datadest scn scn_number For example: if you are replicating from instance oraA on SysA to oraA on SysB, the syntax would be: sp_ctrl(sysB)> reconcile queue SysA for o.oraA-o.oraA scn 0123456789 The reconcile process retains control of sp_ctrl until it is finished, and then the sp_ctrl prompt returns. 9 On the target system, log onto SQL*Plus as the Oracle user for SharePlex, and run the cleanup.sql script located in the bin sub-directory of the SharePlex product
directory. This script truncates and updates the SharePlex tables, which are owned by the SharePlex user. If you are running multiple instances of sp_cop with multiple variable-data directories, there is a SharePlex Oracle user for each one. Make sure you run this script as the SharePlex user that owns the tables you want to restore. The script prompts you for the SharePlex user name and password. SQL> @/productdir/bin/cleanup.sql 10 Disable or modify the following on the target system according to your replication
strategy:
• • • • •
triggers foreign key constraints cascading delete constraints check constraints scheduled jobs that perform DML
11 Start the Post process on the target system. The two instances are now in synchroni-
zation, and SharePlex will continue replicating. sp_ctrl(sysB)> start post
330
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Part 5: Solving replication problems This part of the chapter reviews common problems that you could encounter while replication is underway. You should issue the status, show statusdb and qstatus commands frequently to:
• make sure all processes are running. • to see if SharePlex has generated replication errors. • to make certain the queues are not consuming too much disk space or that message accumulation is causing data latency. You can also use the show log command to view the Event Log. See “Tools for preventing and solving problems” on page 286 for more information about monitoring replication. #
Replication is too slow Many factors can cause replication to be slow. The following are common general and Post-related causes and solutions.
General causes of slow replication The following are general causes of slow replication. For Post-related causes, see “Postrelated causes of slow replication” on page 333.
Excessive chaining Excessive chaining affects several aspects of replication for the following reasons:
• It reduces the performance of the source database because Oracle must read multiple blocks for a single row.
• It reduces Post performance on the target system because block fragmentation in the database slows the writing of Post's SQL statements. Reorganizing chained tables to eliminate chaining makes replication faster.
CHAPTER 3 Preventing and Solving Replication Problems
331
Redo log configuration Capture reads archive logs if the redo logs wrap before Capture is finished with them, but it slows down replication and consumes significant disk space. Ideally, the redo logs should be configured so that SharePlex can avoid using the archive logs. To determine if Capture is reading the archive logs 1 Determine the log that SharePlex is processing by querying the
SHAREPLEX_ACTID table. SQL> select seqno from splex.shareplex_actid 2 Determine the log that Oracle is writing to by querying Oracle's V$LOG table.
SQL> select sequence# from v$log where status='CURRENT' 3 Subtract the seqno value from the sequence# value. This reveals how many logs
Capture lags behind Oracle. 4 Subtract the number of online redo logs from that value. If the number is negative,
SharePlex is processing archive logs. For example, if you have 10 redo logs and SharePlex is 11 logs behind, it is processing archive logs. To configure redo logs for replication Ensure that the online redo logs are large and numerous enough to minimize processing from the archive logs. At minimum, there should be enough redo log capacity to hold several hours worth of data without wrapping. To calculate this value, use the following formula. [number of online redo logs] - [number of switches in 2 hours] >/= 0 Oracle guidelines recommend allowing for 24 hours. The amount of disk space required to store 24 hours worth of archive logs can give you a good estimate of the requirements for the redo logs. For further information about redo log size and replicating from the archive logs, see the SharePlex Administrator’s Guide.
Tablespace in hot backup mode Tablespaces in hot backup mode on the source system affect replication. User changes are written to both the rollback segments and the redo logs, with the entire block containing the changes being written to the redo log. If the database is built with 8k blocks, there is a high amount of redo activity for SharePlex to manage.
332
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Process prioritization If Capture, Read, or both slow down during hot backups or other Oracle-intensive operations, view the process-priority settings on the system to determine if SharePlex can be assigned more resources. Ideally, the SharePlex priority should match Oracle's priority.
Latency You can reduce the latency of data between the source and target systems by changing the setting of the SP_ORD_DELAY_RECORDS parameter. For more information about this parameter, see page 247.
Veritas Quick I/O Because of the way Veritas Quick I/O caches disk information, SharePlex cannot support replication if Quick I/O is used for the redo and archive logs. SharePlex supports the use of Quick I/O for the datafiles.
Network issues If data is not being transmitted to a target system, make sure that Export is running on the source system and Import is running on the target system. It is possible that a user at one location stopped a process without the knowledge of users in other locations. If Export is slow to send data across a WAN to the target system, the reason is usually a network problem. Use a network diagnostic tool to monitor the number of TCP/IP packet retransmissions. If that value is high, and you can resolve the problem, Export's performance should improve. There are two parameters for tuning SharePlex in a WAN environment: SP_COP_SO_RCVBUF (set for the target machine) SP_XPT_SO_SNDBUF (set for the source machine) Those parameters dictate the size of the packet that is sent across the network. If SharePlex is replicating across a WAN, and the export queue is continually backlogged, try adjusting those parameters. If transfer still is slow, try increasing the SP_IMP_WCMT_MSGCNT and SP_IMP_WCMT_TIMEOUT parameters on the target system. Set SP_IMP_WCMT_MSGCNT to at least 10,000. For more information about these parameters, see the parameter descriptions starting on page 255.
CHAPTER 3 Preventing and Solving Replication Problems
333
Parameter settings Some SharePlex parameters, when changed from their default settings, can inhibit replication performance. For example, SP_QUE_SYNC slows performance because it flushes all writes to the queues to disk at the time of the write, and the SP_ORD_HP_IN_SYNC parameter causes SharePlex to use all columns as a key for tables using horizontally partitioned replication. These parameters are necessary for certain situations, and their value is weighed against performance issues. To determine if any parameter settings are responsible for reduced performance, issue the list param modified command and view parameters that have user-defined settings, then review their documentation. Parameter descriptions begin on page 234.
Post-related causes of slow replication There are a number of things that cause the Post process to slow down. SharePlex generates the sp_opst_mt - operation taking too long message when it takes more than five seconds to apply a SQL statement to the target instance. Often it only takes one table to cause a bottleneck. Use the show sql or show post command to find out which table Post is processing, and then check for the following.
Full table scans The lack of an index or unique key on a target table causes SharePlex to perform full table scans. This slows the Post process significantly, especially if there are LONG columns or chained rows, or both. Add an index or key to such tables if possible. To ensure that Oracle uses the correct index, you can use the hints file feature of SharePlex. As an alternative to adding a key, you can specify a key definition based on one or more columns that ensure uniqueness. For more information about creating a key definition, see Chapter 5 of the SharePlex Administrator’s Guide. If these suggestions are not practical in your environment, you can set the Oracle DB_FILE_MULTIBLOCK_READ_COUNT parameter to the maximum number of blocks that can be read in one I/O request. This is defined by the system setting MAX_IO_SIZE/DB_BLOCK_SIZE. You can increase the DB_BLOCK_BUFFERS parameter as well.
Bitmap indices on target tables If Post is slow, check to see if there are bitmap indices on the target table(s) and, if so, what type of operations are being performed. Bitmap indices are beneficial for queries, but they slow down Post's DML operations.
334
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
When Oracle adds, updates or deletes a bitmap entry, it effectively locks all the rows associated with the bitmap segment, which can contain references to hundreds of rows. Consequently, changes made by different Post sessions (there is a Post session for every session on the source system) can block each other if rows they are processing update bitmap entries in the same bitmap segment. To proceed, Post must detect and resolve the blocking, which results in delays if the number of locks is high. In general, frequent inserts by multiple concurrent sessions into a table with bitmap indices will incur lock conflicts, but random update and delete activity on such a table will not.
Disk I/O bottleneck Disk I/O bottlenecks on the target system are the most common cause of slow Post performance. Post can spend a high percentage of its time waiting for Oracle to commit data. The effect is worse when there is a Capture process reading from the same log device in peer-to-peer replication. Disk I/O is the nature of the database environment. You can reduce the bottleneck by locating the redo logs on faster hard drives or on a solid-state drive. Oracle8 and later allow multiple I/O processes to write to the redo log, and that can be enabled with certain I/O configurations to alleviate the problem.
High number of buffer gets Review any table with SQL statements that cause a high number of buffer gets. There should only be two to four buffer gets on an index, depending on size and whether or not it is a unique index. If there are more buffer gets than that, the index probably needs to be rebuilt. You need not reactivate the configuration after you rebuild an index.
Oracle write-rate bottlenecks One buffer writer writes all dirty Oracle blocks to disk. Whenever that buffer writer process wakes up to write, it locks portions of shared memory and, in effect, blocks the processes that are either modifying or reading data blocks — including the Post process.
Transaction size Normally, Post performs an internal read/release after it receives each COMMIT, which means it purges that data from the queue as part of the checkpoint recovery process. For smaller transactions, this can cause excessive I/O on the target system and hinder the Post process. If most of your transactions are small, you can set the SP_OPO_READRELEASE_INTERVAL parameter to tell Post to read/release only after a certain number of messages have been processed, instead of after every COMMIT. See Chapter 2 for more information about this parameter.
CHAPTER 3 Preventing and Solving Replication Problems
335
Sequence replication Verify that replicating sequences are cached. If they are not, they can represent a large but unnecessary portion of replication volume. If replicated sequences are part of a key, replicate the tables that contain those keys, and remove the sequences from the replication configuration. You should see significant performance improvement.
Low ulimit (UNIX systems) The following error in the Event Log means that the system file descriptors setting on the target system needs to be increased: Error 07-24-08 12:11:40.360226 8693 12345 Poster error: /var/quest/ vardir/log/event_log: Too many open files (posting from ora102, queue prodsys, to ora10b) To ensure fast, problem-free posting to the target database, SharePlex requires a hard limit system file descriptors setting of 1024 or as close to that value as your system resources can accommodate.
Compare process locks A compare table or compare config command issued with a repair option locks the target table throughout the repair process. This could block Post if Post tries to apply data to the table being repaired. If you do not want Post to wait for a repair process to finish, you can kill the compare process. For information about how to kill a compare process, see “Solving compare command errors” on page 362. To avoid issues with locks caused by repair processes, consider running the repairs during non-peak hours.
Difference in Capture and Post speed SharePlex reads and processes records from the redo logs faster than it can post those operations to the target database with standard SQL statements. See Chapters 4 and 6 in the SharePlex Administrator’s Guide for information about optimizing Post’s performance.
Full archived log directory If Post appears stalled and will not shut down normally, but the only error in the Event Log is sp_opst_mt - operation taking too long, it could be that the archived log directory on the target system is full. If so, then Oracle cannot create new logs, and it sus-
336
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
pends processing. Post stalls because it is waiting for Oracle. To correct the problem, move some of the old archive logs to another device, or delete them to make room for new ones.
Capture stopped If Capture is stopped, issue the status command in sp_ctrl to verify whether or not it was stopped by a SharePlex user. If it was, find out why and make certain that it is not stopped for too long. If Capture was not stopped by a user, it could have stopped for any of the following reasons.
archive logs not available When Capture detects a log wrap and the archive logs are not available, Capture stops and returns a “Log wrap detected” error. It waits a certain amount of time and then starts again, continuing this process until the logs are restored. To restore replication, uncompress (if applicable) and restore the archive logs. See “Missing archive logs” on page 314 for instructions for restoring archive logs. If the archive logs are unavailable, Capture stays stopped, and you must resynchronize the data.
Compressed archive logs Capture cannot read compressed archive logs. If Capture stopped because the log it needs is compressed, uncompress it and restore the subsequent logs so that Capture can process them. To restore the archive logs, see the instructions in “Missing archive logs” on page 314. To prevent errors, do not compress the archive logs until SharePlex is finished processing them. To determine the current log for SharePlex, issue the show capture command with the [detail] option in sp_ctrl on the source system. You can compress any logs that were generated prior to the current one for SharePlex.
archive logs in unexpected location Capture stops if it cannot locate the archive logs it needs. When the redo logs wrap, Capture looks for the archives in Oracle’s archived-log list, but if the logs cannot be found, Capture looks in the directory or directories specified by the
CHAPTER 3 Preventing and Solving Replication Problems
337
SP_OCT_ARCH_LOC parameter. If you are storing the archive logs in a location other than the normal Oracle location, make sure this parameter is set to the full path name of the directory containing the archive logs. For more information about SP_OCT_ARCH_LOC, see page 236.
No access to the redo logs Capture stops when it cannot read or find the logs, then it tries to read the log again. If you know the archive logs are available, find out if someone changed permissions denying SharePlex the ability to read the redo logs.
No access to the variable-data directory Capture stops if it is unable to write to the SharePlex logs because of restrictive permissions on the state sub-directory in the variable-data directory, or if there are space restrictions in that directory. Verify the permissions and space for the variable-data directory.
Corrupted archive logs Capture stops due to the error “a portion of redo logs could not be parsed...”. This error occurs because of corrupted archive logs.
Post stopped If Post stops, issue the status command in sp_ctrl to find out why.
• An idle status means there is no data in the post queue to post. • A stopped by user status means that a SharePlex user stopped the Post process. To find out which user is responsible, view the user issued commands in the Event Log.
• A stopped due to error status means a replication or Oracle error caused Post to stop. The following are some potential causes for Post to stop without user intervention.
338
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Oracle errors Post stops for Oracle errors that can be corrected, enabling you to fix the problem so that the data in the object remains synchronized. The errors and the faulty SQL statement are logged to the SID_errlog.sql file (SID is the target ORACLE_SID) in the log sub-directory of the variable-data directory on the target system. Use this file to help you correct the problem, then start Post again. Posting resumes from the point where it stopped. For more information about the SID_errlog.sql file, see “Manually patching out-of-sync tables” on page 324. Other errors, such as out-of-sync conditions, cannot be corrected. In that case, SharePlex reports the error to the Event Log, writes the error and SQL statement to the SID_errlog.sql file, and continues processing. Sometimes, errors that cannot be corrected cause Post to stop. If you have accounted for those errors, you can set the SP_OPO_CONT_ON_ERR parameter to tell SharePlex to ignore those errors and continue posting. See page 257 for more information about this parameter.
Locks on target tables If a target table is locked, the Post process cannot apply a SQL statement and generates an error message: Currently involved in a transaction. This message could mean that a user, application, or job is accessing the table and might have caused an out-of-sync condition. Or, it could mean that a compare config or compare table command has locked the table to perform a repair. To find out if the table is locked, check the V$LOCK system statistics table, and resolve the situation accordingly. You might have to resynchronize the data if DML was performed on the table. See “How to resynchronize objects” on page 324.
No more open cursors If you see the following error, Post has exceeded the available open cursors. Warning: sp_opst_mt (for o.oracle-o.oracle queue oracle) Post has opened number cursors. No more available cursors! Exiting Post requires a certain number of open cursors to the target database. To view the OPEN_CURSORS value, query the database using the following SQL statement: select value from V$PARAMETER where name = 'open_cursors' ;
CHAPTER 3 Preventing and Solving Replication Problems
339
To determine an adequate OPEN_CURSORS value for SharePlex, see page 97 of the SharePlex Administrator’s Guide.
Oracle login terminates If Post stops because of an error, or if it is purposely or inadvertently killed, its login to Oracle terminates. If the login terminates in the middle of a transaction, Oracle rolls back that transaction because it did not receive a COMMIT. That is not a problem, because the post queue retains copies of all operations for a transaction until the COMMIT has been applied to the target database. When you restart Post, it checks for the last committed transaction and resumes applying everything after that point, including operations from the incomplete transaction. If Post receives a ROLLBACK instead of a COMMIT, it rolls back all operations for that transaction.
Deactivating when there are named export queues When you are using named export queues, and you deactivate the configuration, Post could stop with the following error instead of posting the remaining data from the queues: sp_opst_mt (for o.qa920-o.qa920 queue q5) 15007 - Can't open poster queue que_NOEXIST: Queue does not exist. To start Post and finish replication, shut down SharePlex, then start it again.
Queue name is too long Post exits if a queue name is too long. If you are using named queues, make certain the name assigned in the configuration file is no longer than 15 characters.
The post queue is not emptying If it seems like the post queue is not emptying, issue the status command to make sure Post is running. If Post is running, the delay in the queue could be caused by large operations for which there has not yet been a COMMIT. To allow for rollbacks and data recovery, SharePlex retains data in the post queue until it receives the COMMIT.
340
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
View the post queue with the qstatus command. If the value in the Backlog (messages) field remains constant or is shrinking, while the value in the Number of messages field is increasing, Post is waiting for a COMMIT before releasing the data. Use the show post detail command to verify that Post is processing transactions normally. If possible, set the COMMIT point for your application to 500 to generate smaller SQL statements for SharePlex to process. Also, consider creating a configuration that uses named post queues which isolate tables known for long transactions. See Chapter 5 of the SharePlex Administrator’s Guide for instructions on creating named post queues. If the accumulation of messages in the Post queue is threatening to cause disk space issues, see “SharePlex is running out of disk space” on page 345 for help with controlling when SharePlex sends the messages to the queue.
There is an extra import process If there is an extra Import process on the target system (possibly without a PID), or if a compare process does not start on the target system, it could be caused by a non-alphanumeric character, such as a dot (.) or an underscore (_), in the host name. SharePlex supports only host names that contain letters or numbers. If any host names in the replication network contain a dot or any other non-alphanumeric character, 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. For example, in the following sample /etc/hosts file, the alias sys1 was created for host sys1.company.com. 123.456.789.10
sys1.company.com
sys1
CHAPTER 3 Preventing and Solving Replication Problems
341
There is a “failure to write and open queue” error If there is a sequence of messages in the Event Log similar to the following, stop and start sp_cop. 1 08-06-12 13:20:17.089485 2384 1 sp_ordr(rim) (for o.user queue o.user) Error opening output queue rv=9 que_open(-,writeuser+X,0x0a02d364+PR+o.user+sp_ordr+o.user) Notice 08-06-12 13:20:17.089485 2384 1 sp_ordr (for o.user queue o.user) data route to a02d364.48.7e failed err=100 Error 08-06-12 13:20:17.089485 2384 1 sp_ordr (for o.user queue o.user) 11004 - sp_ordr failure writing to queue(s) Notice 08-06-12 13:20:17.089485 2384 1 sp_ordr (for o.user queue o.user) Exit sp_ordr to retry rim-write. Info 08-06-12 13:20:17.089485 2384 1 Process exited sp_ordr (for o.user queue o.user) [pid = 8183] - exit(1)
The queues are corrupted If a system fails, one or more SharePlex queues can become corrupted, and there will be errors reading from and writing to them. In that case, the purge config and abort config commands cannot be used, because they rely on the queues to operate. To resolve this problem, use the delete queue command in sp_ctrl. For more information about this command, see page 104. Note that queue corruption results in total data loss. You can contact Quest Technical Support to discuss salvaging the data if the data is important.
The post queue seems too large If the size of the post queue seems too large relative to the number of messages it contains, that is not unusual. The SharePlex post queue actually consists of a number of sub-queues, each approximately corresponding to a user session on the source system. A sub-queue can have one or more files associated with it, each with a default size of 8 MB. If the entire 8-MB of size is not used, the file remains on the system even after the data has been posted and read-released. The size for the post queue in a status display is the actual disk space used by all of the queue files. You can eliminate obsolete files that have been read-released by using the
342
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
trim command in the SharePlex qview utility. The command preserves files containing data not yet posted and committed to the target database. Instructions for running qview
are in Chapter 12 of the SharePlex Administrator’s Guide.
You had to unexpectedly stop replication (UNIX) If an unforeseen condition such as database corruption or a system problem forced you to shut down SharePlex, especially if you had to re-run ora_setup, verify that the semaphores and shared memory that SharePlex was using have been released. The following procedure shows you how. 1 Look for any SharePlex processes that did not shut down, and kill them.
$ ps -ef | grep sp_ $ kill -9 PID 2 Change directories to the rim sub-directory of the SharePlex variable-data directory, and issue the od -x command for the shmaddr.loc and the shstinfo.ipc files.
# od -x shmaddr.loc 0000000 0000 00e1 ed40 0000 4400 9328 0080 0000 0000020 0002 0021 0000024 # od -x shstinfo.ipc 0000000 0000 00e0 ee90 0000 4100 9328 0010 0000 0000020 0002 0020 0000024 3 Make a note of the following values:
The first 32-bit word of each of the files above reveals the hexadecimal equivalent of the ID of the shared memory segment. Convert this value to decimal. For example, in the shmaddr.loc file shown in step 2, the first word is 0000 00e1, which equates to a decimal value of 225. In the shstinfo.ipc file, the first word is 0000 00e0, which equates to a decimal value of 224. The third word of the shmaddr.loc and the shstinfo.ipc files reveals the hexadecimal equivalent of the KEY of the shared memory segment and the semaphore. (Each
CHAPTER 3 Preventing and Solving Replication Problems
343
set has the same key value.) Do not convert this value to decimal. For example, in the shmaddr.loc file, the third word is 4400 9328. In the shstinfo.ipc file, the third word is 4100 9328. The fifth word of each file is the SEMAPHORE ID. Convert this value to decimal. The semaphore IDs in the examples are hex 0002 0021 and 0020 0020, which in decimal are 131105 and 131104, respectively. 4 Issue the ipcs -smaa command at the UNIX command prompt to view all of the
shared memory segments and semaphores. (Shared memory segments are listed first and are denoted with an “m.” Semaphores are denoted with an “s.”) The display looks similar to the following, but will be more extensive. # ipcs -smaa T ID KEY MODE OWNER GROUP CREATOR CGROUP NATTCH SEGSZ CPID LPID ATIME DTIME CTIME Shared Memory: m 22 0x41009d0f --rw-r--r-- root spadmin root spadmin 0 1048576 6517 6517 8:04:10 8:39:23 13:57:15 m 23 0x44009d0f --rw-r--r-- root spadmin root spadmin 0 8388608 6517 6517 8:04:10 8:39:23 13:57:15 m 224 0x41009328 --rw-r--r-- root staff root staff 1 1048576 10030 13299 10:13:40 10:13:40 9:53:33 m 225 0x44009328 --rw-r--r-- root staff root staff 1 8388608 10030 13299 10:13:40 10:13:40 9:53:33 T ID KEY MODE OWNER CTIME Semaphores: s 30 0x41009d0f --ra-ra-ra8:39:19 13:57:15 s 31 0x44009d0f --ra-ra-ra8:39:19 13:57:15 s 131104 0x41009328 --ra-ra-ra-
GROUP CREATOR
CGROUP NSEMS
OTIME
root spadmin
root spadmin
12
root spadmin
root spadmin
2
root
root
staff
staff
12
5 Verify that the shared memory IDs from the shmaddr.loc and shstinfo.ipc are in the
list and that the keys match. 6 For each shared memory segment, verify that the value in the NATTCH column is 0.
This ensures that the SharePlex processes that you killed released their memory segments.
344
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
7 For the semaphores, verify that the semaphore IDs and keys match the file values. 8 As root, issue the ipcrm -m command for the ID values (224 and 225 in the exam-
ples) to remove the memory segments. # ipcrm -m 224 # ipcrm -m 225 9 As root, issue the ipcrm -s command for the key values (131104 and 131105 in the
examples) to remove the semaphores. # ipcrm -s 131104 # ipcrm -s 131105
sp_cop is using too much CPU time If you believe sp_cop is consuming too much CPU, you can increase its idle time with the SP_COP_IDLETIME parameter. See Chapter 2 for information about this parameter.
A table stopped replicating If a table stops replicating, find out if Oracle partition changes were made to the table while replication was underway. After you add or change a partition, the configuration must be reactivated. If you did not reactivate when you made the partition changes, first resynchronize the object(s) using a method of your choice, then reactivate the configuration using default activation (not live). If you did reactivate the configuration, but you used live activation, the partition change was not recognized nor its data replicated. Partition changes are not supported by live activation. Resynchronize the object(s), then reactivate using default activation.
A source table is corrupted If a source table is corrupted or there is another reason that you do not want the replicated data to be posted to the target database, you can prevent posting for that table without removing it from the active configuration or affecting posting for other objects.
CHAPTER 3 Preventing and Solving Replication Problems
345
To disable posting for a table, use the SP_OPO_DISABLE_OBJECT_NUM parameter, which disables posting of both DML and DDL operations. SP_OPO_DISABLE_OBJECT_NUM is disabled by default. To enable it, run sp_ctrl on the target system and issue the set param command for it, using the source table's object ID as the value, as shown in the following example. sp_ctrl(sysB)> set param SP_OPO_DISABLE_OBJECT_NUM 12345 When you are ready to begin posting to the target table again, set SP_OPO_DISABLE_OBJECT_NUM to 0. For more information about this parameter, see page 259.
SharePlex is running out of disk space Data accumulating in the queues can cause SharePlex to run out of disk space.
What to do... • Stopped replication processes cause data to accumulate in the queues. If a process was stopped by a user, find out why and then start it as soon as possible so that SharePlex can process the accumulated data. If a process stopped because of an error, view the Event log with the show log command to find out what happened, then resolve the problem so that processing can continue and the queue backlog can be reduced.
• If a stopped process is not the problem, find out if Capture is processing archive logs. The capture queue consumes disk space while the archived records are being processed. If Capture's location in the logs is far behind Oracle's, it might be more practical to run ora_cleansp, resynchronize the data, and reactivate the configuration than to add disk space and continue replication. Data latency might be too great for users to tolerate waiting for SharePlex to regain parity with Oracle. If activation is an extreme option, contact Quest Support for assistance with a procedure using SP_OCT_GEN_STOP, cycling through the archive logs, and resynchronizing the target system without needing to reactivate.
• If SharePlex continues to run out of disk space, adjust the redo logs to reduce replication's dependence on the archive logs, and increase disk allocation for the variabledata directory. Quest Technical Support can help you tune Capture's performance when it is not keeping pace with Oracle. For more information about how to configure the redo logs for replication, see “Redo log configuration” on page 331.
346
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• If you experience an unplanned increase in activity on the source system that causes data to accumulate in the post queue, you can prevent the queue from exceeding available disk space by stopping the Import process. SharePlex captures and processes data much faster than it posts it with SQL statements on the target system, so you probably have free space on the source system to queue data. Let the data accumulate on the source system until Post has posted enough messages for you to start Import again. You can continue stopping and starting Import for the duration of the peak activity. When you implement this method, monitor the replication services and SharePlex’s disk usage on the source system. On UNIX systems, you can use the sp_ps script to monitor processes and the sp_qstatmon monitoring script to monitor the queues. On Windows systems, you can use the Sp_Nt_Mon utility to monitor those components. See Chapter 12 of the SharePlex Administrator’s Guide for information about these and the other SharePlex monitoring utilities.
• If you do run out of disk space, see “Lack of disk space” on page 322 for help.
Oracle 9i+ DDL is not replicating If you are running an Oracle 9i+ database and are having problems with replication of supported DDL, make certain the following are true:
• Are the source and target databases identical? Components must exist in the target database in order for the replicated DDL to succeed there. The SP_OPO_STOP_ON_DDL9I_ERR parameter is defaulted to direct the Post process to stop if there is an error applying the DDL, to enable you to correct the problem to keep the databases synchronized. This parameter should be set to 1 (on).
• Is the SP_OCT_REPLICATE_ALL_DDL parameter enabled? This parameter must be set to 1 for SharePlex to replicate 9i-supported DDL.
• Does SharePlex have the required privileges? SharePlex needs the following grants: grant select any table to splex with admin option; grant create any view to splex with admin option;
Examples of error messages for 9i+-supported DDL If a user is not found on the target: Skipping generic 9i DDL operation, schema (bob) could not be set.
CHAPTER 3 Preventing and Solving Replication Problems
347
If the DDL fails on the target: FAILED DDL Replication for "create user bob." For more information about DDL and other operations and objects supported by SharePlex, see the SharePlex Administrator’s Guide. Chapter 4 of that guide also contains more information about configuring SharePlex for supported Oracle 9i+ DDL replication.
Oracle 9i+ DDL is not completely displayed in the Event Log SharePlex prints replicated 9i+ DDL to the Event Log, but it truncates statements longer than 2,000 characters. Only the first 2,000 characters are recorded in the log.
Post generates ORA-1762 errors If Post is generating ORA-1762 errors (for invalid number), view the NLS_TERRITORY and NLS_NUMERIC_CHARACTERS database parameters on the source and target systems. If...
• NLS_TERRITORY is set to anything other than AMERICA and...
• NLS_NUMERIC_CHARACTERS is set to use commas (,) ... the following changes might fix the problem. 1 In sp_ctrl, shut down SharePlex on the source and target systems by issuing the shutdown command.
sp_ctrl(sysA)> shutdown sp_ctrl(sysB)> shutdown 2 Export the following environment variable on the source and target systems.
AMERICAN_AMERICA must be in capital letters.
348
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
(ksh) export NLS_LANG=AMERICAN_AMERICA.database_character_set (csh) setenv NLS_LANG AMERICAN_AMERICA.database_character_set 3 Start SharePlex on the source and target systems. 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 to activate
the new parameter setting. sp_ctrl(sysA)> stop read sp_ctrl(sysA)> start 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 ORACLE_SID,AMERICAN_AMERICA.database_character_set 7 In sp_ctrl on the target system, stop the Post process, then start it again to activate
the new parameter setting. sp_ctrl(sysB)> stop post sp_ctrl(sysB)> start post
Post generates a shared memory error Post sometimes generates a “Cannot attach to second shared memory segment” error. This error is incorrect. To resume normal operations, stop and start the Post process.
CHAPTER 3 Preventing and Solving Replication Problems
349
SharePlex does not run on a Windows system SharePlex uses the NuTCRACKER operating environment to run on Windows systems. NuTCRACKER is a third-party program developed by Mortice Kern Systems that enables SharePlex to be ported uniformly in the UNIX and Windows environments. NuTCRACKER runs as a service on Windows. If the NuTCRACKER service is stopped or disabled, or if the NuTCRACKER files have been removed or relocated, there will be errors when you try to run SharePlex. To troubleshoot the errors, do the following: 1 Run the Windows Task Manager, then click the Processes tab. 2 Check to see if the NuTCRACKER service is running. The process name is nutsrvx,
where x is the version of the NuTCRACKER software. 3 If the process does not appear in the processes list, it might have been stopped by someone. To start the NuTCRACKER service, use the Administrative Tools Con-
trol Panel on Windows systems. 4 Do one of the following:
• If you do not see the NuTCRACKER service, re-install SharePlex from the CD and re-install NuTCRACKER. See step 10 for instructions.
• If you were able to start the NuTCRACKER service and you still have problems with errors, check to see if the NuTCRACKER files were relocated. To determine the correct installed location: 5 From the Start menu, select Run, then type regedit in the Run text box. 6 Expand HKEY_LOCAL_MACHINE, then expand SOFTWARE. 7 Expand the Data Focus entry, then highlight the Runtime entry. The InstallDir string
in the right pane shows the correct location for the files. 8 Close the Registry Editor. 9 Do one of the following:
350
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
• Locate the files and restore them to that directory. Search for the folder MKS Toolkit. If that folder cannot be located, search for any of the files shown in the follow-
ing illustration:
• If you cannot locate the files or cannot restore them to the original location, take the following steps to remove the NuTCRACKER Registry entries and reinstall SharePlex and NuTCRACKER. 10 Stop the SharePlex and NuTCRACKER services, if running. 11 Run regedit to open the Registry Editor, and delete the Data Focus and Mortice Kern Systems entries.
CHAPTER 3 Preventing and Solving Replication Problems
351
12 Close the Registry Editor. 13 Restart the system. 14 Reinstall SharePlex, making sure to reinstall it in the current location, and making
sure to install the NuTCRACKER component when prompted. 15 Restart the system to make the new NuTCRACKER environment effective.
Explanation of replication error messages The following table explains many of the common error messages that you might experience during replication. Explanation of replication error messages sp_cop error messages
What to do
sp_cop cannot setup; memory segment n in use.
You can get this message when you try to start sp_cop. It is generated if any processes that access the queues were still running when you last shut down sp_cop. Kill those processes. When all have been killed, sp_cop should start.
Error: sp_cop can't setup shared memory statistics capability exiting Error: sp_cop(shs) Cannot delete previous memory segment 303. Please check to see if any Shareplex processes are running (ps -ef | grep sp_). If there are some processes running then kill them and restart sp_cop.
This indicates that there are already one or more SharePlex sp_cop processes pointing to the same variable-data directory. To run multiple sessions of SharePlex, you need to use separate variable-data directories for each one. See “Running multiple instances of SharePlex” in Chapter 3 of the SharePlex Administrator’s Guide for instructions.
352
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Explanation of replication error messages (continued) Capture error messages
What to do
Capture time limit (300 sec) exceeded.
This message alerts you when Capture is not processing records, which could indicate a problem with the redo log. If, after 300 seconds, Capture is unable to process a record, this message appears and the process stops and logs the record. If you cannot determine the cause of the problem, call Technical Support before a log wrap occurs.
Log wrap detected
This means that the redo logs have wrapped and Capture cannot locate the archive logs. If archive logs are not available, you need to resynchronize the data because messages that SharePlex needed were lost in the log wrap. If archive logs are available, uncompress them (if applicable) and restore them to the archived log directory. When the redo logs wrap, SharePlex looks for the archive logs in Oracle’s archived log list. If SharePlex cannot find the archived log there, it looks in the directory or directories specified by the SP_OCT_ARCH_LOC parameter. This parameter should always be set to the correct archived log directory. If you use compression for the archive logs, do not compress them until SharePlex is finished processing them. To determine the current log for SharePlex, issue the show capture command with the [detail] option in sp_ctrl on the source system. You can compress any logs that were generated previous the current one for SharePlex. Note that this error also occurs when the archived log is corrupted.
Post error messages
What to do
sp_opst_mt - operation taking too long.
This message appears when it takes more than five seconds to apply a SQL statement to the target instance. For help with diagnosing the problem, see the tips beginning on page 330.
Rowid not found
This means that SharePlex cannot locate the correct row to update in the target database. The row needed by the SQL statement probably already was altered, either by a trigger or cascading delete firing or by direct DML access by a user.
CHAPTER 3 Preventing and Solving Replication Problems
353
Explanation of replication error messages (continued) Database not available.
Oracle-related error messages
This message alerts you when the Post process has repeatedly attempted to log onto the target database and failed. Verify that the database is running, and see whether someone changed the SharePlex Oracle user’s password or access permission. What to do
Warning: (sp_opst_mt for o.oracle-o.oracle queue oracle)Oracle parameter 'OPEN_CURSORS' is < 512. Check 'OPEN_CURSORS' setting. or... Warning: sp_opst_mt (for o.oracle-o.oracle queue oracle) Post has opened number cursors. No more available cursors! Exiting. or... ORA1000: maximum open cursors exceeded. or... Notice: sp_opst_mt (for o.oracle-o.oracle queue oracle) Post will not open more than number cursors (OPEN_CURSORS – 10).
These messages all relate to Post’s needing more cursors than are available. If the value for the Oracle parameter OPEN_CURSORS is less than 512, Post sends a warning message. The Post process requires a minimum of 512 total open cursors to process SQL statements. For instructions on setting the correct value for OPEN_CURSORS, see page 97 of the SharePlex Administrator’s Guide.
Can’t access OBJ$Table
This indicates that SharePlex is unable to access the Data Dictionary, which it must be able to do in order to replicate. Check the O7_DICTIONARY_ACCESSIBILITY Oracle tuning parameter and make sure it is set to TRUE (the default).
Forward and backward operation counts do not match...
Find out if Oracle was shut down before SharePlex. This can cause SharePlex to return errors, and in rare cases, corrupt the queues. The proper procedure is to shut down SharePlex and then shut down Oracle. For help resolving this problem, please contact Quest Technical Support.
354
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Explanation of replication error messages (continued) Error: sp_opst_mt (for o.blues920-o.ora9 queue bluesky) 15033 - Failed to execute SQL on table: QA.T_DEST_1: ORA-00001: unique constraint (.) violated.
SQL Cache error messages
If a user on the source system violates a unique constraint, that change enters the redo log. Oracle rejects that change and rolls it back, and the rollback also enters the redo log. Therefore, SharePlex replicates them, and because it finds the constraint violation, it sends this message to the Event Log on the target system. You can ignore this message. The tables are still in synchronization because Oracle rolled back the offending operation. This is an unavoidable error because of the way Oracle handles the violation. What to do
Warning: sp_opst_mt (for o.oracle-o.oracle queue oracle) Too many concurrent transactions. Will disable the SQL Cache capability.
If the SQL Cache size has been reduced to 1, and more cursors are still needed, SharePlex disables the SQL Cache feature and generates a warning message in the Event Log. For more information, see Chapter 6 of the SharePlex Administrator’s Guide.
Warning: sp_opst_mt (for o.oracle-o.oracle queue oracle) Running out of cursors. Number of cursors opened so far is number. Will attempt to decrease SQL Cache size. or... Notice: sp_opst_mt (for o.oracle-o.oracle queue oracle) Shrinking SQL Cache size to number per session.
When SQL Cache is enabled, Post keeps track of the number of cursors it has opened. If Post detects that it will exceed its maximum number of cursors, it issues this message in the Event Log and tries to decrease the SQL Cache size. Do not do anything unless the value gets to 1 and there are still not enough cursors. For more information, see Chapter 6 of the SharePlex Administrator’s Guide.
SQL Cache disabled.
The SQL Cache feature has been disabled. For information, see Chapter 6 of the SharePlex Administrator’s Guide.
CHAPTER 3 Preventing and Solving Replication Problems
355
Explanation of replication error messages (continued) Hints file error messages
What to do
15050 – hint file not found
SharePlex looks for the hints.SID file whether you use it or not. The hints file is installed in the data sub-directory of the SharePlex variable-data directory when you run ora_setup. If this file has been removed or relocated, or if ora_setup was skipped or run incorrectly, you will get this message. To resolve this issue, run ora_setup again, using the current owner and password so that existing configuration information will be retained. If you cannot run ora_setup, create a blank hints file using the “hints.SID” naming format in the data sub-directory of the variable-data directory. On UNIX systems, anyone with root privileges can issue a touch /variable_data_dir/data/hints.SID command (substituting the full path name of the SharePlex variable-data directory for variable_data_dir, and substituting the ORACLE_SID of the target instance for SID) to create a blank hints file that will eliminate this message. For more information about the hints file, see Chapter 6 of the SharePlex Administrator’s Guide.
15051 – missing column in the hint file (either table of index name)
The hints file has not been configured correctly. One or more specifications has been omitted. For instructions for creating a hints file, see Chapter 6 of the SharePlex Administrator’s Guide.
15052 – syntax error for tablename
Check the hints file to make sure that the owner and table name are specified in this format: owner.tablename. For instructions for creating a hints file, see Chapter 6 of the SharePlex Administrator’s Guide.
15053 – syntax error for indexname
Check the hints file to make sure that the owner and index name are specified in this format: owner.indexname. For instructions for creating a hints file, see Chapter 6 of the SharePlex Administrator’s Guide.
356
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Explanation of replication error messages (continued) 15054 – source table’s object_id not found in object cache
The hints file includes a source table that is not in the active configuration. All tables in the hints file must be listed in the active configuration. If this table is in the configuration, make sure that the owner name and table name are spelled in the hints file the same way as they are in the configuration. For instructions for creating a hints file, see Chapter 6 of the SharePlex Administrator’s Guide.
15055 – more than n valid entries were entered into the hints file
The hints file permits only as many table-index combinations as the value set by the SP_OPO_HINTS_LIMIT parameter. For more information about this parameter, see page 260.
15056 – error allocation memory for hints
Generally, this indicates a system-level memory problem; the hints file itself does not demand a significant amount of memory. If you believe the system memory is sufficient, stop the Post process and start it again. If you are not using the hints file, you can ignore this error.
17000 – error opening hint file
SharePlex cannot open the hints file. Check to see if it has been corrupted. If not, make sure there is sufficient read permission. For instructions for creating a hints file, see Chapter 6 of the SharePlex Administrator’s Guide.
Environment-related error messages sp_opst_mt: pid=num date/time src host/ sid=db01:N2PB /var/quest/vardir/log/ event_log: Too many open files
What to do On UNIX systems, SharePlex runs best when the system file descriptors setting is 1024. See page 108 of the SharePlex Administrator’s Guide for instructions for setting the system file descriptors.
CHAPTER 3 Preventing and Solving Replication Problems
357
Explanation of replication error messages (continued) 06/29/00 08:05 System call error: sp_ocap(que) (for o.QA11 queue o.QA11) No space left on device devname 06/29/00 08:05 Internal error: sp_ocap (for o.QA11 queue o.QA11) 10705 writecommit failed que_BUFWRTERR: Error writing buffer to file 06/29/00 08:05 Process exited sp_ocap (for o.QA11 queue o.QA11) [pid = 8692] -exit(1)
SharePlex ran out of space for the queues on the disk. This caused the data to go out of synchronization because there was no more room to write the replicated data in the buffer to disk. To resolve the issue, see page 322.
gethostbyname name failed - exiting
The SP_SYS_HOST_NAME parameter was probably set incorrectly. This parameter is used in a cluster configuration to provide a consistent host name for SharePlex to use so that replication continues seamlessly after failover. • If SP_SYS_HOST_NAME is set to an invalid package name, SharePlex generates this message and exits.
• If SP_SYS_HOST_NAME is set to the local host name instead of the package name, SharePlex generates this error message after the standby node is activated and the cluster manager tries to start SharePlex. SharePlex cannot start because it has not migrated with the rest of the package. To resolve this problem, specify the global cluster package name for SP_SYS_HOST_NAME. For more information on setting this parameter, see page 273. For instructions on establishing SharePlex in a cluster environment, see the SharePlex Installation and Demonstration Guide. Greater than maximum writers number
SharePlex maintains a shared-memory segment that is separate from the shared memory segment used by the queues. This segment allows SharePlex to display status statistics through sp_ctrl. This error message indicates that there is insufficient locking protection for the statistics for the current and subsequent processes.
358
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Explanation of replication error messages (continued) Other error messages
What to do
Snapshot too old.
This is when the read-consistent view required by SharePlex is no longer available. To avoid this message, increase the size of the rollback segment.
Parameter paramname does not exist in the paramdefaults file. Using hard coded default value. Please make sure that your param-defaults file is the correct version.
This indicates that SharePlex cannot find a parameter that it needs to reference, and that it is using a hard-coded default value. If you see this message in the Event Log, it means you have an older version of the param-defaults file than the version of SharePlex that you are running. Someone might have updated the SharePlex binaries using a downloaded patch, and may not have installed the latest param-default file. Parameters are sometimes added or changed in a SharePlex patch release, and you should always check for an updated param-defaults file when you manually update SharePlex.
Invalid DATE format detected in record with rowid=rowid, on obj object_id. See capture log for detail.
A user or application entered an invalid date value into the Oracle database that bypassed the database’s validity check. SharePlex can correct this problem if you specify the correct values using the SP_OCT_DEF_ parameters. See page 240 for more information about these parameters.
shs_SHMERR: an error occurred with shared memory.
This indicates that you tried to run the qview utility without shutting down SharePlex (sp_cop). Shut down SharePlex and re-run qview.
CHAPTER 3 Preventing and Solving Replication Problems
359
Part 6: Solving other problems This part of the chapter reviews solutions to other replication problems.
A configuration was accidentally deleted You might be able to recover an accidentally deleted configuration if that configuration was previously active and you did not run ora_cleansp since it was activated. To recover the configuration, view the Event Log to determine the activation ID for that configuration file, then look in the save sub-directory of the SharePlex variable-data directory for a .conf.actid file, where actid is the activation ID you got from the Event Log.
Conflict resolution generates compile errors If you encounter compile problems with your conflict resolution routines, check to see if any tables have the same names as their owners. A known issue in PL/SQL prevents the SharePlex conflict resolution logic from compiling the PL/SQL for tables whose names are the same as their owners. Oracle has stated that the issue will not be fixed. See Oracle TAR 2577886.996 for more information. This issue does not affect replication; SharePlex replicates data for tables with identical owner and table names.
The reconcile command is slow to complete If you issue the reconcile command when source database activity is low, the command process can, in some circumstances, seem to stall. This happens because the reconcile command is dependent on data continuing to arrive from the source system. If there is no replicated activity on the source system after the point of the hot backup or copy, the reconcile process waits until source activity resumes. This is normal.
360
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Machine names cannot be resolved Sometimes, machine names cannot be resolved between UNIX and Windows systems. To avoid this problem, add the IP addresses and names of all servers (UNIX and Windows) in the replication network to the /etc/hosts file on all UNIX machines, and add the same information to the hosts file on all Windows machines. For more information about this issue, see the Windows Preinstallation Checklist in the SharePlex Installation and Demo Guide.
A “Can’t unlink file” error occurs on Windows systems A nuisance error similar to the ones below sometimes occur on Windows systems. The files eventually unlink. Text file busy Unlinking file: 'r:\splex2102/rim/o.SERV+C+0.0000000 Or... System call error: sp_ordr.exe(osp) (for o.SERV queue o.SERV) Text file busy 17003 - Can't unlink file R:\Splex2100/state/o.SERVlog_sp_ordr.30
Solving connection errors If you are having trouble starting sp_ctrl, or with forming a connection using the host, port or [on host] commands in sp_ctrl, one of the following error messages might be displayed. Explanation of connection error messages Connection error messages Host unknown: cannot form connection
What to do This message appears when either the host command or [on host] option is issued. Verify that the system to which you want to connect is running and that you are using the correct system name.
CHAPTER 3 Preventing and Solving Replication Problems
361
Explanation of connection error messages (continued) Network unreachable
The network is down. Check the network connections to make sure that nothing became disconnected from the machine. If it is truly a network outage, and it affects a replication system, find out how long the network administrator expects it to last. If the downtime could cause the SharePlex queues to exceed their disk space, take measures to avoid having to resynchronize the data. (For more information on sizing a disk for the SharePlex queues, see page 106 of the SharePlex Administrator’s Guide.)
User is not authorized as a SharePlex user -- check /etc/group
You do not have user permissions to execute the operation. SharePlex users must be entered in the /etc/group file (UNIX) or in the Users list (Windows) under one of the SharePlex user groups: SharePlex Admin group, spoper, spview. Refer to Chapter 1 of this guide for instructions for setting up SharePlex users, or consult your SharePlex Administrator.
Invalid password
You incorrectly entered your password, or it is not valid on the system to which you want to connect. Consult your SharePlex or system administrator.
Invalid user name passed
You entered an incorrect user name. Re-enter it, and if it is not accepted, consult your SharePlex or systems administrator, or check the /etc/group file (UNIX) or Users list (Windows) to see if you are part of a SharePlex group. You must be in the SharePlex Admin group, spoper, or spview group to issue commands for SharePlex.
Port number must be a positive number
You could have entered the port number incorrectly. Try again.
unauthorized connection attempt from host hostname.net
A connection from a remote machine has been denied because its name is not listed in the auth_hosts file. The system’s name is shown in the error message. To allow that system to connect to the sp_cop on the local system, add its name to the auth_hosts file. For more information on the auth_hosts file, see Chapter 6 of the SharePlex Administrator’s Guide.
362
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Solving compare command errors If you are having trouble with the compare config or compare table command, refer to the following for assistance.
Compare fails with Oracle error 904 The following error referring to Oracle error 904 in the sp_declt log indicates that a comparison failed because the source and target tables being compared are structurally different. Notice: Object ID of JULIA.T_HFL_101 is 3154 Error 904 calling oexec in de_select_prepare_to_fetch SQL statement: select rowid, “C1”, “C2”, “C3”, “AC1”, “AC2”, “AC3”, “MC1”, “MC2”, “MC3” from “JULIA”.”T_HFL_101” order by “C1” Error 904 calling de_select_prepare_to_fetch in de_batch_setup Error 1 calling de_batch_setup in de_compare_client Error 1 calling de_compare_client in main “ora10_declt-28852-01.log” [Read only] 24 lines, 711 characters
Do a DESCRIBE on both tables. It probably will show that the tables do not have an equal number of columns or the columns’ datatypes are different. The compare commands are designed to detect and repair only rows whose values do not match, generally because of errant DML operations. They are not designed to detect and repair out-of-sync conditions caused by unsynchronized DDL operations or tables that were not structurally identical to begin with. After you correct the DDL problem, you can run a comparison with the [repair] option to resynchronize the values in the rows.
Compare fails with a “Too many users” error A message similar to the following in the Event Log indicates that the maximum number of queue readers and writers (processes reading from, and writing to, the SharePlex queues) has been exceeded, and that the offending compare process failed. Can not add DataEquator queue reader que_TOOMANYUSERS: User table is full
A maximum of 20 processes can read from, and write to, the post queue at the same time, including the replication processes and the compare config and compare table processes. Thus, there is a limit to the number of compare/repair processes that can run at one time. There is no workaround or way to adjust the limit, nor is there a way to
CHAPTER 3 Preventing and Solving Replication Problems
363
determine how many compare processes can run concurrently without exceeding the limit. The compare process attempts to access the queue for five minutes before exiting. An error is most likely to occur when a repair option is used, because a repair accesses the queue much longer than a compare process without a repair. Tip: To compare multiple tables at the same time, without being restricted by process limitations, use the compare config command. To limit the tables being compared, create a new configuration containing only the ones that you want to compare, and use it for the comparison. (Do not activate that configuration.) All of the tables are compared with one compare config process. For more information about comparing subsets of an active configuration, see page 46.
A client process fails to die When a sp_desvr server process dies, the associated sp_declt client process or processes usually die. If you need to kill a sp_declt client process, and there are multiple compares running, you can determine which one to kill in one of the following ways:
• By viewing the sp_declt log file — In the file, look at the Session IDs of the sp_declt processes and find the one that matches the PID of the sp_desvr process that died. That is the sp_declt process to kill. The sp_declt Session ID is the same as the PID of the associated sp_desvr process.
• By viewing the Event Log — The Event Log records the startup of each sp_declt client process and its PID. A subsequent entry in the log records the compare log file to which the process is writing. Within the compare log file’s name in that entry is the PID of the server process. For example, in the following sample entry, the sp_declt process PID is 2450. The process writes to compare log ../o734v32a_declt1228-01.log. The 1228 is the PID of the server process. 05/04/01 17:01 Process launched: sp_declt (for o.o734v32a-o.o734v32a87056 queue all) [pid = 2450] 05/04/01 17:01 Notice: sp_declt(deq) (for o.o734v32a-o.o734v32a-87056 queue all) Opened DataEquator session log file /u10/julia30014/var7/ log/o734v32a_declt-1228-01.log You can search the log file names for the server process that died, and look for the client process associated with that log file to determine the correct PID to kill.
364
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Note: On Windows systems, the logs also record the startup of the associated sp_cop process.
A server process fails to die When you kill a sp_declt client process or it dies on its own — or if the sp_desvr server process has not communicated with the client — the sp_desvr server process usually exits after a certain amount of time, which is controlled by the SP_DEQ_TIMEOUT parameter. If you need to kill a sp_desvr server process when a sp_declt client process dies, look in the Event Log to find out which log the sp_declt client process was writing to. The Event Log records the startup of each client process and its PID. A subsequent entry in the log records the compare log file to which the process is writing. Within the compare log file’s name in that entry is the PID of the server process. For example, in the following sample entry, the sp_declt process PID is 2450. The process writes to log ../o734v32a_declt-1228-01.log. The 1228 is the PID of the server process, and that is the process to kill. 05/04/01 17:01 Process launched: sp_declt (for o.o734v32a-o.o734v32a87056 queue all) [pid = 2450] 05/04/01 17:01 Notice: sp_declt(deq) (for o.o734v32a-o.o734v32a-87056 queue all) Opened DataEquator session log file /u10/julia30014/var7/ log/o734v32a_declt-1228-01.log
Note: On Windows systems, the logs also record the startup of the associated sp_cop process.
You cannot remove a compare log If you issued the remove log compare [ID] command and received an error similar to “Command failed. Either the logs (logname) have been removed from the system, or they are currently in use by other comparison processes,.” there is probably an orphan server process remaining after a client process was killed. See the preceding instructions for killing the server process.
CHAPTER 3 Preventing and Solving Replication Problems
365
Solving errors for other sp_ctrl commands If you are receiving errors when using sp_ctrl commands, try these solutions. CLEAR STATUS error messages
What to do
No such status db entry
Verify the ID number of the Status Database entry that you want to clear, and retry the command.
Input id is of an entry which is not user-clearable.
The Status Database entry you selected is one of the types of entries that SharePlex does not allow to be cleared.
FLUSH error messages
What to do
Deactivate/flush a nonactive datasource
You are attempting to flush a configuration that is not active.
Bad routing specification
Review the syntax of your command. For correct usage, refer to Chapter 1.
LIST PARAM error messages
What to do
Module may be only one of the following: or… Illegal module specified.
You might have specified an unknown argument or option for the command. For the correct syntax for SharePlex commands, see their alphabetical listings in Chapter 1.
LSTATUS/STATUS/SHOW STATUSDB error messages
What to do
Status db file is corrupt.
The Status Database has been damaged. Shut down SharePlex and remove the statusdb file, which resides in the data subdirectory of the SharePlex variable-data directory. SharePlex will create another one when you start sp_cop again.
366
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SET PARAM error messages
What to do
Parameter does not exist in database.
You either specified a non-existent or obsolete parameter, or you misspelled the name. Use the list param command to view the SharePlex parameters for your version and to verify the spelling (see page 124). If you are confident that the parameter you are setting is valid for your version of SharePlex, and that you used the correct parameter name and command syntax, then you might have an older version of the SharePlex parameter database. Contact Quest Technical Support to see if that is the problem and to get an updated version.
Parameter type checking failed - look in param defaults file.
You might have entered the wrong data type for the parameter. To determine the correct data type, view the paramdefaults file in the data sub-directory of the SharePlex product directory. Or, you can use the list param command in sp_ctrl (see page 124).
SHUTDOWN error messages Warning: shutting down capture service may cause out-of-sync state. Are you sure you want to shutdown capturing? (N)
What to do This is not an error; however, if you shut down sp_cop, and users are still changing the data, an out-of-sync condition can occur if SharePlex is not started again before the redo logs wrap and the archive logs become unavailable. Make sure users are finished working before you shut down SharePlex, or make sure that you start sp_cop again as soon as possible. SharePlex will resume processing where it stopped if the redo logs and/or archive logs are available, but long delays can result in error conditions (see page 94 of the SharePlex Administrator’s Guide) or unacceptable latency between source and target data.
CHAPTER 3 Preventing and Solving Replication Problems
Some processes spawned by sp_cop wouldn’t die.
367
There are several SharePlex processes spawned by sp_cop that run in the background as needed during replication. When you shut down sp_cop, either gracefully or forcefully, some of the child processes sometimes remain running. Check to see if processes preceded with sp_ are stalled in a run state by issuing the UNIX ps -ef | grep sp_ command on UNIX systems or by using the special Task Manager in the SpUtils or SpClient utilities or DTaskmgr on Windows systems. To kill orphan processes
• On UNIX systems, kill orphan processes by using the UNIX kill -11 command with the process ID number obtained with the ps -ef | grep sp_ command. The -11 argument creates a core file. After issuing the command, you should be able to shut down sp_cop. If you are still having problems, FTP the core file to Quest Technical Support for evaluation and assistance.
• On Windows systems, there are several ways to kill processes. See “Viewing and terminating SharePlex processes” on page 290 for more information. DO NOT use the Windows Task Manager to kill SharePlex processes. Warning! If you have more than one session of SharePlex running on a machine, use caution when deciding which processes to kill, and kill only the ones pertaining to the session you are attempting to shut down. START/STOP/ABORT error messages A service must be specified.
What to do The command requires an additional argument for the replication service to be affected. View the correct syntax for that command by issuing the help command in sp_ctrl, and then issue the command again. For example: sp_ctrl(sysA)> help abort
368
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Unknown service specified. or... No such module. or... Service may be only one of: post, read, import, export, capture, all.
You could have misspelled the process name when you issued the command. Valid names are capture, read, export,
Command was ignored process is already in the requested state.
You or someone else already stopped/aborted/started the process, or SharePlex did so because of an error. Use the status or lstatus command to find out what happened, or you can view the user issued commands to find out is a user stopped the process.
Warning: stopping/aborting capture log may result in out-of-sync state.
This is just a warning reminding you that stopping Capture stops replication, which can result in an out-of-sync condition if the redo logs wrap and the archive logs become unavailable. You can stop Capture as long as you start it againpromptly. Capture will resume processing where it stopped, but if you wait too long, data latency might be so great that you are better off resynchronizing the data than waiting for replication to regain parity with the source transactions. For more information about this subject, see page 94 of the SharePlex Administrator’s Guide.
STARTUP error messages
What to do
Startup command ignored system was already started.
Someone already started sp_cop on this port number and system.
sp_cop cannot setup; memory segment n in use
When sp_cop was shut down, some processes did not die and were not killed by the user.
Other command error message
What to do
Command was called with an invalid argument. or… Unknown keyword used in command.
You might have misspelled a command name, argument or option, or specified an incorrect one. To view the correct syntax for a SharePlex command, issue the help command in sp_ctrl.
import, post.
CHAPTER 3 Preventing and Solving Replication Problems
369
Permission denied for command - check your authorization level.
You are not authorized to issue this command, or you are not a member of one of the SharePlex user groups. To check your authorization level, issue the authlevel command in sp_ctrl. For information about authlevel and SharePlex users and groups, see Chapter 1.
Default host is not defined: use the ‘host’ command or [on host] option.
SharePlex is unable to determine which system you want the command to affect. You can either establish a default host with the host command or use the [on host] option with the command that you want to issue. See Chapter 1 for more information about SharePlex commands.
The [on host] directive must be last - all extra arguments are ignored.
Always use the [on host] option last in a command, after all other required and optional arguments.
370
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Part 7: How to get help If you tried all of the prescribed methods in this chapter for diagnosing and correcting replication problems on your own, but the problem persists, the next step is to call Quest Software Technical Support. In addition to problems with ongoing replication, other situations when you need to call Quest Software are:
• When you encounter errors during installation. • When you need to change SharePlex parameters from the defaults and are unsure of the correct procedure, or when you think an internal parameter (non-user configurable) needs to be adjusted.
Before you call Quest Technical Support The first step for contacting Quest Technical Support is to gather some information before you report the problem. This helps the support representative resolve your situation in the most expeditious manner possible — minimizing time-consuming phone calls and e-mails, and most importantly, the wait. The following points outline the items that the support team needs in order to create a support case.
Provide login access Quest's Technical Support and development teams require login access to your replication systems to see first-hand what is happening. If you cannot provide access, Quest cannot guarantee that your problem can be resolved in a timely manner, if at all.
Generate a Support Bundle (UNIX systems only) Before contacting Quest Technical Support, generate and send a Support Bundle. A Support Bundle collects information about your replication environment into a compressed file named supportbundle.tar.Z that will help the support team analyze the problem. This file can be sent to Quest via FTP or e-mail. The information gathered by the Support Bundle is:
CHAPTER 3 Preventing and Solving Replication Problems
371
• The oratab file • The version of SharePlex • The last 5,000 entries in the log files from the log sub-directory (event_log, and the Capture, Read, Post and Reconcile logs)
• The statusdb (history of SharePlex status), actdb (history of activation status) and paramdb (user-changed parameter settings) files
• • • • •
Output from the status command The active configuration files The SIDs and Oracle versions for databases in the active configurations The system OS version The files in the state directory (a record of the state of replication, such as the object and sequence caches)
To run sp_bundle: 1 Log onto the source system as a member of the SharePlex Admin group. 2 Start sp_cop on the source system. 3 Change directories to the util sub-directory of the SharePlex product directory. 4 Run sp_bundle.
The system displays the following: Creating temporary directory: /var/opt/splex/SharePlexSB... Cleaning up files... Please send file /var/opt/splex/supportbundle.tar.Z to Quest Technical Support! Please use BINARY mode if transferring file via FTP. 5 Send the Support Bundle to Quest Technical Support, using binary mode if you are
transferring via FTP.
372
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
Other information to send In addition to the Support Bundle, the following items will help the support team diagnose the problem:
• Core files: If any core files were created by a SharePlex process in the /temp directory or the dump directory in the SharePlex variable-data directory, send them to Quest.
• Archive logs: Look in the Event Log to determine the time that the data went out-ofsynchronization. Quest needs all of the archive logs from that point in time backward. Send the archive logs from the source system and the target system, if applicable.
• Conflict resolution file and routines: If you are running peer-to-peer replication, send the conflict resolution routines and the conflict_resolution.SID file, which is located in the data sub-directory of the SharePlex variable-data directory.
How to use Quest support Quest Software's world-class support team is dedicated to ensuring successful product installation and use for all Quest Software solutions. You can access Support at www.quest.com/support or by e-mail at
[email protected]. Access SupportLink to:
• • • •
Create / Update / View Support Requests Search the Knowledge Base Access FAQs Download Patches
Emergency support is available for Level-1 problems as defined in the Technical Support User Guide, posted at www.quest.com/support.
Index
Index Symbols "failure to write and open queue" error 341 /etc/hosts file, and resolving host names 360 A abort config command error messages 367 how to use 17 abort service command 19 activate config command error messages 307 how to use 22 activation process aborting 17 detecting potential problems 224 starting 22 troubleshooting 301–307 viewing 166 adding DML locks for activation 304 host names to auth_hosts file 361 indices to speed posting 333 IP addresses and names to hosts file 360 objects to a configuration 309 Oracle errors to skip 257 ampersand in repair SQL statements 178 append command 87 using Oracle wildcards in CLI 94 archive logs, specifying location of 236 authlevel command 30 authorization levels for SharePlex description 3 viewing 30
373
374
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
B batch size for compare commands 276 buffer size for queues 270 C Capture process controlling the number of blocks read 241 controlling wait time 241 coordinating checkpoints with log switches 238 detecting invalid dates 239 error messages 352 replicating posted changes 245 starting 211 statistics for 169 stopping with abort service command 20 with stop command 218 troubleshooting 336 tuning parameters 236 cascading deletes, detecting associated problems 316 chained rows and live activation 23 replication problems caused by 330
Index
changing column conditions 319 command authorization level 3 configurations 110 default for show log command 154 host for sp_ctrl session 119 key values 317 location of NuTCRACKER files 349 name of a configuration 147 number of Post retries 265 objects in replication 318 parameters Capture process 236 compare commands 276 configuration activation 235 Export process 253 how to 230 Import process 255 Post process 256 queues 269 Read process 246 SNMP 272 sp_cop process 267 system 273 to default 150 permissions for redo logs 337 port for sp_ctrl connection 131 previous command 107 process prioritization 332 PROCESSES parameter for activation 24 repair behavior for partitioned tables 45, 68 ulimit for SharePlex 335 character set, setting source system 251 target system 261 clear status command error messages 365 how to use 31
375
376
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
clusters issuing commands for 15 parameter for 273 column conditions, changes 249, 319 command 138 commands alphabetical reference 13 authorization levels 3 descriptions and usage 1 issuing for remote system 14 on clustered systems 15 quick-reference section 5 repeating 107, 142 scroll bar for viewing command output 15 commit point 340 compare cancel id command stopping a running compare operation 59 compare config command and LOBs 48 and LONGs 47 and use of Oracle JDBC drivers 52, 78 available options 34, 89 changing batch size 276 connection timeout 282 number of threads 282 how to use 33 in peer-to-peer replication 50 parameter for skipping LOBs 281 problem-solving 362 repairing Post reported out-of-syncs 50 updates on partitioned tables 280 using Oracle wildcards 33
Index
compare table command and consolidated replication 73 and LOBs 75 and partitioned replication 73 changing batch size 276 connection timeout 282 number of threads 282 how to use 55 options 56 for clause 80 hint clause 56, 80 key clause 57, 81 key-repair clause 57, 82 orderby clause 56, 83 repair clause 56, 83 sourcewhere clause 56, 85 targetwhere clause 56, 86 where clause 56, 84 parameter for skipping LOBs 281 problem-solving 362 repairing Post reported out-of-syncs 74 updates on partitioned tables 280 with DDL replication 76 with peer-to-peer replication 73 comparing all tables for synchronization 33 individual tables for synchronization 55 comparing tables with LONG columns 75 comparing tables without keys or indices 74
377
378
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
configurations aborting through sp_ctrl 17 activating 22 commands (list) 5 copying 99 creating 101 deactivating 102 deleting from system 143 duplicate entries in 313 editing 110 error messages for 307 listing 122 purging 133 renaming 147 troubleshooting 301 verifying before activation 224 viewing contents of 227 viewing statistics 182 connect commands (list) 6 connecting to remote system for sp_ctrl commands 14 connections between compare server and client processes 35, 57, 89 establishing default host for sp_ctrl session 119 setting alternate port for sp_ctrl 131 troubleshooting 360 consolidated replication and compare table command 73 copy command 87 using Oracle wildcards in CLI 94 copy config command error messages 309 how to use 99 corrupted queues 104 create config command error messages 309 how to use 101
Index
D data about replication state 7 comparing source data with target data 33, 55 flushing from queues 114 preventing DDL posting for a table 259 protecting from system panic 270 removing from queues 133 replication aborting 17 configuring 101 starting 22 stopping gracefully 102 resynchronizing after hot copy 138 solving synchronization problems 311 tuning transfer across network 332 data dictionary, access by SharePlex 353 Data Equator, see compare config command and compare table command dates setting warnings for Capture process 239 for Read process 247 DB_BLOCK_BUFFERS parameter 333 DB_FILE_MULTIBLOCK_READ_COUNT parameter 333 DDL out-of-sync conditions compare config command 34 compare table command 55 parameter for replicating 243 preventing posting for a table 259 problem-solving for 9i support 346 replication for Oracle 9i+ 244 DDLreplication and compare table command 76 deactivate config command error messages 310 how to use 102 deactivating configurations using sp_ctrl 102
379
380
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
default mode for activation 22 port for sp_ctrl session 131 restoring for parameters 150 system for sp_ctrl session 119 delaying posting with parameter 263 with stop post command 221 transfer of data over network 220 delete queue command 104 deleting queues 104 see also removing DICTIONARY_ACCESSIBILITY parameter 353 differences in source and target data correcting 324 direct-path loads, parameter for 244 disk space parameter for variable-data directory 275 when inadequate 322, 345 DML insufficient locks 304 preventing posting for a table 259 viewing out-of-sync 207 double-byte support Post process 261 Read process 251 driver, Oracle JDBC version 52, 78 duplicate entries in the configuration file 313 E edit command 107 edit config command error messages 309 how to use 110 editing configuration file 110 paramdb file 232 previously issued command 107
Index
environment related error messages 356 variables, SharePlex 231 error messages continuing on Oracle errors 257 SharePlex/system errors 275 miscellaneous 368 removing 31 resolving for configurations 307 parameter commands 365 replication 351 run commands 365 status commands 365 stopping for 9i DDL errors 266 out-of-sync errors 262 viewing 286–289 Event Log overview 286 setting maximum size 272 events, viewing 286 exit command 111 exiting sp_ctrl 111, 137 expand command 112 Export process starting 211 statistics 185 stopping with abort service command 20 with stop command 218 tuning parameters 253 F file error on Windows systems 360 firewall, remote command execution 14 flush command error messages 365 how to use 114
381
382
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
force option for shutdown 209 foreign language parameter for source system 251 for target system 261 H help contacting Quest Customer Support 370 getting for command syntax 296 commands in sp_ctrl 117 preventing and solving replication problems 285 help command 117 hints file error messages 355 tuning parameter 260 hints in compare command 80 horizontally partitioned replication changes to column conditions 319 parameter for controlling partition switches 249 host command for obtaining information for 121 remote 14 setting default for sp_ctrl 119 file on Windows 360 name on cluster 15 hot backup for resynchronization 327 problems during replication 331 I I/O controlling for Read process 252 effect on by Read batch size 248 excessive due to transaction size 334 improving for Post 264 resolving disk bottlenecks on target system 334 Veritas Quick I/O and SharePlex 332
Index
Import process duplicate 340 starting 211 statistics for 186 stopping with abort service command 20 with stop command 218 information commands 2 list of 7 J Java, JDBC driver version 52, 78 JDBC driver version 52, 78 K keys on tables, with NULLs 274 killing SharePlex processes 290 KillSharePlex.bat 293 L language parameter for source system 251 for target system 261 latency, minimizing 247, 332 license key, location of 230 list config command 122 list param command error messages 365 how to use 124 viewing current parameters 233 listing, see viewing live activation considerations when using 23 description and syntax 23 troubleshooting 301
383
384
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
LOB datatypes and compare config command 48 compare table command 75 parameter for skipping comparisons 281 setting Capture buffers for 240 locks DML 304 during compare process 35, 57, 89 default activation 22 live activation 23 single-threaded activation 302 on tables source 306 target 338 when updating bitmap index 334 log on from remote system 14 logs compare logs, removing 144 for activation 25 commands 287 compare config command 39 compare table command 61 events 286 out-of-sync SQL statements 324 SharePlex processes 288 maximum size for Event and Trace 272 options for viewing in sp_ctrl 228 redo log wrap with archive logs unavailable 314 setting viewing defaults 154 truncating 222 viewing from sp_ctrl 187 LONG datatypes and compare config command 47 lstatus command error messages 365 how to use 127
Index
M maintenance commands (list) 8 memory error messages for 351, 356, 357 for compare commands 276 for queues buffer size 270 held by SharePlex, releasing 342 locks by buffer writer 334 protecting data in, if system panics 270 used by Read process 252 when replicating LOBs 240 messages definition 135 delaying kill message at Post start 267 enabling for invalid date columns 240 number of before Import checkpoints 255 before Read checkpoints 252 read/released by Post 264 removing from Status Database 31 skipping for Oracle errors 257 volume in queues, viewing 135 monitoring from remote system 14 with monitoring utilities 298 with SNMP traps 298 Mortice Kern Systems 349 moving NuTCRACKER files 349
385
386
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
multiple activation threads 23 activations, showing activity for 166 compare processes, tracking 37, 59 configurations, activating 22 database logons during activation 24 databases and conflict resolution 314 and deactivate config command 102 synchronizing 141 Export/Import processes, viewing 162 instances of sp_cop running 131, 351 viewing 290 oratab files (Sun Solaris) 300 Post processes, viewing 162 processors for activation 24 sub-queues 129 tables activating simultaneously 23 comparing 35, 58 targets and compare config command 46 showing 163 users of SharePlex 232 multi-threaded processing compare commands 282 configuration activation 22 N named queues illustration 164 using for multiple datasources 102 network issuing commands through 14 tuning SharePlex in WAN 254, 255, 268, 332 using SharePlex with alternate interfaces 273 using SNMP with SharePlex 272 notices, removing 31 NULLs in keys, parameter for 274
Index
NuTCRACKER, moving or removing files 349 O ON DELETE CASCADE constraints 316 on host options 14 OPEN_CURSORS error 338 operator 4 ORA-1762 errors 347 Oracle 9i DDL replication problem solving 346 stopping for errors 266 9i+ DDL replication enabling 244 error during repair process 45, 68 skipping 257 troubleshooting 353 hints in compare table command 80 hot backup and reconcile command 138 JDBC driver version 52, 78 objects, verifying before activation 224 partitions, and replication 344 PROCESSES parameter 24 setup, problem-solving 299 Oracle wildcards compare config command 33 copy/append CLI syntax 94 in synchronization routing files 92 ora_cleansp, troubleshooting 321 ORACLE_HOME determining 299 ORACLE_HOME, when incorrect 299 ORACLE_SID determining 299 ORACLE_SID, when incorrect 299 oramsglist file 257 oratab file 299 ordering parameter for selective row replication 248, 252
387
388
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
out-of-sync tables causes of 313 repairing with compare config command 33 with compare table command 55 resynchronizing 324 stopping Post for 262 viewing names of 207 P paramdb editing 232 overview 230 viewing parameters in 124 param-defaults file 230 parameters descriptions and use 234 error messages 365 list of commands 9 methods for setting 230 restoring to default 150 set-at point 150, 156 setting through sp_ctrl 156 where stored 230 partitioned replication and compare table command 73 changes to column conditions 319 troubleshooting 302 partitioned tables repairing with compare commands 280 replication 344 password, scripting for remote commands 14 peer-to-peer replication and compare commands compare config command 50 and compare table command 73 illustrated with show command 165
Index
permissions for issuing SharePlex commands 3, 310 if changed for redo logs 337 variable-data directory 337 port command for sp_ctrl connection 131 for commands in a script 14 setting for SharePlex TCP/IP communication 268 SharePlex UDP communincation 269 Post process continuing on Oracle errors 257 delaying 221, 263 error messages 352 preventing posting for a table 259 problem-solving tips 333–336 reducing/increasing processing attempts 265 replicating posted changes 245 shared memory error 348 starting 211 statistics for 191 global 194 thread 196 stopping for out-of-sync conditions 262 with abort service command 20 with flush command 114 with stop command 218 tuning parameters 256 post queue, problems with 339–342 preventing posting for a table 259 problem-solving, see troubleshooting process ID 127, 287
389
390
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
processes killing 290 setting parameters for 156 starting 211 after -s option was used 214 with start command 211 stopping after purge config command 133 by aborting configuration 17 with abort service command 19 with shutdown command 209 with stop command 218 tab in Task Manager 292 viewing activation 166 Capture 169 compare 173 Export 185 Import 186 Post 191 Read 200 with lstatus command 127 with show command 162 with status command 216 PROCESSES parameter, during activation 24 properties commands (list) 9 ps command 290 purge config command 133 Q qstatus command 135 Quest Customer Support, contacting 370
Index
queues buffer size 270 command for deleting 104 commands (list) 10 controlling disk space 275 name too long 339 named, illustration 164 problem solving 339–342 purging 133 tuning parameters 269 viewing size and status 135 quit command 137 quitting sp_ctrl 137 R Read process defining read-consistency frequency 247 invalid dates 247 starting 211 statistics for 200 stopping with abort service command 20 with stop command 218 tuning parameters 246 read-release, controlling 264 Reconcile to a sequence number 328 to an SCN 328 reconcile command description and syntax 138 in initial synchronization with hot backup on active database 328 redo command 142 redo log wrap, detecting associated problems 314 releasing SharePlex shared memory 342 remote system, issuing commands for 14
391
392
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
removing compare logs 144 configuration files 143 data from queues 133 duplicate configuration entries 313 entries from Event Log 222 hints file 355 memory held by SharePlex 344 messages from Status Database 31 NuTCRACKER files 349 queues 104 replicated data for a table 259 statusdb file 365 rename config command error messages 310 how to use 147 replication controlling from remote system 14 error messages 351 events 286 monitoring tips and tools 297 of DDL for Oracle 9i+ 244 preventing for a table 259 shutdown procedure 209 starting after -s option was used 214 stopping unexpectedly (on UNIX systems) 342 viewing 162 report copy/append 148 reset param command 150 resynchronization procedures 324 rollback segment and snapshot-too-old error 358 row chaining and live activation 23 and replication problems 330 row movement, and compare commands 280 rows, finding and repairing out-of-sync 33, 55 run commands (list) 10 run errors 365
Index
S SCN 328 scripting SharePlex commands 14 sequence number 328 services, see processes set log command 154 set param command error messages 366 how to use 156 setting defaults for show log command 154 number of activation threads 24, 27 port for sp_ctrl connection 131 PROCESSES parameter 24 SharePlex parameters 156 See also changing shared memory held by SharePlex, releasing 342 Post error 348 qview error 358 sp_cop cannot set up 351
393
394
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SharePlex Administrator 4 commands, how to use 13 controlling from remote system 14 license key location 230 operators 4 parameters, overview of 229 problem solving and prevention 285 processes aborting 19 killing 290 starting 211 stopping 218 viewing 127, 162, 166, 169, 173, 185, 186, 191, 200, 216 setting environment variables 231 system file descriptors setting 335 tablespace 303 tuning parameters 229 version number 226 viewers 4 SHAREPLEX_ACTID table 315 show commands show 162 show activate 166 show capture 169 show compare 173 show config 182 show export 185 show import 186 show log 154, 187 show post 191 show read 200 show sql 203 show statusdb error messages 365 how to use 205 in problem-solving 286 show sync 207 shutdown command error messages 366 how to use 209
Index
SID_errlog.sql file 324 SNMP parameters 272 traps, for troubleshooting 298 source WHERE clause comparing dissimilar tables 71 spadmin group assigning 4 available commands for 4 sp_cop changing idle interval 267 error messages 351 shutting down 209 starting 214 tuning parameters 267 SP_COP_IDLETIME parameter 267 SP_COP_SCAN_TIMEOUT 267 SP_COP_SO_RCVBUF parameter 268, 332 SP_COP_TPORT parameter 268 SP_COP_UPORT parameter 269 sp_ctrl alternate port to sp_cop 131 getting help for commands in 117 guidelines for using 13 online help 15 remote connection to 14 stopping 111, 137 sp_declt 35, 57 SP_DEQ_BATCHSIZE parameter 51, 77, 276 SP_DEQ_CHARACTERSET 276 SP_DEQ_CONFIG_LINE_SIZE 276 SP_DEQ_IGNORE_ORACLE_ERROR_NUM 277 SP_DEQ_IP_MAPPING 277 SP_DEQ_NCHAR_CHARACTERSET parameter 278 SP_DEQ_NEW_NUM_COMPARE 278 SP_DEQ_NLS_LANG 278 SP_DEQ_PART_TABLE_UPDATE parameter 280 SP_DEQ_READ_BUFFER_SIZE parameter 280 SP_DEQ_RESULTS_RETENTION 280 SP_DEQ_REUSE_CONFIG 281
395
396
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_DEQ_ROW_LOCK_THRESHOLD 281 SP_DEQ_SKIP_LOB parameter 281 SP_DEQ_THREADS parameter 282 sp_desvr 35, 57 specifying, see setting SP_IMP_WCMT_MSGCNT parameter 332 SP_IMP_WCMT_TIMEOUT parameter 332 SP_OCF_THREAD_COUNT parameter 235 SP_OCT_ARCH_LOG parameter 236 SP_OCT_ARCH_LOG_FIRST parameter 236 SP_OCT_ASM_SID 237 SP_OCT_ASM_SUPPORT 238 SP_OCT_CHECKPOINT_LOG parameter 238 SP_OCT_DATA_OBJ_CACHE_SIZE 239 SP_OCT_DATE_ MSG parameter 239 SP_OCT_DDL_LOGGING 239 SP_OCT_DENIED_USER parameter 240 SP_OCT_LOB_BUFFER_SIZE parameter 240 SP_OCT_LOG_MEMBER parameter 241 SP_OCT_LOG_READ_SIZE parameter 241 SP_OCT_LOGWRAP_RESTART parameter 241 SP_OCT_OLOG_DELAY 242 SP_OCT_REPLICATE_ALL_DDL parameter 244 SP_OCT_REPLICATE_DDL parameter 243 SP_OCT_REPLICATE_DLOAD parameter 244 SP_OCT_REPLICATE_POSTER parameter 245 SP_OCT_REQUIRED_DATA_IS_LOGGED 245 SP_OCT_TARGET_COMPATIBILITY parameter 245 SP_OCT_USE_SUPP_KEYS parameter 245 SP_OPO_CHARACTERSET parameter 256 SP_OPO_CONT_ON_ERR parameter 257 SP_OPO_DISABLE_OBJECT_NUM parameter 259 SP_OPO_HINTS_LIMIT parameter 260 SP_OPO_MAX_CDA 260 SP_OPO_MAX_OEXN_TIME 260 SP_OPO_NLS_LANG parameter 261 SP_OPO_OUT_OF_SYNC_SUSPEND parameter 262 SP_OPO_POSTER_DELAY parameter 263 SP_OPO_PRB_MISMATCH_SUSPEND 264 SP_OPO_READRELEASE_INTERVAL parameter 264 SP_OPO_RETRIES_MAX parameter 265
Index
SP_OPO_SQL_CACHE_DISABLE parameter 266 SP_OPO_STOP_ON_DDL9I_ERR parameter 266 SP_OPO_USE_VARNUM 266 SP_OPO_WAIT_MSG_DELAY parameter 267 spopr group assigning 4 available commands for 4 SP_ORD_BATCH_ENABLE parameter 246 SP_ORD_BATCH_MATCH_MIN parameter 246 SP_ORD_BATCH_MAX parameter 246 SP_ORD_CDA_LIMIT parameter 247 SP_ORD_DATE_ MSG parameter 247 SP_ORD_DEBUG_OBJECT parameter 247 SP_ORD_DELAY_RECORDS parameter 247 SP_ORD_FIRST_FIND parameter 248, 252 SP_ORD_HP_IN_SYNC parameter 249 SP_ORD_LDA_ARRAY_SIZE parameter 250 SP_ORD_MSGS_CK_FREQ parameter 250 SP_ORD_NLS_LANG parameter 251 SP_ORD_RCM_SKIP_RATIO parameter 250, 251 SP_ORD_SKIP_OBJECT 253 SP_OSY_COMPRESSION 282 SP_OSY_LOCK_TIMEOUT 283 SP_OSY_POST_TIMEOUT 283 SP_OSY_TCP_TIMEOUT 283 SP_OSY_THREADS 283 SP_QUE_MAX_QUEUES parameter 269 SP_QUE_Q_SHMSIZE parameter 270 SP_QUE_SHMDBUF parameter 270 SP_QUE_SYNC parameter 270 SP_SLG_LOG_MAXSIZE parameter 272 SP_SLG_SNMP_ACTIVE parameter 272 SP_SLG_SNMP_COMMUNITY parameter 272 SP_SLG_SNMP_ERROR parameter 273 SP_SLG_SNMP_EXIT parameter 273 SP_SLG_SNMP_HOST parameter 272 SP_SLG_SNMP_INT_ERROR parameter 273 SP_SLG_SNMP_LAUNCH parameter 273 SP_SLG_SNMP_MJR_ERRNUM parameter 272 SP_SLG_SNMP_MNR_ERRNUM parameter 272 SP_SLG_SNMP_OUT_OF_SYNC parameter 273
397
398
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
SP_SLG_SNMP_SHUTDOWN parameter 273 SP_SLG_SNMP_STARTUP parameter 273 SP_SLG_SNMP_SYS_ERROR parameter 273 SP_SYS_HOST_NAME parameter 273 SP_SYS_IN_SYNC parameter 274 SP_SYS_JOB_HISTORY_RETENTION 274 SP_SYS_SUSPEND_ON_ERROR parameter 275 SP_SYS_VAR_FULL parameter 275 SP_SYS_VAR_OK parameter 275 spview group assigning 4 available commands for 4 SP_XPT_SO_SNDBUF parameter 254, 332 SP_XPT_USE_LOCAL_HOST parameter 254 SQL Cache enabling and disabling 266 error messages 354 SQL statement taking too long to apply 333 viewing current (or last) 203 SSH Secure Shell parameters for 253, 254 start command error messages 367 how to use 211 starting replication processes 211 startup command error messages 368 how to use 214 status command error messages 365 how to use 216 Status Database clearing messages from 31 description 286, 289 viewing 205
Index
status, viewing activation 166 Capture 169 Export 185 from remote system 14 Import 186 Post 191 Read 200 replication brief status with status command 216 detailed status with lstatus command 127 overall view with show command 162 with show statusdb command 205 stop command error messages 367 how to use 218 stopping a running compare operation 59 for errors 9i DDL 266 Oracle 257 out-of-sync 262 SharePlex 275 system 275 posting for a table 259 replication for a configuration forcefully 17 gracefully 102 replication processes aborting 19 gracefully 218 killing 290 SharePlex command for 209 unexpectedly (on UNIX systems) 342
399
400
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
synchronization causes of out-of-sync conditions 313 command for detecting out-of-sync rows for one table 55 detecting out-of-sync rows in all tables 33 determining out-of-sync objects 207 commands (list) 11 problem-solving procedures 311 restoring 324 synchronization routing file 92 using Oracle wildcards 92 syntax help for commands 117, 223 system commands for remote 14 crash 323 file descriptors 335 obtaining information about 121 panic 270 target cascading deletes 316 DDL changes 318 disk I/O bottleneck 334 extra Import process 340 flushing to 114 I/O bottlenecks 334 inability to create archive logs 335 invalid names or addresses 306 running reconcile command 138 triggers on 315 ulimit setting 335 viewing for Export process 188 viewing SQL statement 203 tuning parameters 273 viewing SharePlex version 226 System Change Number 328
Index
T tables comparing for out-of-sync rows 33, 55 locks during compare process 35, 57, 89 out-of-sync, troubleshooting 311 partitioned 344 preventing posting for 259 verifying before activation 224 target objects repairs when partitioned 280 stopping posting for 259 verifying synchronization 33, 55, 207 target system cascading deletes 316 DDL changes 318 disk I/O bottleneck 334 extra Import process 340 I/O bottlenecks 334 inability to create archive logs 335 invalid 306 running reconcile command 138 triggers firing on 315 ulimit setting 335 viewing for Export process 188 viewing SQL statements 203 target WHERE clause comparing dissimilar tables 72 TCP/IP changing SharePlex port for 268 tuning window size 268 terminating, see stopping threads setting default number for activation 235 for compare process 282 timeout for compare commands 282 Trace Log setting maximum size 272 transportable tablespaces, for resynchronization 326
401
402
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
troubleshooting activation process 301 configuration errors 307 connection errors 360 host names 360 Oracle setup 299 parameter commands 365 reconcile command 359 replication problems 330 run errors 365 status commands 365 synchronization problems 311 tools for 286 truncate log command 222 tuning Capture process 236 compare process 276 configuration activation 235 Export process 253 for WAN environment 332 Import process 255 Post process 256 queue properties 269 Read process 246 SNMP monitoring 272 sp_cop process 267 system parameters 273 U UDP port, setting for SharePlex 269 ulimit parameter, setting for SharePlex 335 unlink file error 360 UPS protection, parameter when unavailable 270 usage command 223 V V$LOG_HISTORY table 315
Index
variable-data directory parameter for disk space 275 removing logs from 144 restoring to clean state 323 shared in cluster 273 verify command 224 verifying configuration before activation 224 synchronization of tables 33, 55, 207 version command 226 version of Oracle JDBC driver 52, 78 view config command 227 view log options command 228 viewer 4
403
404
SHAREPLEX® FOR ORACLE Reference Guide Version 7.5
viewing authorization levels for commands 30 compare results from command line 38, 60 through sp_ctrl 173 configurations activation status 166 contents 227 list of 122 problems before activation 224 statistics if active 182 host information through sp_ctrl 121 list of SharePlex commands 5 logs commands 187 compare config command 39 compare table command 61 events 187 replication processes 288 SQL statements 289, 324 online help for commands 117 out-of-sync objects 207 parameters through sp_ctrl 124 processes and paths 162 SharePlex version number 226 show log command defaults 228 SQL statement processed by Post 203 statistics activation status 166 active configuration 182 Capture 169 Export 185 Import 186 Post 191 queues 135 Read 200 Status Database 205 status of replication brief 216 detailed 127, 294 syntax for SharePlex commands 223
Index
W WAN, tuning SharePlex for 253, 255, 332 WHERE clause in compare table command constraining row selection 70 using a global WHERE 70 WHEREclause in compare table command and source WHERE clause 71 and target WHERE clause 72 Windows determining ORACLE_SID 300 hosts file 360 terminating SharePlex processes on 291 viewing SharePlex processes on 291
405
