Working with Parameter Files

Creating a Parameter File Using Admin Client

To create a parameter file, run the EDIT PARAMS command from the Admin Client. 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 after processing has started.

The EDIT PARAMS command launches the following text editors in Admin Client:

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 Admin Client by using the SET EDITOR command.
1. From the $OGG_HOME/bin directory, run the Admin Client.
2. Connect to the Admin Client using the CONNECT command.
3. In Admin Client, issue the following command to open the default text editor:
```
EDIT PARAMS group_name
```
  where:
  - group_name is 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
```
4. 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 (--).
5. 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.
6. Save and close the file.

Creating a Parameter File with a Text Editor

You can create a parameter file outside 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. Use the .prm file extension. For example: exte.prm.
Save the parameter file in the dirprm directory of the Oracle GoldenGate home directory.

Validating a Parameter File

You can validate the parameter file from the Administration Service web interface. You can validate the Extract and Replicat parameters from the Reports tab. To access the Reports tab:

From Extract or Replicat section of the Administration Service Overview Page, click Action and then click Details.
Click the Reports tab to view the report for Extract and Replicat parameters, error log, and other information.

See Access Extract Details to learn how to check and edit the Extract parameters. See Access Replicat Details to learn about editing Replicat parameter files. Also see Additional Parameter Options for Integrated Replicat

You can also use the checkprm validation native command is run from the command line and give an assessment of the specified parameter file, with a configurable application and running environment. It can provide either a simple PASS/FAIL or with additional details about how the values of each parameter are stored and interpreted.

The CHECKPRM executable file can be found in the $OGG_HOME/bin directory of Microservices Architecture. See checkprm in the Reference for Oracle GoldenGate. 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, and the specified parameters. The parameter and options are printed with proper indentation to illustrate these relationships.

See CHECKPARAMS parameter.

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:

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.

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.

Using Macros

You can use macros to automate multiple uses of a parameter statement. See Simplify and Automate Work with Oracle GoldenGate Macros.

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 the following examples:

Example 11-2 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 11-3 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.