Applications DBA System Maintenance Tasks and Tools

Overview

This chapter describes the various operations you will need to perform during your work as an Oracle E-Business Suite DBA. Depending on your organization's requirements, some of the tasks will need to be performed often, and others rarely or never.

In addition, the frequency with which many of the tasks will need to be performed is very likely to vary over the life cycle of your Oracle E-Business Suite system. For example, you will probably apply patches throughout the life of the system, but only add an NLS language when there is a specific business need.

Choosing the Correct File System For Maintenance Tasks

As described in the Patching part of this book, and in Chapters 2 and 4 of Oracle E-Business Suite Concepts, all patching in Release 12.2 is done while the Oracle E-Business Suite system is running and available for use. One of the key concepts involved is the employment of a dual file system: users are connected to the run file system, while patches are, when needed, applied to the patch file system. After all the relevant patches have been applied, the current online patching cycle concludes with the two file systems swapping their identities.

As pre-12.2 Oracle E-Business Suite releases only employed one file system, there was no choice about where maintenance activities had to be carried out from. Use of a dual file system in Release 12.2 has required the introduction of a Configuration Change Detector, which automatically detects when changes are made to one file system and replicates them to the other.

With technology stack components, however, you may need to make updates manually. In such cases, the question arises as to which file system should you perform the updates on.

Your choice should be made as follows:

• When a patching cycle is in progress, you should perform maintenance tasks on the patch file system, keeping the following important related points in mind.

  • In general, you should only make configuration changes to Oracle HTTP Server or Oracle WebLogic Sever (including Managed Servers) on the patch file system when so instructed by the patch readme, a My Oracle Support knowledge document, or Oracle Support.

  • If for some reason you find you need to perform such configuration tasks on the run file system, you must either complete or abort the active patching cycle first.

• When no patching cycle is in progress, you should perform maintenance tasks on the run file system, keeping the following important related points in mind.

  • In general, you should make configuration changes to Oracle HTTP Server or Oracle WebLogic Sever (including Managed Servers) on the run file system when there is no active online patching cycle.

  • After making maintenance or configuration updates on the run file system, you should then always clone the run file system to the patch file system using the adop fs_clone command.

  • If you do not run adop fs_clone after making updates on the run file system, adop will run the command automatically in the prepare phase of the next patching cycle, which may result in that cycle taking significantly longer.

Warning: If you do not wait until after the cutover phase of a patching cycle is complete, any maintenance tasks or configuration changes you have made on the run file system will be lost.

Managing Files

This section contains information about maintenance tasks associated with Oracle E-Business Suite files.

Generating Product Files

Requirement

I want to generate missing product files.

Discussion

Every Oracle E-Business Suite product contains generated files, such as form, report, message, and JAR (Java archive) files. Run AD Administration when you suspect generated files are missing. For example, if users are not able to use a certain General Ledger form, regenerating the form file may resolve the issue. You may also need to generate files after you license additional products.

Note: You do not have to shut down your system to generate files. However, users that are accessing the files being generated (for example, for Human Resources forms) must log out.

Actions

Perform the following steps:

1. Determine the file types that require generation.

2. Start AD Administration by setting the environment and then entering adadmin on the command line.

   Note: For more information, see Setting the Environment in Running AD Utilities.

3. From the AD Administration Main menu, go to the Generate Applications Files menu and select the task for the type of files you want to generate, based on the following criteria:

   • When you choose one of the options for generating form or report files, you can select an individual file, a set of files, or all files of the selected type.

   • The "Generate product JAR files" option allows you to generate all JAR files for all products, or only JAR files that are out-of-date.

     Important: If you are performing a new installation of Oracle E-Business Suite, you must create your own signature, and then force regeneration of all JAR files. This will avoid the occurrence of security warnings, for example when launching forms, that can result from the existence of multiple signatures.

   • The "Generate message files" option generates all message files for all products.

   Note: For more information, see Generating Applications Files.

4. Repeat the generation task on each APPL_TOP that contains the files (if the system contains multiple APPL_TOPs).

5. Review the AD Administration log file for warnings or errors.

Adding New Off-Cycle Products

Requirement

I want to add a product that was released after the last release update pack.

Discussion

Products that are released in between maintenance releases are sometimes referred to as off-cycle products. Since these new products do not appear in the OAM License Manager, you must add them to your product list by using AD Splicer. This utility splices the product into the list of existing products that are known to your system. This process makes the product available, so that you can register it as active, and thus, make it available to the AD maintenance utilities.

Once you have spliced the product, you use the adop utility to install the product-related files.

Note: For more information, see AD Splicer in this chapter.

Actions

Perform the following steps:

1. Download the initial product patch from My Oracle Support.

   This patch contains information about the new product, AD Splicer control files required to add the product, and the associated product files.

2. Review the readme file.

   Unzip the patch in the patch top directory. The patch readme file contains information on how to install the product. It may include manual steps to perform as part of this process.

   Important: Do not apply the patch using adop.

3. Apply prerequisite patches (if any).

   Follow the instructions about prerequisite patches in the patch readme file.

4. Create tablespaces (conditional).

   If you initially installed your system with Rapid Install 11.5.10 or later, omit this step.

   If your system was upgraded to Release 11.5.10 from a previous version of Release 11i, you may have chosen to continue using the OFA tablespace model. If so, create two tablespaces for each product, one for the product tables and another for the product indexes.

   Note: For more information, see Tablespace Management in Oracle E-Business Suite Concepts.

5. Copy AD Splicer control files and product configuration file.

   Copy <prod>prod.txt, <prod>terr.txt, and newprods.txt to APPL_TOP/admin.

   Caution: If a newprods.txt already exists from a previous AD Splicer session, rename the existing file before copying the new newprods.txt file. If you need to edit this file, see AD Splicer in this chapter.

6. Add the off-cycle product to the list of products.

   Log on as applmgr, set the environment, and run AD Splicer. It modifies the APPL_ TOP and database, then performs the same registration function as OAM License Manager.

   UNIX:

   $ cd $APPL_TOP/admin
   $ adsplice

   Windows:

   C:\>cd %APPL_TOP%\admin
   C:\>adsplice

   Run AD Splicer for each APPL_TOP and database combination so that the Applications utilities recognize the off-cycle products as active and valid.

7. Run the AD Configuration report (adutconf.sql). Review the list of registered products to verify that the product was spliced properly into the database.

   Note: For more information, see AD Configuration Report in this book.

8. Log out and log in again so that the new environment file (UNIX) or environment subkey in the registry (Windows) is used to set up the environment.

   Note: For more information, see Setting the Environment in Running AD Utilities.

9. Verify that <PROD>_TOP registry and environment variables are set correctly for the newly spliced off-cycle products.

10. Download and apply the patch that introduces the product functionality.

    The documentation that instructed you to apply this patch using AD Splicer contains information about which patch you need to apply next.

Maintaining Snapshot Information

Requirement

What is a snapshot, and how do I use it?

Discussion

Snapshots are current views of your system: they are created once, and then updated when appropriate to maintain a consistent view. There are two types of snapshot: APPL_TOP snapshots and global snapshots. An APPL_TOP snapshot lists patches and versions of files in the APPL_TOP. A global snapshot lists patches and latest versions of files in the entire Applications system (that is, across all APPL_ TOPs).

Patch Wizard uses a global snapshot to determine which patches have already been applied. An APPL_TOP snapshot is used to determine if prerequisite patches have been applied to a particular APPL_TOP.

Note: For more information, see Maintain Snapshot Information in Maintaining Applications Files.

Actions

If you need to perform any of the Maintain Snapshot tasks, select an option from the Maintain Snapshot Information submenu.

1. Access the Maintain Snapshot Information menu.

   From the AD Administration Main Menu, choose Maintain Applications Files. Then choose Maintain Snapshot Information.

   Maintain Snapshot Information Menu

   

2. Choose an option.

   From this menu, you can:

   • List snapshots (stored in the system)

   • Update current view snapshot (full or partial APPL_TOP and global)

   • Create named snapshot (select a current view snapshot to copy and name)

   • Export snapshot to file (select one to export to a text file)

   • Export snapshot to file (select one to export to a text file)

   • Delete named snapshot (select a snapshot for deletion)

   In addition to the existing snapshots tasks, you can choose to synchronize selected files - a partial snapshot - instead of synchronizing all files for the entire APPL_TOP. You would use this option when you have copied only a few files to the APPL_TOP.

   1. Select the Update Current View Snapshot option.

   2. From the snapshot submenu, select one of the following options:

   Maintain Current View Snapshot Information Menu

   

   • Update Complete APPL_TOP.

     This is the original functionality of the Update Current View Snapshot option. It synchronizes all the files in your APPL_TOP.

   • Update JAVA_TOP only.

     Synchronizes only the files in the JAVA_TOP. At the prompt, enter the path to the JAVA_TOP subdirectory where the files were copied. If the files were copied to more than one directory, press Enter. AD Administration scans the entire JAVA_TOP and updates the information in both the current view and the global view snapshots.

   • Update a <PRODUCT>_TOP.

     Synchronizes only the files in a specific <PRODUCT>_TOP. Enter the product abbreviation, then provide the subdirectory information at the prompt.

     Enter the path to a single subdirectory in the <PRODUCT>_TOP. If the files were copied to more than one directory in the <PRODUCT>_TOP, press Enter. AD Administration scans the entire <PRODUCT>_TOP and updates the information in both the current and the global view snapshots.

   During a new installation, Rapid Install automatically creates a current snapshot as a baseline. Then, each time you apply a patch, a new (updated) snapshot is automatically created to ensure that it reflects application of the patch and so remains up to date.

   Tip: You can update snapshot information using the AD Administration task any time you think it necessary. However, the process can be time-consuming.

Relinking Product Executables

Requirement

How do I relink product executables?

Discussion

Relinking executable programs with the Oracle server product libraries keeps them functioning properly. When you need to relink programs, run the AD Administration "Relink Applications Programs" task.

Note: For more information, see Relink Applications Programs in Maintaining Applications Files.

Actions

Perform the following steps:

1. Start AD Administration.

   Set the environment and enter adadmin on the command line.

   Note: For more information, see Setting the Environment in Running AD Utilities.

2. Shut down services.

   When relinking files on a concurrent processing server, shut down the concurrent managers. When relinking files on a Forms node, shut down the Forms services.

   Note: For more information, see Stopping and Starting Application Tier Services in this chapter.

3. Relink programs.

   From the AD Administration Main menu, go to the Maintain Applications Files menu. Then choose the "Relink Applications programs" task. For each product, choose whether to link all executables or only specific ones.

Relinking AD Executables

Requirement

How do I relink AD executables?

Discussion

You cannot use AD Administration to relink AD executables. Instead, you run AD Relink. With this command line utility, you can relink several AD utilities with a single command.

AD Relink requires the force= parameter. There is no default for this parameter. You must specify either "n" to relink the executable program only if the dependent libraries or object files are more recent than the current executable program, or "y" to relink regardless of the status of the libraries or object files.

An optional command line argument is backup_mode. Use it to indicate whether you want to back up executables. There are three possible values for backup_mode:

AD Relink backup_mode Values

Value	Effect
backup_mode=none	Do not back up any executables.
backup_mode=all	Back up all executables.
backup_mode=file	Back up files according to instructions in adlinkbk.txt (the default).

Actions

Perform the following steps:

1. Log on as applmgr and set the environment.

   Note: For more information, see Setting the Environment in Running AD Utilities.

   Windows users must run %<APPL_TOP>%\relinkenv.cmd, executed from a command window. Change directory to %APPL_TOP% and run apps.sh to set up all required environment variables. (Note there is a space between the dots in this command.)

   C:\> . ./apps.sh

2. Relink files.

   Run AD Relink using the appropriate command for your operating system.

   UNIX:

   $ adrelink.sh force={y | n} [<optional arguments>] <ad program name>

   Windows:

   Change directory to %APPL_TOP%\bin and relink the desired file using the following syntax:

   C:\> sh adrelink.sh force={y | n} [<optional arguments> <ad program name>

   If you want to relink several AD utilities, list the programs on the command line, separating each with a space and enclosing it in quotations. For example, to relink both AD Controller (adctrl) and AD Administration (adadmin), enter:

   UNIX:

   $ adrelink.sh force=y "ad adctrl" "ad adadmin"

   Windows:

   C:\> sh adrelink.sh force=y "ad adctrl.exe" "ad adadmin.exe"

   To create a backup file (for all executables), use the following syntax:

   UNIX:

   $ adrelink.sh force=y backup_mode=all

Compressing, Archiving, and Deleting Files

Requirement

Which Oracle E-Business Suite files can be safely compressed, archived, or deleted?

Discussion

There are several types of files that can be compressed, archived, or deleted: log and output files, upgrade files, and patching backup files. However, Oracle recommends this action only if there is no other way to increase available disk space.

Caution: We strongly recommend creating a backup before you delete any files and keeping the backup readily available in case you need to restore files.

Actions

Perform the following tasks, using the commands specific to your operating system.

1. Compress, archive, or delete the following files, according to your operational requirements. The three categories can be treated independently for cleanup purposes.

   • Log and output files.

     You can compress, archive, or delete log and output files created by AD utilities. They are located in the following directories, where <SID> is the name of the database instance for the current Applications system: $APPL_ TOP/admin/<SID>/log and $APPL_TOP/admin/<SID>/out (UNIX) or %APPL_TOP%\ admin\<SID>\log and %APPL_TOP%\admin\<SID>\out (Windows).

     Caution: Log files may contain passwords. Back up these files to a secure location. Do not delete the directories.

   • Upgrade files.

     After you complete and verify an upgrade, you can compress, archive, or delete the upgrade files located in $APPL_TOP/admin/preupg (UNIX) or in %APPL_ TOP%\admin\preupg (Windows).

     Caution: Do not remove any files under <PROD>_TOP/admin. They are used by AD utilities such as adop and adadmin.

   • Patching backup files.

     After you apply patches, you can compress, archive, or delete old files that have been backed up in the patch top subdirectory.

     Caution: Verify that the patch was applied successfully and the patched functionalities are fully tested before you delete backup files.

Adding NLS Languages

Adding NLS Languages

Requirement

I want to add an additional language to my existing system.

Discussion

You can add a new language to your Release 12.2 system at any time after your installation or upgrade.

Note: For more information, see My Oracle Support Knowledge Document 252422.1, Requesting Translation Synchronization Patches.

Actions

Perform the following steps:

1. From Oracle Applications Manager, go to License Manager and activate or change your base language to a new one.

2. From AD Administration, run Maintain Multi-lingual Tables (AD Administration Main Menu > Maintain Applications Database Entities Menu).

3. To complete your language installation, refer to Oracle E-Business Suite NLS Release Notes for your current release level. Choose the appropriate language installation method for the release level.

Requirement

I want to confirm that my NLS language software is current with the latest US patch levels.

Discussion

If your Oracle E-Business Suite system has active languages other than American English, you can bring them up to the current US Applications patch level by using the Translation Synchronization Patch utility. Alternatively, you can individually download and apply the NLS version of all US patches you have applied to your system. You can use AD Merge Patch to create a single patch, and then apply it using adop.

Actions

Perform the following steps:

1. For details of how to use the Translation Synchronization Utility, follow the instructions in My Oracle Support Knowledge Document 252422.1, Requesting Translation Synchronization Patches.

Requirement

I want to check if there are translation updates other than those associated with US patches.

Discussion

There may be updates that enhance your translated software that are not associated with US patches, and therefore, are not included in the updates you received when you requested a Translation Synchronization patch. You can request these updates using the Translation Synchronization Patch utility by selecting the Get Latest Translations checkbox on the file manifest submission form.

Note: For more information, see My Oracle Support Knowledge Document 252422.1, Requesting Translation Synchronization Patches.

Actions

Perform the following steps:

1. Run the Translation Synchronization Patch utility (adgennls.pl).

2. Create a manifest using the form provided in My Oracle Support. When you submit the manifest, click the Get Latest Translations checkbox option to get translation updates that were made available since the initial Release 12 NLS, in addition to any NLS patches needed to synchronize your NLS patch level with the US patch level.

3. When you are notified that it is available, apply the Translation Synchronization Patch (TSP) for all languages you requested.

Requirement

I want to deactivate a language.

Discussion

Deactivating a language is not supported. Once they have been activated, you must maintain all languages in an NLS system.

Actions

None.

Maintaining the Database

This section contains information you can use to maintain your database and effectively manage system resources.

Using System Resources Efficiently

Requirement

How do I keep optimization statistics up to date?

Discussion

Optimization is the process of choosing the most efficient way to execute a SQL statement. Oracle E-Business Suite Release 12 uses cost-based optimization. By analyzing the "cost" of using each resource, you can keep your system tuned for optimum performance. The optimizer uses actual table statistics to determine the most efficient access paths and join methods for executing SQL statements.

These statistics are gathered when you run the Gather Schema Statistics concurrent program. It is important to run this program after an upgrade and, subsequently, on a regular basis to avoid performance degradation (we recommend once a month). The length of time the statistics in an instance are of any value depends on the amount DML that is done during a period of time. For completely static tables, once may be enough for the life of the table. For tables that are completely reloaded all the time, you must run Gather Schema Statistics more often: tables loaded during a Data Pull in Advanced Planning and Scheduling is a good example of this. OE/OM tables are also constantly updated.

Tip: Based on usage, identify the frequency for gathering all statistics, and the frequency that works best for gathering statistics only for specific products.

Actions

Perform the following steps.

1. Log in to Oracle E-Business Suite with the System Administrator responsibility.

2. Navigate to the Submit Request window (Request > Run).

3. Submit the Gather Schema Statistics program.

   Set the schema name to ALL to gather statistics for all Oracle E-Business Suite schemas (having an entry in the FND_PRODUCT_INSTALLATIONS table). In addition to gathering index and table-level statistics, the procedure also gathers column-level histogram statistics for all columns listed in the FND_HISTOGRAM_ COLS table.

   Note: For more information, see Cost-Based Optimization in Oracle E-Business Suite in the Oracle E-Business Suite Configuration Guide.

Validating the APPS Schema

Requirement

How do I verify the integrity of my APPS schema?

Discussion

AD Administration can run a SQL script (advrfapp.sql) against the APPS schema that checks for certain conditions that are undesirable, but will not produce fatal problems. The Validate APPS Schema task executes this script.

You can run this task at any time, but it is most effective if run:

• Immediately after an upgrade

• Before converting to Multi-Org

• After performing an export/import (migration)

• As a part of custom development in the APPS schema

Actions

Perform the following tasks, using the commands specific to your operating system.

1. Start AD Administration.

   Set the environment and enter adadmin on the command line.

   Note: For more information, see Setting the Environment in Running AD Utilities.

2. Validate APPS schema.

   Select the "Validate APPS schema" task from the Maintain Applications Database Entities menu. Review the output file (<APPS schema name>.lst) for invalid database objects. It is located in $APPL_TOP/admin/<SID>/out (UNIX) or in %APPL_TOP%\admin\<SID>\out (Windows)

   Note: For more information, see Validate APPS Schema in this chapter.

   You can also run this task from SQL*Plus:

   UNIX:

   $ cd $APPL_TOP/admin<SID>/out
   $ sqlplus <SYSTEM username>/<SYSTEM password> \
   @$AD_TOP/admin/sql/advrfapp.sql \
   <APPS schema name> <AOL schema name>
   

   Windows:

   Change directory to %APPL_TOP%\bin and relink the desired file using the following syntax:

   C:\> cd %APPL_TOP%\admin\<SID>out
   C:\> sqlplus <SYSTEM username>/<SYSTEM password> @%AD_TOP%\admin\sql\advrfapp.sql <APPS schema name> <AOL schema name>

3. Resolve any issues.

   The <APPS schema name>.lst file is divided into three sections:

   • Issues you must fix (not specific to the APPS schema)

   • Issues you must fix (specific to the APPS schema)

   • Issues you may want to address (specific to the APPS schema)

   Each section of the file contains instructions for resolving the issues that are listed.

Recreating Grants and Synonyms

Requirement

How do I recreate grants and synonyms in the APPS schema?

Discussion

In order to maintain database objects, you should check the APPS schema for missing grants and synonyms. Using the AD Administration menu, you can run tasks to validate the APPS schema and then recreate any missing grants and synonyms.

Note: For more information, see Recreate Grants and Synonyms for APPS Schema in this chapter.

Actions

Perform the following steps:

1. Start AD Administration.

   Set the environment and enter adadmin on the command line.

   Note: For more information, see Setting the Environment in Running AD Utilities.

2. Recreate grants and synonyms.

   From the Main AD Administration menu, go to the Maintain Applications Database Entities menu. Select the "Recreate grants and synonyms for APPS schema" task.

Compiling Invalid Objects

Requirement

When should I compile invalid objects?

Discussion

The Oracle database automatically compiles invalid database objects the first time an object is used and during patch application. This action can take some time, so you may want to compile objects before the first use, at a time when you know the system usage is low.

You compile invalid objects with AD Administration. This task is most effective under the following circumstances:

• After custom packages are moved to the APPS schema and need to be compiled

• After applying patches that alter packages in the APPS schema

• After validating the APPS schema and identifying invalid objects

Actions

Perform the following tasks, using the commands specific to your operating system.

1. Start AD Administration.

   Set the environment and enter adadmin on the command line.

   Note: For more information, see Setting the Environment in Running AD Utilities.

2. Compile Applications schema.

   From the Main AD Administration menu, go to the Compile/Reload Database Entities menu. Choose the "Compile APPS schema" task.

Listing Objects in the Shared Pool

Requirement

How can I see a list of objects stored in the shared pool?

Discussion

You can run the ADXCKPIN.sql script to query for objects stored in the SGA shared pool. It shows the objects known to the SGA and the size that they consume. The output file is ADXCKPIN.lst.

Actions

1. Run the following commands:

   $ cd $APPL_TOP/admin<SID>/out
   $ sqlplus <SYSTEM username>/<SYSTEM password> \
   @%AD_TOP%\sql\ADXCKPIN.sql

Performing Maintenance Tasks Non-Interactively

Unless otherwise noted, maintenance tasks described in this book are performed interactively: they require user intervention, primarily in the form of responding to prompts. However, you can schedule certain AD Administration and AD Controller tasks to run with little or no user intervention by running these utilities non-interactively: instead of responding to prompts each time you run the task, you specify a file that contains the information necessary to complete the task without user intervention. In such a case, there is no need to monitor the process in order to respond to prompts. The file used is referred to as a defaults file.

Scheduling Non-Interactive Maintenance

Requirement

How do I schedule and run maintenance tasks non-interactively?

Discussion and Actions

To set up a non-interactive task requires the creation of a defaults file. AutoConfig automatically creates a defaults file (adalldefaults.txt) each time it runs. This file can be used as a template to create a customized defaults file.

Important: Running AutoConfig is now the recommended way to create a defaults file, in contrast to previous releases where adadmin could be used to do so.

Once the defaults file has been created and customized, you start the relevant maintenance utility utility from the command line, specifying the name of the defaults file, a log file name, and the number of parallel workers.

The same defaults file can be used to run different AD Administration commands: a single such file can contain all your choices for the different menu options. In order to choose which task the defaults file will run, you also add menu_option=<menu choice> to the utility start command. This overrides any menu-specific key stroke information stored in the defaults file initially, and allows you to use the defaults file for any of the AD Administration menu items. It also ensures that the menu option you intended for the defaults file is always valid, even if the menu items are renumbered or relocated in subsequent releases.

Note: For more information, see Preparing for Non-Interactive Processing.

Restarting a Failed Session

Requirement

My non-interactive AD Administration session failed. How do I restart it?

Discussion

To restart a failed non-interactive session, you run AD Administration using the restart=yes parameter.

Actions

Perform the following tasks, using the commands specific to your operating system.

1. Determine the reason the session failed and fix the issue.

2. Run AD Administration from the command line.

   Use the same parameters that you used to start the original non-interactive session, plus the restart=yes parameter. For example:

   UNIX:

   $ adadmin defaultsfile=$APPL_TOP/admin/testdb1/adadmindef.txt \
   logfile=adadmin_noninteractive.log workers=5 interactive=n \
   restart=y menu_option=CHECK_DUAL

   Windows:

   C:\> adadmin defaultsfile=%APPL_TOP%\admin\testdb1\adadmindef.txt logfile=adadmin_noninteractive.log workers=5 interactive=n restart=y menu_option=CHECK_DUAL

3. AD Administration runs the task. It does not prompt you to continue the previous (failed) session.

Distribute Processing With Distributed AD

Requirement

How can I distribute tasks across my multi-node system?

Discussion

Distributed AD is a special parallel processing feature that can be employed to decrease the time needed for patch application (and other tasks) by allocating the associated worker processes to multiple application tier nodes. The adadmin and adop utilities direct workers running both on that node and on other nodes in the system.

Note: You must have a shared application tier file system to use Distributed AD.

Important: As online patching is performed while the applications remain online, you should take care not to overwhelm the system with an excessive number of AD parallel workers that could reduce the performance of the running applications. There should be less need for numerous workers, since applying patches as quickly as possible (to minimize downtime) is less important in an online patching environment.

Actions

The distribution of workers is specified as follows:

workers=<total number of workers> localworkers=<number of workers on primary node>

The following two examples will illustrate this.

Example 1 - Distribute a total of eight workers across a two-node system

1. To begin, enter a command that will run an adop session with three workers on the primary node and five workers on secondary nodes:

   $ adop phase=apply input_file=myinput.txt

   The file myinput.txt will need to include the lines:

   workers=8
   localworkers=3

2. Now start an AD Controller session on each of the secondary nodes that will run workers, using the distributed=y argument.

   $ adctrl distributed=y

3. To start workers 4 through to 8 on a secondary node, enter "4-8" in response to the prompt from AD Controller:

   Enter the worker range: 4-8

   Note: Workers must be specified in contiguous sequences such as 1-4 or 5-8. You cannot, for example, start workers 1, 3, 5, 7 on one node, and workers 2, 4, 6, and 8 on another.

Example 2- Distribute a total of twelve workers across a three-node system

1. To begin, enter a command that will run an adop session with four workers on the primary node and eight workers on secondary nodes:

   $ adop phase=apply input_file=myinput.txt workers=12 localworkers=4

   The file myinput.txt will need to include the lines:

   workers=12
   localworkers=4

2. Now start an AD Controller session on the second node, specifying that workers 5-8 should run there:

   $ adctrl distributed=y
   Enter the worker range: 5-8

   Note: As in the previous example, workers must be specified in contiguous sequences such as 1-4 or 5-8.

3. Finally, start AD Controller on the third node, specifying that the last four workers (9-12) should run there:

   $ adctrl distributed=y
   Enter the worker range: 9-12

Managing Application Tier Services

When running certain scripts or utilities, you may be directed to stop application tier service (server) processes manually. This section contains information about stopping and starting these processes.

Note: Scripts in this section may contain system-specific information. If you change the Rapid Install defaults, you may need to edit the scripts before rerunning them.

Starting and Stopping Application Tier Services

Requirement

How do I start and stop application tier services?

Discussion

When Rapid Install sets up and configures the service and server processes, it stores a control script for each process in the $INST_TOP/admin/scripts directory.

Certain maintenance procedures require that you stop one or more services or servers manually, and restart them after you complete the procedure. By running the appropriate script on the command line, along with a stop or start argument, you can stop (or start) a single server process, several processes, or all processes. The following table lists the key scripts.

Application Tier Service Process Control Scripts

Service Process and Script Action	Implementation on UNIX	Implementation on Windows
HTTP (Web) Server: Used to start, stop, and check the status of HTTP (Web) server.	adapcctl.sh	adapcctl.cmd
Oracle Process Manager (opmn): Used to start, stop and check the status of opmn.	adopmnctl.sh	adopmnctl.cmd
Concurrent Processing: Used to start, stop, and check the status of concurrent managers.	adcmctl.sh	adcmctl.cmd
Forms (Socket): Used to start, stop and check the status of the Forms services in Socket Mode.	adformsrvctl.sh	adformsrvctl.cmd
Managed Server Control: Used to start, stop and check the status of the Managed Servers. The relevant server name must be supplied on the command line: oacore_server1, forms-c4ws_server1, forms_server1, or oafm_server1. Can also be used in Managed Server Independence Mode, where a Managed Server reads its configuration files directly, instead of contacting the Admin Server.	admanagedsrvctl.sh	admanagedsrvctl.cmd
WLS Admin Server: Used to start, stop, and check the status of the Admin Server. If you specify the -silent option, informational startup messages will not be displayed on the console, but only recorded in a log file. Any error messages will still be displayed, though.	adadminsrvctl.sh	adadminsrvctl.cmd
Node Manager: Used to start, stop, and check the status of Node Manager. Each node in a WLS domain has a Node Manager.	adnodemgrctl.sh	adnodemgrctl.cmd
Oracle TNS Listener: Used to start, stop, and check the status of the TNS Listener.	adalnctl.sh	adalnctl.cmd
Start all application tier server processes: Used to start all processes with one command.	adstrtal.sh	adstrtal.cmd
Stop all application tier server processes: Used to stop all processes with one command.	adstpall.sh	adstpall.cmd

Actions

Choose the procedure that meets your needs.

To start or stop a single application tier server process (UNIX)

Use a command of the following form:

<process script name> [stop | start]

Tip: Many of the relevant scripts also have other options, such as 'status'. Entering the script name alone will display a list of the available options.

1. Open a terminal window.

2. To stop the Concurrent Processing server (for example), run the adcmctl.sh script with the 'stop' option:

   % adcmctl.sh stop
   You are running adcmctl.sh version 120.19
   Enter the APPS username: <APPS username>
   Enter the APPS password: <APPS password>
   

To start or stop a single application tier server process (Windows)

On Windows , services can be started or stopped using the appropriate process control script (command file), or from the Services Control Panel.

Using Process Script

1. Open a command window.

2. To stop the Concurrent Processing server (for example), run the adcmctl.cmd script with the 'stop' option:

   C:\> adcmctl.cmd stop
   You are running adcmctl.cmd version 120.19
   Enter the APPS username: <APPS username>
   Enter the APPS password: <APPS password>
   

Using Services Control Panel

1. Go to Start > Administrative Tools and click Services.

2. Select the relevant service in the Services window.

3. Click Start or Stop, as required.

To start all application tier server processes (UNIX)

Use a command of the following format:

<process script name> [stop | start]

1. Open a terminal window.

2. Enter the command:

   $ adstrtal.sh
   You are running adstrtal.sh version 120.24
   Enter the APPS username: <APPS username>
   Enter the APPS password: <APPS password>
   Enter the WebLogic Server password: <WLS password>

   Tip: As an alternative, you can provide all the required passwords on the command line as follows:

   { echo $APPSUSER ; echo $APPSPASS ; echo $WLSADMIN ; } | adstrtal.sh @ -nopromptmsg

   A more secure alternative, which does not require the APPS credentials to be supplied, is:

   $ adstrtal.sh -secureapps
   You are running adstrtal.sh version 120.24
   Enter the Applications username: <Concurrent Manager operator username>
   Enter the Applications password: <Concurrent Manager operator password>
   Enter the WebLogic Server password: <WLS password>

Starting and Stopping Application Tier Services on Multiple Nodes

You can start and stop services on all application tier nodes of an instance by running adstrtal.sh or adstpall.sh on the primary node and specifying the -allnodes option:

 $ adstrtal.sh -mode=allnodes
 $ adstpall.sh -mode=allnodes 

You will be prompted for the password in the same way as when the command is run on a single node.

Using Managed Server Independence Mode

You can also start managed servers in Managed Server Independence mode, where a managed server retrieves its configuration at startup by reading its configuration and security files directly, instead of contacting the Admin Server.

This is done by specifying the -msimode option on the admanagedsrvctl.sh command line used to start a specific Managed Server. For example:

$ admanagedsrvctl.sh start forms-c4ws_server1 -msimode 

Note: A managed server can only be started in Independence Mode if it has been started at least once by connecting to the Admin Server. This is because starting a managed server in MSI mode requires the presence of a local copy of the configuration and security files.

To start all application tier server processes (Windows)

Use a command of the following format:

<process script name> [stop | start]

1. Open a command window.

2. Enter the command:

   $ adstrtal.cmd
   You are running adstrtal.cmd version 120.24
   Enter the Applications username: <APPS username>
   Enter the Applications password: <APPS password>
   Enter the WebLogic Server password: <WLS password>

   A more secure alternative, which does not require the APPS credentials to be supplied, is:

   $ adstrtal.cmd -secureapps
   You are running adstrtal.cmd version 120.24
   Enter the Applications username: <Concurrent Manager operator username>
   Enter the Applications password: <Concurrent Manager operator password>
   Enter the WebLogic Server password: <WLS password>

To stop all application tier server processes (UNIX)

Use a command of the following format:

<process script name> [stop | start]

1. Open a terminal window.

2. Enter the command:

   $ adstpall.sh
   You are running adstpall.sh version 120.24
   Enter the Applications username: <APPS username>
   Enter the Applications password: <APPS password>
   Enter the WebLogic Server password: <WLS password>

   Tip: As an alternative, you can provide all the required passwords on the command line as follows:

   { echo $APPSUSER ; echo $APPSPASS ; echo $WLSADMIN ; } | adstpall.sh @ -nopromptmsg

   A more secure alternative, which does not require the APPS credentials to be supplied, is:

   $ adstpall.sh -secureapps
   You are running adstpall.sh version 120.24
   Enter the Applications username: <Concurrent Manager operator username>
   Enter the Applications password: <Concurrent Manager operator password>
   Enter the WebLogic Server password: <WLS password>

To stop all application tier server process (Windows)

Use a command of the following format:

<process script name> [stop | start]

1. Open a command window.

2. Enter the command:

   $ adstpall.cmd
   You are running adstpall.cmd version 120.24
   Enter the Applications username: <APPS username>
   Enter the Applications password: <APPS password>
   Enter the WebLogic Server password: <WLS password>

   An alternative, which does not require the APPS password at all, is:

   $ adstpall.cmd -secureapps
   You are running adstpall.cmd version 120.24
   Enter the Applications username: <Concurrent Manager operator username>
   Enter the Applications password: <Concurrent Manager operator password>
   Enter the WebLogic Server password: <WLS password>

Note: The AD-TXK Delta 10 codelevel provides the capability to set the thread count for the adstrtal and adstpall application tier service control scripts.

This feature has been implemented via a new context variable called s_srvctl_thread_count in the application tier context file. The default value is 10. Depending on your requirements, you can change the value. The setting should be based on the number of processors on the system, must always be a value greater than zero, and should not exceed twice the number of processors.

A key benefit of setting the thread count is enabling managed servers to be started in batches, as controlled by the context variable's value. This can help performance, for example in helping fully utilize the resources of a large server with many CPUs.

Starting and Stopping Database Tier Services

Requirement

How do I start or stop the Oracle Net Services listener manually?

Discussion

When Rapid Install sets up and configures the server processes during installation, it stores a script for the Net Services listener process in the Oracle 11g database server $ORACLE_ HOME/appsutil/scripts/<CONTEXT_NAME> directory. You use this script to start or stop the Net Services listener process for the database.

Actions

To start or stop the Net Services listener (UNIX)

1. Open a terminal window.

2. Log in as the oracle user on the database server and navigate to the $ORACLE_ HOME/appsutil/scripts/<CONTEXT_NAME> directory.

3. Enter a command of the form:

   $ addlnctl.sh [start|stop] <listener_name>

   Tip: Many of the relevant scripts also have a 'status' option, which is often useful.

   For example, to start the PROD listener, enter:

   $ addlnctl.sh start PROD

   Note: For more information, see the Oracle Net Services Administrator's Guide.

To start or stop the Net Services listener (Windows)

1. As the oracle user, open a command window and navigate to the %ORACLE_ HOME%\appsutil\scripts\<CONTEXT_NAME> directory.

2. Enter a command of the form:

   C:\> addlnctl.cmd [start|stop] <listener_name>

   For example, to start the PROD listener, enter:

   C:\> addlnctl.cmd start PROD

   Note: For more information, see the Oracle Net Services Administrator's Guide.

Requirement

How do I start or stop the Oracle database manually?

Discussion

When Rapid Install sets up and configures the server processes during installation, it creates a script for the database process in the Oracle 11g database server $ORACLE_ HOME/appsutil/scripts/<CONTEXT_NAME> directory. You use this script to start or stop the database on your database tier.

Actions

To start or stop the Oracle database (UNIX)

1. Log in as the oracle user on the database server.

2. Open a terminal window and navigate to the $ORACLE_ HOME/appsutil/scripts/<CONTEXT_NAME> directory.

3. Enter a command of the form:

   $ addbctl.sh [start|stop] {immediate|abort|normal}

   Tip: Many of the relevant scripts also have a 'status' option, which is often useful.

   For example, to stop the database using the normal option, you would enter:

   $ addbctl.sh stop normal

To start or stop the Oracle database (Windows)

1. Log in as the oracle user on the database server.

2. Open a command window and navigate to the %ORACLE_ HOME%\appsutil\scripts\<CONTEXT_NAME> directory.

3. Enter a command of the form:

   C:\> addlnctl.cmd [start|stop] <listener_name>

   For example, to start the PROD listener, enter:

   For example, to stop the database using the normal option, you would enter:

   C:\> addbctl.cmd stop normal

Oracle E-Business Suite Maintenance Utilities

You use Oracle E-Business Suite system maintenance utilities to perform a variety of operations from installing and upgrading Oracle E-Business Suite systems, to updating configuration parameters, to maintaining and patching your database and file system, to producing system reports.

In this book, these utilities have been categorized by the way you access and use them. This may be from the command line, or via a Web-based interface.

Command Line Utilities

The tools generally referred to as Applications DBA (AD) utilities are started and run from the command line. They initiate processes that perform a variety of system maintenance tasks, such as applying and merging patches. As they run, the utilities prompt you for system-specific parameters necessary to perform the maintenance task. In addition, many of the utilities produce reports that contain information such as job timing and file versions.

The AD utilities have similar interfaces, operation, input, and report formats. Many also share the ability to accept arguments, flags, and options, which you can use to refine the actions they perform. You add the argument on the command line when you start the utility. For example, to specify the number of workers that adop should run in parallel when applying a patch, you enter the number of worker processes on the command line when you run adop. A list of commonly used command line arguments and flags, and a brief description of how to use them, begins later in this chapter.

The command line maintenance utilities are listed in the following table. Their operation is described further in this book, or, in the case of Rapid Install, in Oracle E-Business Suite Installation Guide: Using Rapid Install.

AD Command Line Utilities

AD Utility Name	Executable or Script	Description	Usage Restrictions
AD Administration	adadmin	Performs maintenance tasks for Oracle E-Business Suite.	If a patch edition exists, the tool can be invoked from the patch file system. If a patch edition does not exist, the tool can be invoked from the run file system. In all other cases, adadmin will display an error message.
AD Check Digest	adchkdig	Checks the integrity of Oracle E-Business Suite patches downloaded from My Oracle Support.	None.
AD Configuration	adutconf.sql	Reports standard information about the installed configuration of Oracle E-Business Suite.	If a patch edition exists, the tool can be invoked from the patch file system. If a patch edition does not exist, the tool can be invoked from the run file system.
AD Controller	adctrl	Manages parallel workers in AD utilities.	If adop is run in hotpatch mode, you should run adctrl from the run file system. Otherwise, run adctrl from the patch file system.
AD File Identification	adident	Reports the version and translation level of an Oracle E-Business Suite file.	None.
AD File Character Set Converter	adncnv	Converts a file from one character set to another.	You should run adncnv from the same $APPL_TOP as the source file (to be converted) resides on.
AD Merge Patch*	admrgpch	Merges multiple patches into a single merged patch.	In Release 12.2, adop is the recommended tool for merging patches. If you still wish to run AD Merge Patch, you should do so from the run file system.
AD Relink	adrelink.sh	Relinks Oracle E-Business Suite executable programs with the Oracle server product libraries.	The tool will regenerate the executables on whichever file system it was invoked on.
AD Splicer	adsplice	Adds off-cycle products.	If a patch edition exists, the tool can be invoked from the patch file system. If a patch edition does not exist, the tool can be invoked from the run file system.
AD Job Timing Report		Reports a summary of the timing for jobs run by parallel workers.	If adop is run in hotpatch mode, you should run adtimrpt.sql from the run file system. Otherwise, run adtimrpt.sql from the patch file system.
AD Online Patching	adop	Applies patches and other system updates.	Executed from the run file system.
Patch Application Assistant	admsi.pl	Generates customized installation instructions for a patch.	If you are applying a patch in hotpatch mode, you must run Patch Application Assistant from the run file system. If you are not using hotpatch mode, run Patch Application Assistant in the patch file system after the prepare phase.
Rapid Install	srapidwiz	Provides a wizard for entering parameters that are specific to a new installation or an upgrade of an Oracle E-Business Suite system.	None.

Online Patching and AD Utilities

The use of online patching in Oracle E-Business Suite Release 12.2 has implications for the operation of AD Admin and AD Splicer. If these utilities are run during an online patching cycle, and perform tasks that change the file system, this will trigger corresponding actions during the prepare phase of the next online patching cycle.

Such tasks include:

• GEN_MESSAGES

• GEN_FORMS

• GEN_REPORTS

• GEN_JARS

• RELINK

• COPY_FILES

• CONVERT_CHARSET

• CMP_MENU

• CMP_FLEXFIELDS

• SCAN_APPLTOP

• SCAN_CUSTOM_DIR

Important: AD Admin and AD Splicer can be invoked from the run edition only if there is no patch edition. An error will be displayed if you try to run any of these utilities from the run edition and a patch edition exists. In other words, before running them you will either set your environment to the patch file system, or, if no patch edition exists, set your environment to the run file system.

For more information about the effect of online patching on Oracle E-Business Suite maintenance activities, refer to Choosing the Correct File System For Maintenance Tasks in this book.

Web-Based Utilities

Oracle Applications Manager (OAM) provides a Web-based interface where system administrators can monitor system status, administer services, examine system configuration, manage Oracle Workflow, view applied patches, and measure system usage. It provides a concise overview of the state of your Oracle E-Business Suite system, and serves as a gateway to utilities for tasks such as managing system configuration, reviewing patch history, determining which patches will bring your system up to date, registering additional products and languages, and other maintenance activities.

The Web-based maintenance utilities are listed in the following table. Their operation is described further in Part 2 of this book and in Oracle E-Business Suite Setup Guide.

Oracle Applications Manager Utilities

OAM Utility Name	Description
Applied Patches	Uses key patch information in the patch history database. You can search the database to create reports in several formats.
AutoConfig	Use to view current context files, edit parameters contained in the context files, view previous context files, and compare current context files against previous ones.
File History	Enables the viewing of files that have been updated by a patch.
License Manager	Registers additional Oracle E-Business Suite products, country-specific functionalities, or languages. You can also use License Manager to change the base language for your system.
Patch Wizard	Determines patches that have not been applied, but that should be applied to keep the system current. Downloads and merges patches from My Oracle Support.
Register Flagged Files	Used to record any files in which you have made customizations. Replaces the need to use applcust.txt, which contained the record for all customized files in previous releases.
Software Updates	Provides an overview of all patching-related information for your system.
Timing Reports	Helps you monitor jobs that are running or view statistics of completed patching and AD Administration maintenance sessions.

Online Help

Both the AD utilities and the OAM utilities provide a help function.

Command Line Help

For the AD command line utilities, you can request a list of arguments by entering the utility name with help=y appended. For example, to access help for AD Administration, enter the command:

adadmin help=y

The arguments and options that you can use to refine the operation of a utility are listed, along with a brief description of how they work. Below is an example of the command line help for AD Administration:

usage: adadmin [help=y]

                adadmin
                                [printdebug=y|n][localworkers=<localworkers>]
                                [flags=hidepw|trace]

                adadmin Non-Interactive mode
                                [defaultsfile=<$APPL_TOP/admin/SID/defaultsfile>]
                                [logfile=<logfile>][interactive=y|n]
                                [workers=workers>][menu_option=ASK_NAME>][restart=y|n]

where

Key to options:localworkers = The number of workers to run on the local machine. Used in Distributed AD.

flags = Generic flags passed to AD utilities. The available values for AD Admin are hidepw and trace.

defaultsfile = The defaults file filename, located under $APPL_TOP/admin/SID/ directory.

menu_option = Skips the AD Admin menu and executes the task supplied on the command line. Valid values are listed below.

RELINK                                       Relink Applications programs
GEN_MESSAGES                            Generate message files
GEN_FORMS                                       Generate form files
GEN_REPORTS                             Generate reports files
GEN_JARS                                        Generate product JAR files
VALIDATE_APPS                           Validate APPS schema
CMP_INVALID                             Compile APPS schema
CMP_MENU                                        Compile menu information
CREATE_GRANTS                           Recreate grants and synonyms for APPS schema
CMP_FLEXFIELDS                  Compile flexfield data in AOL tables
MAINTAIN_MLS                            Maintain multi-lingual tables
CHECK_DUAL                                      Check DUAL table
RELOAD_JARS                             Reload JAR files to database
COPY_FILES                                      Copy files to destinations
CHECK_FILES                             Check for missing files
LIST_SNAPSHOTS                          List snapshots
UPDATE_CURRENT_VIEW     Update current view snapshot
CREATE_SNAPSHOT                         Create named snapshot
EXPORT_SNAPSHOT                         Export snapshot to file
IMPORT_SNAPSHOT                         Import snapshot from file
DELETE_SNAPSHOT                         Delete named snapshot(s)
CONVERT_CHARSET                         Convert character set
SCAN_APPLTOP                            Scan the APPLTOP for exceptions
SCAN_CUSTOM_DIR                         Scan a CUSTOM directory for exceptions

Obtaining Help in OAM

OAM Help is available by clicking the Help link in the header of an Oracle Applications Manager screen.

For example, from the OAM Site Map, OAM displays an overview of OAM and page-specific help describing the features of the Site Map page.

Individual help topics may include topical essays, procedures, and page descriptions. The help associated with the utilities and features discussed in this book provides navigation paths, field definitions, and general information about using the page.

Command Line Utilities

The AD maintenance utilities were developed to perform specific Oracle E-Business Suite maintenance and reporting tasks from the command line. For example, you use AD Online Patching (adop) to apply all types of patches to your system, and you use AD Administration to perform routine maintenance tasks.

However, even though the utilities each have a specialized function, they are designed to complement each other, so many employ similar operations. This section summarizes the operations that AD utilities have in common. Subsequent chapters describe each utility's features in detail.

Common AD Operations

Many AD utilities employ similar features and operations as they perform processing tasks. For example, most rely on prompts to gather values for system-specific processes, and all automatically create log files to record processing actions. This section describes some of these common operations.

Prompts

Many AD utilities prompt for information necessary for completing a task. Prompts typically include a description of the information needed, and may include a default answer (in square brackets). You can just press the [Return] key to accept the default.

For example:

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] :

Press [Return] to accept the default value, or type a new value
after the colon and press [Return]. Read the prompts carefully
to make sure you supply the correct information.

Interactive and Non-Interactive Processing

The AD utilities perform processing tasks interactively by default. That means the utility prompts for system-specific information at the point where it needs it, making it necessary for you to be present during the entire operation in order to respond to the prompts.

AD Administration, adop, , and AD Controller can run some file system and database tasks non-interactively: you store the required information in a defaults file, and the utility reads the information from this file instead of prompting you for the input. Non-interactive processing is useful for scheduling routine tasks that require little or no user intervention.

Note: For more information, see Performing Maintenance Tasks Non-Interactively in this book. See also Monitoring and Controlling Parallel Processes in this chapter.

Special Parameter for Using adop and AD Administration Non-Interactively

When running AD Online Patching, AD Administration, or AD Splicer in non-interactive mode, the "stdin=y" option can optionally be used to prompt for passwords in the standard input. The default is for passwords to be supplied without prompting.

Log Files

All AD utilities record their processing actions and any errors that they encounter in log files. Many utilities prompt you for the name of the log file that will record the processing session, with a display such as this:

<utility name> records your <utility name> session in a text file you specify.
Enter your <<utility name> log file name or press [Return] to accept the
default name shown in brackets.

Filename [<utility name>.log] :

The default file name is <utility name>.log. For example, for AD Administration, the default log file is adadmin.log.

AD Administration log files are stored in the following locations:

UNIX:

$APPL_TOP/admin/<SID>/log

Windows:

%APPL_TOP%\admin\<SID>\log

Restart Files

Restart files contain information about what processing has already been completed. They are located in $APPL_TOP/admin/<SID>/restart (UNIX) or in %APPL_ TOP%\admin\<SID>\restart (Windows).

If a utility stops during processing due to an error, or you use AD Controller (in the case of parallel processing) to shut down workers while they are performing processing tasks, you can restart the utility. If you do, it looks for restart files to determine if there was a previous session. If the files exist, the utility prompts you to continue where the processing left off, or to start a new process. If you choose to continue, it reads the restart files to see where the process left off, and continues the process from that point.

Caution: Do not modify or delete any manager or worker restart files unless specifically directed to do so by Oracle Support Services.

By default, AD utilities delete their restart files when processing is complete, but leave backup versions with the extensions .bak, .bk2, or .bk3.

Warning: Restart files record passwords for your Oracle E-Business Suite products. You should restrict access to all restart files (located in $APPL_TOP/admin/<SID>/restart). If you are running a utility with options=nohidepw, the log files may also contain passwords on lines prefixed with HIDEPW.

Configuration and Environment Files

Most AD utilities require access to system parameters stored in various configuration and environment files when processing maintenance tasks. For example, it may be necessary to know the location of an Oracle Application Server ORACLE_HOME or the Database (RDBMS) ORACLE_HOME.

Configuration and environment files are generated by AutoConfig during an installation or upgrade. You typically do not have to manually update or maintain the information in these files. They are updated when you run AutoConfig.

Note: For more information, see AutoConfig, Oracle E-Business Suite Concepts and Using AutoConfig Tools for System Configuration, Oracle E-Business Suite Setup Guide.

The following table lists configuration and environment files commonly used by the AD command line utilities, and in some cases, by the OAM Web-based utilities.

Note: <CONTEXT_NAME> defaults to <SID>_<hostname>.

AutoConfig-Managed AD Utility Files

File name	Location	Description
adconfig.txt	$APPL_TOP/admin	Contains environment information used by all AD utilities. Warning: Do not update this file manually.
<CONTEXT_NAME>.env (UNIX) <CONTEXT_NAME>.cmd (Windows)	RDBMS ORACLE_HOME	Used to configure the environment when performing maintenance operations on the database.
APPS<CONTEXT_NAME>.env (UNIX) APPS<CONTEXT_NAME>.cmd (Windows)	APPL_TOP	This file calls the environment files needed to set up the APPL_TOP and the Applications ORACLE_HOME.
<CONTEXT_NAME>.env (UNIX) <CONTEXT_NAME>.cmd (Windows)	APPL_TOP	Called by APPS<CONTEXT_NAME>.env (UNIX) or APPS<CONTEXT_NAME>.cmd (Windows) file to set up the APPL_TOP. This file calls either adovars.env (UNIX) or adovars.cmd (Windows).
<CONTEXT_NAME>.env (UNIX) <CONTEXT_NAME>.cmd (Windows)	$INST_TOP/appl/admin	Called by APPS<CONTEXT_NAME>.env (UNIX) or APPS<CONTEXT_NAME>.cmd (Windows).
adovars.env (UNIX) adovars.cmd (Windows)	APPL_TOP/admin	Called by the <CONTEXT_NAME>.env (UNIX) or <CONTEXT_NAME>.cmd (Windows) file located in the APPL_TOP. Used to set environment variables for Java and HTML.

The following configuration and environment files are also used by most AD utilities, but are not created by AutoConfig.

Warning: Do not update any of these AutoConfig-managed files manually.

Non-AutoConfig AD Utility Files

File name	Location	Description
applora.txt	APPL_TOP/admin	Contains information about required init.ora parameters for runtime.
applorau.txt	APPL_TOP/admin	Contains information about required command lineinit.ora parameters for install and upgrade.
applprod.txt	APPL_TOP/admin	The AD utilities product description file, used to identify all products and product dependencies.
applterr.txt	APPL_TOP/admin	The AD utilities territory description file. It contains information on all supported territories and localizations.
fndenv.env	FND_TOP	Sets additional environment variables used by Oracle Application Object Library. The default values should be applicable for all customers.

Feature Version Numbers

In order to use some AD Administration and adop features, the version number of the feature must be the same in both the file system and the database. There may be times when these feature versions do not match. For example, if a patch did not run successfully to completion, it may have updated the file system, but not the database. In this case, the file system version and the database version could be different.

When you start AD Administration or adop, an information matrix scrolls on the screen. It indicates the status (Active=<Yes or No>) and version numbers of the following features: CHECKFILE, PREREQ, CONCURRENT_SESSIONS, PATCH_ HIST_IN_DB, PATCH_TIMING, and SCHEMA_SWAP.

The matrix is for information only. No action is required unless the feature versions do not match. If they do not, you can use the OAM Applied Patches utility to determine which patches were applied successfully and verify the version level.

The AD Interface

Some AD utilities are designed to perform a single function. For example, you run AD Relink only to relink executables programs with the server product libraries. These utilities do not use menus or input screens. All user interaction is from the command line in the form of prompts.

However, other utilities have multiple functions, which are presented on menus or input screens. For example, when you run AD Administration, the first screen you see is the main menu.

AD Administration Main Menu

From this screen, choose one of the submenus, and then from there, choose the process you want to run.

Note: You can run the AD Utilities while an online patching cycle is in progress. The only additional step needed is to set the environment to the patch edition. An error will be raised if you try to run a utility from the run edition while a patch cycle is in progress (that is, a patch edition exists).

Command Line Arguments

You can direct the way the AD utilities operate by adding modifiers to the utility's start command. These modifiers may be in the form of arguments, flags, or options. They all refine the actions performed by a utility.

Command line arguments, flags, and options are in the "token=value" format, where token is the name of the modifier. You should enter both the argument and the value in lowercase type (the utility automatically converts the "token" portion to lowercase, but it cannot convert the "value").

For example:

$ adadmin LOGFILE=TEST.LOG

The token ("LOGFILE") will be converted to lowercase, but the value (TEST.LOG) is not recognized by the utility. The correct way to enter this command is:

$ adadmin logfile=test.log

You can enter more than one token=value argument on a single command line by separating them with one blank space as in the following adadmin command.

$ adadmin printdebug=y flags=hidepw

In some cases, you can include more than one value for a token. In this case, separate the values with commas. For example:

$ adadmin flags=nohidepw,trace

Comma-separated lists must not contain blank spaces. For example, the following command is not valid and will give an error:

$ adadmin flags=nohidepw, trace

Some arguments are used only by a specific utility. For example, adop makes extensive use of command line arguments and options that are unique to that utility: these are listed and discussed in the Patching section of this book.

Other command line arguments are used by several utilities. These are listed in the following table.

AD Utility Command Line Arguments

abandon	Description
Used by	AD Administration, adop.
Purpose	Tells AD utilities to abandon an existing non-interactive session. Can be used only when interactive=n is also specified.
Values	y or n
Default	n, meaning that the last utility run non-interactively did not successfully complete the processing.
Example	adadmin interactive=n abandon=y

AD Utility Command Line Arguments

defaultsfile	Description
Used by	AD Administration, adop, AD Controller.
Purpose	Specifies the defaults file which stores answers to interactive AD utility questions. Normally used non-interactively.
Values	A fully-qualified filename. Must be under the $APPL_ TOP/admin/<SID> directory.
Default	None, meaning that no defaults file is used.
Example	adctrl defaultsfile=/d1/apps/prodappl/admin/prod1/prod_ def.txt

AD Utility Command Line Arguments

help	Description
Used by	All AD utilities.
Purpose	Summarizes available command line options.
Values	y or n
Default	n
Example	adadmin help=y

AD Utility Command Line Arguments

interactive	Description
Used by	AD Administration, adop, AD Controller.
Purpose	Tells AD utilities whether to run either interactively or non-interactively.
Values	y or n
Default	y, meaning that the utility runs interactively.
Example	adadmin interactive=n

AD Utility Command Line Arguments

localworkers	Description
Used by	AD Administration, adop.
Purpose	Specifies the number of workers to run on the primary node in a Distributed AD environment.
Values	1 to the maximum supported by your database, but not more than 999, inclusive
Default	Defaults to the value of the workers argument, which means all workers run on the primary node.
Example	adadmin workers=8 localworkers=3

AD Utility Command Line Arguments

logfile	Description
Used by	All AD Utilities.
Purpose	Tells AD utilities what log file to use. Normally used when running a utility non-interactively.
Values	A file name (not a fully-qualified path name)
Default	None, meaning that the utility will prompt for the log file name.
Example	adctrl logfile=test.log

AD Utility Command Line Arguments

menu_option	Description
Used by	AD Administration, AD Controller.
Purpose	When running one of these utilities non-interactively, used to connect the actions in a defaults file with a specific menu item.
Values	See list of menu options in the description of these utilities. Must be used with interactive=n and defaultsfile=<name of defaults file>.
Default	N/A
Example	adctrl interactive=n defaultsfile=$APPL_ TOP/admin/prod/ctrldefs.txt menu_option=SHOW_STATUS

AD Utility Command Line Arguments

parallel_index_threshold	Description
Used by	AD Administration, adop.
Purpose	Specifies the number blocks in a table. If a table contains fewer blocks than the threshold setting, indexes are created with parallel workers and serial DML. If the table contains more blocks than the threshold setting, indexes are created with one worker and parallel DML.
Values	0 to 2147483647; if set to 0, indexes are created with parallel workers and serial DML
Default	20000; meaning a threshold of 20,000 blocks
Example	adadmin parallel_index_threshold=15000

AD Utility Command Line Arguments

printdebug	Description
Used by	All AD Utilities.
Purpose	Tells AD programs to display extra debugging information. In some cases, the amount of extra debugging information is substantial.
Values	y or n
Default	n
Example	adadmin printdebug=y

AD Utility Command Line Arguments

restart	Description
Used by	AD Administration, adop, AD Controller.
Purpose	Tells AD utilities running non-interactively to restart an existing session. Only valid when interactive=n is also specified.
Values	y or n
Default	n, meaning that the utility running non-interactively will expect to run a completely new session.
Example	adadmin interactive=n restart=y

AD Utility Command Line Arguments

wait_on_failed_job	Description
Used by	AD Administration, adop.
Purpose	Directs the utilities to wait for user input in a non-interactive session when a job fails.
Values	y or n
Default	n
Example	adadmin wait_on_failed_job=yes

AD Utility Command Line Arguments

workers	Description
Used by	AD Administration, adop.
Purpose	Specifies the number of workers to run. Normally used when running the utility non-interactively.
Values	1 to the maximum supported by your database, but not more than 999
Default	No, meaning that the program prompts for the number of workers to run
Example	adadmin workers=8

AD Flags Argument

The flags= argument is used by all AD utilities. It passes one of several generic flags to the utility. Enter one flag or a comma-separated list of flags. The default is None.

flags= Argument Options

hidepw	Description
Default	hidepw
Purpose	Directs the utilities to either hide or show passwords in AD Utility log files.
Comments	By default, lines in an AD utility log file containing passwords are modified to hide the passwords. When nohidepw is specified, each line containing hidden passwords is followed by a corresponding line prefixed with HIDEPW:, showing the original line with passwords.
Example	adadmin flags=nohidepw

flags= Argument Options

logging	Description
Default	logging
Purpose	Tells the AD utility whether to create indexes using logging or nologging.
Comments	Using flags=nologging when creating indexes may increase performance. However, flags=nologging makes database media recovery incomplete and does not work with standby databases. Logging is the default in adop to support database media recovery and standby databases. We do not recommend using flags=nologging for production systems unless you make a complete backup both before and after running adop. flags=nologging affects indexes created through ODF only, not SQL scripts. The XDF utility always creates indexes with logging.
Example	adop flags=logging

flags= Argument Options

trace	Description
Default	notrace
Purpose	Tells the AD utility whether to log all database operations to a trace file.
Comments	Database trace files created while running an AD utility may aid debugging. The flags=trace option creates multiple trace files for the AD utility and the AD workers. A new trace file is created each time the AD utility or a worker reconnects to the database. Note that flags=trace only traces database operations internal to the AD utility itself. Database operations in SQL scripts or external programs run by the AD utility are not recorded by flags=trace.
Example	adadmin flags=trace

Note: Many AD utilities accept additional arguments to those listed. However, these should be used only under the explicit direction of Oracle Support.

Running AD Utilities

Important: AD utilities cannot be run in parallel with each other. For example, adadmin should not be run when adop is running on any of the nodes in the system. In addition, parallel sessions of the same utility should not be run. For example, two parallel adadmin sessions cannot be run either on the same node or different nodes in the system. The only exception to this is adop, which can safely be run in parallel on multiple nodes (but not in parallel on a single node).

Important: AD utilities such as AD Admin and AD Splice can be invoked from the run edition only if there is no patch edition. If a patch edition exists, attempting to invoke the utility from the run edition will fail with an error.

To run AD utilities, set the environment to define the system configuration parameters. For example, a utility may require the directory path to the Applications ORACLE_HOME. This parameter, and others, make up your system environment.

Important: Before setting the environment, Windows users must also configure Windows services.

Once you have pointed the utility to the correct environment, you start it by entering the utility name.

Note: See Configuration and Environment Files in this chapter.

Setting the Environment

To set the Oracle E-Business Suite environment, complete the following steps. See the applicable Installation and Upgrade Notes for any additional platform-specific steps.

Important: Remember that there are two file systems in Release 12.2, run and patch. The environment must be set correctly on both.

1. Log in as applmgr (Applications file system owner).

2. Run the environment (UNIX) or command (Windows) file for the current APPL_ TOP and database.

   UNIX:

   The environment file is typically APPS<CONTEXT_NAME>.env, and is located under APPL_TOP. From a Bourne, Korn, or Bash shell, enter the following command:

   $ . APPS<CONTEXT_NAME>.env

   Windows:

   Using either Windows Explorer or the Run option from the Start menu, enter the command:

   %APPL_TOP%\envshell.cmd

   This creates a command window with the required environment settings for Oracle E-Business Suite. All subsequent commands should be run in this window.

3. If you have made any changes to the environment, check that it is correctly set by entering the following commands:

   UNIX:

   $ echo $TWO_TASK
   $ echo $ORACLE_HOME
   $ echo $PATH

   Windows:

   C:\> echo %LOCAL%
   C:\> echo %ORACLE_HOME%
   C:\> echo %PATH%
   C:\> echo %APPL_CONFIG%

   For UNIX, the ORACLE_HOME must be set to the proper database directory, and TWO_TASK or LOCAL must identify the correct database. For Windows, APPL_ CONFIG must be set to <CONTEXT_NAME>.

4. Ensure that there is sufficient temporary disk space.

   You should have at least 50 MB in the temporary directories denoted by $APPLTMP and $APPLPTMP (UNIX), or %APPLTMP% and %APPLPTMP% (Windows). You should also have space in the operating system's default temporary directory, which is usually /tmp or /usr/tmp (UNIX) or C:\temp (Windows).

5. If you are running an AD utility to relink or update Oracle E-Business Suite product files or modify Oracle E-Business Suite database objects, shut down the concurrent manager, Web server listeners, forms server listeners if the files are on a node that contains the associated servers. For example, if the files are on the node that contains the concurrent processing server, shut down the concurrent managers.

   Note: For more information, see Administer Concurrent Managers in Oracle E-Business Suite System Setup Guide.

Configuring Windows Services

If you are running AD utilities on a Windows platform, you must first shut down all forms services, Web listener services, and concurrent manager services. In addition, you must verify that the database and database listeners are running.

To view and change the status of a service, follow these steps:

1. Select Start > Settings > Control Panel, and double-click on Services.

2. Highlight the appropriate service name and click Stop or Start as appropriate. The following table lists the services and status required when running an AD utility:

   Windows Services and AD Utility Status Requirements

   Service Type	Service Name	Status
   Concurrent Manager Services	OracleConcMgr<CONTEXTNAME>	Stopped
   Database Services	OracleService<SID>	Started
   Database Listener	Oracle<SID>_<DB_VERS>RDBMSTNSListener<SID>	Started

Starting a Utility

To start an AD utility, enter the utility's executable name on the command line. For example, to start AD Administration, you would enter the command:

$ adadmin

Note: For more information, see Command Line Utilities in this chapter for a list of AD executables.

Exiting or Stopping a Utility

When menu-driven utilities complete a processing task, they return you to the main menu, where you either choose another process or Exit. AD Administration is an example. Other utilities do not use a menu format. In this case, the utility exits automatically when processing is complete. adop, AD Merge Patch, and File Character Set Converter File Character Set Converter are examples.

Before it begins processing tasks, you can stop a utility by entering abort at any prompt. You can use this command only for utilities that display prompts, and only when a prompt is displayed on the screen.

In some cases, a utility may begin the processing actions, but quits before the actions are complete (because of an error). Or, during a parallel processing session, you may decide to stop the processing actions by shutting down the workers.

Note: For more information, see the Troubleshooting chapter in this section for additional details about shutting down and restarting workers.

Restarting a Utility

You can restart a utility by entering the executable name on the command line. When you restart, the utility prompts you to enter a new log file, or to specify the log file from the interrupted session. When you reuse the log file from a previous session, the utility adds the message “Start of <utility name> session” to the end of the file and appends messages from the continued session as it generates them.

The utility prompts you to do one of the following:

• Continue Session (the default)

  The utility checks the progress of the previous session in the restart files, and begins processing at the point where your last session stopped.

• Start New Session

  The utility asks you to confirm your choice if you choose not to continue the previous session. It starts the process from the beginning.

If the process that stopped was running in parallel, a FND_INSTALL_PROCESSES table may exist. If it does, the utility asks if you want to drop the table. This message serves as a warning to make you aware of the existing AD session. Determine if any other utility is running in another session or on another node. If you are sure that the AD utility that is currently running is not needed, you can drop the FND_INSTALL_ PROCESSES table and continue with the newer AD session that you started.

Note: For more information, see Restart Files in this chapter.

Using Parallel Processing

Processing Tasks in Parallel

Parallel processing is typically used by AD Administration and to:

• Compile invalid objects.

• Run database driver tasks, such as SQL scripts.

• Generate various kinds of files, such as forms, report, and message files.

Workers complete processing tasks assigned to them by the manager. The utilities themselves determine the list of tasks to be performed and prioritize them for execution. They also prompt for the number of workers to perform the tasks. For example, when is applying a database driver, it creates a list of database tasks and prompts you to specify the number of workers that should run concurrently to execute these tasks.

The worker processes are instances of the adworker program. This program can only be called by the manager processes, and cannot be run stand-alone.

Managers

The manager assigns each worker a unique ID and inserts a row for each worker in the FND_INSTALL_PROCESSES table. It creates this table to serve as a staging area for job information, and as a way to communicate with the worker. Communication is accomplished using two columns: CONTROL_CODE and STATUS.

The manager updates the table with a subset of the list of jobs, one job per worker. For example, if there are five workers, then the table holds five jobs (even though there may be 100 or more jobs involved in the complete action). The manager starts the workers and uses the CONTROL_CODE and STATUS columns to assign tasks. It polls these two columns continuously, looking for updates from the workers. As a worker finishes its assignment, the manager updates each row with the next task in the list, and leaves another message for the worker.

Once all jobs are complete, the manager tells the workers to shut down, and then drops the FND_INSTALL_PROCESSES table (after it is sure all workers have actually shut down).

Workers

Each worker updates the STATUS column, giving the manager a report on its progress. As the jobs are completed, the manager updates the table with the next job in the queue, and updates the CONTROL_CODE and STATUS columns telling the worker to start processing. If there is a failure, the worker reports a failed status.

For certain tasks, some worker processes spawn other child processes that do the actual work. The spawned child process returns a status code to the worker that spawned it. The worker interprets the code to determine if the job has been completed successfully. Examples of child processes are SQL*Plus and FNDLOAD.

Deferred Jobs

The first time a job fails, the manager automatically defers the job and assigns a new one to the worker. If the deferred job fails the second time it is run, the manager defers it again only if the total runtime of the job is less than ten minutes. If the deferred job fails a third time (or if the job's total runtime is not less than ten minutes the second time it is run) the job stays at failed status and the worker waits. At this point, you must address the cause of the failure, and then restart the job.

Note: For more information, see Running AD Controller Interactively in this chapter.

The deferred job feature uses the AD_DEFERRED_JOBS table. This table is created when the FND_INSTALL_PROCESSES table is created, and is dropped when the FND_INSTALL_PROCESSES table is dropped.

Determining Number of Workers

The AD utilities provide a default number of workers of twice the number of CPUs on the database server. Oracle recommends you choose a number of workers between 2-4 times the number of CPUs. For example, if there are four CPUs on the database server, you should choose something in the range of 8-16 workers.

The AD utilities calculate a maximum number of workers that your database can support (up to 999). You cannot enter a number of workers greater than the database can support.

Note: In Release 12.2, AD utilities execute during runtime. Therefore, the number of available DB processes is also taken into account when calculating the number of workers. During periods of presumed high activity, estimating the requirement for DB processes can limit the number of AD workers more than the actual number of DB processes.

Worker Log Files

In addition to the information recorded in the <utility name>.log file, utilities that process jobs in parallel write details about errors to worker log files. The adwork<number>.log files (adwork001.log, adwork002.log...) reside in the $APPL_ TOP/admin/<SID>/log directory, where <SID> is the value of the ORACLE_SID or TWO_TASK variable (UNIX), or in %APPL_TOP%\admin\<SID>\log, where <SID> is the value of ORACLE_SID or LOCAL (Windows).

Concurrent requests run by adop and adadmin create their own log files.

Note: For more information, see Log and Output File Names and Locations in Oracle E-Business Suite Setup Guide.

Worker Restart Files

Restart files are used to continue processing at the point where it stopped. Each worker may also have a restart file called adworkxxx.rf9. These files are stored in $APPL_TOP/admin/<SID>/restart (UNIX) or in %APPL_TOP%\admin\<SID> \restart (Windows). The worker creates the restart file when the manager assigns it a job, and deletes the restart file when it finishes the job.

Caution: Do not modify or delete any manager or worker restart files unless explicitly told to do so by Oracle Support.

The Troubleshooting chapter in this section discusses various error situations when running a utility and how to resolve them.

Parallel Support for Data Manipulation Language (DML)

To reduce downtime when creating indexes, the parallel_index_threshold argument for AD utilities is set to a default value of 20,000. This means that if a table contains less than 20,000 blocks, the AD utilities create indexes with parallel workers and serial DML (just as in earlier releases). If a table contains 20,000 blocks or more, indexes are now created with only one worker and parallel DML. You can adjust this threshold value by specifying the parallel_index_threshold argument on the AD utility command line.

Monitoring and Controlling Parallel Processes

AD sessions that use parallel processing may run to completion without user intervention. However, it is often useful to determine how many jobs have been completed or whether processing has stopped for some reason. AD Controller is a utility that you can use to determine the status of AD Administration or adop workers and to control their actions. You can run AD Controller interactively or non-interactively. It must be run in its own window, not in the same window as adadmin or adop.

Note: For more information, see Interactive and Non-Interactive Processing in this chapter.

You choose options that display worker status, restart workers, or issue commands to the manager from the AD Controller main menu.

Running AD Controller Interactively

Follow these steps to access AD Controller.

1. Log in as applmgr and set the environment as described in Setting the Environment in this chapter.

   Important: AD Controller (adctrl) can only be run from the patch edition of the file system. Attempting to run it from the run edition will give an error. You can identify which edition you are in by checking the value of the FILE_EDITION environment variable.

2. Start AD Controller with the adctrl command. This will prompt you to:

   • Confirm the value of APPL_TOP.

   • Specify an AD Controller log file (the default is adctrl.log). The AD Controller log file is written in the current working directory.

   • Supply the Oracle Application Object Library user name and password.

3. Choose an option from the main menu.

   Once you respond to the prompts, the main menu appears.

   AD Controller Menu

   

   Type a number to select an option. Press [Return] at any time to return to the AD Controller main menu.

   Note: See the Troubleshooting Applications DBA Operations chapter in this book for instructions on using each menu option.

Running AD Controller Non-Interactively

You can run AD Controller without user intervention by creating a defaults file, which captures information you supply at the interactive prompts in a file that you can later use to run AD Controller without user intervention. Creating a defaults file and running AD Controller non-interactively works in much the same way as it does for AD Administration.

Note: For more information, see Scheduling Non-Interactive Maintenance in this book.

Like AD Administration, the same defaults file can be used to run different AD Controller commands: a single file can contain all your choices for the different menu options. In order to choose which task the defaults file will run, you add menu_ option= <menu choice> to the utility start command. This overrides any menu-specific key stroke information stored in the defaults file initially, and allows you to use the defaults file for any of the AD Controller menu items. It also ensures that the menu option you intended for the defaults file is always valid, even it the menu items are renumbered or relocated in subsequent releases.

The available options are listed in the following table.

AD Controller Menu Options

Menu Option	Effect
ACKNOWLEDGE_QUIT	Tell manager that a worker acknowledges quit
INFORM_FAILURE	Tell manager that a worker failed its job
RESTART_JOB	Tell worker to restart a failed job
SHOW_STATUS	Show worker status
SHUTDOWN_WORKER	Tell worker to quit
START_WORKER	Restart a worker on the current machine

Note: The menu options for running AD Administration are listed in the Preparing for Non-Interactive Processing section of this book.

The following is an example of running AD Controller non-interactively to show worker status:

$ adctrl interactive=n defaults_file=$APPL_TOP/admin/prod/ctrldefs.txt \
logfile=adctr.log menu_option=SHOW_STATUS

Using any menu option on the command line, except for SHOW_STATUS, requires that you also use the worker_ range=<range> option. See the AD Controller command line help for details.

Distributing Processing Tasks Across Nodes

AD uses its existing manager-worker job system employed in parallel processing to include Distributed AD. This parallel processing feature allows workers in the same AD session to be started on multiple application tier servers to utilize all available resources. Because the AD workers create and update file system objects, as well as database objects, Distributed AD must be used only on systems that are using a shared application tier file system to ensure the files are created in a single, centralized location.

While running either adadmin or adop on the primary node, you can start an AD Controller session from any of the nodes in the shared application tier file system environment to perform any standard AD Controller operation, using both local and non-local workers.

Note: For more information, seethe Distribute Processing with Distributed AD of this book.

About System Maintenance

After your system is installed, it will be necessary to perform certain maintenance tasks to keep it running smoothly. For example, you will generate form files, maintain snapshot information, relink executables, compile or validate the APPS schema, and so on. Some tasks are routine and should be performed on a regular basis. Other tasks are non-routine and generally performed infrequently.

You run maintenance tasks from the command line using AD Administration. Once you start this utility, it presents the tasks in menu form, grouped generally by type of activity you will perform. For example, the tasks associated with compiling and reloading Applications database entities are grouped on the same menu.

In addition to the AD Administration maintenance tasks, this chapter describes AD Relink, a command line utility used to relink AD executables.

Important: You cannot relink AD utilities executables using AD Administration.

AD Administration Overview

AD Administration manages most of the maintenance tasks required for your Oracle E-Business Suite system. Currently, these maintenance tasks are grouped by types on the AD Administration main menu.

When you start AD Administration from the command line, it prompts you for the basic system-specific information it needs. For example, you need to supply a name for the log file where processing actions and error messages will be recorded.

Note: For more information, see Prompts in Chapter 1.

Once you respond to these prompts, AD Administration displays the main menu, which serves as the gateway to various submenus where you select the individual maintenance tasks. For example, on the Generate Applications Files menu, you can run tasks that generate message files, forms files, report files, message files, or product JAR files. These submenu tasks may also require you to respond to prompts to collect task-specific information. For example, some tasks require you to enter the number of workers you want to employ to process the jobs associated with the task.

Note: For more information, see Processing Tasks in Parallel in Chapter 1.

When you respond to AD Administration prompts, you are running the utility interactively. However, like adop and AD Controller, you can also run AD Administration non-interactively, specifying a previously created defaults file that contains the information necessary to run a specific maintenance task without user intervention.

Note: For more information, see Interactive and Non-Interactive Processing in Chapter 1.

Prompts

In addition to the basic prompts described in Chapter 1, AD Administration may require additional information that is specific to one of the submenu tasks. If so, it displays additional prompts. For example, when running the Generate Product JAR files task from the Generate Applications Files menu, AD Administration prompts you as follows:

Do you wish to force generation of all jar files? [No]:

The task-specific prompts are described more fully in the discussion of each task.

Preparing for Non-Interactive Processing

The discussion of command line prompts assumes you are running AD Administration interactively. You respond to the standard prompts and those required for specific tasks you choose from the AD main menu and submenus. AD Administration can also run some tasks non-interactively by using the information you store in a defaults file, instead of requiring you to respond to prompts.

Note: For more information, see Interactive and Non-Interactive Processing in this book.

Specifying a Menu Option in the AD Administration Defaults File

The same defaults file can be used to run different AD Administration tasks a single file can contain all your choices for the different menu options. In order to choose which task the defaults file will run, you add menu_option= <menu choice> to the utility start command. This overrides any menu-specific key stroke information stored in the defaults file initially, and allows you to use the defaults file for any of the AD Administration menu items. It also ensures that the menu option you intended for the defaults file is always valid, even if the menu items are renumbered or relocated in subsequent releases.

Defaults File menu_option Values

menu_option Value	Corresponding AD Administration Menu Choice
GEN_MESSAGES	Generate message files
GEN_FORMS	Generate form files
GEN_REPORTS	Generate reports files
GEN_JARS	Generate product JAR files
RELINK	Relink Applications programs
COPY_FILES	Copy files to destinations
CONVERT_CHARSET	Convert character set
SCAN_APPLTOP	Scan the APPL_TOP for exceptions
SCAN_CUSTOM_DIR	Scan a CUSTOM directory for exceptions
LIST_SNAPSHOT	List snapshots
UPDATE_CURRENT_VIEW	Update current view snapshot
CREATE_SNAPSHOT	Create named snapshot
EXPORT_SNAPSHOT	Export snapshot to file
IMPORT_SNAPSHOT	Import snapshot from file
DELETE_SNAPSHOT	Delete named snapshot
CHECK_FILES	Check for missing files
CMP_INVALID	Compile APPS schema
CMP_MENU	Compile menu information
CMP_FLEXFIELDS	Compile flexfield data in AOL tables
RELOAD_JARS	Reload JAR files to database
VALIDATE_APPS	Validate APPS schema
CREATE_GRANTS	Recreate grants and synonyms for APPS schema
MAINTAIN_MLS	Maintain multi-lingual tables
CHECK_DUAL	Check DUAL table

The AD Administration Interface

You start AD Administration from the command line. However, all maintenance tasks are initiated from the AD Administration Main Menu. This section describes some of the common features used to run this utility.

Main Menu

After you start AD Administration and respond to the prompts, the AD Administration Main Menu appears.

AD Administration Main Menu

This menu displays the submenus where the individual maintenance tasks are grouped. To choose a submenu, type the number of the menu at the prompt. To exit AD Administration, press [Return].

Available Options

Depending on your system configuration, the submenus for AD Administration may show slightly different option names and numbers from the ones displayed here.

Running AD Administration Interactively

Complete the steps in this section to display the AD Administration Main Menu and access the submenus and the maintenance tasks.

1. Set the environment.

   You must set the environment in order to apply the environment variables that define your system. This task is common to many AD utilities. See Setting the Environment in this book for the preparatory steps.

2. From any directory, start AD Administration with this command:

   $ adadmin

   The utility starts and displays the first prompt.

3. Respond to prompts.

   Supply the information requested by the AD Administration prompts. Prompts unique to an option are described with the option.

   When you complete the prompts, the Main Menu appears.

4. Choose maintenance tasks.

   On the Main Menu, choose a submenu. The submenus and the options they display are described fully beginning with Generate Applications Files in the next section.

5. Exit AD Administration.

   You can exit AD Administration from the Main Menu by choosing option 6 (Exit AD Administration) at the screen prompt. You can also choose to exit the utility at any prompt by typing abort on the command line. See Restart Files in this book for information about restarting AD utilities after using the abort command.

Generating Applications Files

You may need to generate Applications files from time to time during your Applications life cycle. You access the associated tasks from the Generate Applications Files menu.

Generate Applications Files Menu

If system users are having difficulty accessing messages, forms, or reports, you may be able to resolve the issue by generating the associated files. Or, when you apply a patch that adds or changes product functionality, you may want to generate the associated files after you apply the patch, instead of running the generate driver during the patching downtime. The Generate Files tasks may be performed on any server, as required.

You do not have to shut down your system to generate files. However, users that access the files being generated (for example, for Human Resources forms) must log off.

Generate Message Files

Oracle E-Business Suite uses files to display messages. This task generates binary message files (extension .msb) from Oracle Application Object Library tables.

Caution: Run this task only when instructed to do so in a patch readme file, or by Oracle Support Services.

Generate Form and Report Files

These activities are carried out in much the same way.

• Generate forms files

  Generates executable Oracle forms files (extension .fmx) from the binary forms definition files (extension .fmb). The definition files are located under AU_TOP, and the executable files are stored under each product's directory.

• Generate report files

  Generates the binary Oracle Reports report files (extension .rdf).

The prompts and behavior work in similar fashion, except as noted:

• Ask for the number of workers and generate selected objects for selected products in parallel

• Display the current character set (from NLS_LANG) and ask if you want to generate form or report objects in this character set

• Ask if you want to regenerate Oracle Forms PL/SQL library files, menu files, and executable files (forms files only)

• Ask for the products associated with the form or report objects

• Ask if you want to generate specific form or report objects for each selected product

• Display the current set of installed languages and ask if you want to generate form or report files in these languages

• Create a list of all objects to generate

• Display the list of objects to be generated (specific objects or all objects)

Generate Product JAR Files

Generate Java archive (JAR) files whenever you upgrade the Oracle Developer technology stack, or when advised by Oracle Support Services. This task signs JAR files (if on a Web server) and also does the following:

• Generates product JAR files in JAVA_TOP and copies them to APPL_TOP

• Generates other Java-related files under APPL_TOP and JAVA_TOP

• Recreates Java libraries (appsborg.zip and appsborg2.zip) under APPL_TOP and JAVA_TOP

When you run the task, it prompts:

Do you wish to force generation of all jar files? [No]

If you choose No, it generates only JAR files that are missing or out-of-date. If you choose Yes, all JAR files are generated (more time-consuming).

If AD Administration displays a list of warnings or errors and objects that did not generate successfully and asks if you want to continue as if successful, review the log file to determine if the problems require attention. If you choose not to continue and restart your session at a later time, AD Administration attempts to regenerate only the files that did not generate successfully.

Maintaining Applications Files

Certain maintenance tasks are required to keep your Applications files up to date. For example, you may need to copy product files to a central location or convert files in the APPL_TOP to another character set. These tasks are grouped on the Maintain Applications Files menu.

Maintaining Applications Files Menu

You can run any of these tasks by choosing it from this menu.

Relink Applications Programs

Relinks Oracle E-Business Suite executable programs with the Oracle server libraries so that they function with the Oracle database. For each product, you can choose whether to link all executables or specific ones only.

The default is to relink without debug information. You should use the debug option only when requested to do so by Oracle Support Services.

Important: AD Administration cannot be used to link executables for the AD products themselves. You must use AD Relink for this. See Relinking AD Executables in this chapter.

Copy Files to Destinations

Copies files from each product area to central locations where they can be easily referenced by non-Applications programs. This option uses revision-based copy logic to ensure that the destination file versions are the same as, or higher than, the source file versions.

Oracle recommends that you do not use the force option to overwrite existing files, unless so instructed by Oracle Support Services. Copying files with this option updates all JAR files, resulting in them all being downloaded to each client again and causing runtime performance degradation.

The file types and their respective destinations are shown in the following table:

Copy Files to Destinations Summary

These files ...	... are copied to: (UNIX)	... are copied to: (Windows)
Java files	$JAVA_TOP	%JAVA_TOP%
HTML files	$OAH_TOP	%OAH_TOP%
Media files	$OAM_TOP	%OAM_TOP%

The directories for the variables are specified in the adovars.env file (UNIX) or the adovars.cmd file (Windows).

When this option is used to copy reports files, the default destination is under AU_TOP.

Convert Character Set

Prepares the files in the APPL_TOP for conversion to another character set, and then performs the conversion.

Note: For more information, see Globalization Support in Oracle E-Business Suite Concepts.

When you choose this option, AD Administration presents another submenu, which contains options for scanning your files in preparation for the conversion. The scan searches for exceptions - files that will have incomplete (lossy) conversions - so that you can fix potential problems before you actually convert the character set. Choose one of the following scan options.

Tip: Always verify the compatibility of the database character set before converting the APPL_TOP character set.

The options are:

1. Scan the APPL_TOP for exceptions.

   Scans the APPL_TOP and creates three files in the admin\<SID>\out directory.

   Scan APPL_TOP for Exceptions Output Files

   File	Contents
   admanifest_excp.lst	Lists files that will not be converted because of lossy conversion.
   admanifest.lst	Lists files that can be converted.
   admanifest_lossy.lst	Lists files with lossy conversions, including line by line detail.

   Review the files listed in admanifest_excp.lst. Fix files that report lossy conversion before you convert the character set. Repeat this task until there are no entries in admanifest_excp.lst. If you need to see more detail, review admanifest_lossy.lst.

2. Scan a CUSTOM directory for exceptions.

   Collects the same information as the first task, but scans custom Applications directories rather than the APPL_TOP directory.

   Note: With this option, adamin may list additional files (such as .rdf, .doc, and .zip) as exceptions in admanifest_excp.lst. This is because the CUSTOM directory can be modified by users, so the file extension is not enough for adadmin to determine whether a file can be successfully converted. In contrast, users cannot modify the files under $APPL_TOP, so the file extensions there are a reliable guide to whether a file can be successfully converted.

3. Convert character set.

   Run this task only if admanifest_excp.lst has no entries. It prompts you for the manifest file (admanifest.lst) created when you ran the scan option(s).

   The utility backs up the product source files and the APPL_TOP/admin source files. It saves product files in the <PROD>_TOP directories in the format <prod>_ s_<char_set>.zip. It saves admin source files in the APPL_TOP/admin directory in the format admin_s_<char_set>.zip

Maintain Snapshot Information

There are two types of snapshots: APPL_TOP snapshots and global snapshots. An APPL_TOP snapshot lists patches and versions of files in the APPL_TOP. A global snapshot lists patches and latest versions of files in the entire Applications system (that is, across all APPL_TOPs).

Both APPL_TOP snapshots and global snapshots may be either current view snapshots or named view snapshots. A current view snapshot is created once and updated when appropriate to maintain a consistent view. A partial view snapshot allows you to synchronize only selected files from a current view. A named view snapshot is a copy of the current view snapshot at a particular time (not necessarily the latest current view snapshot), and is not updated.

Patch Wizard uses the information contained in the global current view snapshot to determine which patches have already been applied. The APPL_TOP current view snapshot is used to determine if all prerequisite patches have been applied to that APPL_TOP. Snapshot information is stored in the AD_SNAPSHOTS, AD_ SNAPSHOT_FILES, and AD_SNAPSHOT_BUGFIXES tables.

During a new installation, Rapid Install creates a current snapshot as a baseline. Whenever you apply a patch, a new (updated) snapshot is created to reflect the application.

Snapshot information maintenance is performed by choosing Maintain Snapshot Information from the Maintain Applications Files menu, and then selecting the required option.

Maintain Snapshot Information Main Menu

These options allow you to:

• List snapshots stored in the system

• Update a current view snapshot (full or partial APPL_TOP and global)

• Create a named snapshot (you select a current view snapshot to copy and name)

• Export a snapshot to file (you select a snapshot to export to a text file)

• Import a snapshot from a text file (you select a snapshot to import from a text file)

• Delete a named snapshot

Maintain Current View Snapshot Information

When you maintain a current view snapshot, you can choose to synchronize selected files (to maintain a partial snapshot), instead of synchronizing all files for the entire APPL_TOP. Use this option when you have copied only a few files to the APPL_TOP.

1. Select the Update Current View Snapshot option from the Maintain Snapshot Information menu.

   Maintain Current View Snapshot Information Menu

   

2. From the Maintain Current View Snapshot Information menu, you can select one of the following options:

   • Update Complete APPL_TOP

     This is the original functionality of the Update Current View Snapshot option. It synchronizes all the files in your APPL_TOP.

   • Update JAVA_TOP only

     Synchronizes only the files in the JAVA_TOP. At the prompt, enter the path to the JAVA_TOP subdirectory where the files were copied. If the files were copied to more than one directory, press Enter. AD Administration scans the entire JAVA_TOP and updates the information in both the current view and the global view snapshots.

   • Update a <PRODUCT>_TOP

     Synchronizes only the files in a specific <PRODUCT>_TOP. Enter the product abbreviation, then provide the subdirectory information at the prompt.

     Enter the path to a single subdirectory in the <PRODUCT>_TOP. If the files were copied to more than one directory in the <PRODUCT>_TOP, press Enter. AD Administration scans the entire <PRODUCT>_TOP and updates the information in both the current and the global view snapshots.

Check for Missing Files

Verifies that all files needed to run Oracle E-Business Suite for the current configuration are in the current APPL_TOP. Choose this task if you suspect there are files missing in your APPL_TOP.

Managing Database Entities

Database entities are database objects or data in the database related to Oracle E-Business Suite. Tasks for managing entities are grouped into two options on the AD Administration Main Menu: one for compiling or reloading entities and one for verifying their integrity.

Compiling or Reloading Database Entities

To compile or reload database entities, choose the Compile/Reload Applications Database Entities Menu option from the AD Administration Main Menu.

Compile/Reload Applications Database Entities Menu

You run the tasks on this menu any time you need to compile or reload database objects; for example, after you upload new menu entries, or apply a patch that changes the setup of flexfields. Run these tasks only on the node where the core AD technology directories are located.

Compile APPS schema

Spawns parallel workers to compile invalid database objects in the APPS schema.

Note: For more information, see Compiling Invalid Objects in this chapter.

Compile Menu Information

Compiles menu data structures. Choose this task after you have uploaded menu entries to the FND_MENU_ENTRIES table, or if Compile Security concurrent requests submitted from the Menus form (after changing menu entries) fail for any reason.

AD Administration asks if you want to force compilation of all menus. If you choose the default (No), only menus with changes are compiled. If you enter Yes, all menus are compiled. Compiling all menus is generally not required.

Compile Flexfields

Compiles flexfield data structures in Oracle Application Object Library (FND) tables. Choose this task after you apply a patch that changes the setup of flexfields. Patches usually indicate when you should perform this step

Flexfields automatically compile data when you use them for the first time, so running this task is generally not required. However, compiling flexfields at a specific time can alleviate potential runtime performance issues. For example, you may choose to compile them when system usage is known to be low, rather than automatically on first use.

Reload JAR files to Database

Reloads all appropriate Oracle E-Business Suite JAR files into the database. Choose this task if all Oracle E-Business Suite Java classes are removed from your database; for example, if the database Java Virtual Machine (JVM) is reloaded because of database corruption.

Maintaining Applications Database Entities

During normal system use, the integrity of your database can be compromised, for example through user error or after you apply an inappropriate patch. It is advisable to verify the integrity of database entities as a regular maintenance procedure, or whenever the behavior of your system indicates that database entities may have been corrupted.

To perform these maintenance tasks, select the Maintain Applications Database Entities Menu option from the AD Administration Main Menu.

Maintain Applications Database Entities Menu

Some tasks on this menu report on issues, or potential issues, with database entities, and others actually remedy the issues.

Validate APPS schema

Verifies the integrity of the APPS schema. It produces a report named <APPS schema name>.lst. that lists issues and potential issues, grouped by the action required:

• Issues you must fix (not specific to the APPS schema)

• Issues you must fix (specific to the APPS schema)

• Issues you may want to address (specific to the APPS schema)

The report is located in $APPL_TOP/admin/<SID>/out (UNIX), where <SID> is the value of the ORACLE_SID or TWO_TASK variable, or in %APPL_ TOP%\admin\<SID>\out (Windows), where <SID> is the value of the LOCAL variable. Each section of the file contains instructions for resolving the issues that are listed. Most issues can be fixed by either compiling invalid database objects or recreating grants and synonyms.

Recreate Grants and Synonyms for APPS Schema

This task recreates grants and synonyms for the Oracle E-Business Suite public schema (APPLSYSPUB) and recreates grants and synonyms linking sequences and tables in the base schemas to the APPS schema.

Typically, you run this task after the Validate APPS schema task has reported issues with missing grants and synonyms.

Maintain Multi-Lingual Tables

Run this task after you add a language. It prompts you for the number of workers, then updates all multilingual tables.

Check DUAL Table

Some Oracle E-Business Suite products must access the DUAL table. It must exist in the SYS schema and contain exactly one row. This tasks verifies the existence of this table and the single row.

Important: If the DUAL table does not exist, or if it does not contain only one row, the Oracle E-Business Suite products that access it will fail to operate correctly.

Using AD Relink

You use AD Relink to relink AD executables with the Oracle server product libraries when required, to ensure they will keep functioning properly with the Oracle database.

Note: AD executables can only be relinked using AD Relink. This is in contrast with other product executables, which are relinked using the Relink Applications Executables task on the AD Administration Maintain Applications Files menu.

Relinking AD Executables

A number of options are available to provide extra control over the relinking process. For example, you can relink multiple AD executables in one operation.

Log Files

As you run AD Relink, it creates a log file (adrelink.log) where it records errors and messages. AD Relink appends information about the latest relink action to the end of the file. This file is located in APPL_TOP/admin/log. If an error occurs while you are using AD Relink, or if you are not sure that the relinking was successful, review this file to see what issues should be fixed.

Relinking errors encountered during an AD Administration or patching session are recorded in the main log files for those utilities. See Log Files.

A new log file is created each time AD Relink runs. To recover disk space, or just as good housekeeping practice, you can delete adrelink.log files that are no longer needed (for example, after a relink operation is found to have completed successfully).

Command Line Arguments

You can modify or refine the operation of AD Relink with the command line arguments in the following table.

AD Relink Command Line Arguments

force	Description
Purpose	Indicates which executable programs to relink
Values	n, (relink only if the libraries or object files are more recent that the current executable program) y (relink regardless of the status of the libraries or object files)
Default	none (must enter either y or n)
Example	adrelink force=n

AD Relink Command Line Arguments

backup_mode	Description
Purpose	Indicates whether you want to back up executables
Values	none (do not back up any executables) all (back up all executables) file (back up files according to instructions in adlinkbk.txt)
Default	backup_mode=file
Example	adrelink force=n backup_mode=all

Note: These command line arguments are intended for use with the AD Relink utility only.

Files that are critical to running Oracle E-Business Suite are listed in the adlinkbk.txt file, which is located in APPL_TOP/admin. Using the backup_mode=file argument directs AD Relink to back up only these files.

The AD Relink Interface

You run AD Relink from the command line. It does not use menus or input screens.

Running AD Relink

Run AD Relink as follows.

1. Set the environment.

   You must set the environment to indicate the location of the configuration parameters that define your system. This task is common to many AD utilities. See Setting the Environment in this book for the basic steps.

2. Relink files.

   Run AD Relink with the appropriate command for your operating system:

UNIX

S adrelink.sh force=n "ad <executable name>"

Windows

C:\> sh adrelink.sh force=n "ad <executable name>"