GGSCI Commands

1 GGSCI Commands

Oracle GoldenGate Command Interface (GGSCI) allows the command-line interface between users and Oracle GoldenGate functional components. It gives access to users to edit, modify, update, synchronize, replicat, trail, database, and so, on. Here we describe the purpose and syntax for these commands.

The following table summarizes the functions that you can control with Oracle GoldenGate commands.

Command Group	Purpose
Manager commands	Start and stop the Manager program and determine whether it is running.
Extract commands	Establish Extract checkpoints and manage and monitor Extract processing.
Replicat commands	Establish Replicat checkpoints. Manage and monitor Replicat processing.
ER Commands	Allow you to manage Extract and Replicat groups as a unit with a single command. The commands you can use are the same `INFO`, `KILL`, `SEND`, `START`, `STAT`, and `STATUS` commands you would use for the Extract or Replicat.
Logger Commands	Add and alter Logger configuration and manage Logger processes.
Trail commands	Create and manage Oracle GoldenGate trails.
Database commands	Supply information about data definitions and tables and encrypt logon password.
Audit trail commands	Determine audit trail management parameters and whether audit trail files are still required.
Remote checkpoint commands	Establish remote checkpoints that Manager checks before purging data used by Replicat processes.
TMF commands	Manage TMF dump information.
Coordinator commands	Start and stop the Coordinator program, manage and monitor Coordinator processing.
Process commands	Enable you to send commands to a process name instead of a group name.
Marker commands	Enable you to insert application-specific markers into audit trails or Logger trails to identify critical points in Extract and Replicat processing.
Programs commands	Bind `GGSLIB` intercept library into application programs for non-TMF audited database extraction.
Syncfile commands	Set up and manage Syncfile processes for duplicating files from one location to another.
Report commands	Allow you to scroll through Extract and Replicat processing reports.
Miscellaneous commands	Control various other aspects of Oracle GoldenGate.

1.1 Manager commands

The Manager module must be running for other Oracle GoldenGate components to operate. The process ensures proper startup, monitoring, and other activities. Once you start the Manager process, you can:

Determine whether the Manager process is running
Retrieve information about the running Manager process
Stop the process

The Manager process ($GGMGR), runs as a NonStop process pair that includes the process ($GGMGR) and a child process ($GGMGX).

You can change the default process name from $GGMGR to another name. To change this and other default settings, see Changing Default Component Names.

1.1.1 INFO MANAGER

Use INFO MANAGER to determine whether the Manager process is running. If Manager is running, the process name, port number, TCPIP process, and IP address may be displayed depending on the parameters set for Manager.

Syntax

INFO MANAGER

Example

The following examples show different displays for the INFO MANAGER command.

Example 1

If the IP port is not configured, the display will be similar to:

Manager process $GGMGR is running.
(IP port not configured).

Example 2

If the TCPIP process name and port are configured, the display will be similar to:

Manager process $GGMGR is running 
(Process \NY.$ZTC1, port 7830).

Example 3

If the IP port, TCPIP process name, and IPINTERFACE are all configured, the display will be similar to one of the following:

Manager process $GGMGR is running 
(Process \NY.$ZTC1, IP 192.0.2.1 port 7830).

Manager process $GGMGR is running 
(Process \NY.$ZTC1, IP 2001:db8:2010:5040:4fff:ffff:ffff:28 port 7830).

1.1.2 SEND MANAGER

Use SEND MANAGER to communicate with the current Manager process.

Syntax

SEND MANAGER 
{CHILDSTATUS | 
GETPORTINFO [DETAIL] | 
GETPURGEOLDEXTRACTS |
KILL process_name}

CHILDSTATUS

Displays information about all processes started by Manager.

GETPORTINFO [DETAIL]

Retrieves the status of ports in use. Also returns statistical information about port sessions.

Include DETAIL with GETPORTINFO to retrieve information about all dynamically allocated ports, regardless of whether they are in use, as in:

SEND MANAGER, GETPORTINFO DETAIL

GETPURGEOLDEXTRACTS

Displays information about trail maintenance rules set with the PURGEOLDEXTRACTS parameter in the Manager parameter file. For more information about PURGEOLDEXTRACTS, see "PRIORITY".

KILL process_name

Stops a process that was previously created by Manager. Manager returns an error if the process is not one it created.

Examples

Example 1

SEND MANAGER CHILDSTATUS returns a child process status similar to the following.

ID  Process         Retry   Retry Time         When added
--- --------------- ------- ----- ------------ -------------------
  3 \NY.$GGS03      0,0512      0 None         2014/08/16 14:39:07

Example 2

SEND MANAGER GETPURGEOLDEXTRACTS returns a report similar to the following:

PurgeOldExtracts Rules
Fileset                       MinHours  MinFiles     UseCP
$DATA04.GGSDAT.HT*                   0         1       Y
$DATA04.GGSDAT.ET*                   0         1       Y

Extract Trails
Filename                    Group    Oldest Seqno MinHours 
\NY.$DATA04.GGSDAT.ET       REPACL              0        0 
\NY.$DATA04.GGSDAT.HT       ACTHIST             0        0 
\NY.$DATA04.GGSDAT.LT       ACRLOG              0        0 
\NY.$DATA04.GGSLOG.LT       ACELOG              0        0

1.1.3 START MANAGER

Use START MANAGER to start the Manager process.

Syntax

START MANAGER 
[, CPU primary_cpu]
[, BACKUPCPU backup_cpu] 
[, PRI priority]

CPU primary_cpu: The primary CPU name.
BACKUPCPU backup_cpu: The backup CPU name. If a backup CPU is specified in the Manager parameter file, it overrides any START MANAGER backup CPU specification.
PRI priority: Sets the NonStop priority of the process.

Example

 START MANAGER, CPU 1, BACKUPCPU 3, PRI 170

1.1.4 STATUS MANAGER

Use STATUS MANAGER to determine whether the Manager process is running and to identify its characteristics.

Syntax

STATUS MANAGER

Example

The command STATUS MANAGER will display the Manager process name, the running process, and the port number as shown below.

Manager process $ACMGR is running (IP \NY.$ZTC1 port 7670)

If a specific IP address or DNS name has been assigned using IPINTERFACE, it will be included as shown below.

Manager process $ACMGR is running (IP \NY.$ZTC1 192.0.2.2 port 7670)

1.1.5 STOP MANAGER

Use STOP MANAGER to stop the Manager process. You will be asked to confirm this command, since stopping Manager eliminates important activities. GGSCI logs STOP MANAGER commands to the Oracle GoldenGate event log.

Syntax

STOP MANAGER [!]

!: Unless you specify the exclamation point (!), you must confirm this operation.

1.2 Extract commands

Use Extract commands to create and manage Extract groups. The Extract process captures operations and sends the data to the target system. The Extract process maintains checkpoints to provide a starting point for subsequent runs, provides run history information, and displays the audit trails required for a given Extract group.

Process names, parameter files, and report files take system-assigned default values. Oracle GoldenGate Software recommends using the default names. If your installation requires different names see Changing Default Component Names.

1.2.1 ADD EXTRACT

Use ADD EXTRACT to add Extract groups, allowing change records to be processed from run to run without data loss.

Using ADD EXTRACT options you can perform the operations that are summarized in "ADD EXTRACT options summary".

Syntax

ADD EXTRACT group_name
{
[, BEGIN time |, AUDSEQNO seq_num, AUDRBA rba] |
[[, SOURCE trail_name
  {BEGIN time |, EXTSEQNO seq_num, EXTRBA rba}] |
[, LOGTRAILSOURCE trail_name
  {BEGIN time |, EXTSEQNO seq_num, EXTRBA rba}] |
[, SOURCEISTABLE]] |
[, FILETYPE file_type file_name]
}
[, CPU primary_cpu] 
[, BACKUPCPU backup_cpu]
[, PRI priority]
[, PROCESS process_name] 
[, PROGRAM program_name] 
[, PARAMS param_file_name] 
[, REPORT report_name] 
[, DESC "text"]

ADD EXTRACT options summary

group_name: The group name.
SOURCE trail_name | LOGTRAILSOURCE trail_name | SOURCEISTABLE | FILETYPE file_type, file_name: The default source for ADD EXTRACT is the TMF audit trail. For information on other data sources see "Specifying the Data Source".
BEGIN time | , {AUDSEQNO seq_num , AUDRBA rba | EXTSEQNO seq_num, EXTRBA rba}: To specify a begin time or starting point in an audit trail or an Oracle GoldenGate trail, see "Specifying a Starting Point".
CPU cpu BACKUPCPU cpu PRI priority: To specify the CPUs, see "Assigning CPUs".
DESC "text": See "Describing the Group".
PARAMS param_file_name REPORT report_name: See "Specifying an Alternative Parameter or Report File".
PROCESS process_name: See "Specifying an Alternative Process".
PROGRAM program_name: The name of the object file to run. See "Executing user exits".

Example

The following example creates an Extract group called DISTRIB that:

Begins at midnight on May 1, 2010
Runs in CPU 9 at priority 170 with an assigned backup CPU in case the primary fails

ADD EXTRACT DISTRIB, BEGIN 2010-05-01 00:00, CPU 9, BACKUPCPU 7, PRI 170

Specifying the Data Source

The default ADD EXTRACT source is a TMF audit trail. If your source is not the audit trail, you can specify an alternative source. Valid sources are:

A local Oracle GoldenGate trail
An Oracle GoldenGate Logger trail
An entry-sequenced or BASE24 TFL/PTLF file
Data captured directly from a file or table for one-time processes, such as initial synchronization

Using a Local Oracle GoldenGate Trail

A local Oracle GoldenGate trail is specified by SOURCE trail_name. The following example identifies the data source as a local Oracle GoldenGate trail, and specifies a sequence number in the trail at which to begin extracting data.

ADD EXTRACT FINANCE, SOURCE \LA.$D1.GGSDAT.AA, EXTSEQNO 26

Not Creating the : Use the NOCREATE option of SOURCE to specify that the trail is not created. If the CREATE option or no value is specified, the trail is created.

Using the Logger Trail

A Logger trail is specified by LOGTRAILSOURCE trail_name, as in:

ADD EXTRACT FINANCE, LOGTRAILSOURCE $DATA2.GLOGGGL.AA

Using a File

An entry-sequenced or ACI file source is specified by FILETYPE file_type file_name, as in:

ADD EXTRACT DISTRIB, FILETYPE ENTRY $DATA5.GGSDAT.FL1234

For file_name, enter one of: ENTRY, ACITLF, ACIPTLF, ACITLFX, ACIPTLFX, or ADVANTAGE.
Include the ALTINPUT and RANGE parameters in the Extract parameter file when capturing directly from a sequence of files

For One-time Processing

Initial synchronization or other one-time tasks are specified by SOURCEISTABLE (or SOURCEISFILE for an Enscribe file), as in:

ADD EXTRACT GROUP1, SOURCEISTABLE

When you configure Extract for a task, you must include a corresponding SOURCEISTABLE parameter in the Extract parameter file.

SOURCEISTABLE does not maintain checkpoints unless RESTARTCHECKPOINTS is used.

Specifying a Starting Point

You can specify a trail file sequence number and relative byte address as a starting point within an audit trail or local Oracle GoldenGate trail. However, it is more typical to specify a starting point using BEGIN with a date and time, which is the preferred method.

BEGIN time: Determines when Extract begins processing data in the audit trail. The time options are: NOW, or a date and time as yyyy-mm-dd [hh:mi:[ss[.cccccc]]].
AUDSEQNO seq_num: Identifies the TMF audit trail file sequence number at which to begin extracting data
AUDRBA rba: Specifies that processing begin at the specified relative byte address.
EXTSEQNO seq_num: Identifies the Oracle GoldenGate trail file sequence number at which to begin extracting data.
EXTRBA rba: Specifies that processing begin at the specified relative byte address.

Example

 ADD EXTRACT ORDERS, BEGIN NOW

Assigning CPUs

When you add an Extract group you can specify primary and backup CPUs and a process priority.

CPU cpu: The primary CPU in which Extract runs. The default is the CPU in which Manager runs.
BACKUPCPU cpu: An alternative CPU on which Extract runs if the primary CPU becomes unavailable.
PRI priority: The NonStop priority for the process. This defaults to the NonStop priority assigned to the TACL process underlying the ADD.

Example

This example assigns both the primary and backup CPUs and a priority.

ADD EXTRACT DISTRIB, BEGIN 2010-05-01 00:00, LOGTRAILSOURCE $DATA2.GLOGGGL.AA, CPU 9, BACKUPCPU 7, PRI 170

Specifying an Alternative Process

The default process name is $GGSnn, 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 EXTRACT FINANCE, BEGIN 2010-05-01 00:00, PROCESS $GGE07

Specifying an Alternative Parameter or Report File

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

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

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 an alternative report file name. Enter the fully qualified path name for the parameter file.

Example

These examples change the default parameter file and report names.

ADD EXTRACT FINANCE, BEGIN 2010-05-01 00:00, PARAMS $DATA01.NEWPARM.FINANCE 
ADD EXTRACT FINANCE, BEGIN 2010-05-01 00:00, REPORT $PROD.NEWRPT.FINANCE

Describing the Group

Use the DESC "text" option to describe an Extract group.

Example

ADD EXTRACT ET24AT2, LOGTRAILSOURCE GGSLOG.LT,
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 Extract program using the TACL macro named BINDEXIT. For more information, see Creating User Exits.

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

Example

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

1.2.2 ALTER EXTRACT

Use ALTER EXTRACT primarily to change attributes of the CPU, PRIORITY or BACKUPCPU options. You can use ALTER EXTRACT to change attributes of the options you specified with ADD EXTRACT, but you should consider the following:

Use caution when changing the BEGIN values previously set with ADD EXTRACT. Since the BEGIN option checkpoints the starting point in the source, changing it may cause duplicate or missing records.
You can change EXTRAILSOURCE or LOGTRAILSOURCE settings with ALTER EXTRACT, but Oracle GoldenGate recommends deleting and re-adding the group instead.

Syntax

ALTER EXTRACT group_name 
[, ETROLLOVER]
[, ETPURGE]
[, option ]

group_name: The group name.
ETROLLOVER: Causes Extract to increment and write to the next file in the trail sequence when restarting. For example, if the current file is ET000002, the current file will be ET000003 when Extract restarts.
ETPURGE: Causes old trails to be purged before the new one is created. Valid only when ETROLLOVER is specified.
option: In addition to the above described options, you can specify any appropriate ADD EXTRACT option.

1.2.3 CLEANUP EXTRACT

Use CLEANUP EXTRACT to delete old run history records for a group. This command keeps the last run record, enabling processing to resume from the correct position.

For example: CLEANUP EXTRACT FINANCE deletes the 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 EXTRACT * SAVE 5, saving the last five run records.

Syntax

CLEANUP EXTRACT group_name [, SAVE count ]

group_name: An Extract group name or wildcard specification, such as * or FIN*.
SAVE count: Save the last option run records instead of just the last record.

1.2.4 DELETE EXTRACT

Use DELETE EXTRACT to delete an Extract group and its associated checkpoints. Use this when the TMF configuration changes, or when you no longer require the group.

When you delete an Extract group, Oracle GoldenGate deletes both the group and the metadata that controls the group's trail. By default it retains all the files currently in the trail. If you want to delete the trail files, you must use the exclamation point (!) in the DELETE EXTRACT statement or manually purge the files.

Syntax

DELETE EXTRACT group_name [!]

group_name: An Extract group name or wildcard specification, such as * or FIN*.
!: (exclamation point) Deletes trail files associated with each group without prompting the operator.

1.2.5 INFO EXTRACT

Use INFO EXTRACT to retrieve processing history for an Extract group. You can specify reporting options to obtain:

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

Syntax

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

group_name

An Extract group name or wildcard specification, such as * or FIN*.

BRIEF

Reports:

Status of the process (STARTING, RUNNING, STOPPED or ABENDED).
An approximation of the time and byte lag between the associated source and Extract processing.

DETAIL

Reports:

Process run history, which includes starting and stopping points within the audit.
Run history for trails.
Process parameters established by the ADD EXTRACT command.

LAG number SECONDS | MINUTES | HOURS

Restricts the display to groups that are a specified time interval behind. This helps spot critical conditions. The lag returned by this command is approximate. For precise information, use LAG EXTRACT. Lag measures both bytes behind and time behind. For more information about how Oracle GoldenGate reports lag, see Changing Default Component Names.

SHOWCH

Shows detailed historical checkpoints.

UP | DOWN

Shows processes that are either running, (UP) or not (DOWN). Specify either UP or DOWN.

TASKS | ALLPROCESSES

Shows information about 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.2.6 KILL EXTRACT

Use KILL EXTRACT to force Extract to stop immediately. Try STOP EXTRACT first because it also performs cleanup. Using the Oracle GoldenGate commands STOP or KILL is preferred to stopping processes from TACL. Manager automatically restarts processes that are stopped from TACL.

Syntax

KILL EXTRACT group_name

group_name: The group name. You can use wildcards to kill a set of groups.

1.2.7 LAG EXTRACT

Use LAG EXTRACT to determine Extract's relative position in the audit trail. This command estimates the lag behind the source database more precisely than INFO EXTRACT.

For more information about how Oracle GoldenGate reports lag, see Changing Default Component Names.

To determine lag for local processes, specify the group name. To determine lag for remote processes, specify the remote process name.

Syntax

LAG EXTRACT {group_name | process_name}

group_name: The group name, as in: LAG EXTRACT FINANCE
process_name: The process name, as in: LAG EXTRACT $GGE00

1.2.8 SEND EXTRACT

Use SEND EXTRACT to communicate with a running Extract process. Using SEND EXTRACT options, you can perform a variety of operations that are summarized in "SEND EXTRACT options summary".

Syntax

SEND EXTRACT group_name {
ARCLOSECATALOG |
AUDITEND | 
STATUS | 
GETTCPSTATS | 
RESETTCPSTATS |
REPORT [time_option [RESET | FILE name | TABLE name]] |
ROLLREPORT |
GETEXTARSTATS | 
RESETEXTARSTATS |
GETARSTATS, [MAT | AUXnn] | 
RESETARSTATS, [MAT | AUXnn] | 
GETTRANSINFO |
GETARPROCESS | 
GETARPARAMS, [MAT | AUXnn] | 
GETARFILELIST, [MAT | AUXnn]] 
GETARFILESTATS, [FILE | MAT | MINRECS | RESET | QUIET |
NOPARTITIONS] | 
GETAREXCLUDELIST, [FILE | MAT | AUXnn] | 
CLEAREXCLUDELIST | 
ROLLOVER | 
LAGSTATS option | 
LAGSNAPSHOT | 
LAGREPORTON |
LAGREPORTOFF | 
LAGOFF | 
FORCESTOP | 
STOP |
GETROLLBACKS | 
IGNOREROLLBACKS
}

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

SEND EXTRACT options summary

AUDITEND | STATUS | REPORT | GETTCPSTATS | RESETTCPSTATS: See "Obtaining process reports".
ARCLOSECATALOG | GETEXTARSTATS | RESETEXTARSTATS | GETARSTATS | RESETARSTATS |
GETTRANSINFO | GETARPROCESS | GETARPARAMS | GETARFILELIST | GETARFILESTATS |
GETAREXCLUDELIST | CLEAREXCLUDELIST: See "Managing the Audserv program".
ROLLREPORT: See "Opening a new report file".
ROLLOVER: See "Rollover Oracle GoldenGate trails".
LAGSTATS option: See "Obtaining lag reports".
FORCESTOP | STOP: See "Stopping the process".
GETROLLBACKS | IGNOREROLLBACKS: See "Processing rollbacks".

Example

SEND EXTRACT FINANCE, STOP
SEND EXTRACT MANUFACT, ROLLOVER

Obtaining process reports

You can generate reports for:

Report	Option	Description
End of audit trail	AUDITEND	Queries the Extract process to determine whether all records in the audit trails have been processed. This command indicates whether more Extract and Replicat activity must occur before a scheduled switch between databases. Until `AUDITEND` returns "All audit processed," more data must be processed before it can be assumed that secondary databases are synchronized.
Processing status	STATUS	Returns a detailed status of the processing state, including current position and activity.
Processing statistics	REPORT	Generates an interim statistical report to the report file, including the number of inserts, updates, and deletes. Refer to "SEND REPORT" for detail on `SEND` `REPORT` options.
TCP/IP statistics	GETTCPSTATS	Retrieves TCP/IP statistics, such as the quantity and byte length of inbound and outbound messages, the number of messages received and sent, wait times, process CPU time, and byte transmit averages. Time accumulates when Extract is waiting on a socket send or receive and all times are reported in microseconds.
TCP/IP statistics type	RESETTCPSTATS	Resets the TCP/IP statistics so the next report displays fresh statistics.

Example

The first example uses the AUDITEND option to report on the end of an audit trail. The second example specifies the STATUS option to return details of the processing state.

SEND EXTRACT FINANCE, AUDITEND
SEND EXTRACT FINANCE, STATUS

Opening a new report file

To close the current report file and open a new one, specify the ROLLREPORT option. ROLLREPORT renames the current file by appending a number to the end of the report name (such as EXTACCT0), then opens a new report file with the original name.

Managing the Audserv program

SEND EXTRACT supplies the following options for determining the status of Audserv operations.

ARCLOSECATALOG: Instructs Audserv to close its opens on the SQL Catalog.
GETEXTARSTATS: Retrieves information about Audserv activity. Information returned includes: first and last record timestamp, first and last read timestamp, bytes processed, commits, and other processing statistics.
RESETEXTARSTATS: Resets the report generated by GETEXTARSTATS.
GETARSTATS, [MAT | AUXnn]: Retrieves audit trail statistics from Audserv.
RESETARSTATS, [MAT | AUXnn]: Resets the report generated by GETARSTATS.
GETTRANSINFO: Retrieves information from Extract's pending transaction table.
GETARPROCESS: Retrieves the process names of Audserv processes.
GETARPARAMS, [MAT | AUXnn]: Retrieves Audserv run-time parameters.
GETARFILELIST, [MAT | AUXnn]: Retrieves the Audserv file list.
GETARFILESTATS, [FILE | MAT | MINRECS | RESET | QUIET | NOPARTITIONS]: Retrieves Audserv file level statistics.
GETAREXCLUDELIST, [FILE | MAT | AUXnn]: Retrieves the contents of the Audserv exclude list.
CLEAREXCLUDELIST: Clears the Audserv exclude list.

Rollover Oracle GoldenGate trails

The ROLLOVER option closes the current trail and opens the next trail in the sequence.

Obtaining lag reports

SEND EXTRACT supplies options for generating a variety of lag reports.

LAGSTATS option

Retrieves and optionally reports lag statistics. The options are the same as those for the LAGSTATS parameter. See additional LAGSTATS information "LAGSTATS".

The SEND EXTRACT LAGSTATS specification replaces any previous LAGSTATS entry.

LAGSNAPSHOT

Writes a current statistics report to the screen and to the report file. To generate this report, specify either the LAGSTATS parameter in the parameter file, or issue SEND EXTRACT group_name, option.

LAGREPORTON

Generates a report for each lag interval.

LAGREPORTOFF

Turns off automatic reporting, but continues to retrieve data.

LAGOFF

Turns off lag statistics.

Stopping the process

You can stop the current process with:

FORCESTOP: Terminates the process with a STOP operation.
STOP: Terminates the run gracefully. This command is preferable to stopping from TACL, which results in an ABEND status.

Processing rollbacks

Process rollback records with:

GETROLLBACKS: Retrieves rollback records. Use this command only before extracting changes during an initial-load phase.
IGNOREROLLBACKS: Ignores rollback records. Use this command after completing your initial load.

1.2.9 START EXTRACT

Use START EXTRACT to start Extract. GGSCI routes the START request to Manager to start and monitor the process.

Syntax

START EXTRACT group_name
[, FILTERRESTART | NOFILTERRESTART]

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

FILTERRESTART | NOFILTERRESTART: NOFILTERRESTART causes Extract to ignore transactions that it has already processed to the output trails. Use only when Extract is to re-process data and you are confident that likely duplicated transactions in the trail that would normally cause Replicat to abend are accounted for.
The default is FILTERRESTART.

1.2.10 STATUS EXTRACT

Use STATUS EXTRACT to determine if Extract groups are running. A report displays to the Extract process's home terminal.

Syntax

STATUS EXTRACT group_name 
[, DETAIL] | [,TASKS | ALLPROCESSES]

group_name

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

DETAIL

When you specify DETAIL, (STATUS EXTRACT *, DETAIL) the audit trails required by the group are also listed. Output consists of the locations of required audit trails, whether they are on disk or tape, and whether the trails still exist.

DETAIL is useful for determining whether audit must be restored from tape before the group is run and which groups are causing Manager to tie up TMF resources.

TASKS | ALLPROCESSES

Determine either the tasks or all processes that are running. Specify either TASKS or ALLPROCESSES.

1.2.11 STOP EXTRACT

Use STOP EXTRACT to stop Extract gracefully. Use STOP when you are changing the process configuration and to prevent Manager from automatically restarting the process.

Syntax

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

group_name

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

WAIT seconds

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

ATEND

Instructs Extract to stop when it reaches end-of-file for the last sequence of audit trails. If the application that updates the source database is brought down first, this ensures that Extract processed all relevant database updates before stopping.

If Extract is reading data from an Oracle GoldenGate trail instead of TMF audit trails, ATEND causes Extract to terminate when end-of-file is reached for the last sequence of the trails.

!

(Exclamation point) Stops Extract immediately, 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.

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

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.

1.4 ER Commands

Oracle GoldenGate lets you manage Extract and Replicat as a unit with a single command. For example, to start the modules separately for group FINANCE, you would normally enter commands similar to:

GGSCI> START EXTRACT EXTFIN
GGSCI> START REPLICAT REPFIN

Using combined management, you can start both modules with a single command, as in:

GGSCI> START ER *FIN

Syntax

command ER group_name [, option]

command

Any one of the following:

INFO

Returns the processing status of both modules, including lag information

KILL

Forces the processes to stop immediately. Oracle GoldenGate recommends first attempting to stop processes using the STOP command. Either KILL or STOP is preferred over stopping processes from TACL.

SEND

Sends a performance option to the programs, such as REPORT.

SEND ER *FIN, REPORT

The REPORT option generates an interim statistical report to the report files.

START

Begins the programs. Manager receives the START command and starts and monitors the programs.

STATUS

Determines whether the processes are running.

STOP

Causes a graceful stop, ensuring configuration changes can be made without impacting future runs.

For more information about these commands, see the command's description in "Extract commands" or "Replicat commands".

ER

Required. Informs Oracle GoldenGate that the command applies to both of the programs.

group_name

The Extract or Replicat group name. You can use wildcard specifications. The following commands act upon any group containing the characters FIN.

START ER *FIN*
START ER FIN*
START ER *FIN

option

Can be any option associated with the command, such as the INFO command DOWN option, which shows only processes that are not running, as in:

INFO ER *FIN, DOWN

For details about the options, see the command's description in "Extract commands" or "Replicat commands".

1.4.1 SEND ER* STATS

Use the following commands to get process status from Extract and Replicat, as in:

Syntax

SEND [EXTRACT | REPLICAT] group_name, 
STATS [time_option [RESET | FILE name | TABLE name]]

group_name

The group name you defined with the appropriate GGSCI ADD command

STATS time_option [RESET | FILE name | TABLE name

Returns Extract and Replicat processing statistics based on the selected options.

RESET

This resets the time_option counters to zero. For example, the command SEND RECENT RESET will report the RECENT counters and then reset them to zero.

FILE name | TABLE name

This limits the display to statistics for the file or table specified in name.

time_option

Each of these returns processing statistics for the specified process. TRANSACTION is valid only for Replicat.

TOTALS: since the Extract or Replicat was started

DAILY: since the beginning of the current day

HOURLY: since the beginning of the current hour

RECENT: since the last time the RECENT counter was reset

TRANSACTION: since the beginning of the current transaction

Examples

The following sample Extract report uses the default STATS option.

Report at 2010-02-27 12:43:07 (activity since 2010-02-27 11:43:44)
Elapsed time 0-00:59:22.916658
Total # records written to \NODEA.$TEST04.GGSDAT.ET                19
   \NODEA.$TEST04.GGSSOU.TCUSTMER            #  inserts:            3
                                             #  updates:            0
                                             #  deletes:            0
   \NODEA.$TEST04.GGSSOU.TCUSTORD            #  inserts:            3
                                             #  updates:           13
                                             #  deletes:            0

The next sample Extract report uses the following options.

TOTALS statistics since 2018-07-12 10:37:53             
				#  inserts:         1           
				# purgedatas:         1 
DAILY  statistics since 2018-07-12 10:37:53             
				#  inserts:         1          
				 # purgedatas:         1 
HOURLY statistics since 2018-07-12 10:59:59             
				#  inserts:         1           
				# purgedatas:         1 
RECENT statistics since 2018-07-12 10:37:53             
				#  inserts:         1           
				# purgedatas:         1

The following Replicat report uses the TRANSACTION option.

Report at 2010-02-28 06:51:15 counters for TRANS since 2010-02-14 13:46:54
Elapsed time 13-17:04:21.290242
From \A.$TEST04.GGSSOU.ECUSTMER to \A.$TEST04.GGSTAR.HCUSTMER:
            #  inserts:         3
            #  updates:         1
            #  deletes:         0
            # discards:         0
From \A.$TEST04.GGSSOU.ECUSTORD to \A.$TEST04.GGSTAR.HCUSTORD:
            #  inserts:         3
            #  updates:         3
            #  deletes:         2
            # discards:         0

1.5 Logger Commands

Use Logger commands to configure Logger for extracting data changes from non-TMF applications.

Logger processes default to a prefix of $GGL. To change these default settings, see Change Synchronization for Non-TMF Applications.

Note:

The oldformat parameter is deprecated. When you add a logger command with the oldformat as a parameter in the PARAM file, then a warning is displayed. In the GGSCI command prompt, enter INFO command to see the new format instead of the old format. New is the parameter that gets updated under the Trail Format.

1.5.1 ADD LOGGER

Use ADD LOGGER to configure GGSLIB and Logger. By default, ADD LOGGER reads a parameter file called GGS_volume.GGSPARM.LOGPARM. Before invoking ADD LOGGER, edit LOGPARM to enter the appropriate parameters. See "Logger Parameters Summary" for information about the parameters you can enter into this file.

To bind GGSLIB to the application, see "Programs commands".

Syntax

ADD LOGGER [, PARAMS param_file_name]

PARAMS param_file_name: Use the PARAMS option to indicate a different parameter file name.

ADD LOGGER performs the following:

Validates the configuration parameters for Logger.
Creates a segment file containing parameters used by GGSLIB intercept library routines. These parameters tell the intercepts where to send logged information (that is, which Loggers should receive it).

The default segment file is $SYSTEM.GGS.AUDCFG. It is strongly recommended that you use the default location. If you must use a different location (such as for running multiple occurrences of the Oracle GoldenGate environment), see Changing Default Component Names.

If the segment file exists at the time ADD LOGGER is issued, GGSCI renames the existing segment and issues a message informing you the existing AUDCFG is renamed.
Creates log trail files and pre-allocates space for the log trails. GGSCI has a limit of 200 log trails per Logger process. The maximum number of Logger processes per instance is 50.
Updates the GGS database to recognize the Loggers and configuration parameters.

1.5.2 ALTER LOGGER

Use ALTER LOGGER to change parameters for an existing Logger process. As with the ADD LOGGER command, ALTER LOGGER reads and validates the parameters in LOGPARM and pre-allocates log trail files.

Syntax

ALTER LOGGER [, PARAMS param_file_name]

PARAMS param_file_name: Use the PARAMS option to indicate a different parameter file name.

Configuration segment files are aged every time ALTER LOGGER is invoked (AUDCFG00, AUDCFG01, and so on). If the segment file exists at the time ALTER LOGGER is issued, GGSCI renames the existing segment and issues a message informing you the existing AUDCFG is renamed. ALTER LOGGER renames up to 99 files.

Logger parameter changes take effect immediately. Altering Logger parameters while Logger or Replicat processes are running requires careful consideration. In particular, consider the situation in which a file set is switched from one Logger to another.

If you execute commands for ALTER LOGGER that change what files are logged to which Logger process, expect to see a message similar to the following:

14-11-12;12:23:28:22.964 \NY,3,28      ORACLE.1.H06            512
             FILE \NY.$DATA04,TEST1.ABC switched to logger \NY.$KK00

1.5.3 DELETE LOGGER

Use DELETE LOGGER to delete the internal Oracle GoldenGate Logger configuration files created when you entered ADD LOGGER.

Optionally, you can also delete the Logger trails with the ! (exclamation point) option. Before executing this option, ensure that all of the data has been processed out of the trail.

Syntax

DELETE LOGGER [!]

!: The exclamation point (!) deletes files from the associated log trail. The log trails associated with the process must be manually deleted if you omit the exclamation point or they will still exist.

1.5.4 INFO LOGGER

Use INFO LOGGER to retrieve the following information about Logger:

The location of the shared configuration segment used by GGSLIB
The date Logger was added and the location of the parameter file used to create it
The settings for timeout and debug, and whether logging is currently on
Which sequence number Logger currently has open for each Logger process
The location of the trail used by each Logger process
Whether each Logger process in the group is running
CPU, BACKUPCPU and PRIORITY values for each process
Configured flushing and tracing parameters
The block size used to write the trail
Whether the trail is version 7 format (New) or the format from before version 7 (Old)
FILE entries for each Logger process, along with the settings for the following FILE configuration options for each file
- Whether the image is compressed for updates
- Whether TMF audited file changes are logged
- Whether unstructured file changes are logged
- Whether Logger includes bulk I/O updates
- The delay interval to detect and record a new name
- The Log Mode of the file (suspended or active)

Syntax

INFO LOGGER 
[, AUDCFG segment_file] 
[, SHOWLOGGED file_name 
[, PROGRAM program_set | PROCESS process_set | USER user_set]]
[, BRIEF]

AUDCFG segment_file

Determines the parameters for any configuration, including the current one. Configuration segment files are aged every time ALTER LOGGER is invoked (AUDCFG00, AUDCFG01, and so on).

BRIEF

Limits the INFO LOGGER display to information about the SHOWLOGGED file name.

SHOWLOGGED file_name

Lets you determine which log process, if any, is capturing a particular file. Specify the file name or wildcard file set. Whether the file is included, excluded or omitted for each Logger is displayed.

If you specify SHOWLOGGED, you can also detect whether a file is included or excluded according to one of the following:

PROCESS process_set: Directs Logger to extract data only when the opener is the process or set of processes specified. (The process set can be a single process or a wildcard, for example $APP*.)
PROGRAM program_set: Directs Logger to extract data only when the opener is the program or set of programs specified. (The program set can be a single program or a wildcard, for example $DATA1.PROGS.*.)
USER user_set: Directs Logger to extract data only when the creator access ID of the opener is the user specified. (The user set can be a single user, for example FINANCE.JOE, or a wildcard, for example SUPER.*.)

Example

Sample results from an INFO LOGGER command:

Information for Logger Group $GGL

Intercept segment file \NY.$SYSTEM.GGS.AUDCFG
Created  2010-10-21 11:24
Built from \NY.$DATA01.GGSPARM.LOGPARM
Logger timeout: 60.00 seconds
Debug on stack check: Off
Current mode: Logging is ON

  Process:        $GGL49
  Log Trail:      \NY.$DATA01.LOGGER.ET000013
  Status:         DOWN
  CPUs:           2,3
  Priority:       170
  Logopens:       16
  Flush recs:     16
  Flush secs:     0.85
  Trace IOs:      Off
  Trace Stats:    Off
  Heartbeat:      Off
  AdjustPriority: On
  BlockSize:      57344
  TrailFormat:    New
  SourceAppInfo:  Included
  Logger Timeout: 60.00 seconds
                                   Comp   Unstr TMF    Bulk  Rename Log
  Files                            Updts  Files Files  IO    Delay  Mode
  \NY.$D*.*.*                       No     Yes    No     Yes   No     Normal

1.5.5 SEND LOGGER

Use SEND LOGGER to communicate with one or more running Logger processes.

Syntax

SEND LOGGER 

[, PROCESS process_name]
[, ADJUSTPRIORITY | NOADJUSTPRIORITY]
[, ROLLOVER]
[, REFRESH]
[, PROCESSINFO [, DETAIL]]
[, LOGFILECLOSEDELAY seconds]
[, LOGINFO]
[, FLUSHSTATS
   [, FILTERPROCESS process_name | 
      FILTERPROGRAM program_name | 
      FILTERLIBRARY library_name] | 
   [, RESET]]
[, GETSTATS 
   [, FILTERPROCESS process_name | 
      FILTERPROGRAM program_name | 
      FILTERLIBRARY library_name] | 
   [, RESET]]
[, GETLOGFILECLOSEDELAY]
[, HOTSWAP object_name]

PROCESS process_name

Sends to the named process. Otherwise, the command is sent to all Logger processes in the default Logger group ($GGL*).

ADJUSTPRIORITY | NOADJUSTPRIORITY

Determines how Logger adjusts its priority in relation to the sender priority.

Logger checks at 1 minute intervals to determine if there was a high priority sender during the previous interval. If not, by default, Logger sets its priority back down to the original value.

To retain the value set by the sender, specify ADJUSTPRIORITY, as in:

GGSCI SEND LOGGER, ADJUSTPRIORITY

If NOADJUSTPRIORITY is in effect Logger does not increase its priority to match that of a higher priority sender.

ROLLOVER

Instructs Logger to move to the next log file in the log trail sequence.

REFRESH

Instructs Logger to read its LOGCONF record to pick up configuration option changes.

PROCESSINFO

Instructs Logger to return input and output statistics, lag, and other information to the screen. Optionally, include DETAIL to report process details.

LOGFILECLOSEDELAY

Sets the time to delay closing the old file when rolling to a new one. Logger starts the timer, writes to the new file and closes the old file when the timer is reached or when it rolls to another new file. The default value is 120 seconds.

LOGINFO

Displays information on Logger's current log file.

FLUSHSTATS

Instructs Logger to output current process statistics to the log trail. Optionally, include RESET to reset all statistics counters to zero.

You can specify one of the following filters per SEND LOGGER FLUSHSTATS command.

FILTERPROCESS process_name
FILTERPROGRAM program_name
FILTERLIBRARY library_name

These allow you to restrict flushed information to the specified process, program, or library. The name is the specified process, program, library, or a wildcard. Use only one of these options.

GETSTATS

Outputs current process statistics to the screen.

If you specify GETSTATS, you must specify either TRACESTATS or TRACEPROCESSIOS in the Logger parameter file.

Optionally, include RESET to reset all statistics counters to zero.

You can specify one of the following filters per SEND LOGGER GETSTATS command.

FILTERPROCESS process_name
FILTERPROGRAM program_name
FILTERLIBRARY library_name

These allow you to restrict flushed information to the specified process, program, or library. The name is the specified process, program, library, or a wildcard. Use only one of these options.

GETLOGFILECLOSEDELAY

Outputs the current value for LOGFILECLOSEDELAY.

HOTSWAP object_name

Instructs Logger to use the specified object file. Allows a running Logger to be changed to a different Logger object.

Caution: The HOTSWAP command must be performed with the manual steps used to upgrade BASELIB as part of the upgrade process.

1.5.6 START LOGGER

Use START LOGGER to start a group of Logger processes. By default, this group is $GGL. If some log processes are running, START LOGGER begins the ones that are down.

Syntax

START LOGGER [, NAME process_name]

NAME process_name: The name of the Logger process, such as $GGL. To start a particular process within the group name specify the full name of the process, such as $GGL01.

1.5.7 STATUS LOGGER

Use STATUS LOGGER to obtain process status for the specified Logger process.

Syntax

STATUS LOGGER [,NAME process_name]

NAME process_name: Provides the status of a particular process within the group, such as $GGL01.

1.5.8 STOP LOGGER

Use this command to stop a group of Logger processes. By default, this group is $GGL.

If some log processes are down, STOP LOGGER brings down the remainder. Use this command cautiously, since no data is logged while log processes are down. When issuing this command, you will be prompted to specify whether you want to continue.

Use STOP LOGGER instead of stopping log processes individually from TACL. By default, Manager restarts log processes stopped from TACL.

Syntax

STOP LOGGER [, NAME process_name] [!]

NAME process_name: To stop a particular process within the group, specify the full name of the process (for example, $GGL01).
!: When you issue STOP LOGGER, with or without options, you are prompted to confirm the operation. To override the prompt, include ! (exclamation point) in the command argument.

1.6 Trail commands

Trail commands allow you to create and associate a sequence of local or remote trails with a particular Extract group. This is particularly useful in online processing to purge or transfer old Oracle GoldenGate trails without bringing down the associated Extract process.

Use RMTTRAIL commands to create and manage trails on remote systems, and use commands to create and manage local Oracle GoldenGate trails.

1.6.1 ADD EXTTRAIL

Use ADD EXTTRAIL to create a local trail, associate it with an Extract group, and assign trail attributes. If the trail already exists, GGSCI rejects the ADD command.

Syntax

ADD EXTTRAIL trail_name, EXTRACT group_name 
[, OWNER group_number, user_number] [, SECURE "rwep"]
[, EXTENTS (primary, secondary, maximum) | MEGABYTES number]
[, MAXFILES num_files]
[, SEQNO number],
[, CREATE | NOCREATE]]

trail_name

The fully qualified trail name: $vol.subvol.trail_prefix. The trail_prefix must be two characters long. Each file in the trail is automatically identified by the prefix and a six-digit serial number. The parameter file for group_name must have a matching trail_name parameter.

EXTRACT group_name

Specifies the Extract group to which the is bound. Only one group can write to an associated trail.

EXTENTS (primary, secondary, maximum) | MEGABYTES number

See "Specifying file size".

MAXFILES num_files

See "Specifying a maximum number of files".

OWNER group_number, user_number SECURE "rwep"

See "Specifying security".

SEQNO number

See "Specifying sequence number".

See Ongoing Trail Managementfor more information on managing trails.

CREATE | NOCREATE

To specify whether the file is created, see "Using a Local Oracle GoldenGate Trail"".

Specifying file size

Control file size with one of the following options:

Use the EXTENTS primary, secondary, maximum option to specify extent sizes for individual trails. Default extent sizes are 64, 128 and 512.
Use the MEGABYTES number option to specify the maximum number of megabytes per file in the trail. The default is 134 megabytes, and the maximum is 2000. To allow the Extract ROLLOVER parameter to determine when new files are created, set number to a large number, such as 1000 megabytes.

Examples

Example 1

This example adds a trail with a maximum size of 300 megabytes.

ADD EXTTRAIL $DATA.GGSDAT.EX, EXTRACT FINANCE, MEGABYTES 300

Example 2

This example adds a trail with the extents set to 10 for primary and secondary and 16 for the maximum.

ADD EXTTRAIL $DATA1.EXTDAT.EX, EXTRACT FINANCE, EXTENTS (10,10,16)

Specifying a maximum number of files

Use the MAXFILES num_files option to specify the maximum number of files that can exist in a trail. The default for MAXFILES is 100.

Example

This example adds a trail with a maximum of 20 files.

ADD EXTTRAIL $DATA1.EXTDAT.EX, EXTRACT FINANCE, MAXFILES 20

Specifying security

Specify security measures to restrict access to Oracle GoldenGate trails. If you do not specify security, the defaults are assumed.

Use OWNER group_number, user_number to specify the NonStop group ID and user ID of the person who started the GGSCI process.
Use SECURE "rwep" to specify the default Guardian security attributes (read, write, execute, purge) of the person who started the GGSCI process.

Example

This example specifies a trail that is owned by user 100, 23 and can be read by anyone in the network in group 100.

ADD EXTTRAIL $DATA1.EXTDAT.EX, EXTRACT FINANCE, OWNER 100,23, SECURE "CUUU"

Specifying sequence number

Specify the trail sequence number for the first file in the trail. Do not include any zero padding.

Example

The following example specifies that the first file in the trail will be ex000003.

ADD EXTTRAIL $DATA1.EXTDAT.EX, EXTRACT FINANCE, SEQNO 3

Use SEQNO during troubleshooting when Replicat must be repositioned to a certain trail sequence number. This eliminates the need to alter Replicat to read the required sequence number.

1.6.2 ADD RMTTRAIL

ADD RMTTRAIL creates a remote Oracle GoldenGate trail on a remote system, assigns a maximum size to each file, and associates the file with a particular group. Rolling over from one sequence to the next can be controlled using the maximum size allowed, or by using the EXTRACT ROLLOVER startup parameter or ETROLLOVER option of the GGSCI ALTER EXTRACT command.

In the parameter file, specify a RMTHOST entry before any RMTTRAIL entries to identify the remote system and TCP/IP port.

Syntax

ADD RMTTRAIL trail_name, EXTRACT group_name 
[, MEGABYTES number]
[, SEQNO number]

trail_name

The fully qualified trail name: $vol.subvol.trail_prefix. The trail_prefix must be two characters long. Each file in the trail is automatically identified by the prefix and a six-digit serial number. The trail_name must have a matching entry in the Replicat parameter file.

The name you specify here must be the same name you specify for the RMTTRAIL parameter in the Extract parameter file.

Remote trails are used over TCP/IP connections only. Do not use when you are transmitting a trail over Expand even when the remote system is also connected with Expand. To specify a trail on a different NonStop node over an Expand connection, use ADD .

EXTRACT group_name

The group to which the RMTTRAIL is bound. Only one group can output extracted data to each trail.

MEGABYTES number

Optional. The maximum number of megabytes per file in the trail. The default is 30 megabytes and the maximum is 2000. To allow the Extract ROLLOVER parameter to determine when new files are created, set number to a large number, such as 1000 megabytes.

SEQNO number

Optional. Specifies the trail sequence number for the first file in the trail. Do not include any zero padding. Use SEQNO during troubleshooting when Replicat must be repositioned to a certain trail sequence number. It eliminates the need to alter Replicat to read the required sequence number.

Examples

Example 1

The following example illustrates how to add three remote Oracle GoldenGate trails; the first trail residing on UNIX, the second on a Windows platform, and the third on NonStop.

ADD RMTTRAIL /usr/extdat/xx, EXTRACT FINANCE, MEGABYTES 30
ADD RMTTRAIL c:\ggsdat\ex, EXTRACT FINANCE, MEGABYTES 30
ADD RMTTRAIL $DATA.GGSDAT.RT, EXTRACT FINANCE, MEGABYTES 30

Example 2

The following example specifies that the first file in the trail will be rt000003.

ADD RMTTRAIL $DATA1.GGSDAT.RT, EXTRACT FINANCE, SEQNO 3

1.6.3 ALTER EXTTRAIL

ALTER EXTTRAIL changes attributes for an existing .

Syntax

ALTER EXTTRAIL trail_name, [, options]

trail_name

options

ALTER can be used with the following options:

EXTENTS (primary, secondary, maximum) | MEGABYTES number
MAXFILES num_files
OWNER group_number, user_number SECURE "rwep"

SEQNO is not a valid option for ALTER .

Example

ALTER  $DATA1.EXT1.AA, MAXFILES 50

1.6.4 ALTER RMTTRAIL

ALTER RMTTRAIL changes attributes for an existing RMTTRAIL.

Syntax

ALTER RMTTRAIL trail_name [, MEGABYTES number]

trail_name

The fully qualified name of the remote trail: $vol.subvol.trail_name. A six-digit serial number will be appended to each file in the trail.

Remote trails are used over TCP/IP connections only. Do not specify an Expand node name in the trail_name, even if the remote system is also connected with Expand. To specify a trail on a different NonStop node over an Expand connection, use ADD .

MEGABYTES number

The maximum number of megabytes per file in the trail. The default is 30 megabytes, and the maximum is 2000. To allow the Extract ROLLOVER parameter to determine when new files are created, set number to a large number, such as 1000 megabytes.

1.6.5 DELETE EXTTRAIL

DELETE EXTTRAIL deletes checkpoints for a specified trail. It does not delete the trail or the files in the trail.

Syntax

DELETE EXTTRAIL  trail_name [!]

trail_name

The fully qualified trail name: $vol.subvol.trail_prefix, or a wildcard specification, as in:

DELETE EXTTRAIL $DATA1.EXTDAT.AA
DELETE EXTTRAIL *

!

(exclamation point) Deletes trail files associated with each group.

1.6.6 DELETE RMTTRAIL

DELETE RMTTRAIL deletes checkpoints for a particular remote trail. It does not delete the files in the remote trail.

Syntax

DELETE RMTTRAIL trail_name

trail_name

The fully qualified name of the remote Oracle GoldenGate trail as in: DELETE RMTTRAIL /usr/dat/aa. A six-digit serial number will be appended to each file in the trail.

Remote trails are used over TCP/IP connections only. Do not specify an Expand node name in the trail_name, even if the remote system is also connected with Expand.

1.6.7 INFO EXTTRAIL

INFO EXTTRAIL retrieves configuration information about the trail.

Syntax

INFO EXTTRAIL trail_name

trail_name

The fully qualified trail name: $vol.subvol.trail_prefix, or a wildcard specification, as in:

INFO EXTTRAIL $DATA1.EXTDAT.AA
INFO EXTTRAIL*

1.6.8 INFO RMTTRAIL

INFO RMTTRAIL retrieves configuration information for the remote trail.

Syntax

INFO RMTTRAIL trail_name

trail_name

The name of the Oracle GoldenGate trail. trail_name must be a fully qualified file name, as in:

INFO RMTTRAIL $DATA6.GGSDAT.BB

Remote trails are used over TCP/IP connections only. Do not specify an Expand node name in the trail_name, even if the remote system is also connected with Expand. Use INFO instead.

1.7 Database commands

Use database commands to get information about data definitions and tables.

1.7.1 CAPTURE TABLEDEFS

CAPTURE TABLEDEFS returns information for SQL tables and for Enscribe files when you provide a DICTIONARY name and RECORD definition name.

Syntax

CAPTURE TABLEDEFS file_name
[, DICTIONARY volume.subvol]
[, RECORD record_name]
[, OPTIONS command_line_options]

file_name

The fully qualified name of the file or table.

DICTIONARY volume.subvol

The volume and subvolume of the Enscribe dictionary. Required for Enscribe files.

RECORD record_name

The name of the record definition within the Enscribe dictionary. Required for Enscribe files.

OPTIONS command_line_options

Valid DEFGEN command-line options. See the chapter on DEFGEN arguments for more information.

Note:

If the OPTIONS argument contains EXPANDDDL parameters, then it overrides the default EXPANDDDL parameters. Currently the default EXPANDDDL parameters are:

EXPANDDDL 
EXPANDGROUPARRAYS 
NOFIXLONGNAMES 
MAXCOLNAMELEN 130

Example

CAPTURE TABLEDEFS \PROD.$DATA1.ACCTS.KEYSEQ

The result of the example command is the following display:

Definition for table \PROD.$DATA1.ACCTS.KEYSEQ 
Record length: 198 
Syskey: 0 
Columns: 13 

   TS           LARGEINT  PK
   RECNUM       INT       PK
   SYSNAME      CHAR      (8)
   TEXT         CHAR      (64)
   VAL1         LARGEINT
   VAL2         LARGEINT
   COL_COMPUTE  LARGEINT
   I16          SMALLINT
   I32          INT
   I64          LARGEINT
   I32_TOTAL    INT
   JTS          LARGEINT
   JTS_TEXT     CHAR      (64)

1.7.2 ENCRYPT PASSWORD

Use ENCRYPT PASSWORD to encrypt a login password for an Oracle GoldenGatedatabase user and, optionally, supply an encryption key for password lookup. This encryption method defaults to BLOWISH and cannot be changed at this time. To specify the encrypted password in a parameter file, use the LOGON parameter (see "LOGON").

For more information about Oracle GoldenGate security, see Encrypting a Database Password.

Syntax

ENCRYPT PASSWORD password [ENCRYPTKEY {DEFAULT | keyname}]

password

The login password. The encrypted password is output to the screen. You can copy the encrypted password and paste it into the LOGON parameter in a parameter file.

ENCRYPTKEY {DEFAULT | keyname}

Optional, specifies one of the following:

DEFAULT: Specifies a default encryption key that is randomly generated by Oracle GoldenGate and automatically decrypted on the target system.
keyname: Specifies an encryption key contained in the ENCKEYS lookup file. Oracle GoldenGate uses the key name to look up the actual password in the file. To use the keyname option, you must create the ENCKEYS file on each system (if it does not exist) and create entries in the file for the keys.

Example

ENCRYPT PASSWORD ny14072 ENCRYPTKEY superkey2

1.7.3 INFO DDLDEFS

Use INFO DDLDEFS to retrieve information for Enscribe data dictionary definitions.

Syntax

INFO DDLDEFS def_name [, DDLDEFS def_name,...,] 
DICT subvolume 
[, DEFSONLY | RECSONLY]

def_name: The name of a DDL definition or record. You can specify def_name multiple times to display multiple definitions or records. Wildcards are accepted.
DICT subvolume: The subvolume in which the dictionary is located.
DEFSONLY: Specifies that GGSCI should return only definitions, not records.
RECSONLY: Specifies that GGSCI should return only records, not definitions.

Example

This example lists each DDL record or definition which begins with ACC, or which ends in REC from the dictionary located in $DATA3.MYDICT.

INFO DDLDEFS ACC*, DDLDEFS *REC, DICT $DATA3.MYDICT

1.7.4 INFO FILES

Use INFO FILES to retrieve information about files or tables on the system; then filter the resulting list according to different criteria.

Syntax

INFO FILES file_name, [FILES file_name,...]
[,TMF | 
NONTMF | 
ENSCRIBE | 
SQL | 
EXCLUDELASTDIGIT |
CODE file_code | 
TANDEMFILES | 
UNSTRUCT]

file_name: A file name or wildcard specification. Multiple entries of file_name are allowed.
TMF: Returns TMF audited files.
NONTMF: Returns files not audited by TMF.
ENSCRIBE: Returns Enscribe files.
SQL: Returns NonStop SQL tables.
EXCLUDELASTDIGIT: Excludes file names which end in a digit. Use EXCLUDELASTDIGIT to filter out alternate key files that end in a digit.
CODE file_code: Returns files with file_code only. Multiple entries of CODE are allowed.
TANDEMFILES: Returns NonStop files (file codes between 1 and 1000) only.
UNSTRUCT: Restricts the list to unstructured files.

1.8 Audit trail commands

Use ATCONFIG commands to protect TMF audit trails until Extract has processed them. Manager uses ATCONFIG commands to determine how to preserve audit files that are needed by Extracts.

The ATCONFIG command specification can be abbreviated as AT.

For details about managing audit resources, see Keeping Necessary Audit Available for Extract.

1.8.1 ADD ATCONFIG

Use ADD ATCONFIG to configure audit management options. With the ADD ATCONFIG options, you can:

Duplicate to an alternative subvolume
Duplicate all audit files or a specified number of files
Purge audit trails from the alternative subvolume

You can override any previously specified option by adding NO, as in NO PURGE.

Note:

Contact Oracle GoldenGate support before using the DUP, DUPFILES, or PURGE options. These options require storage that is not necessary if large enough audit trails can be specified when TMF is configured.

Syntax

ADD ATCONFIG at_name
[, ALTLOC alt_subvolume] 
[, DUP | NO DUP | 
DUPFILES num_files | NO DUPFILES | 
PURGE | NO PURGE]

at_name

The audit trail designation, that is MAT, AUXnn. The audit trail can also be expressed as a wildcard.

ALTLOC alt_subvolume

Identifies an alternative subvolume to which audit trails are duplicated or restored from tape. ALTLOC directs Extract to read audit from the alternative subvolume rather than from the production area.

Specify up to seven characters for the volume name.

DUP | NODUP

Duplicates audit files to the volume specified by ALTLOC. DUP has no effect if the file already exists as a TMF disk dump. DUP copies audit files that are still needed by an Extract group.

DUPFILES num_files | NO DUPFILES

Duplicates up to num_files audit files to the volume specified by ALTLOC. Unlike DUP, DUPFILES limits the number of files that can be copied to the alternative subvolume. When num_files is reached on the alternative subvolume, the oldest audit file is purged to make room for the newest file. Enter ALTLOC when this option is used.

PURGE | NOPURGE

Purges audit trails from the alternative subvolume when they are no longer needed. PURGE has no effect when DUPFILES is specified since DUPFILES keeps a constant number of backup files.

Example

The following examples show the MAT trail being added and an AUX trail being altered.

ADD AT MAT DUPFILES 6, ALTLOC $DATA1.ALTTMF
ALTER AT AUX01, ALTLOC $DATA1.EXTRACT, PURGE, DUP

1.8.2 ALTER ATCONFIG

Use ALTER to change existing audit trail configuration parameters.

Syntax

ALTER ATCONFIG at_name
[, ALTLOC alt_subvolume] 
[, DUP | NO DUP | 
DUPFILES num_files | NO DUPFILES | 
PURGE | NO PURGE]

See the ADD ATCONFIG command for option descriptions.

1.8.3 DELETE ATCONFIG

Use DELETE ATCONFIG to delete audit management configuration. After this command is carried out, Manager will not manage the associated audit trails.

Syntax

DELETE ATCONFIG at_name

at_name: The audit trail designation, that is MAT, AUXnn. The audit trail can also be expressed as a wildcard.

1.8.4 INFO ATCONFIG

Use INFO ATCONFIG to view processing information about audit trails that are defined by ADD ATCONFIG or ALTER ATCONFIG.

Syntax

INFO ATCONFIG at_name

at_name: The audit trail designation, that is MAT, AUXnn. The audit trail can also be expressed as a wildcard.

1.8.5 STATUS AUDITTRAIL

Use STATUS AUDITTRAIL to determine which audit trail files are still required by any Extract group. This command determines if a file exists, then supplies:

The location of the file.
Whether it is the original audit file (ORIG), a duplicate audit file (DUP), or a dump (DUMP).
Whether the file is on tape or disk. If audit is on tape, this provides the information needed to restore dumps before processing — useful when an operator is not available while Extract processes are running.

Syntax

STATUS AUDITTRAIL at_name

at_name: The audit trail designation, that is MAT, AUXnn. The audit trail can also be expressed as a wildcard.

1.9 Remote checkpoint commands

Use REMOTECHKPT when both of the following apply:

The Manager process is configured to perform local trail maintenance using checkpoints
The local trail is being processed by programs on remote systems

If the PURGEOLDEXTRACTS parameter is set, Manager periodically examines checkpoint files and purges files that satisfy the rules of the PURGEOLDEXTRACTS parameter.

1.9.1 ADD REMOTECHKPT

Use ADD REMOTECHKPT to tell Manager where to find checkpoints for Extract or Replicat processes running on remote systems. The Replicat checkpoint file is called REPCTXT and exists in the same subvolume where Oracle GoldenGate is installed, as in:

ADD REMOTECHKPT \NY.$DATA5.GGS.REPCTXT

Syntax

ADD REMOTECHKPT checkpoint_file

checkpoint_file: The checkpoint file to examine. The file name must include the remote node name.

1.9.2 DELETE REMOTECHKPT

DELETE REMOTECHKPT deletes a remote checkpoint reference.

Syntax

DELETE REMOTECHKPT checkpoint_file

checkpoint_file: The checkpoint file to examine.

1.9.3 INFO REMOTECHKPT

INFO REMOTECHKPT lists all remote checkpoint references.

Syntax

INFO REMOTECHKPT checkpoint_file

checkpoint_file: The checkpoint file to examine. You can specify a wildcard, as in INFO REMOTECHKPT *.

1.10 TMF commands

You can issue TMF commands for managing TMF dump information.

1.10.1 REFRESHTMFINFO

Forces the TMF information to be refreshed.

Syntax

REFRESHTMFINFO

1.10.2 TMFDUMPAGE

Specifies the number of days during which information will be returned for dumps that are created. The information returned by TMFDUMPAGE is limited to dumps that are created during the specified number of days.

Syntax

TMFDUMPAGE num_days

num_days: The number of days for limiting TMF dump information. The default is 30 days.

1.10.3 TMFDUMPINFO

TMFDUMPINFO returns information about TMF dumps on the local system.

Syntax

TMFDUMPINFO

1.10.4 TMFDUMPTABLEENTRIES

TMFDUMPTABLEENTRIES limits information returned by TMFDUMPINFO to the number of specified dumps.

Syntax

TMFDUMPTABLEENTRIES max_dumps

max_dumps: The number of dumps to display. The maximum allowed is 6000. The default is 1024 entries.

1.10.5 TMFREFRESHINTERVAL

Sets the refresh interval in seconds and writes reports to ENV. When you set a refresh interval for GGSCI, it overrides the TMFREFRESHINTERVAL that may have been specified in the GLOBALS, Manager, or Extract parameter files. The override remains in effect for the duration of the current GGSCI session.

Syntax

TMFREFRESHINTERVAL seconds

seconds: The refresh interval in seconds. The default is 15 minutes or the value set in the GLOBALS parameter file.

1.10.6 TMFTRAILINFO

Use TMFTRAILINFO for diagnostic and informational purposes. Running TMFTRAILINFO will print information retrieved about the audit trails, such as the current active trail name and its enabled options.

Syntax

TMFTRAILINFO

Example

Sample output from a TMFTRAILINFO command:

\PROD.$AUDIT.ZTMFAT.AA 
MinFiles 2, MaxFiles 5, Auditdump On 
Active Vols $AUDIT 
Restore Vols $DATA11 
\MASTER.$DATA11.ZTMFAT.BB 
MinFiles 2, MaxFiles 5, Auditdump On 
Active Vols $DATA11 
Restore Vols $AUDIT

1.11 Coordinator commands

Use Coordinator commands to establish a Coordinator group to monitor distributed network transactions. COORD is an alias for COORDINATOR in these commands.

1.11.1 ADD COORDINATOR

Use ADD COORDINATOR to add the process that will communicate with each node's Reader and Replicat processes to coordinate the application of distributed network transactions.

Syntax

ADD COORDINATOR group_name
[, CPU primary_cpu] 
[, BACKUPCPU cpu] 
[, PRI priority]
[, PROCESS process_name] 
[, PARAMS param_file_name] 
[, PROGRAM program_name] 
[, REPORT report_name] 
[, DESC "text"]

group_name: The group name.
CPU primary_cpu: The primary CPU on which Coordinator runs. The default is the CPU on which Manager runs.
BACKUPCPU cpu: An alternative CPU on which Coordinator runs if the primary CPU becomes unavailable.
PRI priority: The NonStop priority for the process. This defaults to the NonStop priority assigned to the TACL process underlying the ADD.
PROCESS process_name: The default process name is $GGCnn, 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.
PARAMS param_file_name: Specifies the alternative parameter file name to be used. Enter the fully qualified path name for the parameter file.
PROGRAM program_name: Specifies the name of the program that Manager assigns when starting the process. Typically this is not entered, and Manager uses the default $GGCnn name. The HOST parameter in the GLOBALS file determines the location of the default program.
REPORT report_name: Supplies an alternative report file name. The default report file name is install_volume.GGSRPT.rpt_name, where rpt_name represents the group name, such as FINANCE. Oracle GoldenGate creates an entry-sequenced file to hold each group's run results, and by default, the report name is the same as the group name.
DESC "text": Describes the Coordinator group.

Example

ADD COORDINATOR TRXCO, CPU 2, PRI 150, DESC "Network transaction coordinator for NY, FL, and LA"

1.11.2 ALTER COORDINATOR

Use ALTER COORDINATOR to change the checkpoints for an or to change the properties of an existing Coordinator group. You can use ALTER COORDINATOR to change the attribute of any option that you specified with ADD COORDINATOR.

Syntax

ALTER COORDINATOR group_name
[ trail_name
{BEGIN time |, EXTSEQNO seq_number, EXTRBA rba}]
[, options]

group_name: The group name.
| SOURCE {BEGIN time | , EXTSEQNO seq_number , EXTRBA rba}: Specifies the starting point in the Oracle GoldenGate trail as a beginning time, transaction sequence, or relative byte address. The specified must match one of the trails defined in the Coordinator parameter file.
options: The ADD COODINATOR options can be altered with this command. See ADD COORDINATOR for details.

Example

ALTER COORDINATOR TRXCO, CPU 1, PRI 180

1.11.3 DELETE COORDINATOR

Use DELETE COORDINATOR to remove a stopped Coordinator process from the system. DELETE COORDINATOR group_name removes the group and all checkpoints. Using the trail_name option deletes only the trail checkpoints, not the group.

Syntax

DELETE COORDINATOR group_name
[ trail_name]

group_name: The group name. Using this option without the deletes the group and all trail checkpoints.
trail_name: Deletes only the checkpoint.

Example

DELETE COORDINATOR TRXCO

1.11.4 INFO COORDINATOR

Use INFO COORDINATOR to display information on the attributes of the Coordinator.

Syntax

INFO COORDINATOR group_name
[, DETAIL]
[, SHOWCH]
[, PROGRAM]

group_name

The group name.

DETAIL

Reports Coordinator process run history, which includes starting and stopping points within the trail expressed as a time and the process parameters established by the ADD COORDINATOR command.

The default is to report the status of the Coordinator process (STARTING, RUNNING, STOPPED or ABENDED).

SHOWCH

Shows detailed historical checkpoints.

PROGRAM

Displays the name and location of the object that is running.

Example

The following is displayed from the command INFO COORD TRXCO

Coord   TRXCO         Last Started 2010-12-01 15:59  Status RUNNING
Process  $GGC00       Checkpoint Lag: unknown
Checkpoints:
    Trail                  Time                         Seqno         RBA
\NY.$DATA1.GGSDAT.Z1    Updated at 2010-12-01 16:00:22.950722
                          2010-11-17 12:22:46.657637       0            0
                          2010-11-17 12:22:46.657637       0         1779
\LA.$DATA1.GGSDAT.EX    Updated at 2010-12-01 16:00:22.950722
                          2010-12-01 15:55:39.664490       0            0
                          2010-12-01 16:00:11.437578       3    148578373

1.11.5 SEND COORDINATOR

Use SEND COORDINATOR to send a command to a running Coordinator process. Using SEND COORDINATOR you can perform the operations summarized in the table below.

Syntax

SEND COORDINATOR group_name {
GETREADERINFO | 
GETTRANSINFO |
FORCECOMMIT transaction_id |
STATUS |
STOP}

group_name

The group name.

GETREADERINFO

Displays information about the Reader processes and the trails being read.

GETTRANSINFO

Displays information on pending transactions.

FORCECOMMIT transaction_id

Allows the transaction to be committed even though not all required trails have received the entire transaction. If a network connection is lost, for example, the parts of the transaction that are available can be committed.

Note: The ramifications of committing the partial transaction should be considered carefully before using FORCECOMMIT.

STATUS

Displays the current status of the Coordinator process.

STOP

Terminates the run gracefully. This command is preferable to stopping from TACL, which results in an ABEND status.

Examples

Example 1

An example of a display from SEND COORD TRXCO GETTRANSINFO:

  279: 0 TransID 7926335489872297987  2010/11/17 12:22:47.068460
     Pending, Needed 2, Found 1, RefCount 1
     Bitmap 8000 0000 0000
  813: 0 TransID 7926335489872232451  2010/11/17 12:22:46.947382
     Pending, Needed 2, Found 1, RefCount 1
     Bitmap 8000 0000 0000
  825: 0 TransID 7926335489872363523  2010/11/17 12:22:47.317281
     Pending, Needed 2, Found 1, RefCount 1
     Bitmap 8000 0000 0000
  909: 0 TransID 7926335489872166915  2010/11/17 12:22:46.769463
     Pending, Needed 2, Found 1, RefCount 1
     Bitmap 8000 0000 0000
 1701: 0 TransID 7926335489872101379  2010/11/17 12:22:46.657637
     Pending, Needed 2, Found 1, RefCount 1
     Bitmap 8000 0000 0000

Example 2

An example of a display from SEND COORD TRXCO GETREADERINFO:

Reader Information
 0 : \NY.$DATA1.GGSDAT.Z1, \NY.$ZRDR1, Node 109, POS 0,1779
     FastReads  Retries 0
     Current Transactions 5
     Oldest 7926335489872101379  2010/11/17 12:22:46.657637  0,1779
     Newest 7926335489872363523  2010/11/17 12:22:47.317281  0,4280
CurTransCount      5, LastRec 2010/12/01 16:01:34.104281
 Records           14, Bytes          924, Transactions           5
 1 : \LA.$DATA1.GGSDAT.EX, \LA.$ZRDR2, Node 109, POS 4,218437395
     FastReads  Retries 0
     No Current Transactions
CurTransCount      0, LastRec 2010/12/01 16:01:36.233081
 Records           11, Bytes          704, Transactions            0
Totals
Reader Requests           21, Records           25
Commit Requests            0
Force Commit 0

Example 3

An example of a display from SEND COORD TRXCO FORCECOMMIT 7926335489872297987:

TransID '7926335489872297987' set committable

1.11.6 START COORDINATOR

Use START COORDINATOR to start the Coordinator process. GGSCI routes the START request to Manager to start and monitor the process.

START COORDINATOR uses the READER option in Coordinator parameter file to identify the Reader processes that must be started and the trails that will be monitored. The following is an example of such a file.

COORDINATOR TRXCO
FASTREADS
READER  \NY.$DATA5.GGSDAT.AA, PROCESS $GGRD1, CPU 1, PRI 180
READER  \LA.$DATA01.GGSDAT.BB, PROCESS $GGRD2
READER  \FL.$DATA2.GGSDAT.CC, CPU 1, PRI 170

In this example, starting the TRXCO Coordinator will start three Reader processes, each monitoring a trail on one of the three nodes, \NY, \LA, and \FL.

Syntax

START COORDINATOR group_name

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

Example

START COORD TRXCO

1.11.7 STATUS COORDINATOR

Use STATUS COORDINATOR to determine if the Coordinator is running. A report displays to the Coordinator process's home terminal.

Syntax

STATUS COORDINATOR group_name [, DETAIL]

group_name: The group name. You can use wildcards to specify a set of group names, such as, * or TRX*.
DETAIL: When you specify DETAIL, (STATUS COORD *, DETAIL) checkpoint details are displayed. The default is to display the group_name, the status of the process and the process name.

Example

The following is an example display resulting from the command STATUS COORD TRXCO.

COORD    TRXCO      RUNNING (\NY.$GGC00)    ( 0,616 )  (140)

1.11.8 STOP COORDINATOR

Use STOP COORDINATOR to stop the Coordinator process gracefully.

Syntax

STOP COORDINATOR group_name

group_name: The group name.

1.12 Process commands

Process commands communicate using the process name. This is useful for tasks, such as a one-time data synchronization or direct file extraction, that are set up as special runs by using the SPECIALRUN, SOUCEISFILE, or SOURCEISTABLE parameters. These processes do not require an Extract or Replicat group name and can be identified only by the process name.

1.12.1 SEND PROCESS

Use SEND PROCESS to communicate with a running process using the process name rather than the group name. Once the process is started you can:

Send commands recognized by the process
Send a WAKE or BREAK command

Syntax

SEND PROCESS process_name {text | WAKE | BREAK}

process_name: The process name in the format $identifier.
text: One of the subset of GGSCI commands that will be recognized by the process. If there is a response from the process it will be displayed by GGSCI.
WAKE: Sends the WAKE command to the process_name.
BREAK: Sends the BREAK command to the process_name.

Example

The following example sends the STATUS command to the running process $GG12.

SEND PROCESS $GG12 STATUS

GGSCI will display the response, such as the following process status:

CUSTOM: Current Status: Waiting for more audit (seqno 360, rba 1208741308)
Audit Trail position: Seqno 360, Rba 1208741308

1.13 Marker commands

Markers are records inserted into the audit trails and log trails to identify application-specific events during Extract and Replicat processing.

For example, to switch from a primary to a backup database, you must determine that all records have been delivered from the primary to the backup database before switching. Markers provide a method for determining this without shutting down all TMF-related activity on the source node.

To determine that all records have been delivered, perform the following tasks:

Shut down application activity against the source database (for example, bring down PATHWAY).
Add a marker to the audit trail.
Wait until the corresponding Replicat process writes an event message indicating that it processed the marker. At this point, Replicat has processed all data from the source database and you can safely switch to the backup database.

Event messages and history records are written each time a marker is processed by GGSCI, Extract, or Replicat.

1.13.1 ADD MARKER

You can add markers:

For TMF installations
For non-TMF installations
Executing TACL commands
For a Replicat group

Default

By default, Oracle GoldenGate applies markers to the TMF audit trail.

Syntax

ADD MARKER 
[LOGGER logger_prefix] [freeform_text] |
[TACLCMD program group_name command] |
[GROUPCMD] program group_name command ]

LOGGER logger_prefix freeform_text: See "Adding markers for TMF or non-TMF installations" for information on adding markers for TMF and non-TMF installations
TACLCMD program group_name command: See "Invoking TACL commands" for information on executing TACL commands.
GROUPCMD program group_name command: See "Adding markers for an Extract or Replicat group".

Adding markers for TMF or non-TMF installations

For TMF installations, ADD MARKER creates a marker in the local audit trail. For non-TMF installations, specify ADD MARKER with the LOGGER option.

Default

By default, Oracle GoldenGate applies markers to the TMF audit trail.

Syntax

ADD MARKER [LOGGER logger_prefix] [freeform_text]

LOGGER logger_prefix

Required to send markers to Logger processes and associated log trails. Identifies the Logger process group or an individual Logger process within a group. For example, ADD MARKER LOGGER $GGL specifies the Logger group and sends a marker to all processes beginning with $GGL. The command: ADD MARKER LOGGER $GGL01, sends a marker to the logger $GGL01.

freeform_text

Text you want added to the marker record to distinguish the purpose of the marker, as in:

ADD MARKER BROUGHT DOWN FINANCE
ADD MARKER LOGGER $GGL END OF DAY 2010-07-30

Invoking TACL commands

A special form of marker invokes TACL commands through Extract or Replicat. This lets you fit TACL commands into a stream of database activity. The command is carried out when Extract or Replicat encounters the marker record in the data stream.

Extract or Replicat end abnormally if encountering a problem issuing the command, but will not ABEND if the command itself fails. While the command runs, Extract or Replicat waits until it finishes. Specify NOWAIT as part of the command to return control immediately.

Syntax

ADD MARKER [LOGGER logger_prefix] 
TACLCMD program group_name command

LOGGER logger_prefix

Required to send markers to Logger processes and associated log trails. Identifies the Logger process group or an individual Logger process within a group. For example, ADD MARKER LOGGER $GGL specifies the Logger group and sends a marker to all processes beginning with $GGL. The command: ADD MARKER LOGGER $GGL01, sends a marker to the Logger $GGL01.

TACLCMD program group_name command

The TACLCMD keyword informs the process that a TACL command is to be carried out. TACLCMD must include the following:

program: Either EXTRACT or REPLICAT. This determines which program runs the command.
group_name: The group name to run the command. You can specify a wildcard.
command: The TACL command to invoke. This can be the name of a program, a macro or any command that can be executed from TACL.

Example

In this example, TACLCMD specifies that the command is to be invoked by Extract for the FINANCE group. The command is: FUP PURGEDATA $DATA1.DAT.FILE1

ADD MARKER TACLCMD EXTRACT FINANCE FUP PURGEDATA $DATA1.DAT.FILE1

Adding markers for an Extract or Replicat group

You can use markers to send a command to an Extract or Replicat group.

Syntax

ADD MARKER GROUPCMD program group_name command

GROUPCMD program group_name command

The GROUPCMD keyword informs the process that a group command is to be invoked.

program: Enter Extract or Replicat.
group_name: Enter the Extract or Replicat group name.
command: Enter the command. Currently, CLOSEFILES is the only command available for GROUPCMD. CLOSEFILES instructs Replicat to close all opens on Enscribe files and SQL tables. It instructs Extract to close opens from FETCHCOMPS and FETCHLASTIMAGE.

1.13.2 INFO MARKER

Use INFO MARKER to review recently processed markers. A record is displayed for each occasion on which GGSCI, Logger, Extract or Replicat processed the marker.

Syntax

INFO MARKER [COUNT num_items]

COUNT num_items: Specify COUNT to restrict the list to the most recent number of items, as in: INFO MARKER COUNT 2.

Information returned includes:

PROCESSED: The local time that a program processed the marker.
ADDED: The local time at which the marker was inserted into the audit trails or log trails.
DIFF: The time difference between PROCESSED and ADDED. DIFF can serve as an indicator of the lag between application, Extract, and Replicat activities.
PROG: The process that processed the marker, such as GGSCI, Logger, Extract or Replicat.
GROUP: The Extract or Replicat group or Logger process that processed the marker. N/A is displayed if GGSCI processed the marker.
NODE: The node at which the marker was inserted into the audit trails.
Optional text: The free text you entered in the ADD MARKER command.

1.14 Programs commands

The PROGRAMS commands allow you to bind the GGSLIB intercept library to application programs, link GGSDLL intercept library to application programs, and view information about programs that may or may not be bound with GGSLIB.

1.14.1 BIND PROGRAMS

BIND PROGRAMS binds the TNS version of the GGSLIB intercept library to application programs. You must bind the intercept library to capture non-audited database updates to Enscribe files.

After issuing the BIND PROGRAMS command, you are prompted for a list of files with which to bind GGSLIB. You can enter a wildcard or actual program name. Terminate the list with GO (or cancel with EXIT). GGSLIB becomes the Guardian user library for specified programs (through the BIND CHANGE LIBRARY command).

If a program references a user library, that library is added to the bind list and GGSLIB is physically bound to the user library module (through the BIND BUILD command). The calling program's link to the user library is unchanged.

Syntax

BIND PROGRAMS
[, AXCEL| NOAXCEL]
[, PARAMS param_file_name]
[, REPORT report_file]
[, GGSLIB library_filename]
[, ERRORS num_errors]
[, FORCEBIND] 
[, NOLIBBIND]
[, CHANGELIB]

AXCEL|NOAXCEL: AXCEL causes code acceleration after binding with existing user libraries. This option has no effect unless a user library is bound to GGSLIB and can be bypassed with NOAXCEL. If you do not specify NOAXCEL, Oracle GoldenGate will run BIND PROGRAMS with the AXCEL option enabled.
PARAMS param_file_name: The file that contains the program names to bind, as an alternative to entering file names interactively.
REPORT report_file: A file name for the detailed report of activity caused by this command. The default is install_volume.GGSRPT.BIND. Previous versions of the report file are aged to BIND00, BIND01, and so on.
GGSLIB library_filename: Changes the name of the GGSLIB to bind with the application. The default is GGSLIB in the Oracle GoldenGate home subvolume.
ERRORS num_errors: The number of allowable errors encountered by the BIND process before quitting. Default is 5.
FORCEBIND: Forces programs to be rebound with the library, even if they are already bound. Use FORCEBIND, for example, when binding a new release of GGSLIB to the application.
NOLIBBIND: Bypasses binding of existing user libraries with GGSLIB (default is to bind).
CHANGELIB: Instructs the bind process to change libraries to GGSLIB. Use this when receiving a new release of GGSLIB or BASELIB.

Note:

If your application programs are Native, then you must use the LINK PROGRAMS command to bind the Native version of the intercept library to your programs.

1.14.2 INFO PROGRAMS

Use INFO PROGRAMS to retrieve information about programs that may or may not be bound with GGSLIB. Use this command to determine if non-audited data will be extracted on a program-by-program basis.

Each program's modification timestamp is reported, so you can determine when data extraction took effect.

Syntax

INFO PROGRAMS file_name [, BOUND | UNBOUND]

file_name

A single file name or a wildcard list of files.

BOUND | UNBOUND

BOUND limits the output to programs that have GGSLIB bound with either the program or the program's user library.
UNBOUND reports programs that are not bound.

1.14.3 LINK PROGRAMS

LINK PROGRAMS links the native intercept library, GGSDLL, to your application programs. You must bind the intercept library to capture non-audited database updates to Enscribe files. Once this is complete, GGSDLL becomes the Guardian user library for specified programs (through the NLD -change libname command).

Syntax

LINK PROGRAMS 
[, PARAMS param_file_name]
[, REPORT report_file]
[, GGSDLL library_filename]
[, ERRORS num_errors]
[, CHANGELIB]

After issuing the LINK PROGRAMS command, you are prompted for a list of files with which to link the library. You can enter a wildcard or actual program name. Terminate the list with GO (or cancel with EXIT).

PARAMS param_file_name

The file that contains the program names to link, as an alternative to entering file names interactively.

REPORT report_file

A file name for the detailed report of activity caused by this command. The default is install_volume.GGSRPT.LINK.

Previous versions of the report file are aged to LINK00, LINK01, and so on.

GGSDLL library_filename

Changes the name of the library to link with the application. The default name is GGSDLL for the operating systems. This library is stored in the Oracle GoldenGate installation subvolume.

ERRORS num_errors

The number of allowable errors encountered by the NLD process before quitting. Default is 5.

CHANGELIB

Instructs the link process to change libraries to GGSDLL. Use this when receiving a new release of BASELIBR and using NLDLIB.

1.15 Report commands

Extract, Replicat, Logger and Syncfile create reports about group process parameters, run statistics, error messages, and other diagnostic information. These reports can be created with the SEND REPORT command and viewed with the VIEW REPORT command. The report is displayed to your screen. Use the scrolling commands below to scroll through the report.

return: Next page
/string: Search for next occurrence of string in file
number: Go to line indicated by number
l: Go to last page of file
b: Go backward one page in file
q: Quit display
h: Help

1.15.1 SEND REPORT

Use SEND REPORT when you want to narrow reporting to a specific span of time, or to retrieve statistics about the current transaction.

Syntax

SEND [EXTRACT | REPLICAT | SYNCFILE] group_name, 
REPORT [time_option [RESET | FILE name | TABLE name]]

group_name

The group name you defined with the appropriate GGSCI ADD command

REPORT time_option [RESET | FILE name | TABLE name

Returns Extract and Replicat processing statistics based on the selected options.

RESET

This resets the time_option counters to zero. For example, the command SEND RECENT RESET will report the RECENT counters and then reset them to zero.

FILE name | TABLE name

This limits the display to statistics for the file or table specified in name.

time_option

Each of these reports statistics for a different time interval as listed below. REPORT is the default. TRANSACTION is valid only for Replicat.

REPORT: since the last time the REPORT was run

TOTALS: since the Extract or Replicat was started

DAILY: since the beginning of the current day

HOURLY: since the beginning of the current hour

RECENT: since the last time the RECENT counter was reset

TRANSACTION: since the beginning of the current transaction

Examples

Example 1

The following sample Extract report uses the default REPORT option.

Report at 2010-02-27 12:43:07 (activity since 2010-02-27 11:43:44)
Elapsed time 0-00:59:22.916658
Total # records written to \NODEA.$TEST04.GGSDAT.ET                19
   \NODEA.$TEST04.GGSSOU.TCUSTMER            #  inserts:            3
                                             #  updates:            0
                                             #  deletes:            0
   \NODEA.$TEST04.GGSSOU.TCUSTORD            #  inserts:            3
                                             #  updates:           13
                                             #  deletes:            0

Example 2

The next sample Extract report uses the TOTALS option.

Report at 2010-02-27 12:44:15 counters for TOTALS since 2010-02-24 10:23:34
Elapsed time 3-02:20:41.216310
Total # records written to \NODEA.$TEST04.GGSDAT.ET                68
   \NODEA.$TEST04.GGSSOU.TCUSTMER            #  inserts:           11
                                             #  updates:            3
                                             #  deletes:            0
   \NODEA.$TEST04.GGSSOU.TCUSTORD            #  inserts:           15
                                             #  updates:           34
                                             #  deletes:            5

Example 3

The following Replicat report uses the TRANSACTION option.

Report at 2010-02-28 06:51:15 counters for TRANS since 2010-02-14 13:46:54
Elapsed time 13-17:04:21.290242
From \A.$TEST04.GGSSOU.ECUSTMER to \A.$TEST04.GGSTAR.HCUSTMER:
            #  inserts:         3
            #  updates:         1
            #  deletes:         0
            # discards:         0
From \A.$TEST04.GGSSOU.ECUSTORD to \A.$TEST04.GGSTAR.HCUSTORD:
            #  inserts:         3
            #  updates:         3
            #  deletes:         2
            # discards:         0

1.15.2 VIEW REPORT

VIEW REPORT allows read-only viewing of reports. Reports are aged each time Extract or Replicat is started. For example, if the report file for an Extract group is normally GGSRPT.EXTCUST, where EXTCUST is the group name, the reports are aged to GGSRPT.EXTCUST0, GGSRPT.EXTCUST1, and so on. This lets you trace through previous runs for diagnostic information.

Syntax

VIEW REPORT group_name[n] | file_name

group_name: The group name.
n: The sequence number of an aged report.
file_name: The fully qualified report file name. This is used when the report is not in the default location.

1.16 Syncfile commands

Syncfile commands let you manage the Syncfile utility, which duplicates entire files on a scheduled basis.

Use the VIEW REPORT command to view the output of Syncfile.

1.16.1 ADD SYNCFILE

Use ADD SYNCFILE to define a Syncfile group before starting Syncfile.

Using ADD SYNCFILE options you can:

Specify alternative names for the parameter file, the report file, or the Syncfile process
Specify a primary and backup CPU and associated NonStop priority

Syntax

ADD SYNCFILE group_name 
[, PARAMS param_file_name]
[, REPORT report_file] 
[, PROGRAM program_name]
[, PROCESS process_name]
[, CPU primary_cpu] 
[, BACKUPCPU cpu] 
[, PRI priority]
[, DESC "text"]

group_name: A Syncfile group. You can use wildcards to specify a set of group names, such as * or *FIN*.
PARAMS param_file_name: The Syncfile parameter file name.
REPORT report_file: The name of the report file to which Syncfile writes messages.
PROCESS process_name: The process name. See "Specifying an Alternative Process".
PROGRAM program_name: The name of the object to be run. See "Executing user exits".
CPU primary_cpu: The primary CPU name.
BACKUPCPU cpu: The CPU to use in the event the primary CPU is not available when starting or restarting Syncfile.
PRIORITY priority: The NonStop operating system priority.
DESC "text": A description of the Syncfile process.

1.16.2 ALTER SYNCFILE

Use ALTER SYNCFILE to change an existing Syncfile group. Generally, you will use ALTER SYNCFILE to change CPU, BACKUPCPU or PRIORITY options.

Syntax

ALTER SYNCFILE group_name [, option]

group_name: A Syncfile group. You can use wildcards to specify a set of group names, such as * or *FIN*.
option: ALTER SYNCFILE uses the same options as ADD SYNCFILE.

1.16.3 DELETE SYNCFILE

Use DELETE SYNCFILE to delete a Syncfile group.

Syntax

DELETE SYNCFILE group_name

group_name: A Syncfile group. You can use a wildcard in the name.

1.16.4 INFO SYNCFILE

Use INFO SYNCFILE to display information about one or more Syncfile processes, including whether the process is running, and the date of the last time started.

Syntax

INFO SYNCFILE group_name [, DETAIL]

group_name: A Syncfile group. You can use a wildcard in the name.
DETAIL: Provides information regarding parameter, report files, process names and other information.

1.16.5 KILL SYNCFILE

Use KILL SYNCFILE to force a Syncfile process to stop immediately. Try STOP SYNCFILE first because it also performs cleanup work. KILL SYNCFILE is preferable to stopping Syncfile from TACL, which can result in Manager automatically restarting the process.

Syntax

KILL SYNCFILE group_name

group_name: A Syncfile group. You can use a wildcard in the name.

1.16.6 START SYNCFILE

Use START SYNCFILE to start one or more Syncfile processes. Manager receives the START request and starts and monitors the Syncfile process.

Syntax

START SYNCFILE group_name

group_name: A Syncfile group. You can use a wildcard in the name.

1.16.7 STATUS SYNCFILE

Use STATUS SYNCFILE to display the status of the Syncfile group.

Syntax

STATUS SYNCFILE group_name

group_name: A Syncfile group. You can use a wildcard in the name.

1.16.8 STOP SYNCFILE

Use STOP SYNCFILE to stop one or more Syncfile processes gracefully. Using this command lets you make configuration changes without affecting the operation of future Syncfile runs, and ensures that Manager will not restart the process.

Syntax

STOP SYNCFILE group_name

group_name: A Syncfile group. You can use a wildcard in the name.

1.17 Miscellaneous commands

The following commands control various other aspects of Oracle GoldenGate.

1.17.1 CLEANUP NETWORKCHECKPOINTS

Deletes the network checkpoint records in repctxt that were created by replicats when replicating files or tables that are partitioned across nodes.

Syntax

CLEANUP NETWORKCHECKPOINTS

1.17.2 ! command

Use the ! command to run a previous GGSCI command without modifications. To modify a command before reexecuting it, use the FC command. To display a list of previous commands, use the HISTORY command.

Issuing the ! command without arguments reexecutes the most recently used command. By using options, you can reexecute a specific command by specifying its line number or a text substring.

Syntax

! [number | -number | string]

number: Reexecutes the command on the specified GGSCI line. Each GGSCI command line is sequenced, beginning with 1 at the start of the session.
-number: Reexecutes the command issued number lines before the current line.
string: Reexecutes the last command that starts with the specified text string.

Examples

Example 1

! 9

Example 2

! -3

Example 3

! sta

1.17.3 ENV

Use ENV to return information about the current run-time environment. This is based on the current settings for the GLOBALS parameters.

Syntax

ENV

Example

The following display illustrates the information returned for the ENV request.

Version                       192.0.2.2 H06 2010/05/14
Prefix                        $GG
System                        \NY
Programs                      \NY.$DATA1.GGS1040
Params                        \NY.$DATA1.GGSPARM
Report                        \NY.$DATA1.GGSRPT
LogFileOpens                  1
Manager Mandatory             Yes
Hometerm messages             Yes
SWAPVOL                       $DATA1
Reply timeout                 3000
TMF Refresh Interval          900
Current defines
=GGS_AUDCFG             CLASS MAP, FILE \NY.$DATA1.GGS.HHCFG
=GGS_PREFIX             CLASS MAP, FILE \NY.$GG
=_DEFAULTS CLASS DEFAULTS, VOLUME \NY.$DATA1.GGS8040

1.17.4 FC

Use FC to edit a previously issued GGSCI command and then reexecute it. Previous commands are stored in the memory buffer and you can display them by issuing the HISTORY command. The FC command is the same as standard NonStop FIX command functionality.

Issuing FC without arguments retrieves the most recently used command. By using options, you can retrieve a specific command by specifying its line number or a text substring. Previous commands can only be edited for the current command-line session, because command history is not maintained from session to session.

Using the editor

The FC command displays the specified command and then opens an editor with a prompt containing a blank line starting with two dots. Use the space bar to position the cursor beneath the character in the displayed command where you want to begin editing, and then enter one of the following arguments. Arguments are not case-sensitive and can be combined.

Table 1-1 FC editor commands

Argument	Description
i `text`	Inserts text. For example: GGSCI> fc 9 GGSCI> send mgr GGSCI.. i childstatus GGSCI> send mgr childstatus
r `text`	Replaces text. For example: GGSCI> fc 9 GGSCI> info mgr GGSCI.. rextract ggfin GGSCI> info extract ggfin
d	Deletes a character. To delete multiple characters, enter a `d` for each one. For example: GGSCI> fc 10 GGSCI> info extract ggfin, detail GGSCI.. dddddddd GGSCI> info extract ggfin
`replacement_text`	Replaces the displayed command with the text that you enter on a one-for-one basis. For example: GGSCI> fc 10 GGSCI> info mgr GGSCI.. extract ggfin GGSCI> info extract ggfin

To execute the command, press Enter twice, once to indicate there are no more changes and once to issue the command. To cancel an edit, type a slash (/) twice.

Syntax

FC [number | -number | string]

number: Returns the command from the specified line. Each GGSCI command line is sequenced, beginning with 1 at the start of the session.
-number: Returns the command that was issued number lines before the current line.
string: Returns the last command that starts with the specified text string.

Examples

Example 1

FC 9

Example 2

FC -3

Example 3

FC sta

1.17.5 GETMGRVERSION

Use GETMGRVERSION to obtain the version of the Manager process in a remote Oracle GoldenGate install.

Syntax

GETMGRVERSION <DNS | IP Address>  <mgrport>

<DNS>: Any domain name or IP address of an Oracle GoldenGate install.

<mgrport>: IP port of the listining mgr process.

1.17.6 HELP

Use HELP to view information about specific commands. For example, HELP displays information about the ADD REPLICAT command.

For a summary page displaying all commands and objects, enter the single command: HELP.

Syntax

HELP command object

command object: The command you need help with, such as ADD REPLICAT.

1.17.7 HISTORY

Use HISTORY to view a list of the commands issued in GGSCI. Previous commands are stored in GGSCIHST, an edit file located on the NonStop user's saved volume. Command history from each session of GGSCI remains available until the data is manually deleted from this file.

Note:

To clear the history, you can use TACL> WHO to find the saved volume for the user and then edit the GGSCIHST stored there.

You can use the ! command or the FC command to reexecute a command in the list. This command is the same as standard NonStop HISTORY command functionality.

Syntax

HISTORY [number]

number: Returns the last number commands, where number is any positive number.

Example

HISTORY 7

The result of this command would be similar to:

1: start manager
2: status manager
3: info manager
4: send manager childstatus
5: start extract ggfin
6: info extract ggfin
7: history

1.17.8 INFO ALL

Use INFO ALL to display a summary of the status and lag, where relevant, for each Oracle GoldenGate process. This display includes information for Manager, Extract, Replicat, Logger, and Syncfile.

Use INFO ALL to show the status of all active tasks and processes in the system. Use the SYSTEM command to address multiple systems at the same time.

Syntax

INFO ALL, [DETAIL | TASKS | ALLPROCESSES]

DETAIL: Reports process run history.
TASKS | ALLPROCESSES: Shows either tasks or all processes that are running. Specify either TASKS or ALLPROCESSES.

1.17.9 LOG

Using the LOG command, you can save the results of your GGSCI session to an output file. Use LOG to identify where to direct the session output. You can direct output to an edit file, spooler file, or a process name. Any new output will be appended to the file if it already exists.

Syntax

LOG {file_name | process_name | spooler}

file_name: The name of the output file.
process_name: The name of the process.
spooler: The name of the spooler.

1.17.10 LOG STOP

Use the LOG STOP command to close the session output.

Syntax

LOG STOP

1.17.11 OBEY

Use OBEY to process a file that contains a list of Oracle GoldenGate commands. OBEY is useful for executing commands that are frequently used in sequence. This command provides standard NonStop OBEY file functionality.

Syntax

OBEY file_name

file_name: The name of the file containing the list of commands.

Example

OBEY $DATA01.GGSPARM.FINANCE

1.17.12 EDIT PARAMS

EDIT PARAMS launches an editor from GGSCI.

Syntax

EDIT PARAMS file_name

file_name: Specify a parameter file name. If the file name is unqualified, EDIT assumes the parameter file resides in the Oracle GoldenGate home volume: install_volume.GGSPARM.

1.17.13 VIEW PARAMS

VIEW PARAMS displays the named parameter file to your screen. Use the scrolling commands described in Table 1-2 to scroll through the file.

Syntax

VIEW PARAMS file_name

file_name: Specify a parameter file name. If the file name is unqualified, VIEW assumes the parameter file resides in the Oracle GoldenGate home volume: install_volume.GGSPARM.

Table 1-2 Scrolling commands

Command	Description
`return`	Go to the next page.
/`string`	Search for next occurrence of `string` in file.
`number`	Go to line indicated by `number`.
l	Go to last page of file.
b	Go backward one page in file.
q	Quit display.
h	Help.

1.17.14 SYSTEM

The SYSTEM command enables you to manage Oracle GoldenGate processes from a single point of control. Use SYSTEM to switch the reference point from the local system to one or more remote systems, and then back again when needed. After making another system current, you can execute any command, subject to security constraints specified in the CMDSEC file on the remote system.

To enable the SYSTEM command, enter a HOST specification in the GLOBALS parameter file for each remote system with which you intend to communicate. The HOST entry requires the NonStop system name and GGSSUBVOL specification. These parameters identify and start GGSCI sessions on the remote systems.

Syntax

SYSTEM {system [, system] | ALL}

system: The NonStop system to make current. Omitting a system name defaults to the local system.
ALL: Makes all systems current.

Example

If Extract is running on the local system and Replicat is running on the remote system, the following commands would obtain information on each running process.

Get information about all Extract processes at \LA:
```
GGSCI (\LA) > INFO EXTRACT *
```
Switch to \NY:
```
GGSCI (\LA) > SYSTEM \NY
```
Get information about Replicats at \NY:
```
GGSCI (\NY) > INFO REPLICAT *
```
Switch back to \LA (omitting system name defaults to local system):
```
GGSCI (\NY) > SYSTEM
```

Example

You can address multiple systems at the same time:

Make the current systems \LA and \NY:
```
GGSCI (\NY) > SYSTEM \LA, \NY
```
Get information about Extract and Replicat processes on both systems:
```
GGSCI (\LA, \NY) > INFO ER *
```

1.17.15 VIEW GGSEVT

This command enables you to scroll through the Oracle GoldenGate event file (LOGGGS). This file contains event timestamps, text, program names and processes in chronological sequence.The LOGGGS file also includes a history of commands entered through GGSCI. Although this information is also recorded in the HP NonStop Event Management System (EMS), using VIEW GGSEVT is sometimes more convenient.

Syntax

VIEW GGSEVT 
[, ASC | DESC] 
[, TIME timestamp]
[, program] 
[, event] [, SEARCH string]

ASC | DESC: ASC sorts the log in ascending order by time. DESC, the default, sorts entries in descending order.
TIME timestamp: Provides a starting point to look for event records. timestamp is expressed as yyyy-mm-dd hh:mi (for example 2014-03-31 12:30).
program: Specify a program name to filter for events related only to that program: EXTRACT, REPLICAT, LOGGER, SYNCFILE, MANAGER, or GGSCI.
event: Specify one of: START, STOP (includes ABEND events), or ABEND.
SEARCH string: Searches for string in the log message. string must not contain spaces or be enclosed in quotes. You can specify multiple SEARCH string entries. If any string is found, the record is displayed.

GGSCI will display the events and then prompt: enter or q?

enter: Enter additional options for another GGSEVT display.
q: Exit GGSEVT and return to GGSCI.