Chat now with support
Chat with Support

SharePlex 9.2.6 - Reference Guide

About this guide Conventions used in this guide SharePlex commands SharePlex parameters General SharePlex utilities Database Setup utilities SharePlex environment variables

Alphabetical reference for SharePlex commands

This starts the detailed reference documentation for SharePlex commands in alphabetical order.

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.

If 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.

Usage

Supported sources:

Oracle

Supported targets: All
Authorization level: Administrator
Issues for: source system
Related commands: deactivate config, purge config

Syntax

Basic command Remote options
abort config filename

[ on host |

on host:portnumber |

on login/password@host |

on login/password@host:portnumber ]

Syntax description

Component Description
filename 

The name of the configuration that you want to abort. Configuration names are case-sensitive.

Example:

sp_ctrl(sysA)> abort config sales

Remote options

These options enable you to issue the command on a remote machine and to script commands that include a login name, password, port number, or combination of those items.

Option Description
on host

Execute the command on a remote system (one other than the one where the current sp_ctrl session is running). You are prompted for login credentials for the remote system. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on SysA

on host:portnumber

Execute the command on a remote system when a remote login and port number must be provided. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on SysA:8304

on login/password@host

Execute the command on a remote system when a remote login, password, and host name must be provided. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on john/spot5489@SysA

on login/password@host:portnumber

Execute the command on a remote system when a remote login, password, host name, and port number must be provided. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on john/spot5489@SysA:8304

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.

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.

Usage

Supported sources:

Oracle

Supported targets: All
Authorization level: Operator (2); Administrator (1) to abort Capture
Issues for:

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 Remote options
abort service service

[to host]

[from host]

[for datasource]

[for datasource-datadest]

[queue queuename]

[ on host |

on host:portnumber |

on login/password@host |

on login/password@host:portnumber ]

Syntax description

Component Description
service

Required. The SharePlex replication process you want to abort. Valid values are:

capture

read

export

import

post

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.

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.

Remote options

These options enable you to issue the command on a remote machine and to script commands that include a login name, password, port number, or combination of those items.

Option Description
on host

Execute the command on a remote system (one other than the one where the current sp_ctrl session is running). You are prompted for login credentials for the remote system. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on SysA

on host:portnumber

Execute the command on a remote system when a remote login and port number must be provided. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on SysA:8304

on login/password@host

Execute the command on a remote system when a remote login, password, and host name must be provided. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on john/spot5489@SysA

on login/password@host:portnumber

Execute the command on a remote system when a remote login, password, host name, and port number must be provided. If used, must be the last component of the command syntax.

Example: sp_ctrl(sysB)>status on john/spot5489@SysA:8304

activate config

Use the activate config command to activate a configuration. Replication begins immediately as soon as the activation process is complete. For more information about what happens when you activate a configuration, see the SharePlex Administration Guide.

The activation process reads the configuration file, from which it gets all of the information needed for SharePlex to:

  • Identify the objects that are in replication
  • Route the replicated changes to the appropriate target database
  • Generate the SQL that Post uses to apply the changes to the target
  • Activate all of the tables that have been added to replication

The process that sp_cop calls to activate a configuration is sp_tconf.

Activation creates asynchronous, parallel processing threads to activate multiple tables simultaneously. Each table is locked for a very short time, just long enough to activate the table. Replication of each table begins as soon as its activation is complete.

Should one or more table fail to activate, SharePlex continues with the activation of the other tables. 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.

Guidelines for activation

  • 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.
  • 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.
  • Do not perform DDL, including TRUNCATE, during activation. DML changes are the only permissible changes during activation.
  • 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.
  • 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.

  • 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.

Set the number of activation threads

You can set the number of activation threads globally (for all activations) and you can override this setting for any activation.

To set the number of threads globally

  1. Run sp_ctrl

  2. Issue the following command. You may use a value of up to 32 threads.

    sp_ctrl> set param SP_OCF_THREAD_COUNT number_of_threads

To set the number of threads for the current activation

Use the [threads=n] option when you issue the activate config command.

View activation status and results

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.

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

What to do if activation fails

Many things can cause the activation of a table or the entire configuration to fail. For example, 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. For more troubleshooting advice, see the SharePlex Administration Guide.

Usage

Supported sources: Oracle (all options)
Supported targets: All
Authorization level: Administrator (1)
Issues for: source system
Related commands: abort config, copy config, create config, deactivate config, edit config, list config, purge config, remove config, rename config, show config, verify config, view config 

Syntax

Basic command Command options Remote options
activate config filename

[threads=n]

[nolock]

scn=scn_value

seqno=log_sequence_number

[ on host |

on host:portnumber |

on login/password@host |

on login/password@host:portnumber ]

Syntax description

Component Description
filename 

Required. The name of the configuration that you want to activate. Configuration names are case-sensitive.

Example:

sp_ctrl(sysA)> activate config sales

threads=n

(Valid for Oracle) Use this option to set the number of analysis threads that the activation process generates. This option overrides the default value set by the SP_OCF_THREAD_COUNT parameter.

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.

Example:

sp_ctrl(sysA)> activate config sales threads=3

 

nolock

(Valid for Oracle) Use this option to activate without locking the tables being added to replication.

scn=scn_value

(Valid for Oracle) Use this option to activate the configuration to start replication at a specific SCN in the redo logs. Before activating the configuration, do the following:

  • If there was a previously active configuration, run the ora_cleansp utility on the source and all targets to restore the environment to a clean state. For more information, see ora_cleansp.
  • Use the show scn command to get the SCNs of the last transactions that were posted from all the Post processes (if using named queues). Use the lowest of those SCN values for activate config.

Do not use this option with the nolock option.

Example:

sp_ctrl> activate config myconfig scn=123456

seqno=log_sequence_number

(Valid for Oracle) Use this option to activate the configuration to start replication at a specific redo log sequence number.

Do not use this option with the nolock option.

  • If there was a previously active configuration, run the ora_cleansp utility on the source and all targets to restore the environment to a clean state. For more information, see ora_cleansp.

    Example:

    activate config myconfig seqno=98765

    • Remote options

    These options enable you to issue the command on a remote machine and to script commands that include a login name, password, port number, or combination of those items.

    Option Description
    on host

    Execute the command on a remote system (one other than the one where the current sp_ctrl session is running). You are prompted for login credentials for the remote system. If used, must be the last component of the command syntax.

    Example: sp_ctrl(sysB)>status on SysA

    on host:portnumber

    Execute the command on a remote system when a remote login and port number must be provided. If used, must be the last component of the command syntax.

    Example: sp_ctrl(sysB)>status on SysA:8304

    on login/password@host

    Execute the command on a remote system when a remote login, password, and host name must be provided. If used, must be the last component of the command syntax.

    Example: sp_ctrl(sysB)>status on john/spot5489@SysA

    on login/password@host:portnumber

    Execute the command on a remote system when a remote login, password, host name, and port number must be provided. If used, must be the last component of the command syntax.

    Example: sp_ctrl(sysB)>status on john/spot5489@SysA:8304

    Related Documents

    The document was helpful.

    Select Rating

    I easily found the information I needed.

    Select Rating