                             OPATCH USERS GUIDE
                Copyright (c) Oracle Corporation 2002, 2003 and 2004

INTRODUCTION
------------

OPatch is a set of Perl scripts that allow the application and rolling back 
of interim patches to an Oracle product. The program has sub-commands that 
may take arguments. The program requires that the Perl language interpreter
(ref: http://www.cpan/org/ ) is available on the current system. 

Help is available for all commands.

OPatch relies upon Perl version 5.005_03 or greater to run but version
5.6 or greater is recommended.

We will update this user-guide as arguments and commands change.

OPatch expects users to have commands such as jar, java, ar, cp and make
(depending on platforms) available in their PATH.

ENVIRONMENTAL VARIABLES
-----------------------

$ORACLE_HOME must point to a valid Oracle Home and matches the value when that Oracle Home was installed. A list of products that have been installed can be retrieved from the inventory by using "lsinventory -all".

REAL APPLICATION CLUSTERS
-------------------------

When patching a RAC installation with either a rolling patch or minimum
downtime the user is prompted for which nodes to patch during the patch
installation process. A rolling RAC patch is identified inside the patch
and cannot be enabled when invoking the patch tool. More details are in
the FAQ that should be in the same directory as this file.

When patching a RAC on certain platforms, it is important that the LD_LIBRARY_PATH must be set up correctly.  Please see the FAQ for details.

LIMITATIONS
-----------

The current version of OPatch has some limitions that will be resolved
in the future. These limitations are:

1.	Shared ORACLE_HOMEs (clustered file systems):

	Rolling RAC and minimum down options are not supported and should
	not be used on RAC clusers with a shared ORACLE_HOME. This 
	is normally seen when CFS (clustered file systems) are used for
	the installation.

	Patching this type of installtion should be done on a single machine.
	Any instance that uses the ORACLE_HOME on a CFS that is to be 
	patched should be stopped on all nodes before patching the
	installation.

2.	Simultaneous installing new instances and patching:

	Currently installing a new instance while patching an existing
	installation is not supported. Inventory corruption may 
	result from this activity.

3.    Patch process must finish
      
      Currently a partially installed interim patch cannot be removed. 
   The patch process must finish. Once the patch process has finished 
   the patch can be removed.


GENERAL USAGE
-------------

      $ 'opatch apply ...' is to apply a patch
      $ 'opatch rollback ...' is to roll back a patch
      $ 'opatch lsinventory' is to show inventory on an Oracle Home
      $ 'opatch lsinventory -all' is to list all products on all Oracle Homes
      $ 'opatch query ...' is to query a given patch from specific details
      $ 'opatch version' is to show the version of the OPatch being used.

SYNOPSIS
--------

    < perl > < opatch > < opatch sub-command > [ < command_arguments > ]

where:

    perl:               A version of perl. The version must be 5.005_03 or
                        greater but 5.6 or greater is recommended.
    opatch:             The path to the opatch program.
    opatch sub-command: The sub-command to use.
    command_arguments:  Any arguments supported by the sub-command.


DETAILS
-------

Invoking OPatch without arguments or with the 'help' sub-command returns
the list of valid sub-commands to the user:

$ opatch

 Usage: opatch [ -help ] [ -r[eport] ] [ command ]

            command := apply
                       lsinventory
                       query
                       rollback
                       version

 <global_arguments> := -help   Displays the help message for the command.
                       -report Print the actions without executing (deprecated).

                       


APPLY
-----

The apply command is used to install a interim patch.

$ opatch apply -help

DESCRIPTION
This operation applies an interim patch to an ORACLE_HOME from the current
directory. The patch location can specified using the parameter
patch_location.

SYNTAX
opatch apply   [-delay <value> ] [ -force ]
               [-invPtrLoc <Path to oraInst.loc> ]
               [-jdk <LOC> ] [-jre <LOC> ] [-local ]
               [-minimize_downtime ] [-no_bug_superset ]
               [-no_inventory ] [-oh <ORACLE_HOME> ]
               [-responseFile <path to response file>]
               [-retry <value> ] [-silent ] [-verbose ]  [-nolink]
               [-pre <parameters for the pre
                      script in escaped double quotes> [-opatch_pre_end] ]
               [-post <parameters for the post
                      script in escaped quotes> [-opatch_post_end] ]
               [-no_sysmod] <patch zipfile>
OPTIONS
      -delay: If -retry is specified, this options  tells OPatch how many
              seconds it should wait before attempting to lock inventory again
              in case of a previous failure.

      -error_on_conflict: Deprecated. Does not do anything.

      -force: If a conflict exist which prevents the patch from being applied,
              the -force flag can be used to apply the patch.
              OPatch will remove all the conflicting patches before applying
              the current patch.

      -invPtrLoc: Used to locate the oraInst.loc file. Needed when the
              installation used the -invPtrLoc flag. This should be the path 
	      to the oraInst.loc file from -jdk location

      -jre:  This option tells OPatch to use JRE (java) from the specified
             location instead of the default location under Oracle Home.
             Both -jdk and -jre options cannot be specified together.
             OPatch will display error in that case

      -local: Patch the local node, then update inventory of the local node.
              Do not propagate the patch or inventory update to other nodes.

      -minimize_downtime: Only applied to RAC instances. User supplies the
             order of nodes to be patched. This option cannot be used in
             conjunction with -local option with a rolling patch.

      -no_bug_superset: This option tells OPatch to error out if the current
             patch's bugs-to-fix is a super-set (or same set) of an installed
             patch's bugs-fixed in the Oracle Home.

      -no_inventory: Bypass the inventory for reading and updates

      -oh: The oracle home to work on. This takes precedence over the
           environment variable ORACLE_HOME

      -retry: This option tells OPatch how many times it should retry in case
              of an inventory lock failure.

      -silent: This suppresses any user-interaction and uses the response file
               instead

      -verbose: This option prints more OPatch output to the screen as well as
                to the log file

      -report: Just prints out the actions without executing

      -responseFile: Specifies the path to the response file. Should be used
		   in conjunction with the  --silent option. Default however
		   is $OH/OPatch/opatch.rsp.

      -nolink: The nolink option does not perform any make operations. This
               option can be used during multiple patch applications and
               perform the linking step only once. OPatch does not keep track
               of the make operations it did not perform. It is the job of the
               OPatch users to make sure the execute OPatch without this option
               at the end, so that compilation happens once

      -opatch_post_end: This option is used to mark the end of post options.
              Without this option everything after post till end of the command
              is passed into post.This option is meaningless without -post option.

      -opatch_pre_end:  This option is used to mark the end of pre options.
              Without this option everything after pre till end of the command
              is passed into pre.This option is meaningless without -pre option.

      -pre: This option is used to pass parameters to the pre script. This
            script is executed before application of the patch. The value for
            this option have to be enclosed in double quotes

      -post: This option is used to pass parameters to the post script. This
             script is executed after application of the patch. The value for
             this option have to be enclosed in double quotes

      -no_sysmod: This option specifies not to update the files in the system.
             It just updates the inventory. It also will not execute the pre
             and post scripts

PARAMETERS
      patch zipfile:  Path to the zipfile for the patch. OPatch first unzips
              the patch in $ORACLE_HOME/.patch_storage and then installs the
              patch from there.  The unzipped patch location should look like
              <patch_id>_<version_no>.


LSINVENTORY
-----------

This command reports what's installed on the current system.

$ opatch lsinventory -help

DESCRIPTION
        List the inventory for a particular $ORACLE_HOME or display all
        installations that can be found.

SYNTAX
opatch lsinventory [-all ] [-delay <value> ] [-detail ]
               [-invPtrLoc <Path to oraInst.loc> ] [-jre <LOC> ]
               [-oh <ORACLE_HOME> ] [-retry <value> ] [-patch] [-oh]

OPTIONS
      -all: Report the name and installation directory for each
        $ORACLE_HOME found.

      -delay: If -retry is specified, this option tells OPatch how many
        seconds it should wait before attempting to lock inventory again
        in case of a previous failure.

      -detail: Report installed products and other details. This option cannot
        be used in conjunction with ?all option

      -invPtrLoc: Used to locate the oraInst.loc file. When the installation
        used the invPtrLoc flag. This should be the path to the
        oraInst.loc file

      -jre: This option tells OPatch to use JRE (java) from the specified
        location instead of the default location under Oracle Home

      -retry: This option tells OPatch how many times it should retry in case
        of an inventory lock failure

      -patch: Lists the patch IDs installed in the oracle home

      -oh: The oracle home to work on. This takes precedence over the
        environment variable ORACLE_HOME

PARAMETERS
        This operation does not have any required parameters.


ROLLBACK
--------

The rollback command removes a interim patch from the appropriate 
$ORACLE_HOME.

$ opatch rollback -help

DESCRIPTION
Rollback an existing one-off patch indicated by the reference-id.

SYNTAX

opatch rollback -id <ID> -ph <Patch Location>  [-delay <value>]
          [-invPtrLoc <Path to oraInst.loc> ] [-jdk <LOC>]
          [-jre <LOC> ] [-local]  [-oh <ORACLE_HOME>]\
          [-retry <value>]  [-silent]  [-verbose]  [-nolink]
          [-responseFile <path to response file>] [-nolink]
          [-pre <parameters for the pre script
                 in escaped double quotes> [-opatch_pre_end] ]
          [-post <parameters for the post script
                  in escaped double quotes>[ -opatch_post_end] ]
          [-no_sysmod]

OPTIONS

          -delay: If -retry is specified, this option tells OPatch how many
                seconds it should wait before attempting to lock inventory
                again in case of a previous failure.

          -id: Use 'lsinventory' option to display all patch id's. Each
		one-off patch is indicated by its id. To rollback a patch 
		the id for that patch must be supplied

          -invPtrLoc: Used to locate the oraInst.loc file. Needed when the
                installation used the invPtrLoc flag. This should be the path
                to the oraInst.loc file

          -jdk: This option tells OPatch to use JDK (jar) from the specified
                location instead of the default location under Oracle Home.
                If jre option is not specified, java virtual machine is
                executed from jdk location

          -jre: This option tells OPatch to use JRE (java) from the specified
                location instead of the default location under Oracle Home.
                Both jdk and jre options cannot be specified together. OPatch
                will display error in that case

          -local: Roll back then update inventory of the local node.  Do not
                propagate the patch or inventory update to other nodes

          -oh: The oracle home to work on. This takes precedence over the
                environment variable ORACLE_HOME

          -ph: Specify the valid patch directory area. Rollback will use the
                command types found in the patch directory to identify what
                commands are to be used for the current operating system

          -retry: This option tells OPatch how many times should retry
                in case of an inventory lock failure.

          -silent: This suppresses any user-interaction and defaults any Y|N
                question to Y. This option is not supported on RAC yet

          -verbose: This option prints more OPatch output to the screen
                as well as to the log file

          -report: Just prints out the actions, without executing

          -responseFile: Specifies the path to the response file. Default
                however is $OH/OPatch/opatch.rsp

          -nolink: Do not perform the make operations in the patch. This ption
                can be used during multiple patch removals and perform the
                compilation step only once

          -opatch_post_end: This option is used to mark the end of post options.
              Without this option everything after post till end of the command
              is passed into post. This option is meaningless without -post option.

          -opatch_pre_end:  This option is used to mark the end of pre options.
              Without this option everything after pre till end of the command
              is passed into pre.This option is meaningless without -pre option.

          -pre: This option is used to pass parameters to the pre script.
                This script is executed before removal of the patch. The value
                for this option have to be enclosed in double quotes

          -post: This option is used to pass parameters to the post script.
                This script is executed after removal of the patch. The value
                for this option have to be enclosed in double quotes

          -no_sysmod: This option specifies not to update the files in the
                system. It just updates the inventory. It also will not execute
                the pre and post scripts

PARAMETERS
        Patch ID of the patch to be rolled back unless the command is invoked
                within a patch area.


To find the patch id numbers, use 'opatch lsinventory'.

Currently a patch directory must also be supplied. Under normal practice
the directory for the patch when it was installed is available. It is
needed so a list of commands can be retrieved. Any patch directory should 
suffice.

QUERY
-----

This command queries a given patch for specific details.

$ opatch query -help

DESCRIPTION
        This operation loads and prints out various information about a patch.
        Parameter patch_location points to where a patch is located.
        For example, if you specify "path", there should be sub-dir.
        "etc/config" under "path".

SYNTAX
        opatch query  [-all] [-jre] [-jdk] [-oh] patch_location

OPTIONS

        -all:   Get everything available about a patch. This is equivalent
                to setting all available options.

        -jdk:   This option tells OPatch to use JDK (jar) from the specified
                location instead of the default location under Oracle Home.
                If jre option is not specified, java virtual machine is
                executed from jdk location

        -jre:   This option tells OPatch to use JRE (java) from the specified
                location instead of the default location under Oracle Home.
                Both jdk and jre options cannot be specified together. OPatch
                will display error in that case

        -oh:    The oracle home to work on. This takes precedence over the
                environment variable ORACLE_HOME.

PARAMETERS
        The Location of the patch to be queried.


VERSION
-------

This command prints the current version number of the patch tool.


==========================================================================
phnguyen 07/22/03
phnguyen 10/10/03
vsriram  11/25/04
