You are on page 1of 18

THE ADPATCH UTILITY

1
WHAT IS ADPATCH?
AutoPatch or AdPatch is a utility that is used to apply
patches and release updates.

Similar to AutoInstall and adadmin, AutoPatch can run


parallel workers.

Before AutoPatch replaces a file with one from the patch, it


compares the version numbers to ensure that your file will
be replaced only with a newer one. Unless adpatch is run
with forcecopy on the command line:

Adpatch options=forcecopy

Or if the patch driver specifies forcecopy as an action:

Forcecopy po reports POXPOVPS.rdf 110.21

Before replacing any file, AutoPatch always makes a backup


copy.

WHAT DOES A PATCH LOOK LIKE?


A patch may consist of many files.

When you receive a patch, you actually receive a


compressed archive (zip format) of several files. These
include:

Patch driver files


• Every patch comes with one or more patch driver files.
• The patch driver file lists the files (and version numbers) included in the
patch.
• This file tells AutoPatch what steps need to be done to apply the patch and in
what order to apply these steps.

2
Three types of patch drivers, each with its own naming convention:
• c<bugno>.drv is the file, or copy, driver, responsible for copying files and
linking executables.
• d<bugno>.drv is the database driver, and runs SQL scripts and programs
that update the database.
• g<bugno>.drv is the generation driver, and generates forms, reports, and
message files.
• The names were chosen because the order in which they must be applied is
alphabetical: c (for copying), d (for database), and g (for generation).
• Older software releases (10.7 or older) used patch.drv for the file and
generation portions and db<bugno>.drv for the database driver.

A readme file
• Every patch should come with a readme file, usually named readme.txt.
• This file tells the user what bug it is fixing, what files are to be changed, and
special steps the user needs to perform (if any).

"Replacement" files
• These files are listed in the file driver (c<bugno>.drv).
• These are files that replace the ones you have on your current system or add
files that are not on your current system.
• These are usually forms, reports, SQL scripts, or object modules.
• They are organized by subdirectory within the patch directory based on
where they belong on your file system.

Scripts and executables


• These are SQL scripts and executables that need to be run to apply that
patch.
• These scripts often modify the database and are typically called by the
database driver.
• They are organized by subdirectory within the patch directory but actually run
from APPL_TOP, not from where the patch was unloaded.

Patch files are grouped by directory based on their patch number.

Within each patch, files are grouped by product, then by their location in the
<PROD>_TOP directory.

Note that the product version number is not included as a subdirectory.

3
For example, suppose I have patch 123456, which replaces a report file in PO
and includes database update steps. I receive a compressed tar archive, which
expands to this:
123456
|
| | | | |
po readme.txt c123456.drv d123456.drv g123456.drv
|_____________________________
| | |
reports forms patch
| | |
POXPOCPS.rdf US 110
| |________
POXPOMPO.fmb | |
sql driver
| |
b123456.sql d123456.drv

A few notes about this example:


• The directory name for this patch is the same as the bug number we are
patching.
• The readme.txt, c123456.drv, d123456.drv, and g123456.drv are all at the
top level of this patch.
• Note that within the patch, POXPOVPS.rdf is located in the po/reports
directory. On the file system it is located in PO_TOP/reports directory.

4
BEFORE RUNNING ADPATCH
There are a few steps to perform before you run AutoPatch.
These are the same preparatory steps you would follow for running
any other AD utility, such as AdAdmin or AutoInstall.

1. Log in as applmgr. Make sure this account is using a


Bourne shell (or Korn shell on some platforms). It may not
work properly if you are using other shells, such as a C
shell.

2. Run the environment file for the Oracle Applications


product group you want to update.
• This is normally <db_name>.env
• To run the environment file, make sure you are in a Bourne or Korn
shell, and type:
$ . $APPL_TOP/<db_name>.env
• Depending on your setup, you may have already run this file when
you logged in.

3. Verify that ORACLE_HOME and ORACLE_SID or


TWO_TASK point to the correct database and directory.
• To check these variables, "echo" them in UNIX:
$ echo $TWO_TASK
->v1103
$ echo $ORACLE_HOME
->/db02/webhome/v1103
$ echo $ORACLE_SID
->atlcol06_v1103

4. Ensure that your PATH is set correctly.


• At the UNIX prompt, just type:
$ echo $PATH
->/appl01/v1103/fnd/11.0.28/bin:/appl01/v1103/ad/11.0.28/bin:
/db02/webhome/v1103/bin:/usr/sbin:/usr/bin:/usr/ccs/bin:
/usr/ucb:/dba/dbaprod:/usr/local/bin:
/hrdev/cobol.solaris/cobol/bin:/hrdev/cobol.solaris/cobol
• Look for ORACLE_HOME/bin in the path. If it is not there, you can
add it using the command:
$ PATH=$PATH:$ORACLE_HOME/bin; export PATH

5
• Other directories need to be in your PATH as well, such as the
location of the jre executable (from the Java Runtime
Environment).
You should update adovars.env to include all non-database specific
directories in your PATH.

5. Ensure you have sufficient temporary disk space.


• You should have at least 50 MB in the temporary directories
denoted by APPLTMP and REPORTS25_TEMP.
• You should also have space in the operating system’s default
temporary directory (usually /tmp or /usr/tmp).

6. Copy the patch files to your own PATCH_TOP directory.


That is the directory that holds the patch files.
• The file will probably be in zip format. You will need to unzip it.
• The unzip program comes on the Applications Interoperability CD,
or you can download it from
http://www.cdrom.com/pub/infozip/.

7. Read the readme.txt file. It provides information you'll


need to run AutoPatch. This information may include:
• Software requirements, such as other patches you need to apply
first, or what Applications release you should have
• Disk space requirements, if the patch is particularly large
• Time requirements (a patch can take anywhere from 15 minutes to
several hours to run)
• Manual steps to run, if any
• Problems that are fixed in this patch

+ Note: Applications is moving toward a standard format for


readme.txt files. This will include identifying what tiers a patch must be
applied on. In the meantime, you will need to examine the patch
contents to determine this.

8. Backup any previously patched files that you want to


save.

6
Before AutoPatch copies over a file, it backs up that file by renaming it
to <filename>O. If there is already a <filename>O file on the
system, the existing one is overwritten. For example:

Adrelink -> adrelink0


WSHSCOIF.fmb -> WSHSCOIF.fmb0

9. Have all Oracle Applications users log out, and shut down
the concurrent managers, Forms Servers and Web Servers.
• AutoPatch may update seed data and the database structure, so
it's a good idea to make sure nothing is accessing the database
during an AutoPatch session.
• On NT sharing violations can occur when a dynamic linked library
is being accessed and at the same time being rebuild.

10. Perform any preparation steps that are listed in the


readme.txt file.
For example, you may need to run some SQL scripts manually.

11. Type "adpatch" at the command line.


• Adpatch resides under AD_TOP/bin.
• Run AutoPatch from the directory that holds the patch files (we
refer to this as PATCH_TOP).
$ cd /d01/appl/110/patches/123456
$ adpatch
Copyright (c) 1998 Oracle Corporation
Redwood Shores, California, USA
Oracle Applications AutoPatch
Version 11.0.28
NOTE: You may not use this utility for custom development unless you
have written permission from Oracle Corporation

7
RUNNING AUTOPATCH
AutoPatch asks you some initial questions.

Answering questions in AutoPatch is similar to AutoInstall.


• If you’ve used AutoInstall before, most of these questions look
familiar to you.
• Pressing [Return] in answer to a question accepts the default
answer in brackets. Typing "abort" exits immediately.
• You can exit AutoPatch by entering abort at any prompt.
• Similar to AutoInstall, AutoPatch creates and uses restart files
(ada*.rf9).

AutoPatch confirms your APPL_TOP is correct.


• AutoPatch log, output and restart files are written under
APPL_TOP.
Your default directory is ’/d01/appl/110’.
Is this the correct APPL_TOP [Yes] ?

AutoPatch asks for the name of the log file.


• By default this is adpatch.log.
• If a log file of the same name already exists, AutoPatch appends
this session to the end of the log file and includes the line "Start
of AutoPatch session" at the beginning of each session.
AutoPatch records your AutoPatch session in a text file
you specify.Enter your AutoPatch log file name or press [Return]
to accept the default file name shown in brackets.

Filename [adpatch.log] :

You can receive an email message if AutoPatch encounters


a failure.
You can be notified by email if a failure occurs.
Do you wish to activate this feature [Yes] ?

You chose to be notified by email when a failure occurs.


Please enter the email id(s) (separated by space) that notifications
should be sent to [applmgr] :

Some SQL scripts perform row set processing. You can set
the number of rows these scripts process.

8
Please enter the batchsize [1000] :

AutoPatch asks what types of files you currently have.


NOTE: If you do not have or choose not to have certain types of files
installed in this APPL_TOP, you may not be able to perform certain
tasks.

Example 1: If you don’t have files used for installing or upgrading


the database installed in this area, you cannot install or upgrade
the database from this $APPL_TOP.

Example 2: If you don’t have forms files installed in this area, you
cannot generate them or run them from this $APPL_TOP.

Example 3: If you don’t have concurrent program files installed in this


area, you cannot relink concurrent programs or generate reports from
this $APPL_TOP.

Do you currently have files used for installing or upgrading the


database installed in this $APPL_TOP [Yes] ?

Do you currently have Java and HTML files for Self-Service Applications
installed in this APPL_TOP [Yes] ?

Do you currently have Oracle Applications forms files installed


in this $APPL_TOP [Yes] ?

Do you currently have concurrent program files installed


in this $APPL_TOP [Yes] ?

AutoPatch asks you to confirm the database and database


home directory.
You are about to use or modify Oracle Applications product tables
in your ORACLE database ’apptest’
using ORACLE executables in ’/d01/oracle/prod/8.0.5’.

Is this the correct database [Yes] ?

• If these values are not correct, exit AutoPatch (by typing ‘ABORT’)
and edit your ORACLE_HOME and ORACLE_SID or TWO_TASK
variables as needed.

AutoPatch asks for the SYSTEM password. It then


determines the username for your Application Object Library
user.
AutoPatch needs the password for your ’SYSTEM’ ORACLE schema
in order to determine your installation configuration.

Enter the password for your ’SYSTEM’ ORACLE schema: manager

9
Connecting to SYSTEM......Connected successfully.

AutoPatch then validates the ORACLE usernames and


passwords for Applications products.
The ORACLE username specified below for Application Object Library
uniquely identifies your existing product group: APPLSYS

Enter the ORACLE password of Application Object Library [APPS] : APPS

AutoPatch asks for the directory that holds the patch files.
• By default, this is the directory from which you started AutoPatch.
Enter the directory where your Oracle Applications patch has been
unloaded

The default directory is [d01/app1/110/patches123456] :

AutoPatch asks for the name of your patch driver file.


• This is usually c<bugno>.drv, d<bugno>.drv, or
g<bugno>.drv.
Please enter the name of your AutoPatch driver file [patch.drv] :

• AutoPatch tells you what patches you are about to apply, what
products they will change, and asks you if you want to continue.

If the patch is not required to be run serially you are


prompted to enter the number of workers to use.
• The driver file may contain a line "compatible parallel no",
which disables the parallel feature.
• Jobs are then run sequentially based upon the physical order in the
database driver file.
• "compatible parallel yes" is the default for all patches.

At this point, AutoPatch takes over.


• AutoPatch displays messages to show its progress.
• And at the end a success message is displayed.
Log and Info File sync point:
Thu Apr 20 2000 10:29:13
Autopatch is exiting successfully.

AutoPatch is complete.

AutoPatch may have written informational messages to the file


/d01/appl/110/admin/V1103/log/adpatch.lgi

10
You should check the file
/d01/appl/110/admin/V1103/log/adpatch.log

for errors.

Restarting a failed patch.


• Autopatch will ask several questions that have to be carefully
answered.
APPL_TOP is set to /d01/appl/110

Backing up restart files, if any….Done.

Your previous AutoPatch session did not run to completion.


Do you wish to continue with your previous AutoPatch session [Yes]?

1. If you want to continue, you answer with yes. Adpatch will ask
you to confirm the database and database home directory.
You are about to apply a patch to the installation of Oracle
Applications
in your ORACLE database 'atlcol06_v1103'
using ORACLE executables in '/db02/webhome/v1103'.

Is this the correct database [Yes] ?

•After this question, adpatch asks and confirms the same


things as in a regular run.

2. If you don’t want to continue, you answer with No and the


following question will come up.
Enter No to continue with your previous AutoPatch session. [No] :

•If you answer this question with No, you will continue with the
old adpatch session as described above.
•If you answer this question with Yes, you will continue with
the following question.
You can be notified by email if a failure occurs.
Do you wish to activate this feature [Yes] ?

•After this question, adpatch asks and confirms the same


things as in a regular run.

11
AFTER RUNNING AUTOPATCH
There are a few post-AutoPatch steps to complete.
After running AutoPatch, you should check the log files for
errors.
• Log files are located in APPL_TOP/admin/<dbname>/log. .
• You should check your main log file (adpatch.log, by default) as
well as other files generated by AutoPatch (such as
adrelink.log, admvcode.log, adwork*.log, and others).
• AutoPatch also produces an informational log file, adpatch.lgi. This
contains messages on actions that AutoPatch did not perform.

+ Note: The files adfrmgen.log and adrepgen.log are no longer used.

Search for words like "Error:", "Warning", "ORA-", "PLS-",


"APP-", "FRM-", and "REP-".
• Make all searches case insensitive
• Look for "Error:" (with the colon) and not "Error"

Re-run AutoPatch as necessary.


• Most patches have multiple patch drivers (c,d and g).
• You may also need to run the patches on other servers in a multi-
tier configuration.
• You can run all the patch drivers on each tier. If they don’t apply,
nothing will happen.

Clean up or read-protect log/, restart/, and


out/directories under the admin base directory.
• Log, output, and restart files record passwords to your Oracle
Applications products. Restrict access to these files after you've
confirmed the patch was successful.
• Remember: In Release 11, there is no need for Applications users
to access these machines. It may be easiest to protect access to
the entire server, or at least the entire APPL_TOP directory.

Perform manual update steps


• Check your readme.txt file for any manual update steps you
might need to perform at this time.

12
Remove obsolete files
• Once you're sure the patch works, you can delete backup copies of
files (ones that end in O) to free up disk space.
• Do not delete applptch.txt. This file is a history of all patches
that have been applied. Some Applications DBA utilities may need
this information later.

Maintain MLS or MRC Schema(s)


• If using MLS or MRC functionality, you must run adadmin and
choose the option(s) to maintain your MLS or MRC schema(s).
• AutoPatch displays a reminder message at the end of the patch if it
determines you are using either functionality.

13
PATCH DRIVER FILES
Let's go over, line-by-line, the patch driver files used in this
example.
In c123456.drv:
begin aru bug_123456

characterset us7ascii

begin bug po 123456


begin actions
copy po patch/110/sql b123456.sql 110.0
copy po patch/110/driver d123456.drv 110.1
forcecopy po media wfrdflg.gif
libout po lib pocfr.o
libin po lib pocfr.o
link po bin POXCON

end actions
end bug po 123456

end aru bug_123456

In d123456.drv:
begin ARU 123456DB
compatible release 11.0.0
compatible parallel yes

begin bug po 123456


begin actions

sql po patch/110/sql b123456.sql none none


&none sqlplus phase=dat

end actions
end bug po 123456

end ARU 123456DB

14
And in g123456.drv:
begin aru bug_123456

characterset us7ascii

begin bug po 123456


begin actions

genrep po reports POXPOVPS.rdf


genform po forms/US POXPOMPO.fmb

end actions
end bug po 123456

end aru bug_123456

15
"begin ARU 123456" .. "end ARU 123456" indicates this
patch corresponds to ARU request 123456.
• There can only be one "begin ARU" ... "end ARU" statement per
patch driver file.

"compatible release 11.0.0" indicates this patch is


compatible with release 11.0.0.
• As mentioned before, a bug patch compatible with 11.0.0 will work
with an Oracle Applications release of 11.0.0 (or higher).

"compatible parallel yes" indicates that the database actions


in the patch can be executed in a parallel manner.
• In the c<bugno>.drv and g<bugno>.drv files there is nothing to run
in parallel. The d<bugno.>.drv file, however, contains "&phase="
arguments which are used to determine the concurrency of the
actions.

"begin bug po 123456" ... "end bug po 123456" surround the


bug patch to be applied, and indicate what product it is for.

"begin actions" ... "end actions" indicate the actions to be


performed to apply this bug patch.

16
The following are actions that AutoPatch can perform:

copy Copy a file, with version checking


exec Run an executable program
forcecopy Copy a file, without version
checking
genform Generate a form
genfpll Generate a PL/SQL library used
by Applications forms
genmenu Generate Oracle Forms menu file
genrep Generate a report
genrpll Generate a PL/SQL library used
by Applications reports
libin Copy a module into a product
library
libout Extract a module out of a product
library
link Relink an executable with Oracle8
Server
sql Run a SQL script

17
NEW FEATURES
Just a few of the additions and differences in Release 11
AutoPatch.

11.0 New Features:


• AutoPatch displays a list of registered customized files affected by
the patch.
• You can now run multiple sessions of AutoPatch at the same time if
you specify a different admin base directory for each.
• AutoPatch writes version checking output to a separate file
(adpatch.lgi).
• Universe logic (a special algorithm used in 10.7 AutoPatch to avoid
copying unnecessary files) is no longer used.

Changes from 10.7:


• applptch.txt is now stored under the admin base directory,
one per product group. It used to be directly under APPL_TOP.
• Serial mode is no longer supported (i.e.: choosing one worker still
spawns a single worker process).

18