Introduction to Oracle E-Business Suite - Oracle EBS 12.2 File System Structure

Oracle EBS 12.2 File System Structure

The EBS 12.2 file system structure can be classified in two groups: the database tier file system and the application tier file system.

Database Tier File System

The database tier file system consists of a directory structure called Oracle Home , similar to a directory structure that comes after a standard database installation.

The EBS database tier file system structure is similar to a standard database file system structure, but they are not the same. The database tier in EBS has some additions on top of the standard database Home file system structure to support EBS-specific configurations.

The EBS database, when installed using the latest startCD, is delivered as an Enterprise Edition 12.1.0.2 64-bit Oracle Database patched with a list of the latest technology bug fixes required for Oracle E-Business Suite Release 12.2, as well as a set of recommended patches. Oracle Home contains the Oracle Database 12c products (12.1.0.2) delivered with the 12c examples CD, as well. Using a Real Application Cluster (RAC) for the database tier is also an option; it brings a multinode configuration ability to the database tier. Rapidwiz, which is the installation tool of EBS, has an optional Oracle RAC installation, too.

The big difference in an EBS Oracle Home is the existence of an appsutil directory. The appsutil directory inside an Oracle EBS Oracle RDBMS Home contains Perl scripts, bash scripts, SQL scripts, a Java runtime environment, JAR files, a clone directory, and a log directory for the use of application-specific database activities, such as database tier cloning and AutoConfig, as well as pure database-oriented activities such as starting/stopping database and the listener.

The appsutil directory comes with the installation, but it can be rebuilt if needed.

Rebuilding it is easy. To do that, you create an appsutil zip file in the application tier using application utilities designed for this purpose and then copy this zip file to the Oracle Home of the database with the proper file permissions, which lets the Oracle Database software owner use the scripts and all the other files contained in it.

Once the copying is done, you just unzip to extract the content of it. The content is actually the appsutil directory.

So, you have an appsutil directory in the database tier for supporting the EBS-specific database operations. We have mentioned the types of file stored in the appsutil directory. We’ll now cover them in detail.

The appsutil directory consists of several subdirectories and a context file, as listed next.

• Sql: Stores SQL scripts that can be used in apps DBA activities (such as adgrants.sql, which is used for granting necessary privileges on a selected SYS object to the APPS user).
• Java: Stores JAR files (xmlparserv2.jar) and classes (AutoConfigProcess.class, AutoConfigSynchronizer.class, and so on) for use by EBS-specific database utilities such as AutoConfig.
• Media: Contains four standard GIF files for use by Oracle applications, such as the Oracle log. This directory is not relevant to the database tier, but it is there for use by applications, just in case.
• Perl: Contains Perl modules such as AutoConfig.pm for use by TXK utilities such as TXKScript.pl, as well as modules such as Sysutil.pm for use by AD utilities such as adgentns.pl.
• Html: Contains XML and XSL files for use by AutoConfig-related Java classes such as AppltopDrivers.class.
• jre: Provides Java runtime environments for use by Java classes inside the appsutil directory.
• temp: Is a temporary folder for use by application utilities present inside the appsutil directory. This folder acts as temporary file storage. The utilities inside the appsutil directory are designed for placing their temp files within directories related to their core.

Note

txkEBSWrapper.pl sets its temp directory destination to $ORACLE_HOME/appsutil/temp/TXK.

• Clone: Stores the file adcrdb.zip, which contains the scripts adcrdb.sh and adcrdbclone.sql to re-create the control file and start up the database. These script files are used by rapid clone Java classes such as ApplyRmanDatabase.class while creating a clone database. Also, its subdirectory bin (clone/bin) is created by the preclone and stores the post clone-related Perl scripts. 
• Bin: Provides the bash and Perl scripts for application-specific database activities such as AutoConfig. These scripts are normally run by following the directions in the Oracle Support documents, and some of them are used internally, but it is still worth knowing what they’re for. The scripts and their definitions are as follows:
  • pl: This is an AutoConfig tool to generate the context file for the database’s Oracle Home.
  • sh/adchkcfg.cmd (for Windows): This runs the AutoConfig tool to test reconfiguration on the apps tier and the database tier.
  • sh: The checks the system for ld, ar, cc, and make.
  • pl: This is a Perl script that clones the context file.
  • pl: This runs the AutoConfig tool to clone applications.
  • sh: This is an obsoleted script for the same purpose as adclone.pl. It runs the AutoConfig tool to clone applications.
  • pl: This runs the AutoConfig tool to reconfigure the APPL_TOP directory and the database Oracle Home.
  • sh: This runs the AutoConfig tool to reconfigure APPL_TOP.
  • sh/adcustomizer.cmd (for Windows): This is an obsolete script that performs the task of migrating the customizations done by users to AutoConfig-generated files to the custom template. This script has been obsoleted in 12.2 because beginning-to-end customizations are not supported in Release 12.2.
  • sh/adcvm.cmd (for Windows): This manages changes in values of the context file because of changes in the template.
  • pl: This enables/disables password protection for the RDBMS password and changes the password of the already password-protected listener.
  • pl: This creates a database staging area for Rapidwiz, which is the installation tool of EBS.
  • pl: This script is used to generate the tnsnames.ora with all the necessary tns entries, dynamically.
  • sh/adtmplreport.cmd (for Windows): This is a wrapper script for running ATTemplateReport.java, which is a utility to list the template names and their target file names and locations.
  • pl: This displays the cause and action sections of ADX error messages. It uses $AD_TOP/html/adxmsg.xml or <RDBMS_ORACLE_HOME>/appsutil/html/adxmsg.xml as an ADX message repository.
  • pl: This script is used to generate the banner file txkDBSecUserAuditActionBanner.txt in the appsutil/template during an AutoConfig run in the database tier.
  • pl: This script is used to search for a keyword in all product top templates and generate a detailed report (text/HTML).
  • pl: This generates a health check report that contains current versions of the technologies installed, the latest version of the technologies installed, and recommendations, if necessary.
  • pl: This generates a report containing versions of various technology components in the Oracle applications tech stack.
  • pl: This is a simple wrapper script to create a TXK::Script object and run the supplied script.
  • pl: This is a simple wrapper script to create a TXK::Script object and run the supplied script. This script is similar to txkrun.pl, but it takes different arguments like a full path of the script to be executed and the logfile path. This script is generally used within txkInventory.pl for giving an output file to txkInventory.pl to write its report output.
• Admin: Stores some scripts that are transferred from the application tier. Certain patches provide action plans such as “copy the adgrants.sql from Application Server to Database Server and place it inside the $ORACLE_HOME/appsutil/admin directory and run it from there.”
• Out: Stores the output files. This is used for apps utilities in operations such as database cloning. Certain intermediate scripts and their logs that are generated during the cloning operations are placed here (such as restore-single2.rman and run_utlrp.sql).
• log: Stores log files generated during the executions of utilities. An example is the adconfig.log file, which provides the logs generated during an AutoConfig run.
• Template: Stores AutoConfig template files, which are the sources for creating site-specific configuration files. AutoConfig reads the context file and creates the final configuration files by filling these template files with the values it gets from the context file.
• Scripts: Contains scripts for executing AutoConfig, executing preclone, and stopping and starting the database and the listener.
  • sh: This is a script for executing an AutoConfig. It is a wrapper for executing adconfig.sh stored in $ORACLE_HOME/appsutil/bin directory. adconfig.sh in turn calls the adconfig.pl Perl script, which does the actual job.
  • pl: This checks for the existence of the RDBMS $ORACLE_HOME/nls/data/9idata directory and the cr9idata.pl file in that directory.
  • sh: This is a script for starting and stopping the database.
  • sh: This is a script for starting and stopping the database listener.
  • pl: This executes all SQL scripts that update the profiles in an AutoConfig run.
  • sh: This is a wrapper on lsnodes to check whether the cluster manager is available in a RAC environment.
  • pl: This is a Perl script that runs the source system cloning preparation.
  • sql: This is used by addbctl.sh to stop the database.
  • sql: This is used by addbctl.sh to start the database.
• Outbound: Stores file created from inside the database. It is pointed at by the database directory named APPS_DATA_FILE_DIR. It is used as a directory for storing the files created by extracting the data from the database.
• Install: Stores various scripts for EBS-specific database activities such as cleaning the concurrent manager’s queues, creating database directories, and setting some database-related EBS profile options.
• In addition to the appsutil directory, there are two special files in the database tier: the context file and the environment file.
• Context file: The context file is an XML file that stores the inputs mostly used while configuring the EBS system using the autoconfig tool. Its name is in the form of <s_systemname>_<s_hostname>.xml. The context file is used by AutoConfig to make the necessary system-wide configurations for the tier where it is executed. So, it can be considered an input file for the AutoConfig utility. Like the application tier, the context file is also used in the database tier. The context file in the database tier includes configurations for the EBS database. As, various configurations such as the listener port, the domain name can be done using AutoConfig, there are XML tags associated with the configuration of them in the context file.
• Environment file: The environment file is stored in the $ORACLE_HOME directory and used for setting the environment variables for managing EBS’s Oracle database tier from the operating system. Once this file is sourced, you can do the database activities using the environment variables such as ORACLE_HOME, TNS_ADMIN, and so on. Its name is in the form of <s_systemname>_<s_hostname>.env.

So, as shown, the database tier of EBS consists of a standard Oracle RDBMS Home that has some EBS-related additions/utilities on it. EBS-specific utilities bring a need for competence in managing the EBS database stack, as these utilities are used for critical operations. A problem or a misconfiguration in this layer can break down the application tier connections as they rely on apps-specific configurations inside the database. In addition, this adds a new level on top of standard database administration and makes things a little hard. On the other hand, the good news is that once you know what to do and understand the logic, these apps-specific additions (explained earlier) inside the database home make it almost automatic to manage the EBS database.

Well, then, we have explained the database tier file system structure and given the necessary details where needed. Let’s continue with the application file system structure.

Application Tier File System

The root directory of the EBS 12.2 application tier file system is called the base directory. The directory structure branches out from the base directory. The base directory is specified during the installation, and the branches are derived from the base directory.

Just under the base directory, there are three directories named fs1, fs2, and fs_ne and one file called EBSapps.env.

EBSapps.env is the environment file for EBS 12.2. It is EBS 12.2 file system aware and is used by apps DBAs to set the environment for EBS 12.2. EBSapps.env knows the dual file system architecture used in EBS 12.2 and sets the appropriate environment accordingly. That is, when it is executed with the “run” argument, it sets the run time (active file system) environment, and when it is executed with the “patch” argument, it sets the patch environment with all the environment variables pointing to the patch file system directories and files. We will explain the run and patch file system later in this article, but let’s take a quick look now.

The fs acronym is used for referring to the file system, and the numbers denote file system 1, file system 2, and a noneditioned file system. This fs-based file system architecture was introduced in EBS 12.2, and these file system directories, together called a dual file system, are the result of implementing an online patching mechanism. In the online patching mechanism, which is a new feature of EBS 12.2, these file system directories are used to store both the active and patched files in a different directory structure. That is, the fs1 and fs2 directories are used for storing the active (run) file system and patch file system in their subfolders. Thus, they are enabling an environment that can be switched from active to patch and from patch to active. Besides, these directories are switching their roles.

For example, suppose fs1 is the active, and suppose fs2 is the patch file system at time t0; then suppose the apps DBA applies a patch at time t1 and as a result of this patch initiates a cutover operation, which switches the file system from active to patch and from patch to active. So, at time t2, fs2 becomes the active (run), and fs1 becomes the patch file system.

In addition to these active and patch file systems, there is an fs_ne directory just under the base directory.

The directory fs_ne is a noneditioned file system for storing the noneditioned file system objects. Noneditioned here means the fixed files such as concurrent processing log files, adop log files, patch files, and adop wrapper script, which are not changed by any patching operations.

Figure 6 shows the run edition, patch edition, and noneditioned filesystems by providing the top-level directories named fs1, fs2, and fs_ne with their main subdirectories, which store the files that EBS application tier services rely on.

Figure 6. EBS 12.2 dual filesystem and noneditioned filesystem directories: fs1, fs2, and fs_ne

The following environment variables can be used to retrive to full directory paths of fs1, fs2, and fs_ne directories;

• NE_BASE is the environment variable which is set to the full path of the non-editioned file system (fs_ne).
• PATCH_BASE is the environment variable which is set to the full path of the current patch file system (fs1 or fs2, whichever is the patch file system at that time).
• RUN_BASE is the environment variable which is set to the full path of the current run file system (fs1 or fs2, whichever is the run file system at that time).

Under the fs1 and fs2 directories, there are three important top-level directories in an EBS 12.2 application file system structure.

These directories are inst (instance home), EBSapps, and the Fusion Middleware Home (FMW_Home).

The inst directory, also called instance home and pointed at by the $INST_TOP environment variable, contains most of the configuration files created by AutoConfig, configuration files for Oracle Application Server 10.1.3 (which is used by form and reports), and the other files such as forms log files (in the subdirectory pointed by $LOG_HOME), application services start/stop script logs (pointed at by ADMIN_SCRIPTS_HOME environment variable), 10.1.2 make logs, application listener log file, reports cache files, oam diagnostic files, and the context file for the use of AutoConfig.

Figure 7 shows the directory structure of the inst directory and its subdirectories.

Figure 7. Structure of the inst directory ($INST_TOP )

The EBSapps directory is one of the directories in the base directory and at the same level with the instance home directory.

EBSapps consists of three subdirectories. These directories are the appl directory, which is pointed at by the $APPL_TOP environment variable; the common directory, which is pointed at by the $COMMON_TOP environment variable; and the 10.1.2 directory, which is pointed at by the $ORACLE_HOME environment variable.

The appl directory, also known as applications top (APPL_TOP), stores core technology directories, all the product directories, the main EBS environment file (which is in the form of <s_systemname>_<s_hostname>.env and <s_systemname>_<s_hostname>.cmd for Windows), and the consolidated env file in the form of APPS<s_systemname>_<s_hostname>.env and APPS<s_systemname>_hostname.cmd for Windows.

Environment files are for setting the APPS-related environment variables for the executing shells. The APPS<s_systemname>_<s_hostname>.env file is used for setting both the Oracle E-Business Suite and Oracle technology stack environments, whereas the <s_systemname>_<s_hostname>.env file sets the environment for applications only.

That is, the environment file named in the form of <s_systemname>_<s_hostname>.env does not set the environment variable for 10.1.2 Oracle Home that is used by forms and reports.

There are four different environment files for setting the shell environments in EBS 12.2, and each environment file is used for setting a different environment for administrating a different set of Oracle technology products.

Table 7 lists the environment files present in EBS 12.2 and gives information about what they are used for.

Table 7. EBS 12.2 Environment Files

As mentioned earlier, the appl directory consists of several subdirectories, such as the admin directory that stores the adovars.env file to set the location of various files such as Java files, HTML files, and JRE files. The admin directory under the appl directory contains upgrade-related files for all products.

Besides, the appl directory stores several subdirectories for storing the product files.

For every product, there is a subdirectory named with the associated product’s short name. These product directories are used for storing product-specific files and pointed at by the environment variables named with the form <PROD>_Top. <PROD>_Top points to the 12.0.0 directory, which is stored in the product directory. In every product directory, there is a subdirectory named with the release number, which is defined as 12.0.0 for EBS 12.2.

To understand it better, let’s take a look at an example. For example, for General Ledger product files, the gl directory inside the appl directory is used. Thus, the environment variable GL_TOP points to the gl/12.0.0 directory, which resides in the appl directory.

This makes GL_TOP to be $APPL_TOP/gl/12.0.0, and all the GL files are stored there.

Thus, <PROD_TOP> becomes $APPL_TOP/<Product_shortname>/12.0.0.

Figure 8 shows the directory structure of the appl directory, which is pointed at by the APPL_TOP environment variable in a general manner.

Figure 8. APPL_TOP/appl directory structure

As shown in Figure 8, all the product directories contain subdirectories.

In most of the product directories, there are directories named admin, bin, forms, help, html, java, lib, log, mds, media, mesg, out, patch, reports, and sql.

The following list summarizes these subdirectories with the type of files stored in them.

• admin: Contains product-specific files used to upgrade the associated product. This is in distinction to the following.
• driver: Contains driver files (.drv files) to be used in an upgrade.
• import: Contains DataMerge files to be used in seed data upgrades.
• odf: Contains object description files (.odf files) used to create database objects.
• sql: Contains SQL scripts for upgrading and concurrent processing, as well as PLSQL scripts for creating PLsql objects/PL/SQL stored procedures.
• bin: Contains concurrent programs, C programs, and shell scripts.
• forms: Contains Oracle Forms runtime (.fmx) files to be executed by the forms engine. These forms files are stored in subdirectories according to their languages, for example, US to store American English forms.
• help: Contains the online help source files.
• html: Contains HTML, JavaScript, and JSP for HTML-based applications.
• include: Contains C language header files to be linked with the library files stored in the lib directory.
• java: Contains JAR files and Java dependency files. Copies of these JAR files are also located in the directory pointed at by the $AF_JLIB environment variable.
• lib: Contains object files (.o files for UNIX and .obj files for Windows), library files (.a for UNIX and .DLL for Windows), and make files (.mk). These files are used to relink concurrent programs with the Oracle-supplied libraries.
• log: Contains log files for concurrent requests and concurrent managers.
• media: Contains GIF files used to display text and graphics on the desktop tier.
• mesg: Contains message files (msb) to be used by EBS to display messages at the bottom of the forms screens.
• patch: Contains patch files to the data or data model.
• reports: Contains report binary files (rdf). These report files are stored in subdirectories according to their languages, for example, US to store American English Reports.
• resource: Contains PLSQL library files (PLL). These PLL files are later copied to.

Before continuing with the common directory, we want to include some specific information about three subdirectories of the appl directory. That is, there are three important subdirectories inside the appl directory: the ad, au, and fnd directories.

The ad directory is the directory for the AD (Applications DBA product), and it stores the ad utilities such as adadmin and AutoConfig. The au directory is pointed at by AU_TOP, and its name comes from the application utilities.

AU_TOP contains important files such as PL/SQL libraries used by Oracle Forms, forms source files, a copy of all Java files used when regenerating the desktop client JAR, and certain reports needed by products such as Discoverer.

FND is short for Foundation, and the fnd directory pointed by FND_TOP contains important files for building data dictionaries, forms, and C object libraries.

The common directory is also known as COMMON TOP and pointed at by the COMMON_TOP environment variable; it stores files that can be used by several EBS products and even third-party tools. It is called common because it stores the common files such as Java classes, HTML pages, and other files and directories used by multiple products.

Figure 9 represents the COMMON TOP directory structure with all the main subdirectories of it.

Figure 9. Structure of COMMON_TOP/comn directory

The last subdirectory in the EBSapps directory is 10.1.2, and it is pointed at by the $ORACLE_HOME environment variable. As you can probably guess because of its associated environment variable’s name, it is a 10.1.2 Oracle Home, which provides an environment for the server-side 10g forms and report binaries to run properly.

Executables such frmweb, which is the server-side forms process, and rwrun (reports binary) are started from this directory. The application listener, which is used for the FNDFS and FNDSM connections, is also started from this directory.

The Fusion Middleware Home (FMW_Home ) directory consists of the Fusion Middleware components and is pointed at by the $FMW_HOME environment variable. The most important component in this Oracle Home is WebLogic Server, which is the main application server used by the core application services.

There are subdirectories in FMW_Home such as user_projects, wls_10.3, utils, oracle_common, webtier, modules, and Oracle_EBS-appl, as shown in Figure 10.

Figure 10. FMW_Home($FMW_HOME) directory structure

Figure 10 represents the FMW_Home directory and its subdirectories. The subdirectories in the FMW_HOME directory are as follows.

The user_projects directory is a classic directory that is present in every WebLogic-related application environment. It contains the WebLogic domain directory named EBS_domain_<s_systemname> used by EBS application services. This directory is used to deploy Oracle E-Business Suite. EBS_domain_<s_systemname> inside the user_projects directory stores all the configuration and log files related to the EBS domain.

Moreover, all the WebLogic-related environment files and start/stop/control scripts such as setDomain.env and startWebLogic.sh are normally stored in the FMW directory.

• The Wls_10.3 directory is the actual WebLogic server directory. It contains all the binaries and libraries used by WebLogic Server 10.3.6, which comes built in to EBS 12.2.
• The Utils directory contains FMW utilities, such as bsu (Smart Update), which is the patching tool for WebLogic Server.
• The Oracle_common directory contains the JRF files used by Oracle EBS. A JDK comes deployed under this directory, as well.
• The Webtier directory contains all the configuration and log files used by Oracle HTTP Server. Oracle HTTP Server started from this directory, namely, from the ohs subdirectory (webtier/ohs/bin/). In addition, opmn (Oracle Process Manager) for managing the OHS server is stored in here. In addition, this directory has its own JDK stored in its subdirectory named jdk.
• The modules directory contains WebLogic modules, which are presented as JAR files. It also contains applications such as Apache ant, which supplies operations such as compiling, assembling, testing, and running Java applications.
• The last Fusion Middleware directory in the list is the Oracle_EBS-appl directory, which contains the Oracle EBS WebLogic components and the core technology components, which are forms, forms-c4ws, oacore, and oafm. So, they are deployed into this directory. Thus, WebLogic Server inside EBS runs them as applications from this directory. Normally, there is a JDK stored in this Oracle Home. In addition, all the configuration files of these EBS WebLogic components/applications are stored in the Oracle_EBS-appl directory.

You have now seen the main directories in the EBS file system structure. We have gone through the main directories and described their contents. You have seen the important EBS directories, and we have listed their contents with the names and content types of their important subdirectories. Although EBS’s directory structure is a complex one, you have seen the environment variables to reach the desired locations in the directory structure easily.

Important environment variables in this context are listed here:

• IAS_ORACLE_HOME: FMW web tier home directory.
• ORACLE_HOME: 10.1.2 Oracle Home used for forms and reports.
• CONTEXT_FILE: The context file used by the AutoConfig utility. AutoConfig uses it as an input for configuring the EBS system.
• EBS_DOMAIN_HOME: WebLogic domain in where EBS WebLogic deployments are stored.
• ADMIN_SCRIPTS_HOME: Shell scripts for starting/stopping/controlling EBS services.
• EBS_ORACLE_HOME: EBS WebLogic components/applications are stored in this Oracle_EBS-appl directory.
• RW: Oracle Reports directory.
• APPS_VERSION: Returns the EBS version.
• NE_BASE: Nonedition file system base directory.
• APPL_TOP_NE: The appl directory in the nonedition file system.
• RUN_BASE: The run file system directory.
• PATCH_BASE: The patch file system directory.
• APPL_TOP: The appl directory stores core technology directories, all the product directories, and the main EBS environment file.
• COMMON_TOP: The common directory stores files that may be used by several EBS products and even third-party tools.

In addition, you have learned about the EBSapps.env script for setting these environment variables automatically.

When sourced, EBSapps.env sets more than 300 environment variables and thus eases the apps DBA’s work. After connecting to the system using the application owner operating system user and executing EBSapp.env, you can start using these environment variables immediately.

As EBS 12.2 has a dual file system architecture, EBSapps.env is executed by an argument specifying the edition type. When executed with the “run” argument, EBSapps.env sets the environment variable according to the run edition file system. As you may imagine, when executed with the “patch” argument, EBSapps.env sets the environment variable according to the patch edition file system.

Following is an example for setting the run edition environment.

. EBSapps.env run

  E-Business Suite Environment Information

  ----------------------------------------

  RUN File System : /u01/install/APPS/fs2/EBSapps/appl

  PATCH File System : /u01/install/APPS/fs1/EBSapps/appl
  Non-Edition File System: /u01/install/APPS/fs_ne
  DB Host: ermanhost.ermandomain.com Service/SID: ORATEST


Sourcing the RUN File System


. EBSapps.env patch


  E-Business Suite Environment Information

  ----------------------------------------
  RUN File System           : /u01/install/APPS/fs2/EBSapps/appl
  PATCH File System         : /u01/install/APPS/fs1/EBSapps/appl
  Non-Editioned File System: /u01/install/APPS/fs_ne
  DB Host: ermanhost.ermandomain.com Service/SID: ORATEST

Sourcing the PATCH File System

Having a general knowledge about the directory structure is important, but memorizing all the directories inside this huge directory structure is unnecessary because the environment variables do this job.

Later in my blog, we will expand on all the information provided in this article by providing practical examples such as installation, upgrade, patching, and so on. Lastly in this blog, we will look at the technological differences between the major EBS releases.