9 Using Oracle GoldenGate Parameter Files
Most Oracle GoldenGate functionality is controlled by means of parameters specified in parameter files. A parameter file is a plain text file that is read by an associated Oracle GoldenGate process. Oracle GoldenGate uses two types of parameter files: a GLOBALS
file and runtime parameter files.
Topics:
- Globalization Support for Parameter Files
- Working with the GLOBALS File
- Working with Runtime Parameters
- Creating a Parameter File
- Validating a Parameter File
- Viewing a Parameter File
- Changing a Parameter File
- Simplifying the Creation of Parameter Files
- Getting Information about Oracle GoldenGate Parameters
9.1 Globalization Support for Parameter Files
Oracle GoldenGate creates parameter files in the default character set of the local operating system. In the event that the local platform does not support a required character set as the default in the operating system, you can use the CHARSET
parameter either globally or per-process to specify a character set for parameter files.
To avoid issues caused by character-set incompatibilities, create or edit a parameter file on the server where the associated process will be running. Avoid creating it on one system (such as your Windows laptop) and then transferring the file to the UNIX server where Oracle GoldenGate is installed and where the operating system character set is different. Oracle GoldenGate provides some tools to help with character set incompatibilities if you must create the parameter file on a different system:
-
You can use the
CHARSET
parameter to specify a compatible character set for the parameter file. This parameter must be placed on the first line of the parameter file and allows you to write the file in the specified character set. After the file is transferred to the other system, do not edit the file on that system. -
You can use Unicode notation to substitute for characters that are not compatible with the character set of the operating system where the file will be used. See Support for Escape Sequences for more information about Unicode notation.
See Reference for Oracle GoldenGate for more information about the CHARSET
parameter.
Parent topic: Using Oracle GoldenGate Parameter Files
9.2 Working with the GLOBALS File
GLOBALS
file stores parameters that relate to the Oracle
GoldenGate instance as a whole. This is in contrast to runtime parameters, which are
coupled with a specific process such as Extract. The parameters in the
GLOBALS
file apply to all processes in the Oracle GoldenGate
instance, but can be overridden by specific process parameters. A
GLOBALS
parameter file may or may not be required for your
Oracle GoldenGate environment.
Note:
TheGLOBALS
file is specific to
Classic Architecture.
When used, a GLOBALS
file must exist before starting any Oracle GoldenGate processes, including GGSCI. The GGSCI program reads the GLOBALS
file and passes the parameters to processes that need them.
To Create a GLOBALS File
Parent topic: Using Oracle GoldenGate Parameter Files
9.3 Working with Runtime Parameters
Runtime parameters give you control over the various aspects of Oracle GoldenGate synchronization, such as:
-
Data selection, mapping, transformation, and replication
-
DDL and sequence selection, mapping, and replication (where supported)
-
Error resolution
-
Logging
-
Status and error reporting
-
System resource usage
-
Startup and runtime behavior
There can only be one manager process for each Oracle
GoldenGate installation. It is configured using the mgr.prm
parameter file. Although you can have multiple Extracts and Replicats running in a
single installation, each one can only be associated by a single parameter file. For
Extracts and Replicats, they are identified by their case-insensitive name. For
example, an Extract called EXT_DEMO
, would have 1 associated
parameter file called EXT_DEMO.prm
. See Simplifying the Creation of Parameter Files for more information about simplifying the use of parameter
files.
There are two types of parameters: global (not to be confused with GLOBALS
parameters) and object-specific:
-
Global parameters apply to all database objects that are specified in a parameter file. Some global parameters affect process behavior, while others affect such things as memory utilization and so forth.
USERIDALIAS
in Example 9-1 and Example 9-3 is an example of a global parameter. In most cases, a global parameter can appear anywhere in the file before the parameters that specify database objects, such as theTABLE
andMAP
statements in Example 9-1 and Example 9-3. A global parameter should be listed only once in the file. When listed more than once, only the last instance is active, and all other instances are ignored. -
Object-specific parameters enable you to apply different processing rules for different sets of database objects.
GETINSERTS
andIGNOREINSERTS
in Example 9-3 are examples of object-specific parameters. Each precedes aMAP
statement that specifies the objects to be affected. Object-specific parameters take effect in the order that each one is listed in the file.
Example 9-1 and Example 9-3 are examples of basic parameter files for Extract and Replicat. Comments are preceded by double hyphens.
The preceding example reflects a case-insensitive Oracle database, where the object names are specified in the TABLE
statements in capitals. For a case-insensitive Oracle database, it makes no difference how the names are entered in the parameter file (upper, lower, mixed case). For other databases, the case of the object names may matter. See Specifying Object Names in Oracle GoldenGate Input for more information about specifying object names.
Note the use of single and double quote marks in the Replicat example in Example 9-1. For databases that require quote marks to enforce case-sensitive object names, such as Oracle, you must enclose case-sensitive object names within double quotes in the parameter file as well. For other case-sensitive databases, specify the names as they are stored in the database. For more information about specifying names and literals, see Specifying Object Names in Oracle GoldenGate Input.
Example 9-1 Sample Extract Parameter File
-- Extract group name EXTRACT capt -- Extract database user login, with alias to credentials in the credential store. USERIDALIAS ogg1 -- Remote host to where captured data is sent in encrypted format: RMTHOSTOPTIONS sysb, MGRPORT 7809, ENCRYPT AES192 KEYNAME mykey -- Encryption specification for trail data ENCRYPTTRAIL AES192 -- Remote trail on the remote host RMTTRAIL /ggs/dirdat/aa With these lines: -- Encryption specification for trail data ENCRYPTTRAIL AES192 -- Local trail on the remote host EXTTRAIL ./dirdat/aa
Example 9-2 Sample Extract Pump Parameter File
-- Extract Pump group name
EXTRACT pmp
-- Remote host to where captured data is sent in encrypted format:
RMTHOSTOPTIONS sysb, MGRPORT 7809, ENCRYPT AES192 KEYNAME mykey
-- Encryption specification for trail data
ENCRYPTTRAIL AES192
-- Remote trail on the remote host
RMTTRAIL /ggs/dirdat/bb
-- TABLE statements that identify data to capture.
TABLE FIN.*;
TABLE SALES.*;
Example 9-3 Sample Replicat Parameter File
-- Replicat group name REPLICAT deliv -- Replicat database user login, with alias to credentials in the credential store USERIDALIAS ogg2 -- Error handling rules REPERROR DEFAULT, ABEND -- Ignore INSERT operations IGNOREINSERTS -- MAP statement to map source objects to target objects and -- specify column mapping MAP "fin"."accTAB", TARGET "fin"."accTAB", COLMAP ("Account" = "Acct", "Balance" = "Bal", "Branch" = "Branch"); -- Get INSERT operations GETINSERTS -- MAP statement to map source objects to target objects and -- filter to apply only the 'NY' branch data. MAP "fin"."teller", TARGET "fin"."tellTAB", WHERE ("Branch" = 'NY');
Parent topic: Using Oracle GoldenGate Parameter Files
9.4 Creating a Parameter File
Oracle recommends using GGSCI when writing the parameter file in the character set of
the operating system, but if using the CHARSET
parameter and
writing the file in a different character set, use a text editor instead of GGSCI.
Topics:
Parent topic: Using Oracle GoldenGate Parameter Files
9.4.1 Creating a Parameter File in GGSCI and Admin Client
To create a parameter file, use the EDIT PARAMS
command within the
command line interface through GGSCI or Admin Client user interface or use a text editor
directly. When you use the command line interface, you are using a standard text editor, but
your parameter file is saved automatically with the correct file name and in the correct
directory.
When you create a parameter file with EDIT PARAMS
, it is saved to
the dirprm
sub-directory of the Oracle GoldenGate directory. You can create
a parameter file in a directory other than dirprm
, but you also must
specify the full path name with the PARAMS
option of the ADD
EXTRACT
or ADD REPLICAT
command when you create your process
groups. Once paired with an Extract or Replicat group, a parameter file must remain in its
original location for Oracle GoldenGate to operate properly once processing has started.
The EDIT PARAMS
command launches the following text editors within
the GGSCI or Admin Client interface:
-
Notepad on Microsoft Windows systems
-
The vi editor on UNIX and Linux systems. DB2 for i only supports vi when connected with SSH or xterm. For more information, see Creating a Parameter File with a Text Editor.
Note:
You can change the default editor through the GGSCI or Admin Client interface by using the
SET EDITOR
command.
Parent topic: Creating a Parameter File
9.4.2 Creating a Parameter File with a Text Editor
You can create a parameter file outside GGSCI or Admin Client by using a text editor, but make certain to:
-
Save the parameter file with the name of the Extract or Replicat group that owns it, or save it with the name
mgr
if the Manager process owns it. Use the.prm
file extension. For example:extfin.prm
andmgr.prm
. -
Save the parameter file in the
dirprm
directory of the Oracle GoldenGate installation directory. -
For DB2 for i systems, you can edit parameter files from a 5250 terminal using SEU or EDTF. If you use SEU, you must copy the file using the
CPYTOSTMF
command, specify an encoding of CCSID 1208, and line endings of *LF. If editing with EDTF from F15 (services) ensure that you change the CCSID of the file to 1208 and the EOL option to *LF.Alternatively, you can use the
Rfile
command from the IBM Portable Application Solutions Environment for i.
Parent topic: Creating a Parameter File
9.5 Validating a Parameter File
The checkprm
validation native command is run from the command line
and gives an assessment of the specified parameter file, with a configurable
application and running environment. It can provide either a simple
PASS
/FAIL
or with optional details about how
the values of each parameter are stored and interpreted.
The CHECKPRM
executable file can be found in the Oracle GoldenGate
installation directory for Classic Architecture and in the /bin
directory of Microservices Architecture. The input to checkprm
is
case insensitive. If a value string contains spaces, it does not need to be quoted
because checkprm
can recognize meaningful values. If no mode is
specified to checkprm
, then all parameters applicable to any mode
of the component will be accepted.
The output of checkprm
is assembled with four possible sections:
-
help messages
-
pre-validation error
-
validation result
-
parameter details
A pre-validation error is typically an error that prevents a normal parameter validation from executing, such as missing options or an inaccessible parameter file. If an option value is specified incorrectly, a list of possible inputs for that option is provided. If the result is FAIL
, each error is in the final result message. If the result is PASS
, a message that some of the parameters are subject to further runtime validation. The parameter detailed output contains the validation context, the values read from GLOBALS (if it is present), and the specified parameters. The parameter and options are printed with proper indentation to illustrate these relationships.
Table 9-1 describes all of the arguments that you can use with the checkprm
commands. When you use checkprm
and do not use any of these arguments, then checkprm
attempts to automatically detect Extract or Replicat and the platform and database of the Oracle GoldenGate installation.
Table 9-1 checkprm Arguments
Argument | Purpose & Behavior |
---|---|
|
Displays usage information |
|
Displays banner. Cannot be combined with other options. |
|
Displays detailed usage information, include all possible values of each option. Cannot be combine with other options. |
|
Specifies the name of the parameter file, has to be the first argument if a validation is requested. You must specify the absolute path to the parameter file. For example, |
|
Specifies the running component (application) that this parameter file is validated for. This option can be omitted for Extract or Replicat because automatic detection is attempted. Valid values include:
There is no default for this option. |
|
Specifies the mode of the running application if applicable. This option is optional, only applicable to Extract or Replicat. If no mode is specified, the validation is performed for all Extract or Replicat modes. Valid input of this option includes:
When key in the value for this option, the application name is optional, as long as
it matches the va lue of component. For example, |
|
Specifies the platform the application is supposed to run on. The default value is the platform that this The possible values are:
|
|
Specifies the database the application is built against. The default value is the database for your Oracle GoldenGate installation. The database options are (case insensitive):
|
|
Directs It must be the last option specified in a validation. |
Following are some use examples:
checkprm ? checkprm ./dirprm/ext1.prm -C extract -m data pump -p Linux -v checkprm ./dirprm/ext1.prm -m integrated checkprm ./dirprm/rep1.prm -m integrated checkprm ./dirprm/mgr.prm -C mgr -v checkprm GLOBALS -c GLOBALS
Verifying Using CHECKPARAMS
Parameter
An alternative to using the recommended checkprm
utility, is to check the syntax of parameters in an Extract or Replicat parameter file for accuracy using the CHECKPARAMS
parameter. This process can be used with Extract or Replicat.
To Verify Parameter Syntax
For more information about the report file, see Monitoring Oracle GoldenGate Processing.
For more information about CHECKPARAMS
, see Reference for Oracle GoldenGate.
Parent topic: Using Oracle GoldenGate Parameter Files
9.6 Viewing a Parameter File
You can view a parameter file directly from the command shell of the operating
system, or you can view it from the GGSCI or Admin Client command line interface,
using the VIEW PARAMS
command.
VIEW PARAMS group_name
Where:
group_name
is either mgr
(for Manager) or the name of the Extract or Replicat group that is associated with the parameter file.
Caution:
Do not use VIEW PARAMS
to view an existing parameter file that is in
a character set other than that of the local operating system (such as one where
the CHARSET
option was used to specify a different character
set). The contents may become corrupted. View the parameter file from outside
the command line interface.
If the parameter file was created in a location other than the dirprm
sub-directory of the Oracle GoldenGate directory, specify the full path name as shown in the following example.
VIEW PARAMS c:\lpparms\replp.prm
Parent topic: Using Oracle GoldenGate Parameter Files
9.7 Changing a Parameter File
An Oracle GoldenGate process must be stopped before changing its parameter file, and then started again after saving the parameter file. Changing parameter settings while a process is running can have unexpected results, especially if you are adding tables or changing mapping or filtering rules.
Caution:
Do not use the EDIT PARAMS
command to view or edit an existing
parameter file that is in a character set other than that of the local operating
system (such as one where the CHARSET
option was used to
specify a different character set). The contents may become corrupted. View the
parameter file from outside Admin Client or GGSCI.
To Change Parameters:
-
Stop the process by issuing the following command in Admin Client or GGSCI. To stop Manager in a Windows cluster, use the Cluster Administrator.
STOP {EXTRACT | REPLICAT | MANAGER}
group_name
-
Open the parameter file by using a text editor or the
EDIT PARAMS
command in Admin Client GGSCI.EDIT PARAMS mgr
-
Make the edits, and then save the file.
-
Start the process by issuing the following command in Admin Client GGSCI. Use the Cluster Administrator if starting Manager in a Windows cluster.
START {EXTRACT | REPLICAT | MANAGER}
group_name
When an Extract process or Replicat process is restarted, it picks up right where it left off. You do not need to queisce database activity prior to bouncing the Oracle GoldenGate process to replace a parameter file.
Parent topic: Using Oracle GoldenGate Parameter Files
9.8 Simplifying the Creation of Parameter Files
You can reduce the number of times that a parameter must be specified by using the following time-saving tools.
Topics:
Parent topic: Using Oracle GoldenGate Parameter Files
9.8.1 Using Wildcards
For parameters that accept object names, you can use asterisk (*) and question mark (?) wildcards. The use of wildcards reduces the work of specifying numerous object names or all objects within a given schema. For more information about using wildcards, see Using Wildcards in Database Object Names.
Parent topic: Simplifying the Creation of Parameter Files
9.8.2 Using OBEY
You can create a library of text files that contain frequently used parameter settings, and then you can call any of those files from the active parameter file by means of the OBEY
parameter. The syntax for OBEY
is:
OBEY file_name
Where:
file_name
is the relative or full path name of the file.
Upon encountering an OBEY
parameter in the active parameter file, Oracle GoldenGate processes the parameters from the referenced file and then returns to the active file to process any remaining parameters. OBEY
is not supported for the GLOBALS
parameter file.
If using the CHARSET
parameter in a parameter file that includes an OBEY
parameter, the referenced parameter file does not inherit the CHARSET
character set. The CHARSET
character set is used to read wildcarded object names in the referenced file, but you must use an escape sequence (\uX
) for all other multibyte specifications in the referenced file.
See Reference for Oracle GoldenGate for more information about OBEY
.
See Reference for Oracle GoldenGate for more information about CHARSET
.
Parent topic: Simplifying the Creation of Parameter Files
9.8.3 Using Macros
You can use macros to automate multiple uses of a parameter statement. See Using Oracle GoldenGate Macros to Simplify and Automate Work.
Parent topic: Simplifying the Creation of Parameter Files
9.8.4 Using Parameter Substitution
You can use parameter substitution to assign values to Oracle GoldenGate parameters automatically at run time, instead of assigning static values when you create the parameter file. That way, if values change from run to run, you can avoid having to edit the parameter file or maintain multiple files with different settings. You can simply export the required value at runtime. Parameter substitution can be used for any Oracle GoldenGate process.
To Use Parameter Substitution
Example 9-4 Parameter substitution on Windows
C:\GGS> set EXTFILE=C:\ggs\extfile C:\GGS> set TABNAME=PROD.ACCOUNTS C:\GGS> replicat paramfile c:\ggs\dirprm\parmfl
Example 9-5 Parameter substitution on UNIX (Korn shell)
$ EXTFILE=/ggs/extfile $ export EXTFILE $ TABNAME=PROD.ACCOUNTS $ export TABNAME $ replicat paramfile ggs/dirprm/parmfl
UNIX is case-sensitive, so the parameter declaration in the parameter file must be the same case as the shell variable assignments.
Parent topic: Simplifying the Creation of Parameter Files
9.9 Getting Information about Oracle GoldenGate Parameters
You can use the INFO PARAM
command to view a parameter's definition information from GGSCI. The name provided in the command line can be a parameter, or an option, but it must be a full name that is part of the names concatenated together using a period (.) as the delimiter. For example:
INFO PARAM RMTHOST RMTHOST.STREAMING INFO PARAM RMTHOST.STREAMING
Using the GETPARAMINFO
, you can query the runtime parameter values of a running instance, including Extract, Replicat, and Manager. This command is similar to using checkprm -v
, see Validating a Parameter File. The default behavior is to display all that has ever been queried by the application, parameters and their current values. If a particular parameter name is specified, then the output is filtered by that name. Optionally, the output can be redirect to a file specified by the -FILE
option. For example:
SEND ext1pmp GETPARAMINFO
For more information about these and all Oracle GoldenGate parameters including exact syntax, see the Reference for Oracle GoldenGate.
Parent topic: Using Oracle GoldenGate Parameter Files