2 AdminClient Command Line Interface Commands

Learn how to use the Oracle GoldenGate Microservices Architecture AdminClient commands, options, and review examples.

Topics:

2.1 RESTART EXTRACT

Use RESTART EXTRACT to stop then start an Extract group.

Syntax

RESTART EXTRACT group_name [ATCSN csn | AFTERCSN csn]
group_name

The name of an Extract group or a wildcard (*) to specify multiple groups. For example, T* starts all Extract groups whose names begin with T.

ATCSN csn | AFTERCSN csn

Specifies an alternate start point.

ATCSN

Directs Extract to position its start point at the first transaction that has the specified CSN. Any transactions in the data source that have CSN values less than the specified one are skipped.

AFTERCSN

Directs Extract to position its start point at the beginning of the first transaction after the one that has the specified CSN. Any transactions in the data source that have CSN values that are less than, or equal to, the specified one are skipped.

csn

Specifies a CSN value. Enter the CSN value in the format that is valid for the database. Extract abends if the format is invalid and writes a message to the report file. To determine the CSN to supply after an initial load is complete, use the serial identifier at which the load utility completed. Otherwise, follow the instructions in the initial load procedure for determining when to start Extract.

The following are additional guidelines to observe when using ATCSN and AFTERCSN:

  • The CSN is stored in the file header so that it is available to downstream processes.

  • When a record that is specified with a CSN is found, Extract issues a checkpoint. The checkpoint ensures that subsequent Extract start ups begin from the requested location, and not from a point prior to the requested CSN.

  • You must establish a physical start point in the transaction log or trail for Extract with ADD EXTRACT or ALTER EXTRACT before using ATCSN or AFTERCSN. These options are intended to be an additional filter after Extract is positioned to a physical location in the data source.

Examples

RESTART EXTRACT finance
RESTART EXTRACT finance ATCSN 684993
RESTART EXTRACT finance AFTERCSN 684993

2.2 RESTART REPLICAT

Use RESTART REPLICAT to stop then start a Replicat group. To confirm that Replicat has started, use the INFO REPLICAT or STATUS REPLICAT command.

Normal Start Point

Replicat can be started at its normal start point (from initial or current checkpoints) or from an alternate, user-specified position in the trail.

RESTART REPLICAT, without any options, causes Replicat to start processing at one of the following points to maintain data integrity:

  • After graceful or abnormal termination: At the first unprocessed transaction in the trail from the previous run, as represented by the current read checkpoint.

  • First-time startup after the group was created: From the beginning of the active trail file (seqno 0, rba 0).

Alternate Start Point

The SKIPTRANSACTION, ATCSN, and AFTERCSN options of START REPLICAT cause Replicat as a whole, or specific threads of a coordinated Replicat, to begin processing at a transaction in the trail other than the normal start point. Use these options to:

  • Specify a logical recovery position when an error prevents Replicat from moving forward in the trail. Replicat can be positioned to skip the offending transaction or transactions, with the understanding that the data will not be applied to the target.

  • Skip replicated transactions that will cause duplicate-record and missing-record errors after a backup is applied to the target during an initial load. These options cause Replicat to discard transactions that occurred earlier than the most recent set of changes that were captured in the backup. You can map the value of the serial identifier that corresponds to the completion of the backup to a CSN value, and then start Replicat to begin applying transactions from the specified CSN onward.

Syntax

RESTART REPLICAT group_name_wildcard
[SKIPTRANSACTION | {ATCSN csn | AFTERCSN csn}]
[FILTERDUPTRANSACTIONS | NOFILTERDUPTRANSACTIONS]
[THREADS (threadID[, threadID][, ...][, thread_range[, thread_range][, ...])
group_name_wildcard

The name of a Replicat group or a wildcard (*) to specify multiple groups. For example, T* starts all Replicat groups whose names begin with T.

SKIPTRANSACTION

Causes Replicat to skip the first transaction after its expected startup position in the trail. All operations from that first transaction are excluded.

If the MAXTRANSOPS parameter is also being used for this Replicat, it is possible that the process will start to read the trail file from somewhere in the middle of a transaction. In that case, the remainder of the partial transaction is skipped, and Replicat resumes normal processing from the next begin-transaction record in the file. The skipped records are written to the discard file if the DISCARDFILE parameter is being used; otherwise, a message is written to the report file that is similar to:

User requested START SKIPTRANSACTION. The current transaction will be skipped. Transaction ID txid, position Seqno seqno, RBA rba

SKIPTRANSACTION is valid only when the trail that Replicat is reading is part of an online change synchronization configuration (with checkpoints). Not valid for task-type initial loads (where SPECIALRUN is used with ADD REPLICAT).

ATCSN csn | AFTERCSN csn

Sets a user-defined start point at a specific CSN. When ATCSN or AFTERCSN is used, a message similar to one of the following is written to the report file:

User requested start at commit sequence number (CSN) csn-string
User requested start after commit sequence number (CSN) csn-string

General information about these options:

  • Valid only when the trail that Replicat is reading is part of an online change synchronization configuration (with checkpoints). Not valid for task-type initial loads (where SPECIALRUN is used with ADD REPLICAT).

  • To support starting at, or after, a CSN, the trail must be of Oracle GoldenGate version 10.0.0 or later, because the CSN is stored in the first trail record of each transaction. If Replicat is started with AFTERCSN against an earlier trail version, Replicat will abend and write an error to the report stating that the trail format is not supported.

    ATCSN

    Causes Replicat to start processing at the transaction that has the specified CSN. Any transactions in the trail that have CSN values that are less than the specified one are skipped.

    AFTERCSN

    Causes Replicat to start processing at the transaction that occurred after the one with the specified CSN. Any transactions in the trail that have CSN values that are less than, or equal to, the specified one are skipped.

    csn

    Specifies a CSN value. Enter the CSN value in the format that is valid for the database. See Administering Oracle GoldenGate for CSN formats and descriptions. Replicat abends if the format is invalid and writes a message to the report file. To determine the CSN to supply after an initial load is complete, use the commit identifier at which the load utility completed the load. Otherwise, follow the instructions in the initial load procedure for determining when to start Replicat.

FILTERDUPTRANSACTIONS | NOFILTERDUPTRANSACTIONS

Causes Replicat to ignore transactions that it has already processed. Use when Extract was repositioned to a new start point (see the ATCSN or AFTERCSN option of "START EXTRACT") and you are confident that there are duplicate transactions in the trail that could cause Replicat to abend. This option requires the use of a checkpoint table. If the database is Oracle, this option is valid only for Replicat in nonintegrated mode. In case of Integrated mode and automatic target trail file regeneration, the Integrated mode handles the duplicate transactions transparently. The default is FILTERDUPTRANSACTIONS.

THREADS thread_list

Valid for SKIPTRANSACTION, ATCSN, and AFTERCSN when Replicat is in coordinated mode. Not valid for RESTART REPLICAT without those options. Starts the specified Replicat thread or threads at the specified location.

thread_list

A comma-delimited list of ranges in the format of threadIDlow-threadIDhigh, threadIDlow-threadIDhigh.

!

(Exclamation point) Restarts Replicat immediately. The transaction is stopped.

Examples

RESTART REPLICAT finance

The following starts Replicat at a-specific CSN.

RESTART REPLICAT finance, ATCSN 6488359

The following causes threads 4 and 5 of a coordinated Replicat to skip the first transaction after their last checkpoint when Replicat is started. If this were a 10-thread coordinated Replicat, threads 0-3 and 6-10 would all start at the normal start point, that of their last checkpoint.

RESTART REPLICAT fin SKIPTRANSACTION THREADS (4-5)

The following example causes threads 1-3 of a coordinated Replicat to start at CSN 6488359, threads 9-10 to start after CSN 6488360, and threads 7 and 8 to skip the first transaction after its last checkpoint.

RESTART REPLICAT fin ATCSN 6488359 THREADS (1-3), AFTERCSN 6488360 THREADS (9-10), SKIPTRANSACTION THREADS (7,8)

2.3 RESTART SERVICE

Use RESTART SERVICE to restart the specified Oracle GoldenGate services.

Syntax

RESTART SERVICE service-name-wildcard
service-name-wildcard

The name of an service or a wildcard (*) to specify multiple services. Valid services are ADMINSRVR, DISTSRVR, RECVSRVR, and PMSRVR.

Example

RESTART SERVICE ADMIN*