1 Overview of Upgrading Oracle GoldenGate

This guide contains instructions for upgrading Oracle GoldenGate Classic Architecturefrom previous releases of Oracle GoldenGate, to the current release as well as instructions on how apply patches for Oracle GoldenGate.

Topics:

• Who Should Perform the Upgrade
  
• Before You Upgrade
  
• Upgrade Considerations if Using Character-Set Conversion
  
• Upgrade Considerations if Using Quoted Object Names
  

Who Should Perform the Upgrade

Upgrades to Oracle GoldenGate should be performed by an administrator who has thorough knowledge of the commands that are necessary to control processes and obtain status information.

Before You Upgrade

Before performing the upgrade procedure, read the Release Notes for Oracle GoldenGate to determine whether the new release affects the following in your configuration:

• New default process behavior.

• Parameters that changed or were deprecated.

• Parameters that were added to support a desired new feature or database type.

• Parameter default values that have changed.

• New data type support that might require changes to TABLE or MAP statements.

• Interaction with native database components that might require database change.

You can prevent startup delays that can cause lag by having all of your parameter changes made ahead of time, so that they are ready when you restart the processes. You should not make parameter changes while a process is running, but you can:

1. Make a copy of the parameter file.
2. Make edits to the copy.
3. After you shut down the processes during the upgrade procedure, copy the old parameter file to a new name (to save it as backup).
4. Copy the new parameter file to the old parameter file's name.

Upgrade Considerations if Using Quoted Object Names

Oracle GoldenGate treats strings that are within single quotes as literals. Oracle GoldenGate has supported double-quoted object names since release 11.2 but did not fully implement the rule of single quotes for literals until release 12.1. Supporting double quotes for object names and single quotes for literals brings Oracle GoldenGate into compliance with SQL-92 rules and is now enabled by default. The USEANSISQLQUOTES parameter, which forced the SQL-92 standard in previous releases, is now deprecated.

The change to default SQL-92 rules affects object names in parameter files, input to SQLEXEC clauses, OBEY files, conversion functions, user exits, and commands. You have the following options as a result of this change:

• Retain non-SQL-92 quote rules: Oracle GoldenGate retains backward compatibility to enable the retention of current parameter files that do not conform to SQL-92 rules. To retain non-SQL-92 rules, add the NOUSEANSISQLQUOTES parameter to the GLOBALS file before you perform the upgrade and retain that parameter going forward. NOUSEANSISQLQUOTES affects Extract, Replicat, DEFGEN, and GGSCI.

• Upgrade your parameter files to use SQL-92 rules: Oracle GoldenGate provides the convprm conversion tool which you can run to convert your parameter files to be in conformance with SQL-92 rules. Run the convprm tool before you start the upgrade process.

• Overview of the convprm Tool
  
• Running convprm
  

Overview of the convprm Tool

The following describes the convprm tool:

• It is a command line program which can be run either manually or scripted.

• It converts string literals from double-quoted character strings to single-quoted character strings, but leaves double-quoted object names intact. It can distinguish between an object name and a string literal even when both are represented as a sequence of characters delimited with double quotes.

• It escapes quotation marks. Quotation marks must be escaped when the character that is used to delimit the string appears in the literal string itself. For example, the sentence "This character "" is a double quote" contains an escaped quote mark. The sentence 'This character '' is a single quote' contains an escaped single quote mark. When converting from double quotes to single quotes, convprm removes one of the repeated double quotes from escaped double quotes and escapes the single quotes that are embedded in the character sequence.

• It issues a warning message if NOUSEANSISQLQUOTES is specified in the GLOBALS file. The message states that the converted parameter file is incompatible with NOUSEANSISQLQUOTES, but the parameter file was updated anyway.

• It recursively converts the files that are included through an OBEY or INCLUDE parameter.

• It creates a backup of the initial parameter file in the same directory as the original file. The backup has the name of the original file with the .bck suffix. The creation of a backup file can be disabled when you run the convprm tool.

• It converts the character set. The character set for the new parameter file is taken from the CHARSET parameter in the original parameter file. Absent that parameter, the character set is taken from the CHARSET parameter in the GLOBALS file. Absent a GLOBALS parameter, the new parameter file is written in the character set of the local operating system.

Table 1-1 provides examples of the conversion outcome.

Table 1-1 Comparison of Input Requirements for [NO]USEANSISQLQUOTES

Input variable	String literal with old syntax	String literal with new syntax
Double quotes are escaped in the old syntax but not in the new syntax.	"abc""def"	'abc"def'
Single quotes are escaped in the new syntax but not in the old syntax.	"abc'def"	'abc''def'

Running convprm

To use the convprm tool:

1. Run convprm with the following syntax:

   convprm [options] input_files
   

   where:

   • {-h | --help} displays usage.

   • {-v |--version} displays version information.

   • {-i | --follow-include} recursively converts files included through an OBEY or INCLUDE parameter.

   • {-n |--no-backup} does not create a copy of the original file.

   • {-s | --silent} does not display status messages.

   • {-q | --quotes} performs quote conversion. This is the default.

   • {-d | --dry-run} does not change the parameter file or create a backup file. It only prints out what would happen as the result of the conversion.

   • input_files is a list of the parameter files that are to be converted. Separate each file name with a white space, for example:

     convprm [options] extfin extacct exthr
     

2. Examine the parameter file to make certain the conversion completed successfully. Status messages are displayed at the beginning, during, or at the end of the file conversion process.

On errors, the process abends in the same way as other Oracle GoldenGate executables. All error messages that cause the converter to fail are sent to the Oracle GoldenGate error log.

If you are currently using the USEANSISQLQUOTES parameter, you may remove it or leave it in the parameter files. It is now the default.