Introduction:

AutoConfig is the tool, which is used to configure oracle application systems. Its basically a perl script with a shell wrapper over it. At present there are more then 300 configuration files and environment files in application system. Whenever a change is made to any of the configuration parameter, the change needs to be propagated correctly to correct configuration and environment files. Managing such changes in such large number of files is really difficult.

Context File:

AutoConfig uses a file called context file, which is used to configure changes. Context file is a XML file having all the parameters of application system. These parameters are part of some configuration file for some services or it may be part of some environment file. When we create an application system (using Rapid install), context file gets created automatically will all the parameters and there values. Most of the parameters take default value, where as some parameters takes the value that is supplied at the time of installation.

Optionally we can create context file separately using adbldxml.sh/adbldxml.pl script. These scripts are present in $FND_TOP/bin directory. adbldxml.sh in turn runs oracle.apps.ad.context.GenerateContext java class.

Following is an example entry for the context variable “domainname” from the log file of adbldxml.pl run:

 [ s_domainname ]
SEVERITY         : INFO   
SOURCE SEARCHED  : Using System commands to get Domain name value   
SEARCH RESULTS   : Domainname could not be found using system commands.   
SOURCE SEARCHED  : Database table - GLOBAL_NAME   
SEARCH RESULTS   : Query on database table GLOBAL_NAME returned - XXXX.WORLD;  

                   Table is hosting incorrect value for domain.

SOURCE SEARCHED  : Prompting the user for the domain name.  
SEARCH RESULTS   : Value accepted from the user - its.yale.edu  
VALUE ASSIGNED   : its.yale.edu  
USER ACTION      : No action required           

The above entry shows the sources searched, search results for each search and the final assignment for the context variable domainname. As you can see adbldxml.pl provides the search information in great detail in its log file. This log file helps a lot in debugging adbldxml.pl behavior.

Each placeholder in the template file has a corresponding xml node (a context variable) in the context file. They all have a mandatory attribute called oa_var, the attribute value for this attribute is the placeholder name. Each node is primarily identified by the oa_var attribute value and can optionally have other attributes like oa_type, oa_enabled scope and default. The node’s only child is a text node, which stores the placeholder’s environment specific value. From here on I will refer to this text value as the “text value of the context variable”. The description of these context variables along with their oa_var value can be seen in adctxinf.tmp (stored in $AD_TOP/admin/template).

Context variables in the context file are organized in a hierarchical order, hence the choice of xml to store them. These context variables mainly lie under five top level parent nodes i.e. oa_system, oa_host, oa_install, oa_environments and oa_processes. Each top level parent node is further divided into further levels before you reach the real context variables.

To change any configuration option in the Oracle Applications environment, we need to change the value of corresponding context variable in the context file and then run autoconfig for our changes to take effect. For example if we need to change the web server port then we would change the text value of the context variable “webport” (oa_var value s_webport), and then run autoconfig. Since the context file is just an xml file, it can be updated in many ways. I will describe some of them later.

How it works:

Each configuration file has one (sometimes two, one for NT and one for UNIX) corresponding template file (provided by autoconfig patches, stored in $PROD_TOP/admin/template directory). Profile options and other instance specific information in the database is maintained by many sql scripts, called from wrapper shell/perl scripts. These scripts also have corresponding template files (also provided by autoconfig patches, `in $PROD_TOP/admin/templates). In these template files all the environment specific values are replaced by placeholders (like %s_webhost%).

Following entry in httpd.conf

Timeout 300 is replaced by following in its template $FND_TOP/admin/template/httpd_ux_ias1022.conf

Timeout %s_ohstimeout%

Environment specific values for this placeholder is stored in an environment specific xml file (called application context file) stored in $APPL_TOP/admin.

For e.g.

For the above placeholder the value stored in the xml file is:

<ohstimeout oa_var=”s_ohstimeout”>300</ohstimeout>

Each placeholder has a corresponding xml node in the context file. The placeholder name is the value for the “oa_var” attribute of the xml node, the placeholder name without the prefix “s_” (generally) is the node name for the xml node and the value is stored as a child text node. These xml nodes are termed as context variables by Oracle documentation and each node primarily is identified by its oa_var attribute value. So effectively we can say that in the above case we replace “300” by context variable “ohstimeout” whose oa_var value is “s_ohstimeout”.

Configuration files can be easily created from the template file by just replacing all the placeholders with the corresponding values from the context file. This process is termed as “instantiating the template” in Oracle documentation.

Driver files (stored in $PROD_TOP/admin/driver) store information about what to do with each template (e.g. instantiate it and replace the existing configuration file with it, instantiate it and run it). These files are named as <PROD_TOP>tmpl.drv (e.g. adtmpl.drv, fndtmpl.drv etc.) They contain one line for each template they manage.

When autoconfig (adconfig.pl or adconfig.sh) runs it just processes the driver file for each product, line by line doing what the driver file instructs it to do. The order of execution of each line is not sequential as we shall see later. The diagram below depicts the autoconfig functionality.

Editing context file:

1. Editcontext

Editcontext is a java application provided by oracle for updating the values in the context file. It is provided as a patch (patch: 2873456). Editcontext provides a list of all the updatable context variable values along with their titles. The title is not the variable name or value of oa_var attribute, but it is derived from adctxinf.xml, which comes with the editcontext patch and stores the title along with the oa_var value for each context variable. Editcontext only lists those context variables, which are listed in its repository (adxmlctx.tmp). If you find that, not all variables are listed, then the version of this file is probably lower than the adxmlctx.tmp stored in $AD_TOP/admin/template. In that case just copy this file from $AD_TOP/admn/template to the editcontext repository (i.e. <patch unzip directory>/editcontext/etc).

After launching editcontext, we have to find the context variable that we want to update. Once we find it, we can just change the value and save the new value to the context file (To be precise editcontext rewrites the whole context file instead of just updating one value). Since the list of context variables is quite long, it may take a while to find the desired context variable in the list.

2.      Oracle Applications Manager

Oracle Applications Manager is a web-based portal for managing Oracle Applications. Along with many other features, this product has a section for updating the context files. This product lists everything for each context variable i.e. name, oa_var attribute value, description, and real updateable value. Moreover instead of giving us a long list of context variables to search from, it divides the context file into many sections and each section is displayed in the xml tree format making it easier to find a particular context variable. It also provides us with the option of adding custom context variables (which we will look at in the customization section).

One thing to remember while updating context variables using OAM is that what it displays is gotten; by parsing the context file stored in fnd_oam_context_files table (Autoconfig at each run uploads the context file in this table). When we try to update the context file, OAM first update’s the status flag from ‘S’ to ‘H'(History) for our context file record, it then inserts another row for the same context file with status ‘S’. (OAM inserts another row instead of updating the existing row to maintain change history for each context file) It then requests the specific node’s FNDFS listener for updating the file on the file system (autoconfig uses the file on the file system). So we have to make sure that the FNDFS listeners are running on all the nodes before using OAM to update the context file.

With all the features of Oracle Applications Manager mentioned above, updating context files using Oracle Applications Manager seems to be the direction Oracle is trying to move.

3.      Scripted Update

EditContext and Oracle Application Manager are good for updating context file if you need to update one or two context variables. If you need to modify quite a few variables (for e.g. if you need to update all the ports in the context file) then using these GUI tools do become cumbersome. It would be nice to have a scripted way of updating lots of values in the context file using a data source of changes. I will describe two ways of achieving this using Oracle supplied code.

a. Java class oracle.apps.ad.context.UpdateContext

This java class allows us to change one context variable at a time from the command line. But we can easily use a shell/perl/python/tcl/etc script to call this class multiple times for different context variables based on a changes file, which stores all our required changes

For example let’s say we need to change the following context variables. The first column is the oa_var values of the context variable and the second column is desired value. These values are stored in a file changes.txt

 s_webport 7777
 s_webport_pls 9999
 s_oprocmgr_port 9997
 s_active_webport 9996
 s_forms_servlet_portrange 1801-1810
 s_oacore_servlet_portrange 2801-2810

The following perl script loops through each record in changes.txt and updates the context file by calling the java class once for each line. The syntax it uses to call this java class is:

java oracle.apps.ad.context.UpdateContext CONTEXT NAME VALUE

where

CONTEXT – Context File Name
NAME – context variable name
VALUE – Desired Changed value

b. Using Perl Module TXK::XML:

The above technique works well but it is quite heavy on resource consumption, since we start a new jvm for every update. For every update the java code has to parse the xml file, create the DOM tree, do the update in memory and then write it back to the file system. It would be more efficient if we could just parse the xml file only once and do all our updates before writing the xml file to the file system. This can be achieved by using oracle supplied perl module TXK::XML (Found in $AU_TOP/perl/TXK). For using TXK::XML we load the context file as as TXK::XML object, change the configuration option values by using setOAVar method ot the TXK::XML object and then write the file back to the file system. The only thing to take note of is setOAVar expects a hash reference as the input variable. This hash will contain the list of context variables to be changed in a key value pair; the key is the oa_var value of the context variable and the value is the corresponding desired values.

If we use any programmatic method to update the context file, we are not allowing OAM to maintain a change history for all our context files, which is very important since context file is the central repository for all the configuration options. This can be easily taken care by updating the existing record for our context file to status ‘H’ in fnd_oam_context_files table and then inserting the changed context file into the table using executable FNDCPUCF (in $FND_TOP/bin).

Since the context file is just an xml file, you can basically use any xml parser or write your own xml parser to do the updates, but in my experience the above mentioned methods has been the least error prone and least time consuming. Moreover in all of the above methods I am using Oracle’s code to update the xml file.

The Template Files

Template files are files, which are merged with the context file (instantiated) to produce configuration files or scripts to update the database. They are stored in <PROD_TOP>/admin/templates directory. Autoconfig patches/Technology stack patches install new templates or upgrade existing templates. Now let’s look at how these template files are created.

Let’s take a small configuration file REP60_<SID>.ora (Reports server configuration file):

mailprofile="$Header: REP60_server.ora 115.5 2004/03/24 01:10:51 njoseph ship $"
nlssupport=yes
maxconnect=20
cachedir="/u02/app/oracle/product/8.0.6/reports60/server/cache"
cachesize=50
minengine=5
maxengine=10
initengine=5
maxidle=30
security=1
englife=50   

If we replace all the environment specific values with context variables from the context file, then this is what we get:

mailprofile="$Header: REP60_server.ora 115.5 2004/03/24 01:10:51 njoseph ship $"
nlssupport=yes
maxconnect=20
cachedir="%s_tools_oh%/reports60/server/cache"
cachesize=50
minengine=%s_minengine%
maxengine=%s_maxengine%
initengine=0
maxidle=30
security=1
englife=50  

And now we have a template file corresponding to the Reports server configuration file. The placeholder values enclosed by “%” correspond to the context variable in the context file. If we instantiate this template using the values from the context file we can easily recreate our configuration file. All the configuration files and sql scripts are converted to templates in similar fashion and supplied to us by autoconfig patches.

The Driver Files

Driver files, as the name suggests drives what autoconfig does (stored in <PROD_TOP>/admin/driver). They are named as <PROD_TOP>tmpl.drv i.e. adtmpl.drv, fndtmpl.drv etc. Autoconfig patches install and update these driver files. Each driver file has one line for each template it manages. Each line tells autoconfig what to do with that template. This is achieved by using a particular syntax that conveys the relevant information to autoconfig. Following is the syntax for the lines in the driver files.

<PROD> <Location> < Name> <Action> <Dest directory> <Dest file name> <File permission>

 For e.g.
 ad admin/template adconfig.txt INSTE8 /admin     adconfig.txt      600

Column	Description
PROD	Product Name
Location	Directory underneath PROD_TOP where the template is located. Generally “admin/template”.
Name	Name of the template File
Action	Type of action to be performed on this template (Refer to the following table for description of different kinds of action)
Dest Directory	Destination directory of the instantiated template file. We can use context variables enclosed In “” to specify the destination directory. For example if we want to specify $APPL_TOP/admin as the destination directory we would specify it as “<at>/admin” in the driver file.
Dest file name	Destination configuration file name for the instantiated template file. We can use context variables enclosed in “” to specify the destination configuration file name. For example if the destination file has Database SID we can specify it as “<SID>.env” in the driver file.
File Permission	Autoconfig generates the configuration file with the provided unix style permission.

Actions:

Action	Description
INSTE8	Instantiate (replace context variables with values from xml context file) Copy the result to the <Dest directory>/<Dest file name> overwriting the existing configuration file, if one exists. Change the permission to <File permission>
INSTE8_SETUP	Instantiate (replace context variables with values from xml context file) Copy the result to the <Dest directory>/<Dest file name> overwriting the existing file, if one exists. Change the permission to <File permission> Execute the instantiated file.
INSTE8_APPLY	Instantiate (replace context variables with values from xml context file) Copy the result to the <Dest directory>/<Dest file name> overwriting the existing file, if one exists. Change the permission to <File permission> Execute the instantiated file.
INSTE8_PRF	Instantiate (replace context variables with values from xml context file) Copy the result to the <Dest directory>/<Dest file name> overwriting the existing file, if one exists. Change the permission to <File permission> Execute the instantiated file.
INSTALL	Instantiate the template file only if the resulting configuration file does not already exist.

Though the description of three of the actions is same, they are there to get different execution order within autoconfig’s execution of each driver file. The execution order in which autoconfig processes each line is INSTE8, INSTALL, INSTE8_SETUP, INSTE8_APPLY and INSTE8_PRF. These actions mark the different phases of autoconfig i.e. Setup phase, Apply phase and Profile phase. It’s also possible to run autoconfig only up to a particular phase.

The driver file syntax also supports if then else branching based on type of node (i.e. web, admin, forms etc), which is useful in a multi node installation. The syntax also supports the branching based on the platform type (Unix or Windows). This allows having multiple templates for each configuration file and instantiating a particular template based on the platform.

For e.g.
if platform NT
ad admin/template APPLSYS_nt.env INSTE8 .env 600
endif

or

if installation-type admin node nodedev forms formsdev web webdev
ad admin/template adconfig.txt INSTE8 /admin adconfig.txt 600
end if

The driver file syntax also supports including other driver files which are processed by autoconfig recursively

For e.g.
#include        fnd     admin/driver    fndtmpl.drv

When autoconfig (adconfig.pl or adconfig.sh) runs it just processes each product’s driver file respecting the, if then else branching as it processes the lines in the driver files. It also processes all included driver files recursively.