SharePlex 9.0 - Administration Guide

About this Guide Conventions used in this guide Overview of SharePlex Run SharePlex Run multiple instances of SharePlex Execute commands in sp_ctrl Set SharePlex parameters Configure SharePlex to replicate data Configure replication to and from a container database Configure named queues Configure partitioned replication Configure SharePlex to maintain a change history target Configure a replication strategy Configure SharePlex to replicate Oracle DDL Set up error handling Transform data Configure SharePlex security features Activate replication in your production environment Monitor SharePlex Prevent and solve replication problems Repair out-of-sync Data Procedures to maintain Oracle high availability Make changes to an active replication environment Apply an Oracle application patch or upgrade Back up Oracle data on the source or target Tune the Capture process Tune the Post process Appendix A: Peer-To-Peer Diagram Appendix B: SharePlex environment variables

Change the name or IP address of a replication host

Description

Use the provision utility to change a host name or IP address in the SharePlex configuration.

The SharePlex processes rely on the host names or IP addresses of the source and target machines to route data properly. The provision utility enables you to change host names or IP addresses within an active SharePlex instance, without reactivating a new configuration.

Note: The provision utility does not change anything in the database. It only affects SharePlex internal objects.

Supported databases

All databases supported by SharePlex on all supported platforms

Guidelines for using provision

  • provision is only valid for SharePlex version 6.1.1 and above.
  • (SharePlex 7.0.2 only) If provision is being used because the host name of a machine changed, contact Quest Support to request a new license. Otherwise SharePlex will not start after the change.
  • (SharePlex 7.0.2 only) Add the following parameter to the param-defaults file before you run provision:

    SP_CFP_DEBUG I live int() 0x00000000

  • If running SharePlex on an AIX machine, set EXTSHM before running provision.

    export EXTSHM=ON

  • Run provision on all of the machines in the SharePlex configuration. Each machine can reference the IP addresses of all the other machines.

Run provision

  1. Stop sp_cop. If sp_cop is running, provision will fail. Note: provision prevents sp_cop from being started while it is running.
  2. Using the command line of the operating system, run provision from the SharePlex variable-data directory with the following syntax:

    provision -f old_name[:old_ipaddress] -t new_name[:new_ipaddress] [-n]

    Argument Input
    -f old_hostname[:old_IPaddress]
    • -f is required and represents "from."
    • old_hostname is the old (current) host name.
    • old_IPaddress is the old IP address. Use if the IP address cannot be obtained from the network.
    -t new_hostname[:new_IPaddress]
    • -t is required and represents "to."
    • new_hostname is the new host name.
    • new_IPaddress is the new IP address. Use if the IP address cannot be obtained from the network.
    -n

    Runs provision without actually making any changes. Generates a report on the changes that provision will make.

    Important! The best practice is to run provision with -n first, to make certain you agree with the potential changes, then run it without -n to make the changes.

    -p port For Windows systems, specifies the port of the SharePlex instance for which provision is being run.
    Example:

    provision -f oldname -t newname -n

  3. View the event log to view every change that was made. If the provision run fails or you do not agree with the changes that were made, you can undo them by running the undo_provision script. See Undo changes made by provision

Undo changes made by provision

The provision utility creates an undo_provision script that can be used to restore the host names and IP addresses to their previous state. Run the undo_provision script from the util subdirectory of the SharePlex product directory. There are no input arguments to this script.

Known issues

The following may occur but do not affect the integrity of the replication environment:

  • The provision utility does not change the active configuration file. This means that the configuration file no longer represents the current state of replication after provision is run. If you need to run the compare config command, or if you decide to reactivate the configuration, update the host name or IP address in the configuration file first.
  • If an Export or Import error occurred when SharePlex connected to a machine before the name or address was changed, the error status persists and cannot be cleared.
  • If the new or changed machine is a source machine, provision generates new routing information, but the Read process may still have the old routing in its cache. When you start sp_cop, Read might generate a warning that the stored IP address does not match the one for the machine. You can ignore this error.
  • After provision is run for a source host, it might not update the "hostname" column in SHAREPLEX_ACTID table with the new host name details. If that column is not correctly updated, you must update the SHAREPLEX_ACTID table manually to specify the new host name. This is only required if the name change affected a source machine.

Set the SharePlex port number

The SharePlex processes use TCP and UDP ports to communicate with each other on different systems. The default TCP and UDP port numbers for SharePlex are both set to 2100 at the time of installation. For some deployments of SharePlex you may need to change the port number or add additional ones.

Before selecting a port number, review the following points:

  • If your replication strategy requires multiple instances of sp_cop on a system, you must set a unique port number for each one. For more information, see Run multiple instances of SharePlex.
  • When an non-default port is required, the same number must be used for both the TCP and UDP ports, and it must be used for the TCP and UDP ports of all other instances of sp_cop that are involved in the same replication configuration. If the ports are different, sp_cop on one system cannot connect to the sp_cop on another system to send or receive messages and data.
  • On the Windows platform, SharePlex permits a maximum of 64 port numbers (SharePlex instances) on one system.

Supported databases

All databases supported by SharePlex on all supported platforms

Set the SharePlex port on Unix and Linux systems

To set the port number on Unix and Linux systems, a SharePlex Administrator must set both the TCP and UDP port parameters in the SharePlex environment. If there is an active configuration, you will be instructed to stop access to the source objects and shut down sp_cop.

  1. (If using multiple variable-data directories] Export the SP_SYS_VARDIR environment variable to point to the correct variable-data directory for the port you are setting.

    ksh shell:

    export SP_SYS_VARDIR=/full_path_of_variable-data_directory

    csh shell:

    setenv SP_SYS_VARDIR /full_path_of_variable-data_directory

  2. Export the following environment variables.

    ksh shell:

    export SP_COP_TPORT=port

    export SP_COP_UPORT=port

    csh shell:

    setenv SP_COP_TPORT port

    setenv SP_COP_UPORT port

    where: port is the new port number

  3. Change directories to the SharePlex product directory.
  4. Start sp_cop and sp_ctrl. Note:If you are using multiple variable-data directories, start sp_cop with the -uport option, where port is the port number that you have chosen for the variable-data directory that you exported.

    ./sp_cop [-uport] &

  5. Run sp_ctrl.

    ./sp_ctrl

  6. In sp_ctrl, set the following SharePlex parameters.

    sp_ctrl> set param SP_COP_TPORT port

    sp_ctrl> set param SP_COP_UPORT port

  7. Do one of two things:

    • If there is not an active configuration, use the shutdown command in sp_ctrl to stop sp_cop. The next time you start sp_cop, the new port number takes effect.

      NOTE: If you do not have an active configuration, you are finished setting the port number.

    • If there is an active configuration, continue to the next step.

    To finish setting the port in an active configuration

  8. Stop access to the replicating objects on the source system, then issue the flush command in sp_ctrl on the source system to clear the queues.

    sp_ctrl> flush o.database_identifier

    where: database_identifier is o. followed by the Oracle SID, tns_alias, or PDB name that SharePlex uses to connect to the source database (depends on whether the database is a regular Oracle instance, RAC, or PDB in a container database).

  9. On the source system, issue the qstatus command to verify that all of the messages reached the target system.

    sp_ctrl> qstatus

    Continue to issue the command until the export queue is empty.

  10. On the target system, issue the qstatus command to verify that all of the messages were posted to the database. Continue to issue the command until the post queue is empty.
  11. On the target system, issue the status command to verify that Post stopped.

    sp_ctrl> status

  12. Shut down SharePlex on the source and target systems.

    sp_ctrl> shutdown

  13. Start sp_cop on the source and target systems. Note:If you are using multiple variable-data directories, start sp_cop with the -uport option, where port is the port number that you have chosen for the variable-data directory that you exported.

    ./sp_cop [-uport] &

  14. Run sp_ctrl on the target system.
  15. Start the Post process.

    sp_ctrl> start post

  16. Allow users to access the replicating objects.
  17. Use the status command on the source and target systems to verify that all SharePlex processes are running.

    sp_ctrl> status

Set the SharePlex port on Windows systems

On Windows systems, SharePlex port numbers are stored in the Windows Registry. If it becomes necessary to change a port number, this is the SharePlex entry location:

\HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Software\SharePlex.

  1. Log onto Windows as a SharePlex Administrator using your system password and user name. Your user name must be assigned to the SharePlex Admin group.
  2. Run the SpUtils utility.
  3. Select the SharePlex Services tab.
  4. Under Port, select the port number for the instance of SharePlex whose port you want to change.
  5. Under SharePlex Service Status, click Stop.
  6. Click Close.
  7. From the Start menu, select Run.
  8. In the Run dialog box, type regedit to open the Registry Editor.
  9. In the Registry Editor, under \HKEY_LOCAL_MACHINE\Software\Wow6432node\Quest Software\SharePlex, right click the current port number, then select Rename.
  10. Replace the highlighted port number with the new number.
  11. Click the new port number to highlight it.
  12. In the Name column of the right-hand pane, right-click the SP_SYS_VARDIR entry that is associated with the new port number, then select Modify.
  13. In the Edit String dialog, change the port number (only the port number) in the path to the new port number, then click OK.
  14. Exit the Registry Editor.
  15. In the Windows file explorer, navigate to the variable-data directory for which you changed the port number (the one whose name still shows the old port number).
  16. Right click the name, and then use the Rename command to change only the port number in the name to the new port number.
  17. Run the SpUtils utility, then select the SharePlex Services tab.
  18. Under Port, select the new port number.
  19. Under SharePlex Service Status, click Install to establish the SharePlex service under the new port.
  20. After Current State shows that the service is installed, click Start to start the service.

Apply an Oracle application patch or upgrade

This chapter contains procedures to follow when you need to apply an application patch or upgrade and there is an active replication configuration. These procedures apply to Oracle databases.

Contents

Before you patch or upgrade an application

Review the following topics before you patch or upgrade an application on a system where SharePlex replication is active.

Which procedure to use?

There are different procedures for applying an application patch or upgrade to an Oracle database while replication is in process. Which one to choose depends on what changes the patch or upgrade makes.

Changes made by the patch/upgrade Steps to take

If the patch/upgrade applies DDL that is not supported by SharePlex. For details on the DDL that SharePlex supports, see the SharePlexSharePlex Release Notes.

Manually apply the patch/upgrade to the source and target by following either of these procedures:

Apply patch/upgrade to source then copy it to target

Apply patch/upgrade to source and target

If the patch/upgrade does any of the following:

  • Performs DML changes.
  • Performs supported DDL on the source system. For details on the DDL that SharePlex supports, see the SharePlexSharePlex Release Notes.
  • Changes users and security on source system (other than SharePlex)

Manually apply the patch/upgrade to the source, then allow SharePlex to replicate the changes to the target. Follow this procedure:

Apply patch to source and replicate it to the target

Note: Because this procedure assumes that SharePlex can replicate all of the changes that the patch or upgrade applies, the patch/upgrade is not applied to the target.

The effect of patches and upgrades on partitioned replication

A patch or upgrade can make changes that affect the column partitions of vertically partitioned replication in your configuration file. Take the following into account when you perform this procedure.

If the patch or upgrade does this to a table: Do this:
Adds columns that do not satisfy the column partition of the table (Optional) Drop the columns from the target table after the patch or upgrade is applied.
Adds columns that need to be in the column partition of the table Add those columns to the source and target column partition lists in the configuration file.
Drops columns that are part of the column partition of the table

Remove those columns from the source and target column partition lists in the configuration file.

Changes the name of a column that is in the column partition of a table Change the column name in the source and target column partition lists in the configuration file.

For more information, see Configure vertically partitioned replication.

Naming conventions used

In these procedures, the "source" system is one of the following:

  • The source system of a single-direction replication configuration, including cascading replication.
  • All source systems of a consolidated replication configuration.
  • The trusted source system in a peer-to-peer replication configuration.

In these procedures, the "target" system is one of the following:

  • The target system of a single-direction replication configuration, including cascading and consolidated replication.
  • The secondary systems in a peer-to-peer replication configuration.

In this procedure, the SharePlex commands in the procedure apply to all sp_cop instances that apply to the replication strategy you are using (for example, all sp_cop processes on a target in consolidated replication).

Related Documents