Getting Started

This chapter contains basic information about Oracle E-Business Suite maintenance utilities, both command line and Web-based.

This chapter covers the following topics:

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.

Tip: As of Release 12, all information about patching and AutoPatch operations was moved to a separate book, Oracle E-Business Suite Patching Procedures.

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 AutoPatch should run in parallel when applying a patch, you enter the number of worker processes on the command line when you start AutoPatch. A list of commonly used command line arguments and flags, and a brief description of how to use them, begins later in this chapter.

Except where noted, the AD utilities in the following table are described in this book.

AD Command Line Utilities
AD Utility Name Executable or Script Description
AD Administration adadmin Performs maintenance tasks for Oracle E-Business Suite.
AD Check Digest adchkdig Checks the integrity of Oracle E-Business Suite patches downloaded from My Oracle Support.
AD Configuration adutconf.sql Reports standard information about the installed configuration of Oracle E-Business Suite.
AD Controller adctrl Manages parallel workers in AD Administration and AutoPatch.
AD File Identification adident Reports the version and translation level of an Oracle E-Business Suite file.
AD File Character Set Converter adncnv Converts a file from one character set to another.
AD Merge Patch* admrgpch Merges multiple patches into a single merged patch.
AD Relink adrelink.sh Relinks Oracle E-Business Suite executable programs with the Oracle server product libraries.
AD Splicer adsplice Adds off-cycle products.
AD Job Timing Report   Reports a summary of the timing for jobs run by parallel workers.
AutoPatch* adpatch Applies patches and other system updates.
Patch Application Assistant* admsi.pl Generates customized installation instructions for a patch.
Rapid Install** rapidwiz Provides a wizard for entering parameters that are specific to a new installation or an upgrade of an Oracle E-Business Suite system.

*See Oracle E-Business Suite Patching Procedures for complete information about patches and patch utilities.

**The basic operation of Rapid Install is described here. See Oracle E-Business Suite Installation Guide: Using Rapid Install for complete instructions on using it to install or upgrade an Oracle E-Business Suite system.

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 fully in Oracle E-Business Suite Patching Procedures or Oracle E-Business Suite System Administrator’s Guide - Configuration.

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 AutoPatch and AD Administration maintenance sessions.

* See Oracle E-Business Suite System Administrator’s Guide.

** See Oracle E-Business Suite Patching Procedures.

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
ENABLE_MAINT_MODE               Enable Maintenance Mode
DISABLE_MAINT_MODE              Disable Maintenance Mode

Obtaining Help in OAM

OAM Help is available by clicking the Help link in the top right-hand section of any Oracle Applications Manager screen.

OAM Site Map and Help Link

the picture is described in the document text

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

OAM Site Map Help Page

the picture is described in the document text

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 Applications maintenance and reporting tasks from the command line. For example, you use AutoPatch 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.

Note: See Oracle E-Business Suite Maintenance Procedures for specific tasks performed using the AD utilities, and Oracle E-Business Suite Patching Procedures for information about AutoPatch and AD Merge Patch.

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.

Note: See Oracle E-Business Suite Patching Procedures for information about AD operations that apply to AutoPatch.

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, AutoPatch, 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 Oracle E-Business Suite Maintenance Procedures. See also Monitoring and Controlling Parallel Processes in this chapter.

Special Parameter for Using AutoPatch and AD Administration Non-Interactively

When running AutoPatch, 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. For AutoPatch, it is adpatch.log.

AD Administration (and AutoPatch) place their log files in the following locations:

UNIX:

$APPL_TOP/admin/<SID>/log

Windows:

%APPL_TOP%\admin\<SID>\log

Some utilities may not prompt you for a log file name: instead, they will write the log file in the directory from which the utility was run.

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 in Oracle E-Business Suite Concepts. See also My Oracle Support Knowledge Document 387859.1, Using AutoConfig to Manage System Configurations in Release 12.

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) (UNIX)
<CONTEXT_NAME>.cmd (Windows)
$INST_TOP/ora/10.1.3 Used to configure the environment when performing maintenance operations on the OracleAS 10.1.3 ORACLE_HOME.
<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 Named APPSORA in earlier releases, 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/ora/10.1.2 Called by APPS<CONTEXT_NAME>.env (UNIX) or APPS<CONTEXT_NAME>.cmd (Windows) to set up the OracleAS 10.1.2 ORACLE_HOME.
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 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 init.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 AutoPatch 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 AutoPatch, 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.

Note: For more information, see Applied Patches Information in Oracle E-Business Suite Patching Procedures.

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

the picture is described in the document text

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

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 AutoPatch 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 command line arguments are used by several utilities and are listed in the following table. Other arguments are used only by a specific utility. For example, AutoPatch makes extensive use of command line arguments and options that are unique to that utility. They are listed and discussed in Oracle E-Business Suite Patching Procedures.

AD Utility Command Line Arguments
abandon Description
Used by AD Administration, AutoPatch.
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, AutoPatch, 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, AutoPatch, 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, AutoPatch.
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, AutoPatch.
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, AutoPatch, 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, AutoPatch.
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, AutoPatch.
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 AutoPatch 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 AutoPatch.
flags=nologging affects indexes created through ODF only, not SQL scripts. The XDF utility always creates indexes with logging.
Example adpatch 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 Services.

Running AD Utilities

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 Oracle Installation and Upgrade Notes for any additional platform-specific steps.

  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 APPSCONTEXT_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 Additional Information: See Administer Concurrent Managers in Oracle E-Business Suite System Administrator’s Guide - Configuration.

  6. Enable Maintenance mode if the maintenance task requires system downtime.

    Note: For more information, see Using Maintenance Mode in Chapter 4.

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. AutoPatch, 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 Troubleshooting in Oracle E-Business Suite Maintenance Procedures 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:

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 AutoPatch to:

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 AutoPatch 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. See also Troubleshooting in Oracle E-Business Suite Maintenance Procedures.

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.

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 AutoPatch and AD Administration create their own log files.

Note: For more information, see Log and Output Filenames in Oracle E-Business Suite System Administrator’s Guide - Configuration.

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

The Troubleshooting chapter in Oracle E-Business Suite Maintenance Procedures 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 AutoPatch 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 AD Administration or AutoPatch.

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.

  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

    the picture is described in the document text

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

    Note: See Troubleshooting in Oracle E-Business Suite Maintenance Procedures 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 Oracle E-Business Suite Maintenance Procedures.

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 Preparing for Non-Interactive Processing in Chapter 4.

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 AD Administration or AutoPatch on the primary node, you 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, see Distributing Processing Tasks in Oracle E-Business Suite Maintenance Procedures.

OAM Web-Based Utilities

Oracle Applications Manager (OAM) is a Web-based management tool that allows you to use and access many maintenance utilities that were formerly available only on the command line, and makes it possible to quickly retrieve and display system-specific information in a GUI format. Each utility in OAM is accessed from a main page, which contains links to multiple layers of details that quickly put you in touch with all aspects of your system data. For example, using the Patch Wizard utility, you can access a downloaded list of recommended patches and view the effect on your file system of applying any or all of the patches.

In addition to reporting results based on specific search criteria, many OAM utilities can be used to enter and save changes to your system configuration. For example, using License Manager, you can register products that were not active in your initial installation. Or, with AutoConfig, you can view current configuration parameters and modify the existing values.

Note: For more information, see Chapter 7 of Oracle E-Business Suite Concepts.

Common OAM Operations

The OAM Web-based utilities are designed with the same look and feel, making extensive use of common operations such as uniform navigation tools and drill-down menus. For example, all pages present a Help link that opens a page-specific OAM help screen.

In addition, OAM utilities employ a powerful search feature, which displays the search results directly on the page where you initiated the search. There is no need to review log files or look in a file directory for the report. For example, using the Applied Patches utility, you can perform a simple search for all the patches that have been applied to your system. OAM displays the results on the Simple Search page.

The Applications Navigator and the OAM Dashboard and Site Map

You can access OAM functionality in several ways. You begin from the Navigator, which is the first page you encounter when you log in from the OAM Welcome page. After you choose from the list of responsibilities that define your role for using Oracle E-Business Suite, the Navigator presents a list of options under several headings, based on your Applications user role. For example, the System Administration role provides a path to the several groups of options, including the Oracle Applications Manager and related utilities.

The is the main OAM page. It provides a "snapshot" of your system activity and a drop-down list to provide quick access to some of the most commonly used OAM utilities and the OAM Site Map. In addition, it contains a link to the OAM Site Map, which displays links to all the OAM utilities, segregated on individual tabs by functionality.

Page Navigation

You navigate through OAM pages on the Dashboard and Site Map by clicking on a tab that displays a feature subset. On individual pages, you have navigation options, and, where appropriate, there are drop-down lists that provide links to related features. On pages with lengthy lists of items, OAM displays a subset of the items for easy access.

OAM Interface

The Oracle Applications Manager Dashboard presents a quick overview of the general status of your system. The Site Map provides access to all the utilities and features within the OAM framework.

Reviewing System Status

When you access the OAM Dashboard, you can see a general summary of your system activity.

OAM Dashboard

the picture is described in the document text

The OAM Dashboard serves as an HTML console, where system administrators can check the status of the database, concurrent managers and other services, concurrent requests, and Oracle Workflow processes, as well as view configuration information, such as initialization parameters and profile options.

The Dashboard is used in various ways, many of which are beyond the scope of this book. The Oracle E-Business Suite System Administrator’s Guide contains more complete information.

Accessing Maintenance Utilities

When you access the Dashboard, you can use the Navigate To: drop-down list for quick links. Open the list, make a selection, and click Go.

Navigating in OAM

the picture is described in the document text

Or, for a more complete list of all the utilities and features included in OAM, click the Site Map link.

OAM Site Map

the picture is described in the document text

The Site Map page displays tabs for Administration, Monitoring, Maintenance, and Diagnostics and Repair. On individual tabs, there are links to utilities or functions under general groups. For example, on this page there are headings for System Configuration, Application Services, Workflow, and so on. Under the Maintenance tab, there are headings for Patching Utilities and Critical Activities.

To open the main page for a utility, find it under one of the headings and click the link. For example, to view information about patches that have already been applied to your system, click Applied Patches under the Patching and Utilities heading on the Maintenance tab.

OAM Patching Features

the picture is described in the document text

Click any of the other tabs to access other functions. In this guide, all instructions for accessing OAM Web-based utilities start from the Site Map.

Accessing OAM

You can access the OAM Welcome page after logging into Oracle E-Business Suite via the following URL:

http:.//<server:port>/OA_HTML/AppsLogin

Oracle E-Business Suite Welcome Screen

the picture is described in the document text

Enter your user name and password, and click Login. The system redirects you to the Navigator page, which displays a navigation pane that lists user responsibilities. Click System Administration.

Oracle E-Business Suite Main Navigation Page

the picture is described in the document text

In the System Administration section, click Oracle Applications Manager to access the Dashboard. Alternatively, you can scroll down to the Oracle Applications Manager section, where the utilities are listed as separate links, and choose a utility (or the Dashboard) from that section.

All the information in the Oracle E-Business Suite maintenance documentation assumes that you will start from the Dashboard > Site Map. The individual utility screens discussed all relate to patching your Applications system. Their functionality is described fully in Oracle E-Business Suite Patching Procedures.