1. Oracle GoldenGate Microservices Documentation
  2. Administer
  3. Microservices: Command Line Interface

Microservices: Command Line Interface

To start either the Admin Client, you need to change the current working directory to the Oracle GoldenGate home directory (OGG_HOME).

Note:

The environment variable OGG_HOME and OGG_VAR_HOME must be set before starting the Admin Client.

About Admin Client

Admin Client is a command line utility. It uses the REST API published by the microservices to accomplish control and configuration tasks in an Oracle GoldenGate deployment.

Admin Client is a command line utility that can be used to created, modify, and remove Oracle GoldenGate processes and can be used in place of the MA web user interface.The Admin Client program is located in the $OGG_HOME/bin directory, where $OGG_HOME is the Oracle GoldenGate home directory.

If you need to automate the Admin Client connection with the deployment, you can use an Oracle Wallet to store the user credentials. The credentials stored must have the following characteristics:

  • Single user name (account) and password

  • Local to the environment where the Admin Client runs

  • Available only to the currently logged user

  • Managed by the Admin Client

  • Referenced using a credential name

  • Available for Oracle GoldenGate deployments and proxy connections.

Note:

To use the Admin Client for administration tasks, you need the user credentials that work with both the Service Manager and Administration Service.

To use the Admin Client, perform the following steps:

  1. In Linux, set the OGG_HOME, and PATH environment variable to the following:
    export OGG_HOME=ogg_install_location
    export PATH=$OGG_HOME/bin:$PATH
    If you configure a secure deployment using SSL certificate files (.pem or .der), you must add the OGG_CLIENT_TLS_CAPATH environment variable. This is required to be able to connect to the deployment from Admin Client. This variable is used to specify the location where the certificate files are located on the host. For clients only needing to validate server certificates, the OGG_CLIENT_TLS_CAPATH environment variable should refer to a file containing a trusted CA Certificate that is shared with the server to which the client is expected to connect.
    export OGG_CLIENT_TLS_CAPATH = deployment_rootCA_certificate_location

    Note:

    For Microsoft Windows, the default certificate file format is .der while all other platforms use .pem as the default format.
  2. Run the command:
    [oracle]$ adminclient
    The output displays the Oracle GoldenGate Admin Client prompt, where you can connect to the deployment from the Admin Client:
    OGG (not connected) 1>
  3. Connect to a deployment or to a proxy server from the Admin Client as a security user. This is the user you created while adding the deployment for your Oracle GoldenGate instance using OGGCA.
    CONNECT http(s)://localhost:port DEPLOYMENT deployment name AS security role user PASSWORD password

    Note:

    If your password to connect to a secure or non-secure deployment from the Admin Client has an exclamation mark (!) at the end, then you must enter the password in double quotes when using the CONNECT command in a single line. Otherwise, the password is not accepted and the connection fails. This is required for all deployments with a strong password policy.
    Syntax: 
    CONNECT - Connect to an Oracle GoldenGate Service Manager
        |CONNECT server-url [ DEPLOYMENT deployment-name]
        |[ ( AS deployment-credentials-name|
        | USER  deployment-user-name )
        |[PASSWORD deployment-password] ]
        |[PROXY proxy-uri|
        |[(AS proxy-credentials-name
        |USER proxy-user-name)
        |[ PASSWORD proxy-password] ] ] [ ! ]

    See the CONNECT command in the Command Line Interface Reference for Oracle GoldenGate to know more.

    Note:

    The deployment credentials cannot be stored as a USERIDALIAS in the credential store because the Oracle wallet used for storing database credentials is managed by the Administration Service. Instead, a separate Oracle wallet is created for the Admin Client. The Oracle wallet is stored in the users home directory.

    The following example shows adding Oracle GoldenGate deployment user to connect to the deployment from the Admin Client:

    ADD CREDENTIALS admin USER ggadmin PASSWORD oggadmin-A1
    Output:
    2019-02-14T00:35:38Z  INFO OGG-15114  Credential store altered.

    The following example shows adding Oracle GoldenGate deployment proxy user to connect to the deployment from the Admin Client:

    ADD CREDENTIALS proxy USER proxyadmin PASSWORD oggadmin-A2
    Output:
    2019-02-14T00:35:48Z  INFO OGG-15114  Credential store altered.
    OGG (Not Connected)4> CONNECT http://www.example.com:12000 deployment EAST PROXY http:111.1.1.1:3128 as proxyadmin password oggadmin-A2
Using default deployment 'Local' 
OGG (http://www.example.com:12000 Local) 4>
    If the credentials are invalid for a proxy connection, then an error similar to the following error occurs:
    ERROR: Proxy server user name 'proxyadmin' or password is incorrect.

  4. You can view the full list of Admin Client commands using the HELP command. Use the HELP SHOWSYNTAX command to view the syntax for specific commands.

Using Wildcards in Command Arguments

You can use wildcards with certain Oracle GoldenGate commands to control multiple Extract and Replicat groups as a unit. The wildcard symbol that is supported by Oracle GoldenGate is the asterisk (*). An asterisk represents any number of characters. For example, to start all Extract groups whose names contain the letter X, issue the following command.

START EXTRACT *X*

Using Command History

The execution of multiple commands is made easier with the following tools:

  • Use the HISTORY command to display a list of previously executed commands.

  • Use the ! command to execute a previous command again without editing it.

  • Use the FC command to edit a previous command and then execute it again.

Storing and Calling Frequently Used Command Sequences

You can automate a frequently-used series of commands by using an OBEY file and the OBEY command. The OBEY file takes the character set of the local operating system. To specify a character that is not compatible with that character set, use the Unicode notation.

To use OBEY

  1. Create and save a text file that contains the commands, one command per line. This is your OBEY file. The name can be anything supported by the operating system. You can nest other OBEY files within an OBEY file.
  2. Run the Admin Client.
  3. (Optional) If using an OBEY file that contains nested OBEY files, issue the following command. This command enables the use of nested OBEY files for the current session and is required whenever using nested OBEY files.
    ALLOWNESTED
  4. Call the OBEY file by using the OBEY command from the Admin Client.
    OBEY file_name

    Where:

    file_name is the relative or fully qualified name of the OBEY file.

Example 11-37 OBEY command file

ADD EXTRACT myext, TRANLOG, BEGIN now
START EXTRACT myext

ADD REPLICAT myrep, EXTTRAIL /ggs/dirdat/aa
START REPLICAT myrep

INFO EXTRACT myext, DETAIL
INFO REPLICAT myrep, DETAIL

The following example illustrates an OBEY command file for use with the OBEY command. It creates and starts Extract and Replicat groups and retrieves processing information.

See OBEY for more information in Parameters and Functions Reference for Oracle GoldenGate.

Controlling Extract and Replicat

Here are basic directions for controlling Extract and Replicat processes.

To Start Extract or Replicat

START {EXTRACT | REPLICAT} group_name

Where:

group_name is the name of the Extract or Replicat group or a wildcard set of groups (for example, * or fin*).

To Stop Extract or Replicat Gracefully

STOP {EXTRACT | REPLICAT} group_name

Where:

group_name is the name of the Extract or Replicat group or a wildcard set of groups (for example, * or fin*).

To Stop Replicat Forcefully

STOP REPLICAT group_name !

The current transaction is aborted and the process stops immediately. You cannot stop Extract forcefully.

To End a Process that STOP Cannot Stop

KILL {EXTRACT | REPLICAT} group_name

Ending a process does not shut it down gracefully, and checkpoint information can be lost.

To Control Multiple Processes at Once

command ER wildcard specification

Where:

  • command is: KILL, START, or STOP

  • wildcard specification is a wildcard specification for the names of the process groups that you want to affect with the command. The command affects every Extract and Replicat group that satisfies the wildcard. Oracle GoldenGate supports up to 100,000 wildcard entries.

Deleting Extract and Replicat

This section contains basic directions for deleting Extract and Replicat processes.

To Delete an Extract Group

  1. Connect to the deployment from the Admin Client.

  2. Issue the DBLOGIN command as the Extract database user (or a user with the same privileges). You can use either of the following commands, depending on whether a local credential store exists. 

    DBLOGIN [SOURCEDB dsn] {USERID user, PASSWORD password [encryption_options] | USERIDALIAS alias [DOMAIN domain]}

  3. Stop the Extract process.

    STOP EXTRACT group_name

  4. Issue the following command.

    DELETE EXTRACT group_name

  5. (Oracle) Unregister the Extract group from the database.

    UNREGISTER EXTRACT group_name,database_name

To Delete a Replicat Group

  1. Stop the Replicat process.
    STOP REPLICAT group_name
  2. Issue one of the following commands to log into the database.
    DBLOGIN [SOURCEDB dsn] {USERID user, PASSWORD password [encryption_options] | USERIDALIAS alias [DOMAIN domain]}

    Where:

    • SOURCEDB dsn supplies the data source name, if required as part of the connection information.

    • USERID user, PASSWORD password specifies an explicit database login credential.

    • USERIDALIAS alias [DOMAIN domain] specifies an alias and optional domain of a credential that is stored in a local credential store.

    • encryption_options is one of the options that encrypt the password.

  3. Issue the following command to delete the group.
    DELETE REPLICAT group_name

Deleting a Replicat group preserves the checkpoints in the checkpoint table (if being used). Deleting a process group also preserves the parameter file. You can create the same group again, using the same parameter file, or you can delete the parameter file to remove the group's configuration permanently.

Specifying Object Names in Oracle GoldenGate Input

The following rules apply when specifying object names in parameter files (such as in TABLE and MAP statements), column-conversion functions, commands, and in other input.

Topics:

Specifying Filesystem Path Names in Parameter Files on Windows Systems

On Windows systems, if the name of any directory in a filesystem path name begins with a number, the path must be specified with forward slashes, not backward slashes, when listing that path in Oracle GoldenGate input, such as parameter files or commands. This requirement prevents Oracle GoldenGate from interpreting the name as an octal escape sequence. For example, the following paths contain a directory named \2014 that will be interpreted as the octal sequence \201: 

C:\ogg\2014\install\dirdat\aa
C:\ogg\install\2014\dirdat\aa

The preceding path can be used with forward slashes as follows:

C:/ogg/2014/install/dirdat/aa
C:/ogg/install/2014/dirdat/aa

For more information, see Support for Escape Sequences.

Supported Database Object Names

Object names in parameter files, command, and other input can be any length and in any supported character set. For supported character sets, see Supported Character Sets.

Oracle GoldenGate supports most characters in object and column names. Specify object names in double quote marks if they contain special characters such as white spaces or symbols.

The following lists of supported and non-supported characters covers all databases supported by Oracle GoldenGate; a given database platform may or may not support all listed characters.

Topics:

Supported Special Characters

Oracle GoldenGate supports all characters that are supported by the database, including the following special characters. Object names that contain these special characters must be enclosed within double quotes in parameter files.

Character Description

/

Forward slash (See Specifying Names that Contain Slashes)

*

Asterisk (Must be escaped by a backward slash when used in parameter file, as in: \*)

?

Question mark (Must be escaped by a backward slash when used in parameter file, as in: \?)

@

At symbol (Supported, but is often used as a resource locator by databases. May cause problems in object names)

#

Pound symbol

$

Dollar symbol

%

Percent symbol (Must be %% when used in parameter file)

^

Caret symbol

( )

Open and close parentheses

_

Underscore

-

Dash

<space>

Space
Non-supported Special Characters

The following characters are not supported in object names and non-key column names.

Character Description

\

Backward slash (Must be \\ when used in parameter file)

{ }

Begin and end curly brackets (braces)

[ ]

Begin and end brackets

=

Equal symbol

+

Plus sign

!

Exclamation point

~

Tilde

|

Pipe

&

Ampersand

:

Colon

;

Semi-colon

,

Comma

' '

Single quotes

" "

Double quotes

'

Accent mark (Diacritical mark)

.

Period

<

Less-than symbol (or beginning angle bracket)

>

Greater-than symbol (or ending angle bracket)

Specifying Names that Contain Slashes

If a table name contains a forward-slash character (/) in any part of its name, that name component must be enclosed within double quotes unless the object name is from an IBM i platform . The following are some examples: 

"c/d" 
"/a".b 
a."b/"

If the name contains a forward slash that is not enclosed within double quotes, Oracle GoldenGate treats it as a name that originated on the IBM i platform (from a DB2 for i database). The forward slash in the name is interpreted as a separator character.

Qualifying Database Object Names

Object names must be fully qualified in the parameter file. This means that every name specification must be qualified, not only those supplied as input to Oracle GoldenGate parameter syntax, but also names in a SQL procedure or query that is supplied as SQLEXEC input, names in user exit input, and all other input supplied in the parameter file.

Oracle GoldenGate supports two-part and three-part object names, as appropriate for the database.

Topics:

Two-part Names

Most databases require only two-part names to be specified, in the following format:

owner.object

For example: HR.EMP

Where:

owner is a schema or database, depending on how the database defines a logical namespace that contains database objects. object is a table or other supported database object.

The databases for which Oracle GoldenGate supports two-part names are as follows, shown with their appropriate two-part naming convention:

  • Db2 for i: schema.object and library/file(member)

  • Db2 LUW: schema.object

  • Db2 on z/OS: schema.object

  • MySQL: database.object

  • Oracle Database (non-CDB databases): schema.object

  • SQL Server: schema.object

  • Teradata: database.object

Three-part Names

Oracle GoldenGate supports three-part names for the following databases:

  • Oracle container databases (CDB)

Three-part names are required to capture from a source Oracle container database because one Extract group can capture from more than one container. Thus, the name of the container, as well as the schema, must be specified for each object or objects in an Extract TABLE statement.

Specify a three-part Oracle CDB name as follows:

container.schema.object

For example: PDBEAST.HR.EMP

Applying Data from Multiple Containers or Catalogs

To apply data captured from multiple source containers or catalogs to a target Oracle container database, both three- and two-part names are required. In the MAP portion of the MAP statement, each source object must be associated with a container or catalog, just as it was in the TABLE statement. This enables you (and Replicat) to properly map data from multiple source containers or catalogs to the appropriate target objects. In the TARGET portion of the MAP statement, however, only two-part names are required. This is because Replicat can connect to only one target container or catalog at a time, and schema.owner is a sufficient qualifier. Multiple Replicat groups are required to support multiple target containers or catalogs. Specify the target container or catalog with the TARGETDB parameter.

Specifying a Default Container or Catalog

You can use the SOURCECATALOG parameter to specify a default catalog for any subsequent TABLE, MAP, (or Oracle SEQUENCE) specifications in the parameter file.

The following example shows the use of SOURCECATALOG to specify the default Oracle PDB named pdbeast for region and jobs objects, and the default PDB named pdbwest for appraisal objects. The objects in pdbeast are specified with a fully qualified three-part name, which does not require a default catalog to be specified. 

TABLE pdbeast.hr.emp*; 
SOURCECATALOG pdbeast 
TABLE region.country*; 
TABLE jobs.desg*; 
SOURCECATALOG pdbwest 
TABLE appraisal.sal*;

Specifying Case-Sensitive Database Object Names

Oracle GoldenGate supports case-sensitive names. Follow these rules when specifying case-sensitive objects.

  • Specify object names from a case-sensitive database in the same case that is used to store them in the host database. Keep in mind that, in some database types, different levels of the database can have different case-sensitivity, such as case-sensitive schema but case-insensitive table. If the database requires quotes to enforce case-sensitivity, put quotes around each object that is case-sensitive in the qualified name.

    Correct: TABLE "Sales"."ACCOUNT"

    Incorrect: TABLE "Sales.ACCOUNT"

  • Oracle GoldenGate converts case-insensitive names to the case in which they are stored when required for mapping purposes.

Table 11-18 provides an overview of the support for case-sensitivity in object names, per supported database. Refer to the database documentation for details on this type of support.

Table 11-18 Case Sensitivity of Object Names Per Database

Database Requires quotes to enforce case-sensitivity? Unquoted object name Quoted object name

DB2

Yes. Differentiates between case-sensitive and case-insensitive by use of quotes.

Case-insensitive, stores in upper case

Case-sensitive, stores in mixed case

MySQL

(Case-sensitive database)

No

  • Always case-sensitive, stores in mixed case

  • The names of columns, triggers, and procedures are case-insensitive

No effect

No effect

Oracle Database

Yes. Differentiates between case-sensitive and case-insensitive by use of quotes.

Case-insensitive, stores in upper case

Case-sensitive, stores in mixed case

SQL Server

(Database created as case-sensitive)

No

Always case-sensitive, stores in mixed case

No effect

No effect

SQL Server

(Database created as case-insensitive)

No

Always case-insensitive, stores in mixed case

No effect

No effect

Teradata

No

Always case-insensitive, stores in mixed case

No effect

No effect

Note:

For all supported databases, passwords are always treated as case-sensitive regardless of whether the associated object name is quoted or unquoted.

Using Wildcards in Database Object Names

You can use wildcards for any part of a fully qualified object name, if supported for the specific database. These name parts can be the following: the container, database, or catalog name, the owner (schema or database name), and table or sequence name. For specifics on how object names and wildcards are supported, see the Oracle GoldenGate installation and configuration guide for that database.

Where appropriate, Oracle GoldenGate parameters permit the use of two wildcard types to specify multiple objects in one statement:

  • A question mark (?) replaces one character. For example in a schema that contains tables named TABn, where n is from 0 to 9, a wildcard specification of HQ.TAB? returns HQ.TAB0, HQ.TAB1, HQ.TAB2, and so on, up to HQ.TAB9, but no others. This wildcard is not supported for the DB2 LUW database nor for DEFGEN. This wildcard can only be used to specify source objects in a TABLE or MAP parameter. It cannot be used to specify target objects in the TARGET clause of TABLE or MAP.

  • An asterisk (*) represents any number of characters (including zero sequence). For example, the specification of HQ.T* could return such objects as HQ.TOTAL, HQ.T123, and HQ.T. This wildcard is valid for all database types throughout all Oracle GoldenGate commands and parameters where a wildcard is allowed.

  • In TABLE and MAP statements, you can combine the asterisk and question-mark wildcard characters in source object names only.

Topics:

Rules for Using Wildcards for Source Objects

For source objects, you can use the asterisk alone or with a partial name. For example, the following source specifications are valid:

  • TABLE HQ.*;

  • TABLE PDB*.HQ.*;

  • MAP HQ.T_*;

  • MAP HQ.T_*, TARGET HQ.*;

The TABLE, MAP and SEQUENCE parameters take the case-sensitivity and locale of the database into account for wildcard resolution. For databases that are created as case-sensitive or case-insensitive, the wildcard matches the exact name and case. For example, if the database is case-sensitive, SCHEMA.TABLE is matched to SCHEMA.TABLE, Schema.Table is matched to Schema.Table, and so forth. If the database is case-insensitive, the matching is not case-sensitive.

For databases that can have both case-sensitive and case-insensitive object names in the same database instance, with the use of quote marks to enforce case-sensitivity, the wildcarding works differently. When used alone for a source name in a TABLE statement, an asterisk wildcard matches any character, whether or not the asterisk is within quotes. The following statements produce the same results: 

TABLE hr.*;
TABLE hr."*";

Similarly, a question mark wildcard used alone matches any single character, whether or not it is within quotes. The following produce the same results:

TABLE hr.?;
TABLE hr."?";

If a question mark or asterisk wildcard is used with other characters, case-sensitivity is applied to the non-wildcard characters, but the wildcard matches both case-sensitive and case-insensitive names.

  • The following TABLE statements capture any table name that begins with lower-case abc. The quoted name case is preserved and a case-sensitive match is applied. It captures table names that include "abcA" and "abca" because the wildcard matches both case-sensitive and case-insensitive characters. 

    TABLE hr."abc*";
TABLE hr."abc?";

  • The following TABLE statements capture any table name that begins with upper-case ABC, because the partial name is case-insensitive (no quotes) and is stored in upper case by this database. However, because the wildcard matches both case-sensitive and case-insensitive characters, this example captures table names that include ABCA and "ABCa". 

    TABLE hr.abc*;
TABLE hr.abc?;
Rules for Using Wildcards for Target Objects

When using wildcards in the TARGET clause of a MAP statement, the target objects must exist in the target database. (The exception is when DDL replication is being used, which allows new schemas and their objects to be replicated as they are created.)

For target objects, only an asterisk can be used. If an asterisk wildcard is used with a partial name, Replicat replaces the wildcard with the entire name of the corresponding source object. Therefore, specifications such as the following are incorrect: 

TABLE HQ.T_*, TARGET RPT.T_*;
MAP HQ.T_*, TARGET RPT.T_*;

The preceding mappings produce incorrect results, because the wildcard in the target specification is replaced with T_TEST (the name of a source object), making the whole target name T_T_TESTn. The following illustrates the incorrect results:

  • HQ.T_TEST1 maps to RPT.T_T_TEST1

  • HQ.T_TEST2 maps to RPT.T_T_TEST2

  • (The same pattern applies to all other HQ.T_TESTn mappings.)

The following examples show the correct use of asterisk wildcards.

MAP HQ.T_*, TARGET RPT.*;

The preceding example produces the following correct results:

  • HQ.T_TEST1 maps to RPT.T_TEST1

  • HQ.T_TEST2 maps to RPT.T_TEST2

  • (The same pattern applies to all other HQ.T_TESTn mappings.)

Fallback Name Mapping

Oracle GoldenGate has a fallback mapping mechanism in the event that a source name cannot be mapped to a target name. If an exact match cannot be found on the target for a case-sensitive source object, Replicat tries to map the source name to the same name in upper or lower case (depending on the database type) on the target. Fallback name mapping is controlled by the NAMEMATCH parameters. For more information, see Parameters and Functions Reference for Oracle GoldenGate.

Asterisks or Question Marks as Literals in Object Names

If the name of an object itself includes an asterisk or a question mark, the entire name must be escaped and placed within double quotes, as in the following example:

TABLE HT."\?ABC";
How Wildcards are Resolved

By default, when an object name is wildcarded, the resolution for that object occurs when the first row from the source object is processed. (By contrast, when the name of an object is stated explicitly, its resolution occurs at process startup.) To change the rules for resolving wildcards, use the WILDCARDRESOLVE parameter. The default is DYNAMIC.

Excluding Objects from a Wildcard Specification

You can combine the use of wildcard object selection with explicit object exclusion by using the EXCLUDEWILDCARDOBJECTSONLY, CATALOGEXCLUDE, SCHEMAEXCLUDE, MAPEXCLUDE, and TABLEEXCLUDE parameters.

Differentiating Case-Sensitive Column Names from Literals

By default, Oracle GoldenGate follows SQL-92 rules for specifying column names and literals. In Oracle GoldenGate parameter files, conversion functions, user exits, and commands, case-sensitive column names must be enclosed within double quotes if the database requires quotes around a name to support case-sensitivity. For example:

"columnA"

Case-sensitive column names in databases that do not require quotes to enforce case-sensitivity must be specified as they are stored in the database. For example:

ColumnA

Literals must be enclosed within single quotes. In the following example, Product_Code is a case-sensitive column name in an Oracle database, and the other strings are literals. 

@CASE ("Product_Code", 'CAR', 'A car', 'TRUCK', 'A truck')

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:

  1. From Extract or Replicat section of the Administration Service Overview Page, click Action and then click Details.

  2. 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 Parameters and Functions 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.

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 Parameters and Functions Reference for Oracle GoldenGate for more information about OBEY.

See Parameters and Functions 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

  1. 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;
  2. 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-38 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-39 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.