Replicat commands

1.3 Replicat commands

With Replicat commands, you can establish initial checkpoints so that data can be continuously and accurately processed. After the initial run, these checkpoints provide a starting point for subsequent runs. Replicat commands also provide run history information.

Replicat process names, parameter files and report files take system assigned default values. To change these default settings, see Changing Default Component Names.

1.3.1 ADD REPLICAT

Use ADD REPLICAT to add a Replicat group. A Replicat group allows data changes to be processed from run to run without missing records.

Using ADD REPLICAT options you can perform a variety of operations that are summarized in the argument table.

Syntax

ADD REPLICAT group_name 
{, SPECIALRUN |  trail_name | LOGTRAIL trail_name}
[, BEGIN time |, EXTSEQNO seq_number, EXTRBA rba]
[, CPU primary_cpu] 
[, BACKUPCPU cpu] 
[, PRI priority]
[, PROCESS process_name]
[, PARAMS param_file_name]
[, REPORT report_name]
[, DESC "text"]
[, PROGRAM program_name]

group_name

Required. Up to 7 characters to designate some logical function of this Replicat group. You can use wildcards to specify a set of group names, such as, * or *FIN*.

To use a group name of up to 10 characters, you can use the global parameter OLDGROUPNAMING. However, Oracle GoldenGate recommends constraining group names to 7 characters.

SPECIALRUN | trail_name | LOGTRAIL trail_name

Either SPECIALRUN or one of the two record sources is required. A warning is issued if the specified record source does not exist.

For SPECIALRUN see "Configuring initial data synchronization or other tasks".
Specify trail_name when the source is a local trail.
Specify LOGTRAIL trail_name where the record source is a Logger trail.

BEGIN time EXTSEQNO seq_num, EXTRBA rba

See "Specifying a starting point".

CPU primary_cpu BACKUPCPU cpu PRI priority

See "Assigning CPUs".

DESC "text"

See "Enter a Replicat group description".

PARAMS param_file_name REPORT report_name

See "Specifying an alternative parameter or report file".

PROCESS process_name

See "Specifying an alternative Replicat process".

PROGRAM program_name

The object to be run. See "Executing user exits".

Example

This Replicat group reads data from a trail created and stored at \NY. It starts processing from the beginning of the AA trail and runs on CPU 5 at a priority of 160.

ADD REPLICAT FINANCE,  \NY.$DATA2.EXTDAT.AA, 
CPU 5, PRIORITY 160

Specifying a starting point

Normally, Replicat begins processing at the beginning of the trail. However, you can control when and where Replicat begins processing with one of the following options:

BEGIN time

Determines when Replicat begins processing data the audit trail. The time options are:

NOW
A date/time in the format yyyy-mm-dd [hh:mi:[ss[.cccccc]]]

Note: Using BEGIN is not recommended, because it causes Replicat to bypass data preceding the specified begin point and can cause the target data to be out of synchronization.

EXTSEQNO seq_number

Identifies a specific sequence number in the local Oracle GoldenGate trail at which to begin extracting data.

For example, if the is $SYSTEM.GGSDAT.ET and EXTSEQNO is 26, processing begins in trail file $SYSTEM.GGSDAT.ET000026. Omit this parameter unless special circumstances arise.

EXTRBA rba

Specifies that processing begin in the local Oracle GoldenGate trail at the specified relative byte address.

Example

Example 1

ADD REPLICAT ORDERS,  \NY.$DATA2.EXTDAT.AA, BEGIN NOW, CPU 6, PRI 170

Example 2

ADD REPLICAT ORDERS,  $SYSTEM.GGSDAT.ET, EXTSEQNO 26, EXTRBA 1203780

Assigning CPUs

When you add a Replicat group you can specify CPUs and a process priority. The options are:

CPU primary_cpu: The processor on which Replicat will run. The default is the CPU on which Manager runs.
BACKUPCPU cpu: An alternative CPU on which to run Replicat if the primary CPU becomes unavailable.
PRI priority: The NonStop priority of the process. Refer to the HP NonStop documentation for more information.

Specifying an alternative Replicat process

The default process name is $GGRnn, where nn represents the sequence of the process. Oracle GoldenGate recommends that you use the default, however, if you must specify an alternative process, you can do so with the PROCESS process_name option.

Example

ADD REPLICAT FINANCE,  $SYSTEM.GGSDAT.ET, PROCESS $GGR04

Specifying an alternative parameter or report file

Oracle GoldenGate recommends that you use the default names, however, if you must specify an alternative process, use the options described here. Alternatively, you can change the default names globally from the GLOBALS parameter file using ADD DEFINE; see "GLOBALS Parameters Summary" for more detail on this parameter. Also see Changing Default Component Names.

The default parameter file name is GGS_volume.GGSPARM.group_name, where group_name represents a Replicat group, such as FINANCE.
The default report file name is GGS_volume.GGSRPT.report_name, where report_name represents the report file name, such as FINANCE. Oracle GoldenGate creates an entry-sequenced file to hold each Replicat group's run results. By default, the report name is the same as the Replicat group.

To change the default names:

PARAMS param_file_name: Supplies an alternative parameter file name. Enter the fully qualified path name for the parameter file.
REPORT report_name: Supplies the new report file name. Enter the fully qualified path name for the parameter file.

Example

This example changes the default parameter file and report names.

ADD REPLICAT FINANCE, 
 $SYSTEM.GGSDAT.ET, 
PARAMS $PARAMS.GGSPARM.FINANCE,
REPORT $REPORTS.GGSRPT.FINANCE

Configuring initial data synchronization or other tasks

For initial synchronization or other task processing, you can configure Replicat to run as a task by specifying the SPECIALRUN parameter.

Example

ADD REPLICAT group_name, SPECIALRUN

Enter a Replicat group description

Use the DESC "text" option to describe a Replicat group.

Example

ADD REPLICAT T24SEA,  $SYSTEM.GGSDAT.ET, 
DESC "T24 data pump for ATM transactions to IBM in Seattle"

Executing user exits

You can create and run your own routines by compiling them into an object file and binding this to the Replicat program by using the TACL macro named BINDEXIT. For more information, see User Exits.

When you are ready to call the user exit, launch the Replicat object that has the bound routines with the PROGRAM program_name option. Manager uses that program when starting the process.

Example

ADD REPLICAT GROUP1, BEGIN NOW, CPU 1, PRI 150, PROGRAM $DATA.GGS.FINEXIT1

1.3.2 ALTER REPLICAT

Use ALTER REPLICAT to change attributes established in ADD REPLICAT.

Syntax

ALTER REPLICAT group_name [, options...]

group_name: An existing Replicat group name.
options: You can specify any ADD REPLICAT option here. If no options are specified, the checkpoint is reset to the beginning of the trail. If BEGIN is not specified, the first file in the sequence must exist.

The following example alters the checkpoints for a group of Replicat processes. Use this to skip over data that had not been processed before an unplanned outage.

Example

ALTER REPLICAT REP1AP BEGIN NOW

1.3.3 CLEANUP REPLICAT

CLEANUP REPLICAT deletes old run history records for a group, but keeps the last run record intact, enabling processing to resume from the correct position.

For example: CLEANUP REPLICAT FINANCE deletes run history records for the finance group, and keeps the last run record. You can also specify a quantity of records to save, as in: CLEANUP REPLICAT * SAVE 5, saving the last 5 run records.

Syntax

CLEANUP REPLICAT group_name [SAVE count]

group_name: The group name. You can use wildcards to specify a set of group names, such as, * or *FIN*.
SAVE count: Save the last count runs.

1.3.4 DELETE REPLICAT

DELETE REPLICAT deletes a Replicat group. DELETE can have the side effect of freeing up trails for purging by Manager, since associated trail checkpoints are deleted.

Syntax

DELETE REPLICAT group_name [!]

group_name: The group name. You can use wildcards to specify a set of group names, such as, * or *FIN*.
!: (Exclamation point) Deletes each group without prompting the user to confirm the operation.

1.3.5 INFO REPLICAT

INFO REPLICAT retrieves processing history for a Replicat group. You can specify reporting options to obtain:

Status of the process
Process run history
A lag report
Detailed historical checkpoints
Only processes that are running, or stopped

Syntax

INFO REPLICAT group_name 
[, BRIEF | DETAIL]
[, LAG number {SECONDS | MINUTES | HOURS}]
[, SHOWCH]
[, UP | DOWN]
[, TASKS | ALLPROCESSES]
[, PROGRAM]

group_name: The group name. You can use wildcards to specify a set of group names, such as, * or *FIN*.
BRIEF: Reports the status of the Replicat process (STARTING, RUNNING, STOPPED or ABENDED) and an approximation of the time and byte lag between the associated trail and Replicat processing.
DETAIL: Reports Replicat process run history, which includes starting and stopping points within the trail expressed as a time, and the process parameters established by the ADD REPLICAT command.
LAG number SECONDS | MINUTES | HOURS: Restricts the display to groups that are a specified number of seconds, minutes or hours behind. This helps spot critical conditions. The lag returned by this command is approximate. For precise information, use LAG REPLICAT. Lag measures both bytes behind and time behind.
SHOWCH: Shows detailed historical checkpoints.
UP | DOWN: Shows processes that are running (UP) or not (DOWN).
TASKS | ALLPROCESSES: Shows either tasks or all processes that are running. Specify either TASKS or ALLPROCESSES.
PROGRAM: Displays the name and location of the object that is running.

1.3.6 KILL REPLICAT

KILL REPLICAT forces a Replicat process to stop immediately. Try STOP REPLICAT first because it also performs cleanup. STOP and KILL are preferred to stopping from TACL. Manager automatically restarts processes that are stopped from TACL.

Syntax

KILL REPLICAT group_name

group_name: The group name. You can use wildcards to specify a set of group names, such as, * or *FIN*.

1.3.7 LAG REPLICAT

Instead of reading the current checkpoint position, LAG REPLICAT queries Replicat to determine the relative position of the process in the local trail. This command provides a better estimate of Replicat's lag behind the process than INFO REPLICAT.

You can retrieve lag information from remote processes by specifying the Replicat process name instead of group name.

Syntax

LAG REPLICAT {group_name | process_name}

group_name: The group name, as in: LAG REPLICAT FINANCE
process_name: The Replicat process name, as in: LAG REPLICAT $DATA.GGS.$GGR00

1.3.8 SEND REPLICAT

SEND REPLICAT communicates with a running Replicat process.

Using SEND REPLICAT options you can perform a variety of operations that are summarized in "SEND REPLICAT Options Summary".

Syntax

SEND REPLICAT group_name {
DEFERAPPLYINTERVAL n unit |
GETDEFERAPPLYINTERVAL |  
STATUS | 
REPORT [time_option [RESET | FILE name | TABLE name]]|
ROLLREPORT |
LAGSTATS option | 
LAGSNAPSHOT | 
LAGREPORTON | 
LAGREPORTOFF | 
LAGOFF | 
FORCESTOP | 
STOP |
HANDLECOLLISIONS file_name |
NOHANDLECOLLISIONS file_name | 
REPORT HANDLECOLLISIONS |
CLOSEFILES |
GETGROUPTRANSOPS | 
SETGROUPTRANSOPS number |
GETMAXTRANSOPS | 
SETMAXTRANSOPS number |
GETNETWORKCHECKPOINTS |
	ROLLDISCARD |
ROLLSQLDISCARD 
}

group_name: A running Replicat group. If the group is not running, an error is returned.

SEND REPLICAT Options Summary

FORCESTOP | STOP: See "Stopping the process".
CLOSEFILES |: Causes Replicat to close any open Enscribe and SQL/MP tables.
REPORT HANDLECOLLISIONS GETGROUPTRANSOPS | SETGROUPTRANSOPS number |
GETMAXTRANSOPS | SETMAXTRANSOPS number | GETNETWORKCHECKPOINTS |
HANDLECOLLISIONS file_name | NOHANDLECOLLISIONS file_name: See "Setting and viewing parameters".
LAGSTATS option | LAGSNAPSHOT | LAGREPORTON | LAGREPORTOFF | LAGOFF: See "Obtaining lag reports".
ROLLREPORT |: See "Opening and Closing Discard and Report files".
STATUS | REPORT: See "Obtaining process reports".
ROLLDISCARD | ROLLSQLDISCARD: See "Opening and Closing Discard and Report files"

Obtaining process reports

You can specify reports for:

Processing status by specifying the STATUS option. STATUS returns a detailed status of process state, including current position and activity.
Process statistics by specifying the REPORT option. REPORT generates an interim Replicat statistical report to the report file, including the number of inserts, updates, and deletes. Refer to "SEND REPORT" for detail on SEND REPORT options.

Opening and Closing Discard and Report files

To close the current report file and open a new one, specify the ROLLREPORT option. ROLLREPORT renames the current file to report_file1, then opens a new report file with the original name. For example, if the original name was $DATA.GGSRPT.REPCUST, the ROLLREPORT option would rename files: $DATA.GGSRPT.REPCUST0, $DATA.GGSRPT.REPCUST1, up to $DATA.GGSRPT.REPCUST9. The original report name is recycled and the new report would be named: $DATA.GGSRPT.REPCUST.

To close the current discard and open a new one, specify the ROLLDISCARD option. To close the current SQL formatted discard file and open a new one, specify the ROLLSQLDISCARD option. Like the ROLLREPORT, these options rename the current discard file by adding 0 and increment the sequence number of the remaining discard files. If a discard_file9 exists, it will be deleted to make room for the replacement.

Note:

Discard files that have been created by default cannot be rolled over.

Obtaining lag reports

You can obtain a variety of lag reports with the following options:

LAGSTATS option: Collects and optionally reports lag statistics. The options are the same as those in the LAGSTATS parameter for Replicat. This LAGSTATS specification replaces any previous LAGSTATS entry.
LAGSNAPSHOT: Outputs a report regarding current statistics to the screen and to the report file. To generate this report, set up LAGSNAPSHOT, either through the parameter file or dynamically using SEND.
LAGREPORTON: Generates a report for each lag interval.
LAGREPORTOFF: Turns off automatic reporting, but continues to collect data.
LAGOFF: Turns off lag statistics.

Setting and viewing parameters

You can set and view the settings for certain parameters.

DEFERAPPLYINTERVAL n unit

A numeric value for the amount of time to delay. The minimum delay time is the value that is set for the EOFDELAY parameter. The maximum delay time is seven days.

unit

GETDEFERAPPLYINTERVAL: Shows the current delay value for that Replicat group

GETGROUPTRANSOPS: Outputs the current number of operations that are grouped together for processing.
SETGROUPTRANSOPS number: Sets the number of operations that are to be grouped to the number value.
GETMAXTRANSOPS: Outputs the maximum number of operations that are currently allowed for a transaction.
SETMAXTRANSOPS number: Sets the maximum number of operations that can be in a transaction to the number value.
GETNEWWORKCHECKPOINTS: Outputs the network checkpoint file locations, date of last update, and status information.
HANDLECOLLISIONS file_name: Directs Replicat to apply HANDLECOLLISIONS logic. This can also be specified as a startup parameter in the Replicat parameter file. The file_name option can be used with or without wildcards to include one or more files. If no file_name is specified, HANDLECOLLISIONS will be turned on for all.
NOHANDLECOLLISIONS file_name: Directs Replicat to stop applying HANDLECOLLISIONS logic. The file_name option can be used with or without wildcards to specify one or more files. If no file_name is specified, HANDLECOLLISIONS will be turned off for all.
REPORT HANDLECOLLISIONS: Outputs the status (ON or OFF) of the HANDLECOLLISIONS flag for each file or table.

Examples

Example 1

This example requests the number of operations being grouped for all Replicats.

SEND REP *, GETGROUPTRANSOPS

The Replicats return:

GGRLOG     GROUPTRANSOPS is 50
REPSQL     GROUPTRANSOPS is 100

Example 2

This example sets the maximum number of operations that can be in a transaction to 1000.

SEND REP REQSQL, SETMAXTRANSOPS 1000

Replicat returns:

MAXTRANSOPS was set to 1000

Example 3

The following command requests information on network checkpoint files.

SEND REPLICAT REP01 GETNETWORKCHECKPOINTS

This returns a display similar to:

Network Checkpoints       Entries 3, Table Size 16
Filename                                 Updated                Fnum  Err  State
----------------------------------- -------------------- ---- ---- -----
\NY.$DATA01.GGS.REPCTXT               2010/01/08 10:43:28      2    0
\LA.$DATA03.GGS.REPCTXT               2010/01/08 10:43:28      3    0
\SEA.$DATA01.GGS.REPCTXT              2010/01/08 10:43:28      4    0

Example 4

Sending the first of the following commands turns HANDLECOLLISIONS ON for TCUSTMER. The second requests a report on the settings for HANDLECOLLISIONS.

SEND REQSQL, HANDLECOLLISIONS \NY.$DATA4.GGSTAR.TCUSTMER
SEND REQSQL, REPORT HANDLECOLLISIONS

The report will be similar to:

Reading \NY.$DATA4.GGSDAT.ET000000, Current RBA       2280
Report at 2010-11-10 09:02:39 (Current settings)
Table/File                                            HANDLECOLLISIONS
MAP \LA.$DATA4.GGSSOU.TCUSTMER
       to \NY.$DATA4.GGSTAR.TCUSTMER                      On
MAP \LA.$DATA4.GGSSOU.TCUSTORD
       to \NY.$DATA4.GGSTAR.TCUSTORD                      Off

Stopping the process

You can stop the current process using either the FORCESTOP or STOP option.

FORCESTOP: Instructs Replicat to rollback the pending transaction and stop the process immediately.
STOP: Terminates Replicat gracefully. This command is preferable to stopping Replicat from TACL or other command prompt, which results in an ABEND status.

1.3.9 START REPLICAT

Use START REPLICAT to begin a Replicat process. Manager receives the request to start and monitor the process.

Syntax

START REPLICAT group_name

group_name: The group name. You can use wildcards to specify a set of group names, such as, * or *FIN*.

1.3.10 STATUS REPLICAT

Use STATUS REPLICAT to determine whether Replicat processes are running.

Syntax

STATUS REPLICAT group_name [, DETAIL | TASKS | ALLPROCESSES]

group_name

The group name. You can use wildcards to specify a set of group names, such as, * or *FIN*.

DETAIL

If DETAIL is specified, (STATUS REPLICAT *, DETAIL) the audit trails required by the Replicat group are also displayed. Output consists of the locations of required audit trails, whether they are on disk or tape, and whether they still exist.

DETAIL is useful for determining:

Whether audit must be restored from tape before the group is run
Which Replicat groups are causing Manager to tie up TMF resources

TASKS | ALLPROCESSES

Provides status on tasks or all processes that are running. Specify either TASKS or ALLPROCESSES.

1.3.11 STOP REPLICAT

STOP REPLICAT stops a Replicat process gracefully. Using this command lets you make configuration changes without affecting the operation of future runs, and ensures that Manager will not restart the process.

Syntax

STOP REPLICAT group_name [, WAIT [seconds] | ATEND |!]

group_name

The group name. You can use wildcards to specify a set of group names, such as, * or *FIN*.

WAIT seconds

GGSCI waits for the process to terminate before issuing the next prompt. When a value is specified for seconds, GGSCI waits up to that many seconds before returning control to the user. If you do not specify WAIT, GGSCI issues the next prompt immediately.

ATEND

Instructs Replicat to terminate when it reaches end-of-file in the last sequence of trails. Replicat also terminates if the trail is no longer available (due to network outage, or other condition). ATEND guarantees that all outstanding records have been processed.

The current transaction is rolled back if the trail contains only part of the last transaction. If the last transaction was part of a grouped transaction (GROUPTRANSOPS parameter) and the source trail is available, the individual transactions are replayed up to the point where Replicat is quitting.

!

Stops Replicat even in the middle of a transaction. Use this option to terminate long running transactions. As with ATEND, a grouped transaction is rolled back but the individual transactions are replayed if the trail is available.