Chat now with support
Chat with Support

SharePlex 9.0 - Reference Guide

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

Open Target Post Parameters

These parameters are used by the SharePlex Post process when applying data to an Open Target (non-Oracle) target.

SP_OPX_COMMIT_REDUCE_MSGS

Sets the threshold for the Commit Reduction feature of Post. When the specified number of messages is reached, Post issues a commit. The commits of transactions whose transactional borders are within this span of messages are skipped, and those transactions are all committed as one transaction. Commit reduction is on by default. To disable it, set this parameter to a value of 1.

 

Default: 100 messages

Range of valid values: 1 or any positive integer.

Takes effect: when Post is restarted

 

SP_OPX_CONT_ON_ERR

This parameter controls whether or not Post stops when it encounters specific ODBC errors. When this flag is set to the default of 0, Post stops for all ODBC errors. To configure Post to ignore certain errors and continue processing, list them in one of the following files (depending on the database) and then set SP_OPX_CONT_ON_ERR to 1.

hanamsglist

postgresmsglist

sqlservermsglist

sybasemsglist

tdmsglist

These files are located in the data subdirectory of the variable-data directory. For more information about how to configure these files, see the SharePlex Administration Guide.

For each error that it ignores, Post will log an error in the SharePlex errlog.sql file and then resume posting. If Post receives an error that is not specified in the file, the process stops.

 

Default: 0 (stop on all errors)

Range of valid values: 0 or 1 (flag)

Takes effect: immediately

 

SP_OPX_DISABLE_OBJECT_NUM

This parameter prevents Post from posting replicated DML and DDL operations to the target, based on the object ID of the source table. You can set this parameter if the data in a source table is invalid or corrupted, if the source table contains datatypes that are not supported on the target, or for any other reason that you do not want operations for a table to be reflected in the target database.

You can set this parameter for one or more tables. It prevents further replication activity on the target table(s) of a source table 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.

This parameter is disabled by default. To enable it, issue the following command on the target system, where the numbers shown are the object IDs of the source tables to exclude from posting.

sp_ctrl(sysB)> set param SP_OPX_DISABLE_OBJECT_NUM object 12345,67890

Separate each object ID with a comma, and allow no spaces between them. To use spaces between entries, enclose the entire list within quotes, as in the following example:

sp_ctrl(sysB)> set param SP_OPX_DISABLE_OBJECT_NUM "498438, 1000, 497109")

Invalid object IDs will be ignored.

When you are ready to begin posting to the target table again, set SP_OPX_DISABLE_OBJECT_NUM to 0.

 

Default: 0 (off)

Range of valid values: list of valid object IDs separated by commas

Takes effect: when Post is restarted

 

SP_OPX_MSGS_IN_MEMORY

This parameter controls the amount of memory that the Post process uses. The Open Target Post process uses an internal queue to store transaction data temporarily. This parameter controls the maximum amount of memory that this internal queue uses.

 

Default: default 5000 messages

Range of valid values: integer, no maximum

Takes effect: when Post is restarted

 

SP_OPX_NLS_CONVERSION

This parameter controls character set conversion between an Oracle source and a non-Oracle target.

When replicating to an Open Target target (non-Oracle target), SharePlex supports replication from any Oracle Unicode character set and the US7ASCII character set. SharePlex posts data to Open Target in the Unicode character set, and therefore if the source data is Unicode or US7ASCII, no conversion on the target is required.

However, if the following are true, conversion is required on the target:

  • If the character set of the source data is anything other than Oracle Unicode or US7ASCII, you must install an Oracle client on the target to perform the conversion to Unicode for posting to the target.
  • If the data must be posted to the target database in any character set other than Unicode, you must install an Oracle client on the target to perform the conversion and use the target command to identify the target character set for Post to use.
  • If you are replicating LOB data, conversion is required regardless of what the source character set is.

To perform conversion with an Oracle client on Linux

  1. Install an Oracle Administrator client on the target system. The client must be the Administrator installation type. The Instant Client and Runtime installation types are not supported.
  2. Set ORACLE_HOME to the client installation. Set ORACLE_SID to an alias or a non-existing SID. SharePlex does not use them and a database does not have to be running.
  3. Download the Oracle-based SharePlex installer, rather than the Open Target installer, to install SharePlex on the target system. The Oracle-based installer includes functionality that directs Post to use the conversion functions from the Oracle client library to convert the data before posting to the target database.
  4. Follow the instructions for SharePlex for Oracle (not the ones for installing on Open Target).
  5. Make certain the SP_OPX_NLS_CONVERSION parameter is set to the default of 1.

To perform conversion with an Oracle client on Windows

  1. Install an Oracle Administrator client on the target system. The client must be the Administrator installation type. The Instant Client and Runtime installation types are not supported.
  2. In the SharePlex Registry key \HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\QuestSoftware\SharePlex\port_number, set ORACLE_HOME to the Oracle client installation location, and set ORACLE_SID to an alias or a non-existing SID. No Oracle database is required. SharePlex only needs to use the client libraries.
  3. SharePlex using the Windows installer.
  4. Make certain the SP_OPX_NLS_CONVERSION parameter is set to the default of 1.

To apply Unicode and US7ASCII data without conversion

If the source data is Unicode or US7ASCII and you are not replicating LOB data, no conversion or Oracle client is needed. Set the SP_OPX_NLS_CONVERSION parameter to 0 to disable conversion, and then restart Post if it is running.

 

Default: 1

Range of valid values: 0 or 1 (flag)

Takes effect: when Post is restarted.

 

SP_OPX_ONELINE_DEBUG

This parameter controls the oneline debug feature for the Open Target Post process.

The oneline debug feature enables you to perform debugging for out-of-sync errors without consuming a large amount of the system resources. The oneline debug logs just enough information in one line to detect where in the data stream an out-of-sync condition occurred. Once oneline debug identifies the process that is causing the problem, you can then enable regular debugging for that process.

To enable this parameter, specify the objects that you want to debug by their object ID, and separate each one by a comma. An example is:

sp_ctrl> set sp_opo_oneline_debug 230230, 351626

The following items are logged:

  • The state of the operation, which can be Process (read from queue), Skipped (commit if the Commit Reduction feature is enabled) or Applied (apply to target)
  • The transaction identifier used by SharePlex
  • The type of DML or DDL operation that was affected
  • The object ID of the affected source table
  • The row identifier of the affected row. (Oracle rowid or a placeholder consisting of the letter A for SQL Server tables, because SQL Server does not use row IDs.)
  • The time when the operation occurred (Oracle) or the time when the operation was captured by Capture (SQL Server)
  • The log sequence number and offset within the log of the affected operation
  • The Oracle SCN or SQL Server LSN for the transaction
  • An internal SharePlex code that prevents redundant operations

 

Default: Disabled

Range of valid values: a string that forms a list of objects listed by object ID, separated by commas.

Takes effect: Immediately

 

SP_OPX_OUT_OF_SYNC_SUSPEND

This parameter controls what SharePlex does when it encounters an out-of-sync condition, based on the following:

  • INSERT: The row already exists, resulting in a Unique constraint violation error.
  • UPDATE and DELETE: The row is not in the database.

Value of 0 (default)

The default Post behavior when a transaction contains an out-of-sync operation is to continue processing other valid operations in the transaction to minimize latency and keep targets as current as possible. Latency is the amount of time between when a source transaction occurs and when it is applied to the target. Different factors affect the amount of latency in replication, such as unusually high transaction volumes or interruptions to network traffic.

Post logs the SQL statement and data for the out-of-sync operation to the ID_errlog.sql log file, where ID is the database identifier. This file is in the log sub-directory of the variable-data directory on the target system.

Value of 1

A value of 1 directs Post to stop posting when it encounters an out-of-sync condition. Post logs the SQL statement and data for the out-of-sync operation to the ID_errlog.sql log file, and then stops.

When you set this parameter to a value of 1, 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, and it provides tools for unattended SharePlex monitoring. See the SharePlex Administration Guide for more information about how to monitor SharePlex.

 

Default: 0 (do not stop for out-of-sync conditions)

Range of valid values: 0 or 1 (flag)

Takes effect: immediately

 

SP_OPX_READRELEASE_INTERVAL

This parameter is used when Post is configured to post to a JMS server in transactional style (issue a JMS commit at intervals, rather than after every message as directed by the session_transacted property of the target command).

This parameter controls the read/release interval, which is how often Post purges the data of a transaction from the queue.

 

Default: 1,000

Range of valid values: any positive integer

Takes effect: when Post is restarted

 

SP_OPX_REDUCED_KEY

This parameter controls the content of the Post WHERE clause. Post uses a WHERE clause to find the row in the target that needs to be changed by a replicated UPDATE from the source. Different SharePlex features may require more or less data to be used in the Post WHERE clause.

  • If set to 0, this parameter directs Post to construct a WHERE clause of all of the data that is sent by Capture. The data that Capture sends depends on the setting of the SP_OCT_REDUCED_KEY parameter. If you want the WHERE clause to include the values of the keys and all of the columns other than LONGs or LOBs, set both parameters to 0.

    IMPORTANT! In a peer-to-peer configuration, a setting of 0 is required.

  • If set to 1, this parameter directs Post to build a WHERE clause with the key values and the before values of the columns that changed. This setting provides a good balance between replication performance and target data integrity, because it enables Post to perform a before-and-after comparison of the changed columns when constructing the WHERE clause. To be able to use this setting, the SP_OCT_REDUCED_KEY parameter must be set to 0 or 1. For more information about how SharePlex uses before and after values, see the SharePlex Administration Guide.
  • If set to 2, this parameter directs Post to build a WHERE clause of only the key columns. This setting can be used to maximize posting performance. Because this setting omits the before-and-after comparison of the changed columns, you should ensure that no process or user can make changes to the target data except SharePlex. Additionally, it is recommended that you perform regular integrity verification by using the compare command.

See also SP_OCT_REDUCED_KEY .

 

Default: 1

Range of Valid Values: 0, 1, 2

Takes effect: When Post is restarted

 

SP_OPX_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 Cache. A setting of 3 disables SQL Cache for batch operations to reduce the amount of memory that Post uses. (A setting of 2 is not available.)

If you disable SQL caching, SharePlex prints the following message to the Event Log: SQL Cache disabled.

For more information about SQL Cache, see the SharePlex Administration Guide.

 

Default: 0 (on)

Range of valid values: 0, 1, or 3

Takes effect: when Post is restarted

 

SP_OPX_STOP_ON_DDL_ERR

This parameter controls whether or not the Post process stops when there is an error applying DDL. 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.

 

Default: 1 (on)

Range of valid values: 0 or 1 (flag)

Takes effect: immediately

Queue Parameters

These parameters control properties of the SharePlex queues.

SP_QUE_MAX_QUEUES

This parameter determines the maximum number of queues allowed per instance of sp_cop. By default, each capture and export queue uses 8 MB of shared memory and each post queue uses 32MB. If the system has enough memory, you can increase the value of this parameter. On startup, SharePlex displays the amount of shared memory that is required for the number of queues in the active configuration files.

 

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.

Important: Increasing this parameter might require an increase in the maximum shared memory segment size in your system settings.

 

Default: 32 megabytes

Range of valid values: integer greater than 0

Takes effect: When sp_cop is restarted

 

SP_QUE_Q_SHMSIZE

This parameter determines the specific shared-memory size for the capture and export queues.

 

Default: 8 megabytes

Range of valid values: integer greater than 0, 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 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.

Important: 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 and Linux.

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.

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.

What SP_QUE_SYNC does not do

There are many functions that the SP_QUE_SYNC parameter does not do. Among the most common issues:

  • SP_QUE_SYNC does not choose between shared memory and disk. It also does not influence when the decision is made to write to disk. It only tells the OS to guarantee that the disk write is complete to the physical disk before returning.
  • It does not prevent an “out of subqueues” error.
  • It does not address the “out of disk space” error - the space for file data is allocated before the write or sync to physical media is performed. If an out-of-space error occurs, it would occur before the sync is performed. Data loss is likely, but the queue is expected to be usable once free space becomes available.
  • It does not cause or prevent “out of shared memory” errors or “out of virtual memory” errors. Any message indicating loss of shared memory is most likely a failure in the queue module’s demand paging system. If an “out of virtual memory” error occurs, verify the OS parameters for data segment limits. If the usual or expected limits are not enough, contact Technical Support.

Using SP_QUE_SYNC in a cluster

In a cluster, setSP_QUE_SYNC on the primary node of the cluster (the node to which the shared variable-data directory is mounted) and on each source and target machine outside the cluster that is part of the same replication environment.

 

Default: 2

Range of valid values: 0 - 2

Takes effect: When SharePlex is restarted

 

SP_QUE_USE_SUBQUE_INDEX

This parameter improves queue performance. If the source has a high amount of concrrency, the post queue may contain numerous subqueues, each of which represents a transaction session. This may reduce the performance of the Post process. This parameter directs SharePlex to use improved indexing to access the subqueue structures. A message "Subqueue index enabled queuename" is written to the Event Log for every Post queue for which this parameter is enabled.

This parameter does not support VARRAYs. If you are replicating VARRAYs and this parameter is enabled, the parameter is ignored.

 

Default: 0

Range of valid values: 0 (disabled) or 1 (enabled)

Takes effect: When SharePlex is restarted

sp_cop Parameters

These parameters are used by the SharePlex sp_cop program.

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

 

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 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 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 Share- Plex 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

 

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

 

Log Parameters

These parameters are used to control properties of the SharePlex logs.

SP_SLG_LOG_MAXSIZE

This parameter controls the size of the SharePlex Event and Trace logs. When the file reaches its maximum size, the following happens, depending on the log:

  • The Event Log is renamed to event_log_n, where n is the next number in the sequence of files, and then a new file is created as the active event log. For example, when the first event log reaches its maximum size, it is renamed to event_log_0000000001 and then a new file is opened as the active log. When that file reaches its maximum size, it is renamed to event_log_0000000002, and so forth.
  • The Trace Log is truncated. Before writing to this log, SharePlex checks its size. If the size is larger than the value of this parameter, SharePlex truncates the file before writing to it.

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

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating