Control how the Parallel Upgrade Utility (catctl.pl) runs. You can also use these arguments to run the dbupgrade shell command.
Note:
The shell command utility dbupgrade starts catctl.pl. The dbupgrade utility resides in the ORACLE_HOME/bin directory. You can use the shell command utility to start the Parallel Upgrade Utility at the command prompt.
You can either run the utility using default values, or you can use
catctl.pl input parameters to specify Parallel Upgrade Utility arguments.
Table 4-1 Parallel Upgrade Utility (catctl.pl) Parameters
Parameter Description
-c Specifies a space-delimited inclusion list for PDBs that you want to upgrade. For example, in an Oracle Multitenant deployment with PDB1, PDB2, PDB3, and PDB4, include PDB1 and PDB2, but exclude the PDBs not named. PDB 1 and PDB 2 are upgraded, but PDB 3 and PDB4 are not upgraded.
Linux and UNIX (use single quotes):
-c 'PDB1 PDB2'
Windows (use double quotes):
-c "PDB1 PDB2"
Table 4-1 (Cont.) Parallel Upgrade Utility (catctl.pl) Parameters
Parameter Description
-C Specifies a space-delimited exclusion list for PDBs that you want to upgrade. For example, in an Oracle Multitenant deployment with PDB1, PDB2, PDB3, and PDB4, you can use an exclusion list to exclude PDB1 and PDB2, but include the PDBs not named. PDB1 and PDB2 are not upgraded, but PDB3 and PDB4 are upgraded.
Linux and UNIX (use single quotes):
-C 'PDB1 PDB2'
Windows (use double quotes):
-C "PDB1 PDB2"
Note: -c and -C are mutually exclusive.
-C 'CATCTL_LISTONLY' is an option that specifies that the Parallel Upgrade Utility processes only the PDBs in a priority list. Use this option with the -L parameter, specifying a list.
-d Specifies the location of the directory containing the files that you want processed.
-e Sets echo OFF while running the scripts. The default is echo ON.
-E Enables you to run an upgrade emulation.
You can use the -E parameter to run the Parallel Upgrade Utility in emulation mode to test how priority lists run, or to test how other upgrade parameter selections are carried out during an upgrade. For example, you can run an upgrade emulation to obtain more information about how the resource allocation choices you make using the -n and -N parameters are carried out.
To carry out an upgrade emulation, complete all upgrade preparations before you run the Parallel Upgrade Utility, and then run the command using -E.
When you run the Parallel Upgrade Utility with the -E parameter, and call a priority list as part of the command using the -L parameter, the utility writes the upgrade order to the file catctl_priority_run.lst. This list is placed in the file path that you specify by the -l parameter, or in the default log file area if you do not specify a different output file path.
-F Forces a cleanup of previous upgrade errors.
Non-CDB databases require only the -F parameter. For CDBs, use this option with a space-delimited inclusion list, which you specify with -c. -i Specifies an identifier to use when creating spool log files.
-l Specifies the location for the directory to use for spool log files.
The default location is Oracle_base/cfgtoollogs/dbname/
upgradedatetime. The date and time strings are in the character string format YYYYMMDDHHMMSC, in which YYYY designates the year, MM designates the month, DD designates the day, HH designates the hour, MM designates the minute, and SC designates the second.
Oracle strongly recommends that you do not write log files to the /admin directory.
Chapter 4 Upgrading Manually with Parallel Upgrade Utility
Table 4-1 (Cont.) Parallel Upgrade Utility (catctl.pl) Parameters
Parameter Description
-L Upgrades PDBs using a priority list during an Oracle Database upgrade, and specifies the priority list name. The priority list updates priority status in the database during upgrade. This priority listing is maintained in future upgrades.
By default the CDB$ROOT and PDB$SEED databases are always processed first. They are processed first even if they are not added to a priority list. All PDBs in the priority list are processed before PDBs not in the priority list.
-M Keeps CDB$ROOT in UPGRADE mode while the PDBs are upgraded.
For non-CDBs, this parameter is ignored.
During CDB upgrades, using this parameter setting places the CDB and all its PDBs in upgrade mode, which can reduce total upgrade time. However, you cannot bring up any of the PDBs until the CDB and all its PDBs are upgraded.
By default, if you do not use the -M parameter setting, then CDB$ROOT is upgraded and restarted in normal mode, and the normal background processes are started. As each PDB is upgraded, you can bring the PDB online while other PDBs are still being upgraded.
-n Specifies the number of processes to use for parallel operations.
Non-CDBs: The -n parameter specifies the number of SQL processes to use when upgrading the database.
Multitenant architecture databases (CDBs): The number of PDBs upgraded concurrently is controlled by the value of the -n parameter. Multiple PDB upgrades are processed together. Starting in Oracle Database 12c, the default value for multitenant architecture databases is the number of CPUs on your system. A cpu_count equal to 24 equates to a default value of 24 for -n.
Values for the -n parameter:
Non-CDBs: The maximum value for -n is 8. The minimum value is 1. The default value is 4.
Multitenant architecture databases (CDBs): The maximum value for -n is unlimited. The minimum value is 4. The maximum PDB upgrades running concurrently is the value of -n divided by the value of -N.
-N Specifies the number of SQL processors to use when upgrading PDBs.
For non-CDBs, this parameter is ignored.
For CDBs, the maximum value is 8. The minimum value is 1. The default value is 2.
-p Restarts from the specified phase. When you re-run an upgrade, it does not restart phases already completed successfully.
-P Stops from the specified phase.
-R Resumes the upgrade from a failed phase. Using the -R parameter enables the upgrade to resume at the point of failure, so that only the missing upgrade phases are rerun.
-s Names the SQL script that initializes sessions.
-S Specifies serial upgrade instead of parallel.
Starting with Oracle Database 12.2, catupgrd.sql is no longer supported using the -S option.
Table 4-1 (Cont.) Parallel Upgrade Utility (catctl.pl) Parameters
Parameter Description
-t Uses Classic Upgrade for the upgrade, instead of the default Replay Upgrade process.
-T Takes offline user schema-based table spaces.
-u Specifies user name, and prompts for password.
-y Displays phases only.
-z Turns on production debugging information for catcon.pm. -Z Turns on debug tracing information for catctl.pl.
For example, to set the number to 1, enter -Z 1.