Using Oracle GoldenGate Parameter Files

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

The 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:

The GLOBALS 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

From the Oracle GoldenGate installation location, run GGSCI and enter the following command, or open a file in a text editor.
```
EDIT PARAMS ./GLOBALS
```
Note:

The ./ portion of this command must be used, because the GLOBALS file must reside at the root of the Oracle GoldenGate installation file.
In the file, enter the GLOBALS parameters, one per line.
Save the file. If you used a text editor, save the file as GLOBALS (uppercase, without a file extension) at the root of the Oracle GoldenGate installation directory. If you created the file correctly in GGSCI, the file is saved that way automatically. Do not move this file.
Exit GGSCI. You must start from a new GGSCI session before issuing commands or starting processes that reference the 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 the TABLE and MAP 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 and IGNOREINSERTS in Example 9-3 are examples of object-specific parameters. Each precedes a MAP 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.

From the directory where Oracle GoldenGate is installed, run GGSCI or Admin Client.
In GGSCI or Admin Client, issue the following command to open the default text editor.
```
EDIT PARAMS group_name
```
Where:

group_name is either mgr (for the Manager process) or the name of the Extract or Replicat group for which the file is being created. The name of an Extract or Replicat parameter file must match that of the process group.

The following creates or edits the parameter file for an Extract group named extora.
```
EDIT PARAMS extora
```
The following creates or edits the parameter file for the Manager process.
```
EDIT PARAMS MGR
```
Using the editing functions of the text editor, enter as many comment lines as you want to describe this file, making certain that each comment line is preceded with two hyphens (--).
On non-commented lines, enter the Oracle GoldenGate parameters, starting a new line for each parameter statement.
Oracle GoldenGate parameters have the following syntax:
```
PARAMETER_NAME argument [, option] [&]
```
Where:
- PARAMETER_NAME is the name of the parameter.
- argument is a required argument for the parameter. Some parameters take arguments, but others do not. Commas between arguments are optional.
```
EXTRACT myext
USERIDALIAS ogg1
ENCRYPT AES192 KEYNAME mykey
ENCRYPTTRAIL AES 192
EXTTRAIL ./dirdat/c1, PURGE
CUSEREXIT userexit.dll MyUserExit, INCLUDEUPDATEBEFORES, &
  PARAMS "init.properties"
TABLE myschema.mytable;
```
- [, option] is an optional argument.
- [&] is required at the end of each line in a multi-line parameter statement, as in the CUSEREXIT parameter statement in the previous example. The exceptions are the following, which can accept, but do not require, the ampersand because they terminate with a semicolon:
  - MAP
  - TABLE
  - SEQUENCE
  - FILE
  - QUERY
Note:

The RMTHOST and RMTHOSTOPTIONS parameters can be specified together; the RMTHOST parameter is not required for RMTHOSTOPTIONS if the dynamic IP assignment is properly configured. When RMTHOSTOPTIONS is used, the MGRPORT option is ignored.
Save and close the file.

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 and mgr.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
`None`	Displays usage information
`-v`	Displays banner. Cannot be combined with other options.
`? \| help`	Displays detailed usage information, include all possible values of each option. Cannot be combine with other options.
`parameter_file`	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, `CHECKPRM ./dirprm/myext.prm`.
`-COMPONENT \| -C`	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: `CACHEFILEDUMP COBGEN CONVCHK CONVPRM DDLCOB DEFGEN EMSCLNT EXTRACT GGCMD GGSCI KEYGEN LOGDUMP` `MGR OGGERR REPLICAT RETRACE` `REVERSE SERVER GLOBALS` There is no default for this option.
`-MODE \| -M`	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: Integrated Extract Initial Load Extract Remote Task Extract Data Pump Extract Passive Extract Classic Replicat Coordinated Replicat Integrated Replicat Parallel Integrated Replicat Parallel Nonintegrated Replicat Special Run Replicat Remote Task 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, `"Data Pump Extract"` is equivalent to `"Data Pump"` if the component is Extract. However, it is invalid if the component is Replicat.
`-PLATFORM \| -P`	Specifies the platform the application is supposed to run on. The default value is the platform that this `checkprm` executable is running on. The possible values are: `AIX HP-OSS HPUX-IT HPUX-PA` `Linux OS400 ZOS Solaris SPARC` `Solaris x86 Windows x64 All`
`-DATABASE \| -D`	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): `Generic Oracle 8 Oracle 9i Oracle 10g Oracle 11g Oracle 12c Oracle 18c Oracle 19c Oracle 21c Sybase DB2LUW 9.5 DB2LUW 9.7 DB2LUW 10.5 DB2LUW 10.1 DB2LUW 11.1 DB2 Remote Teradata Timesten Timesten 7 Timesten 11.2.1 MySQL Ctree8 Ctree9 DB2 for i Remote MSSQL MSSQL CDC Informix Informix1150 Informix1170 Informix1210 Ingres SQL/MX DB2 z/OS PostgreSQL`
`-VERBOSE \| -V`	Directs `checkprm` to print out detailed parameter information, to demonstrate how the values are read and interpreted. 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

Include the CHECKPARAMS parameter in the parameter file.
Start the associated process by issuing the START EXTRACT or START REPLICAT command.
```
START {EXTRACT | REPLICAT} group_name
```
The process audits the syntax, writes the results to the report file or the screen, and then stops.
Do either of the following:
- If the syntax is correct, remove the CHECKPARAMS parameter before starting the process to process data.
- If the syntax is wrong, correct it based on the findings in the report. You can run another test to verify the changes, if desired. Remove CHECKPARAMS before starting the process to process data.

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

For each parameter for which substitution is to occur, declare a runtime parameter instead of a value, and precede the runtime parameter name with a question mark (?) as shown in the following example.
```
SOURCEISFILE
EXTFILE ?EXTFILE
MAP scott?TABNAME, TARGET tiger ACCOUNT_TARG;
```
Before starting the Oracle GoldenGate process, use the shell of the operating system to pass the runtime values by means of an environment variable, as shown in Example 9-4 and Example 9-5.

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