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.
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
"PARAMS
param_file_name
REPORT
report_name
PROCESS
process_name
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
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:
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
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
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.
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
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.
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.
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.
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 { 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 }
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
LAGSTATS
option
| LAGSNAPSHOT
| LAGREPORTON
| LAGREPORTOFF
| LAGOFF
See "Obtaining lag reports".
ROLLREPORT |
STATUS | REPORT
See "Obtaining process reports".
ROLLDISCARD
| ROLLSQLDISCARD
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.
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
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
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
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
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.
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
.
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.