1

THE ADPATCH UTILITY

2

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

Similar to AutoInstall and adadmin, AutoPatch can runparallel workers.

Before AutoPatch replaces a file with one from the patch, itcompares the version numbers to ensure that your file willbe replaced only with a newer one. Unless adpatch is runwith 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 backupcopy.

WHAT DOES A PATCH LOOK LIKE?A patch may consist of many files.

When you receive a patch, you actually receive acompressed archive (zip format) of several files. Theseinclude:

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.

3

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.

4

For example, suppose I have patch 123456, which replaces a report file in POand includes database update steps. I receive a compressed tar archive, whichexpands 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.

5

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

1. Log in as applmgr. Make sure this account is using aBourne shell (or Korn shell on some platforms). It may notwork properly if you are using other shells, such as a Cshell.

2. Run the environment file for the Oracle Applicationsproduct 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 whenyou logged in.

3. Verify that ORACLE_HOME and ORACLE_SID orTWO_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

6

• Other directories need to be in your PATH as well, such as thelocation of the jre executable (from the Java RuntimeEnvironment).You should update adovars.env to include all non-database specificdirectories 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 fromhttp://www.cdrom.com/pub/infozip/.

7. Read the readme.txt file. It provides information you'llneed 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 forreadme.txt files. This will include identifying what tiers a patch must beapplied on. In the meantime, you will need to examine the patchcontents to determine this.

8. Backup any previously patched files that you want tosave.

7

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

Adrelink -> adrelink0WSHSCOIF.fmb -> WSHSCOIF.fmb0

9. Have all Oracle Applications users log out, and shut downthe 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 databaseduring an AutoPatch session.

• On NT sharing violations can occur when a dynamic linked libraryis being accessed and at the same time being rebuild.

10. Perform any preparation steps that are listed in thereadme.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 CorporationRedwood Shores, California, USAOracle Applications AutoPatchVersion 11.0.28NOTE: You may not use this utility for custom development unless youhave written permission from Oracle Corporation

8

RUNNING AUTOPATCHAutoPatch 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 "Startof AutoPatch session" at the beginning of each session.

AutoPatch records your AutoPatch session in a text fileyou 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 encountersa 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 notificationsshould be sent to [applmgr] :

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

9

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 filesinstalled in this APPL_TOP, you may not be able to perform certaintasks.

Example 1: If you don’t have files used for installing or upgradingthe database installed in this area, you cannot install or upgradethe database from this $APPL_TOP.

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

Example 3: If you don’t have concurrent program files installed in thisarea, you cannot relink concurrent programs or generate reports fromthis $APPL_TOP.

Do you currently have files used for installing or upgrading thedatabase installed in this $APPL_TOP [Yes] ?

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

Do you currently have Oracle Applications forms files installedin this $APPL_TOP [Yes] ?

Do you currently have concurrent program files installedin this $APPL_TOP [Yes] ?

AutoPatch asks you to confirm the database and databasehome directory.You are about to use or modify Oracle Applications product tablesin 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_TASKvariables as needed.

AutoPatch asks for the SYSTEM password. It thendetermines the username for your Application Object Libraryuser.AutoPatch needs the password for your ’SYSTEM’ ORACLE schemain order to determine your installation configuration.

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

10

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

AutoPatch then validates the ORACLE usernames andpasswords for Applications products.The ORACLE username specified below for Application Object Libraryuniquely 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 beenunloaded

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, whatproducts they will change, and asks you if you want to continue.

If the patch is not required to be run serially you areprompted 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:13Autopatch is exiting successfully.

AutoPatch is complete.

AutoPatch may have written informational messages to the file/d01/appl/110/admin/V1103/log/adpatch.lgi

11

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 askyou to confirm the database and database home directory.

You are about to apply a patch to the installation of OracleApplicationsin 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 samethings as in a regular run.

2. If you don’t want to continue, you answer with No and thefollowing 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 theold adpatch session as described above.

• If you answer this question with Yes, you will continue withthe 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 samethings as in a regular run.

12

AFTER RUNNING AUTOPATCHThere are a few post-AutoPatch steps to complete.After running AutoPatch, you should check the log files forerrors.• 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 asadrelink.log, admvcode.log, adwork*.log, and others).

• AutoPatch also produces an informational log file, adpatch.lgi. Thiscontains 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/, andout/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'veconfirmed the patch was successful.

• Remember: In Release 11, there is no need for Applications usersto access these machines. It may be easiest to protect access tothe 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.

13

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 needthis 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.

14

PATCH DRIVER FILESLet's go over, line-by-line, the patch driver files used in thisexample.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 actionsend bug po 123456

end aru bug_123456

In d123456.drv:begin ARU 123456DB

compatible release 11.0.0compatible parallel yes

begin bug po 123456begin actions

sql po patch/110/sql b123456.sql none none&none sqlplus phase=dat

end actionsend bug po 123456

end ARU 123456DB

15

And in g123456.drv:begin aru bug_123456

characterset us7ascii

begin bug po 123456begin actions

genrep po reports POXPOVPS.rdfgenform po forms/US POXPOMPO.fmb

end actionsend bug po 123456

end aru bug_123456

16

"begin ARU 123456" .. "end ARU 123456" indicates thispatch 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 iscompatible 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 actionsin 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 theactions.

"begin bug po 123456" ... "end bug po 123456" surround thebug patch to be applied, and indicate what product it is for.

"begin actions" ... "end actions" indicate the actions to beperformed to apply this bug patch.

17

The following are actions that AutoPatch can perform:

copy Copy a file, with version checkingexec Run an executable programforcecopy Copy a file, without version

checkinggenform Generate a formgenfpll Generate a PL/SQL library used

by Applications formsgenmenu Generate Oracle Forms menu filegenrep Generate a reportgenrpll Generate a PL/SQL library used

by Applications reportslibin Copy a module into a product

librarylibout Extract a module out of a product

librarylink Relink an executable with Oracle8

Serversql Run a SQL script

18

NEW FEATURESJust a few of the additions and differences in Release 11AutoPatch.

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).