2
Installation and Configuration

This chapter describes installation and configuration of the Database adapter. The following topics are discussed:

• Installing the Database Adapter

• Configuring the Database Adapter

Installing the Database Adapter

This section contains these topics:

• Preinstallation Tasks

• Installation Tasks

• Post-Installation Steps

• Verification Test

Preinstallation Tasks

The Database adapter must be installed in one of the following Oracle homes:

• An existing OracleAS InterConnect Oracle home for 10g (9.0.4).

• A new Oracle home (the installer creates this for you)

Consult the following guides before proceeding with Database adapter installation:

• Oracle Application Server Installation Guide, which includes information on:
  • Oracle Universal Installer startup

• Oracle Application Server InterConnect Installation Guide, which includes information on:
  • CD-ROM mounting

  • OracleAS InterConnect software, hardware, and system requirements

  • OracleAS InterConnect installation

    Note: OracleAS InterConnect Hub is installable through the OracleAS InterConnect Hub installation type. You must install the OracleAS InterConnect Hub before proceeding with the Database adapter installation.

Installation Tasks

To install the Database adapter, start the installer and complete the following steps:

1. On the Available Product Components page of the OracleAS InterConnect installation, select Database adapter, then select Next.

   Consider the following scenarios:

   • If installing the Database adapter in an independent Oracle home, make sure that the OracleAS InterConnect Hub has been installed, not necessarily in the same Oracle home. Continue to step 2.

   • If installing the Database adapter in an existing Oracle home, make sure that it is a home directory to one of the OracleAS InterConnect component. Continue to step 3.

     Note: The hub database information, such as the SID, host, port, and username/password from the Hub installation, is needed for step 2.

2. If installing OracleAS InterConnect for the first time on this machine, complete the following steps to enter the hub database information:
   1. On the Welcome page, select Next. The Database Configuration page displays. Enter information in the following fields:
      • Host Name--The host name of the machine where the hub database is installed.

      • Port Number--The TNS listener port for the hub database.

      • Database SID--The SID for the hub database.

   2. Click Next. The Database User Configuration page displays. Enter information in the following fields:
      • User Name--The hub database user name. Make sure the OracleAS InterConnect Hub is installed. If the Hub is not installed, complete the installation and note the user name and password.

      • Password--The password for the hub database user.

3. Click Next. The Adapter Configuration page displays. Enter the application to be defined or already defined in iStudio in the Application Name field. White spaces or blank spaces are not permitted. The default value is myDBApp.

4. Select Next. The Spoke Application Database Configuration page displays. Enter information in the following fields:
   • Host Name--The name of the machine where the application database is installed.

   • Port Number--The database TNS listener port.

   • Database SID--The SID for the application database.

   The information on this page is for the database on the application side from which the adapter will put or receive messages. This is not the information for the hub database.

5. Select Next. The Spoke Application Database User Name page displays. Enter information in the following fields:
   • User Name--The name the Database adapter uses to connect to the database.

   • Password--The password for the user name.

6. Select Next. Complete the fields for any other components selected for installation, such as other adapters. When finished, the Summary page displays.

7. Select Install to install the Database adapter and other selected components. The Database adapter is installed in the following directory:

   Platform	Directory
   Windows	ORACLE_HOME\oai\9.0.4\adapters\Application
   UNIX	ORACLE_HOME/oai/9.0.4/adapters/Application

   Application is the value you specified in Step 3 .

Post-Installation Steps

After installation a set of post-installation steps displays. These steps are also copied to the post-installation.txt file in the Database adapter directory.

Note: The default sys password is change_on_install unless otherwise specified during installation.

To create the schema used by the Database adapter, complete the following tasks:

1. Access the directory where the Database adapter is installed.

2. Execute the following for the correct database version:

   Database Version	Code to Execute
   Oracle7.x	oaischema -create -pre8i sys/[password] [tnsname]
   Oracle8i	oaischema -create -8i sys/[password] [tnsname]
   Oracle9i	oaischema -create sys/[password] [tnsname]

   where:

   • Password--The password for the system user.

   • tnsname--The tnsname for the spoke database.

Verification Test

When completing the post-installation steps, no errors should occur. If there are errors, verify that the application using the oai schema in the specified database is the only occurrence. Errors can occur if a Database adapter from previous version installation is talking to this same database.

Configuring the Database Adapter

Table 2-2, Table 2-3, and Table 2-4 describe executable files, configuration files and directories. These files and directories are accessible from the directory shown in Table 2-1:

Table 2-1 Database Adapter Adapter Directory

Platform	Directory
UNIX	ORACLE_HOME/oai/9.0.4/adapters/Application
Windows	ORACLE_HOME\oai\9.0.4\adapters\Application

Table 2-2 Executable Files

File	Description
start.bat (Windows)	Takes no parameters, starts the adapter.
start (UNIX)	Takes no parameters, starts the adapter.
stop.bat (Windows)	Takes no parameters; stops the adapter.
stop (UNIX)	Takes no parameters; stops the adapter.
ignoreErrors.bat (Windows)	If an argument is specified, then the given error code will be ignored. If no argument is specified, than all error codes specified in the ErrorCodes.ini will be ignored.
ignoreErrors (UNIX)	If an argument is specified, then the given error code will be ignored. If no argument is specified, than all error codes specified in the ErrorCodes.ini will be ignored.

Table 2-3 Configuration Files

File	Description
ErrorCodes.ini (Windows and UNIX)	Contains one error code per line.
adapter.ini (Windows and UNIX)	Consists of all the initialization parameters which the adapter reads at startup.

Table 2-4 Directories

File	Description
persistence	The messages are persisted in this directory. Do not edit this directory or its files.
logs	The logging of adapter activity is done in subdirectories of the logs directory. Each new run of the adapter creates a new subdirectory in which logging is done in an oailog.txt file.

Using the Application Parameter

Adapters do not have integration logic. The Database adapter has a generic transformation engine that processes metadata from the repository as runtime instructions to do transformations. The application defines for an adapter what its capabilities are. For example, it can define what messages it can publish, what messages it can subscribe to, and what are the transformations to perform. The application parameter allows the adapter to become smart in the context of the application to which it is connected. It allows the adapter to retrieve from the repository only that metadata that is relevant to the application. The application parameter must match the corresponding application that will be defined in iStudio under the Applications folder.

If you are using pre-packaged metadata, after importing the pre-packaged metadata into the repository, start up iStudio to find the corresponding application (under the Applications folder in iStudio) to use as the application for the adapter you are installing (unless the package you are using provides directions for what the application should be).

Ini File Settings

The following .ini files are used in configuring the Database adapter.

• hub.ini

• adapter.ini

hub.ini Parameters

The Database adapter connects to the hub database using parameters from the hub.ini file located in the hub directory. Table 2-5 lists the parameter name, description, the possible and default values, and example for each parameter

Table 2-5 Hub.ini Parameters

Parameter	Description	Example
hub_username	The name of the hub database schema (or username). The default value is oaihub904.	hub_username=oaihub904
hub_password	The password for the hub database user. There is no default value. You input the hub_password value during installation	hub_password=manager
hub_host	The name of the machine hosting the hub database. There is no default value. You input the hub_host value during installation.	hub_host=mpjoshipc
hub_instance	The valid SID of the hub database. There is no default value. You input the hub_instance value during installation.	hub_instance=orcl
hub_port	The TNS listener port number for the HUB database instance. There is no default value. You input the hub_port value during installation.	hub_port=1521
repository_name	The valid name of the repository this adapter talks to. The default value is InterConnectRepository.	repository_name=InterConnectRepository

RAC-specific hub.ini Parameters

When a hub is installed on a Real Application Cluster (RAC) database, parameters listed in Table 2-6 represent information on additional nodes used for connection and configuration. These parameters are added on top of the default parameters which represent the primary node. In Table 2-6, x represent the node number, which varies between 2 and the number of nodes. For example, if the RAC setup contains 4 nodes, x can take a value between 2 and 4.

Table 2-6 RAC-specific Hub.ini Parameters

Parameter	Description	Example
hub_num_nodes	Number of nodes in Real Application Clusters.	hub_num_nodes=4
hub_hostx	The host where the Real Application Clusters database is installed.	hub_host2=dsunram13
hub_instancex	The instance on the respective node.	hub_instance2=orcl2
hub_portx	The port on which the listener is listening.	hub_port2=1521

adapter.ini Parameters

The Database adapter connects to the spoke application using parameters from the adapter.ini file. Table 2-7 lists the parameter name, description, the possible and default values, and example for each parameter.

Table 2-7 Adapter.ini Parameters

Parameter	Description	Example
application	The name of the application this adapter connects to. This must match with the name specified in iStudio during creating of metadata. Any alphanumeric string can be used. There is no default value.	application=dbapp
partition	The partition this adapter handles as specified in iStudio. Any alphanumeric string is a possible value. There is no default value.	partition=germany
instance_number	To have multiple adapter instances for the given application with the given partition, each adapter should have a unique instance number. Possible values are any integer greater than 1. There is no default value.	instance_number=1
agent_log_level	Specifies the amount of logging necessary. Possible values are: 0=errors only 1=status and errors 2=trace, status, and errors The default value is 1.	agent_log_level=2
agent_subscriber_name	The subscriber name used when this adapter registers its subscription. The possible value is a valid Oracle Advanced Queuing subscriber name and there is no default value.	agent_subscriber_name=dbapp
agent_message_selector	Specifies conditions for message selection when registering its subscription with the hub. The possible value is a valid Oracle Advanced Queuing message selector string. There is no default value.	agent_message_selector=recipient_list like '%,dbapp,%'
agent_reply_subscriber_name	The subscriber name used when multiple adapter instances for the given application with the given partition are used. Optional if there is only one instance running. The possible value is application name (parameter: application) concatenated with instance number (parameter: instance_number). There is no default value.	If application=dbapp, instance_number=2, then, agent_reply_subscriber_name=dbapp2
agent_reply_message_selector	Used only if multiple adapter instances for the given application with the given partition. The possible value is a string built using concatenating application name (parameter:application) with instance number (parameter:instance_number). There is no default value.	If application=dbapp, instance_number=2, then agent_reply_message_selector=receipient_list like'%,dbapp2,%'
agent_tracking_enabled	Specifies if message tracking is enabled. Set to false to turn off all tracking of messages. Set to true to track messages with tracking fields set in iStudio. Possible values are true or false. The default value is true.	agent_tracking_enabled=true
agent_throughput_measurement_enabled	Specifies if throughput measurement is enabled. Set to true to turn on all throughput measurements. Possible values are true or false. The default value is true.	agent_throughput_measurement_enabled=true
agent_use_custom_hub_dtd	Specifies if a custom DTD should be used for the common view message when handing it to the hub. By default adapters use an OracleAS InterConnect-specific DTD for all messages sent to the hub as other OracleAS InterConnect adapters will be retrieving the messages from the hub and know how to interpret them. Set to true if for every message, the DTD imported for the message of the common view is to be used instead of the OracleAS InterConnect DTD. Only set to true if a OracleAS InterConnect adapter is not receiving the messages from the hub. Possible values are true or false. There is no default value.	agent_use_custom_hub_dtd=false
agent_metadata_caching	Specifies the metadata caching algorithm. Possible values are: startup--Cache everything at startup. This may take a while if there are a lot of tables in the repository. demand--Cache metadata as it is used. none--No caching. This slows down performance. The default value is demand.	agent_metadata_caching=demand
agent_dvm_table_caching	Specifies the domain value mapping (DVM) table caching algorithm. Possible values are: startup--Cache all DVM tables at startup. This may take a while if there are a lot of tables in the repository. demand--Cache tables as they are used. none--No caching. This slows down performance. The default value is demand.	agent_dvm_table_caching=demand
agent_lookup_table_caching	Specifies the lookup table caching algorithm. Possible values are: startup--Cache all lookup tables at startup. This may take a while if there are a lot of tables in the repository. demand--Cache tables as they are used. none--No caching. This slows down performance. The default value is demand.	agent_lookup_table_caching=demand
agent_delete_file_cache_at_startup	With any of the agent caching methods enabled, metadata from the repository is cached locally on the file system. Set this parameter to true to delete all cached metadata on startup. Note: After changing metadata or DVM tables for this adapter in iStudio, you must delete the cache to guarantee access to the new metadata or table information. Possible values are true or false. The default value is false.	agent_delete_file_cache_at_startup=false
agent_max_ao_cache_size	Specifies the maximum number of application objects' metadata to cache. Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_ao_cache_size=200
agent_max_co_cache_size	Specifies the maximum number of common objects' metadata to cache. Possible values are any integer greater than or equal to 1. The default value is 100.	agent_max_co_cache_size=100
agent_max_message_metadata_cache_size	Specifies the maximum number of messages' metadata to cache (publish/subscribe and invoke/implement). Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_message_metadata_cache_size=200
agent_max_dvm_table_cache_size	Specifies the maximum number of DVM tables to cache. Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_dvm_table_cache_size=200
agent_max_lookup_table_cache_size	Specifies the maximum number of lookup tables to cache. Possible values are any integer greater than or equal to 1. The default value is 200.	agent_max_lookup_table_cache_size=200
agent_max_queue_size	Specifies the maximum size that internal OracleAS InterConnect message queues can grow. Possible values are any integer greater than or equal to 1. The default value is 1000.	agent_max_queue_size=1000
agent_persistence_queue_size	Specifies the maximum size that internal OracleAS InterConnect persistence queues can grow. Possible values are any integer greater than or equal to 1. The default value is 1000.	agent_persistence_queue_size=1000
agent_persistence_cleanup_interval	Specifies how often the persistence cleaner thread should run. Possible values are any integer greater than or equal to 30000 milliseconds. The default value is 60000.	agent_persistence_cleanup_interval=60000
agent_persistence_retry_interval	Specifies how often the persistence thread should retry when it fails to push a OracleAS InterConnect message. Possible values are any integer greater than or equal to 60000 milliseconds. The default value is 60000.	agent_persistence_retry_interval=60000
agent_pipeline_to_hub	Specifies how to turn on or off the pipeline for messages from the Bridge towards the hub. If you set the pipeline to false, the file persistence is not used in that direction.	agent_pipeline_to_hub=false
agent_pipeline_from_hub	Specifies how to turn on or off the pipeline for messages from the hub towards the Bridge. If you set the pipeline to false, the file persistence is not used in that direction.	agent_pipeline_from_hub=false
service_path	Windows only. Specifies the value that the environment variable PATH should be set to. The PATH variable is set to the specified value before forking the Java VM. Typically, all directories containing all necessary DLLs should be listed here. Possible values are the valid path environment variable setting. There is no default value.	service_path=%JREHOME%\bin;D:\oracle\ora904\bin
service_classpath	Specifies the classpath used by the adapter Java VM. If a custom adapter is developed and as a result, the adapter is to be used to pick up any additional jars, add the jars to the existing set of jars being picked up. Possible values are the valid classpath. There is no default value.	service_classpath=D:\oracle\ ora904\oai\904\lib\ oai.jar;%JREHOME%\lib\i18n.jar;D:\oracle\ora904\jdbc\classes12.zip
service_class	Specifies the entry class for the Windows service. Possible values are oracle/oai/agent/service/AgentService. There is no default value.	service_class=oracle/oai/agent/service/AgentService
service_max_java_stack_size	Windows only. Specifies the maximum size to which the Java VM's stack can grow. Possible values are the valid Java VM maximum native stack size. The default value is the default for the Java VM.	service_max_java_stack_size=409600
service_max_native_stack_size	Windows only. Specifies the maximum size to which the Java VM's native stack can grow. Possible values are the valid Java VM maximum native stack size. The default value is the default for the Java VM.	service_max_native_size=131072
service_min_heap_size	Windows only. Specifies the minimum heap size for the adapter Java VM. Possible values are the valid Java VM heap sizes. The default value is the default Java VM heap size.	service_min_heap_size=536870912
service_max_heap_size	Windows only. Specifies the maximum heap size for the adapter Java VM. Possible values are any valid Java VM heap sizes. The default value is 536870912.	service_max_heap_size=536870912
service_num_vm_args	Windows only. Specifies the number of service_vm_arg<number> parameters specified. Possible values are the number of service_vm_arg<number> parameters. There is no default value.	service_num_vm_args=1
service_vm_arg<number>	Windows only. Specifies any additional arguments to the Java VM. For example, to get line numbers in any of the stack traces, set service_vm_arg1=java.compiler=NONE. If there is a list of arguments to specify, use multiple parameters as shown in the example by incrementing the last digit starting with 1. Be sure to set the service_num_vm_args correctly. Possible values are any valid Java VM arguments. There is no default value.	service_vm_arg1=java.compiler= NONE service_vm_arg2=oai.adapter=.db
service_jdk_version	Windows only. Specifies the JDK version the adapter Java VM should use. The default value is 1.4.1.	service_jdk_version=1.4.1
service_jdk_dll	Windows only. Specifies the dll the adapter Java VM should use. The default value is jvm.dll.	service_jdk_dll=jvm.dll
encoding	Character encoding for published messages. The adapter uses this parameter to generate encoding information in encoding tag of transformed OracleAS InterConnect message. OracleAS InterConnect represents messages internally as an XML document. The default encoding of the XML document is UTF-8. However, this encoding can be configured using this parameter, which is typically used when the OracleAS InterConnect message consists of characters not supported by UTF-8 and when the XMLParser is unable to handle them.	encoding=JA16SJIS
corba_port_number	Specifies the CORBA port number on which the adapter CORBA service listens. Generally, this port is allocated dynamically. However, it can be configured to enable access across firewall.	corba_port_number=14000
nls_date_format	Format for date fields expressed as string. The default date format is EEE MMM dd HH:mm:ss zzz yyyy. For the meaning of this string, see the list of reserved characters in Table 2-8.	Date format pattern dd/MMM/yyyy can represent 01/01/2003. nls_date_format=dd-MMM-yy Multiple date formats can be specified as num_nls_formats=2 nls_date_format1=dd-MMM-yy nls_date_format2=dd/MMM/yy
nls_country	This parameter is a valid ISO Country Code. These upper-case and two-letter codes are defined by ISO-3166. You can find a full list of these codes at a Web site, such as, http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html The default Country code is US. Note: This parameter specifies date format. It is applicable for the date format only.	US
nls_language	This parameter is a valid ISO Language Code. These lower-case and two-letter codes are defined by ISO-639. You can find a full list of these codes at a Web site, such as, http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt The default language code is en. Note: This parameter specifies date format. It is applicable for the date format only.	nls_language=en

Table 2-8 shows the reserved characters used to specify the value of the nls_date_format parameter. Using these characters, you can construct a pattern to define date formats.

Table 2-8 Reserved Characters for the Value of the nls_date_format Parameter

Letter	Description	Example
G	Era designator	AD
y	Year	1996; 96
M	Month in year	July; Jul; 07
w	Week in year	27
W	Week in month	2
D	Day in year	189
d	Day in month	10
F	Day of week in month	Number 2
E	Day in week	Tuesday; Tue
a	A.M./P.M. marker	P.M.
H	Hour in day (0-23)	0
k	Hour in day (1-24)	24
K	Hour in A.M/P.M. (0-11)	0
h	Hour in A.M./P.M. (1-12)	12
m	Minute in hour	30
s	Second in minute	55
S	Millisecond	978
G	Era designator	AD

Database Adapter-specific Parameters

Table 2-9 lists parameters specific to the Database adapter.

Table 2-9 Database Adapter-specific Parameters

Parameter	Description	Example
bridge_class	Indicates the entry class for the Database adapter. Do not modify this value. The default value is oracle.oai.agent.adapter.db. DBBridge.	bridge_class=oracle.oai.agent.adapter.db. DBBridge
db_bridge_use_thin_jdbc	Indicates whether to use a thin JDBC driver when talking to the database. The possible values are true and false. The default is true.	db_bridge_thin_jdbc=true
db_bridge_sql_ trace	Used to enable or disable the SQL trace facility for all reader and writer database sessions. Setting this to true results in the SQL query ALTER SESSION SET SQL_TRACE = TRUE being run in the session, therefore enabling the SQL trace facility. For more information on the SQL trace facility, including how to format and interpret the output, see the Oracle Tuning Guide. The possible values are true or false; the default value is false.	db_bridge_sql_trace = true
db_bridge_instance	The SID of the database instance. The possible value is the valid SID. There is no default value.	db_bridge_instance=orcl
db_bridge_num_schemas	The number of alternate schemas that this database adapter will fail over to. The possible values are any integer greater than 0 and the default value is 1.	db_bridge_num_schemas = 1
db_bridge_schema<#>_username	The username for the schema number <schema#>. The possible values for the schema number are 1 through <db_bridge_num_schemas>. This value should not be modified. Possible values are any valid database user name and there is no default value.	db_bridge_schema1_username=oai
db_bridge_schema<#>_password	The password for the user specified in the db_bridge_schema<schema#>_username. The possible value is the password for the corresponding database user and There is no default value.	db_bridge_schema1_password=oai encrypted_db_bridge_schema1_password=112511011064109110871093
db_bridge_schema<#>_host	The name of the machine hosting the database instance specified by the db_bridge_schema<#>_instance. The possible value is the name of the machine hosting the database and There is no default value.	db_bridge_schema1_host=ssuravar-sun
db_bridge_schema<#>_port	The port where the TNS listener is running for the database instance specified by db_bridge_schema<#>_instance parameter. The possible value is any valid TNS listener port number and There is no default value.	db_bridge_schema1_port=1521
db_bridge_schema<#>_instance	The SID of the database instance. The possible value is any valid SID and There is no default value.	db_bridge_schema1_instance=oiddb1
db_bridge_schema<#>_num_readers	The number of database readers corresponding to the schema number. This is the same as the number of reader threads; each thread has its own database session. The possible values are any integer greater than 0 and there is no default value.	db_bridge_schema1_num_readers=1
db_bridge_schema<#>_num_writers	The number of database writers corresponding to the schema number. This is the same as the number of writer threads; each thread has its own database session. The possible values are any integer greater than 0 and there is no default value.	db_bridge_schema1_num_writers=1
db_bridge_schema<#>_writer_username	The username to be used by this writer to log on to the database as specified by the db_bridge_schema<#>_instance parameter. The possible values are any valid database user and there is no default value.	db_bridge_schema1_writer_username=mydbapp
db_bridge_schema<#>_writer_password	The password corresponding to the database user specified by the db_bridge_schema<#>_writer_username parameter. The possible values are any valid password and there is no default value.	db_bridge_schema1_writer_password=welcome
db_bridge_schema<#>_writer_use_oracle_objects	Specifies whether to use Oracle Objects, available in Oracle8 and later releases. Set this to true unless talking to an Oracle 7.x database. The possible values are true or false and the default value is false.	db_bridge_schema1_writer_use_oracle_objects=true

RAC-specific adapter.ini Parameters for the DB Adapter

When the Database adapter is servicing a RAC database as the spoke database, the parameters listed in Table 2-10 represent information on connection and configuration.

Table 2-10 RAC-specific adapter.ini Parameters

Parameter	Description	Example
db_bridge_num_nodes	Indicates the number of nodes in RAC cluster.	db_bridge_num_nodes=4
db_bridge_schema1_hostx	Indicates host for the node x.	db_bridge_schema1_host2=dsunram13
db_bridge_schema1_portx	Indicates port for node x.	db_bridge_schema1_port2=1421
db_bridge_schema1_instancex	Indicates instance on node x.	db_bridge_schema1_instance2=orcl2