2
Installation and Configuration

This chapter describes the FTP adapter installation and configuration.

This chapter discusses these topics:

• Installing the FTP Adapter

• FTP Adapter Configuration

Installing the FTP Adapter

This section contains these topics:

• Preinstallation Tasks

• Installation Tasks

• Postinstallation Tasks

Preinstallation Tasks

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

• An existing Oracle9i Application Server Oracle home

• An existing Oracle9i Application Server Infrastructure Database Oracle home

• An existing Oracle9iAS InterConnect Oracle home

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

Consult the Oracle9i Application Server Installation Guide before proceeding with FTP adapter installation. This guide includes information on:

• CD-ROM mounting

• Oracle Universal Installer startup

• Oracle9iAS InterConnect software, hardware, and system requirements

• Oracle9iAS InterConnect installation

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

Installation Tasks

To install the FTP adapter:

1. Click Next on the Welcome page.

   The File Locations page displays.

2. Enter the following information in the Destination fields:
   • Name--The Oracle home name.

   • Path--The full path to the Oracle home in which to install the FTP adapter.

     Note: Do not change the path specified in the Source field. This is the location on the CD-ROM from which to install the FTP adapter.

3. Click Next.

   The Installation Types page displays.

4. Select Oracle9iAS InterConnect Adapters and click Next.

   The Available Product Components page displays.

5. Select Oracle9iAS InterConnect FTP Adapter and click Next.

6. If the FTP adapter is not being installed on the same computer as Oracle9iAS InterConnect and another adapter is not installed in the current Oracle home, the Oracle9iAS InterConnect Hub Database page displays. Enter the following information about the Oracle9iAS InterConnect Hub to use:
   • Host Name--The hostname of the computer on which Oracle9iAS InterConnect is installed

   • Port Number--The port number of the computer

   • Database SID--The system identifier (SID) of the Oracle9iAS InterConnect Oracle9iAS Metadata Repository

   • Password--The password for the Oracle9iAS Metadata Repository schema

   The Oracle9iAS Metadata Repository stores metadata used by Oracle9iAS InterConnect to coordinate communication between components.

7. Click Next.

   The Oracle9iAS InterConnect FTP Adapter Configuration page displays.

8. Enter the name of the application associated with the FTP adapter. White spaces or blanks are not allowed. This is the same application name created or to be created in iStudio. The default value is myFTPApp.

9. Click Next.

   The Oracle9iAS InterConnect FTP Adapter usage page displays.

10. Select one of the following options and go to the step specified to enable the sending and/or receiving of messages from an external data source, such as an FTP server. You can change your selections later by editing parameter settings in the adapter.ini file.

    If You Select...	Then Click Next and Go to Step...
    Configure for both sending and receiving messages	11
    Configure for sending messages ONLY	11
    Configure for receiving messages ONLY	13

11. Enter the following information in the Oracle9iAS InterConnect FTP Adapter Configuration - Configure sending endpoint information page:
    • Username--The username for the FTP server.

    • Password--The password for the FTP server.

    • FTP Mode--The mode of access used to send information to the specified URL. Select either binary or ascii.

    • URL--The URL to be used for sending information. Enter one of the following:
      • For sending to an FTP server--ftp://<host name>/<path>

      • For sending to a local file system--file://localhost/<path>

        Note: If the sender endpoint is a local file system, the user name, password, and file type are not required.

12. Click Next.

    The installation page that displays next is based on the selection you made in Step 10:

    If You Selected...	Then Go to Step...
    Configure for both sending and receiving messages	13
    Configure for sending messages ONLY	15

13. Enter the following information in the Oracle9iAS InterConnect FTP Adapter Configuration - Configure receiving endpoint information page:
    • Username--The username account of the FTP server from which the Oracle9iAS InterConnect Hub receives messages

    • Password--The password for the username account

    • FTP Mode--The mode of access used to receive information from the specified URL. Select either binary or ascii.

    • URL--The FTP URL to be used for receiving information. Enter one of the following:
      • For sending to an FTP server--ftp://<host name>/<path>

      • For sending to a local file system--file://localhost/<path>

        Note: If the sender endpoint is a local file system, the user name, password, and file type are not required.

        Caution: For testing purposes, do not specify a personal FTP account or personal file directories as the receiving endpoint. During runtime, the FTP adapter connects to the FTP server or accesses the file system and removes the files in the directory specified by the receiving endpoint after processing. Oracle Corporation recommends that you create a dedicated FTP account or user a account (if the local file system is used for the receiving endpoint) for testing and deploying this adapter.

14. Click Next.

15. Complete any other fields for other components selected for installation, such as other adapters.

    When finished, the Summary page displays.

16. Click Install to install the FTP adapter. The adapter is installed in the following directory:

    Platform	Directory
    Windows	%ORACLE_HOME%\oai\9.0.2\adapters\Application
    UNIX	$ORACLE_HOME/oai/9.0.2/adapters/Application

    Application is the value you specified in Step 8.

Postinstallation Tasks

FTP adapter installation creates an adapter.ini file that consists of configuration parameters read by the FTP adapter at startup. These configuration parameter settings are appropriate for most FTP application environments. You can customize some adapter.ini file parameter settings for the FTP application after installation. See the following sections:

• Customizing the Payload Data Type

• Customizing the Sending Endpoints

• Customizing the Receiving Endpoints

  See Also: Table 2-1 for the location of the adapter.ini file Table 2-6 for adapter.ini file parameter setting information specific to the FTP adapter

Customizing the Payload Data Type

Payload data is the data sent between applications. If you want to change the payload data type from the default of XML to the data definition description language (D3L), edit the following parameters in the adapter.ini file.

1. Set the ota.type parameter to the payload type D3L. For example:

   ota.type=D3L
   

2. Copy the D3L XML files associated with the FTP application to the directory in which the adapter.ini file is located.

3. Set the ota.d3ls parameter to specify the D3L files associated with the FTP application. For example:

   ota.d3ls=person1.xml,person2.xml
   

   See Also: The following parameter descriptions for additional information: ota.type ota.d3ls

Customizing the Sending Endpoints

If you want to customize the behavior of the sending endpoints (destinations) for messages, edit the following parameters in the adapter.ini file. These parameters are not automatically set to default values during installation.

1. Change the sender endpoint by editing the ota.send.endpoint parameter or leave it blank if it acts only as a receiver. For example:
   • For a remote file system--ota.send.endpoint=ftp://foo.com/test

   • For a local file system--ota.send.endpoint=file://localhost/test

   If the endpoint is a local file system, leave the following parameters blank:

   • file.sender.file_type

   • file.sender.password

   • file.sender.proxy_host

   • file.sender.proxy_port

2. Set the file.sender.file_type parameter to the file type used in FTP. For example:

   file.sender.file_type=BINARY
   

3. Update the file.sender.user and file.sender.password parameters with the information of the FTP account that serves as the sending endpoint.

4. If a proxy host is needed, enter the appropriate values for the file.sender.proxy_host and file.sender.proxy_port parameters.

Customizing the Receiving Endpoints

If you want to customize the behavior of the receiving FTP or file endpoints for messages, edit the following parameters in the adapter.ini file.

1. Change the receiver endpoint by editing the ota.receive.endpoint or leave it blank if the adapter only acts as a sender. For example:
   • For a remote file system--ota.receive.endpoint=ftp://foo.com/test

   • For a local file system--ota.receive.endpoint=ftp://localhost/test

     Note: If the endpoint is a local file system leave the file.receiver.file_type, file.receiver.password, file.receiver.proxy_host, and file.receiver.proxy_port parameters blank.

2. Set the file.receiver.file_type parameter to the file type used in FTP. For example:

   file.receiver.file_type=BINARY
   

3. Update the file.receiver.user and file.receiver.password parameters with the information of the FTP account that serves as the receiving endpoint.

4. If a proxy host is needed, enter the appropriate values for the file.receiver.proxy_host and file.receiver.proxy_port parameters.

5. Set the file.exception.exception_dir to a local file system directory that stores files and cannot be processed successfully. For example:

   file.receiver.exception_dir=/tmp/error
   

6. Set the file.receiver.polling_interval parameter to the time interval in milliseconds during which to poll the FTP server or local file system. For example:

   file.receiver.polling_interval=20000
   

7. Set the file.receiver.max_msgs_retrieved parameter to the maximum number of messages to retrieve in polling a session. For example:

   file.receiver.max_msgs_retrieved=10

FTP Adapter Configuration

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

Table 2-1 FTP Adapter Directory

On...	Go to...
UNIX	$ORACLE_HOME/oai/9.0.2/adapters/Application
Windows	%ORACLE_HOME%\oai\9.0.2\adapters\Application

Table 2-2 FTP Executable Files

File	Description
start.bat (Windows) start (UNIX)	Takes no parameters; starts the adapter
stop.bat (Windows) stop (UNIX)	Takes no parameters; stops the adapter
ignoreerrors.bat (Windows) ignoreerrors (UNIX)	If an argument is specified, then the given error code is ignored: ignoreerrors errorCodeToBeIgnored If no argument is specified, then all error codes specified in the ErrorCodes.ini file are ignored: ignoreerrors

See Also: "FTP Error Code" for a list of error codes

Table 2-3 FTP Configuration Files

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

See Also: Appendix A, "Sample Adapter.ini File"

Table 2-4 FTP Directories

Directory	Description
persistence	The messages are persisted (made available) in this directory. Do not edit this directory or its contents.
logs	The logging of adapter activity is done in subdirectories of the logs directory. Subdirectory names take the following form: timestamp_in_milliseconds Each time the adapter is run, a new subdirectory is created in which logging is done in an oailog.txt file.

Using the Application Parameter

Adapters do not have integration logic. The FTP 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).

adapter.ini Initialization Parameter File

This section contains these topics:

• Agent Connection Parameters

• FTP Adapter-Specific Parameters

Agent Connection Parameters

The agent component of the FTP adapter reads the adapter.ini file at runtime to access FTP adapter parameter configuration information. Table 2-5 lists the parameter name, a description for each parameter, the possible and default values, and an example.

Table 2-5 Agent Connection Parameters

Parameter	Description	Example
application	Specifies the name of the application to which this adapter connects. This must match with the name specified in iStudio during creation of metadata. Use any alphanumeric string. There is no default value.	application=ftpapp
partition	Specifies the partition this adapter handles as defined in iStudio. Any alphanumeric string is a possible value. There is no default value.	partition=germany
instance_number	Specifies the instance number to which this adapter corresponds. Specify a value only if you want to have multiple adapter instances for the given application with the given partition. Possible values are any integer greater than or equal to 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	Specifies the subscriber name used when this adapter registers its subscription. The possible value is a valid Oracle Advanced Queue subscriber name. There is no default value.	agent_subscriber_name=ftpapp
agent_message_selector	Specifies conditions for message selection when registering its subscription with the hub. The possible value is a valid Oracle Advanced Queue message selector string. There is no default value.	agent_message_selector=recipient_list like '%,aqapp,%'
agent_reply_subscriber_name	Specifies the subscriber name used when multiple adapter instances for the given application with the given partition are used. This parameter is optional if there is only one instance running. The possible value is the application name (parameter:application) concatenated with the instance number (parameter:instance_number). There is no default value.	If application=ftpapp and instance_number=2, then agent_reply_subscriber_name=ftpapp2
agent_reply_message_selector	Used only if there are multiple adapter instances for the given application with the given partition. The possible value is a string built using the concatenated application name (parameter:application) with the instance number (parameter:instance_number). There is no default value.	If application=ftpapp and instance_number=2, then agent_reply_message_selector=recipient_list like '%,ftpapp2,%'
agent_tracking_enabled	Specifies if message tracking is enabled. Set this parameter to false to turn off all tracking of messages. Set this parameter 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 this parameter 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 whether to use a custom document type definition (DTD) for the common view message when handing it to the hub (the repository in which metadata is stored). By default, adapters use an Oracle9iAS InterConnect-specific DTD for all messages sent to the hub, as other Oracle9iAS InterConnect adapters retrieve the messages from the hub and know how to interpret them. Set this parameter to true if for every message, the DTD imported for the message of the common view is used instead of the Oracle9iAS InterConnect DTD. Only set this parameter to true if an Oracle9iAS 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 is a lot of metadata 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 many 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 many 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. Possible values are true or false. The default value is false. 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.	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 (publish/subscribe and invoke/implement) to cache. 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 to which internal Oracle9iAS 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 to which internal Oracle9iAS 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 to run the persistence cleaner thread (in milliseconds). Possible values are any integer greater than or equal to 30000. The default value is 60000.	agent_persistence_cleanup_interval=60000
agent_persistence_retry_interval	Specifies how often for the persistence thread to retry when it fails to send an Oracle9iAS InterConnect message. Possible values are any integer greater than or equal to 60000. The default value is 60000.	agent_persistence_retry_interval=60000
service_path	Windows only. Specifies the value to which to set the environment variable PATH. 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\ora902\bin
service_classpath	Specifies the class path used by the adapter Java VM. If a custom adapter is developed and, as a result, the adapter is to pick up any additional jars, add the jars to the existing set of jars being picked up. Possible values are the valid class path. There is no default value.	service_classpath=D:\oracle\ ora902\oai\902\lib\ oai.jar;%JREHOME%\lib\rt.jar;D:\oracle\ora902\jdbc\classes12.zip
service_class	Specifies the entry class for the Windows NT service. A possible value is 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_stack_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_argnumber parameters specified. Possible values are the number of service_vm_argnumber parameters. There is no default value.	service_num_vm_args=1
service_vm_argnumber	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 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=database

FTP Adapter-Specific Parameters

Table 2-6 lists the parameters specific to the FTP adapter. With the exception of the bridge_class parameter, all parameters can be edited after installation.

Table 2-6 FTP Adapter-Specific Values

Parameter	Description	Example
bridge_class	Specifies the entry class for the FTP adapter. A value must be specified and cannot be modified later. A possible value is oracle.oai.agent.adapter.technology. TechBridge. There is no default value.	bridge_class=oracle.oai.agent.adapter.technology. TechBridge
ota.send. endpoint	Defines the FTP sending endpoint url. The url is written as follows: ftp://<host name>/<directory path> or file://localhost/<directory path>. The possible values are ftp://<host name>/<directory path>. There is no default value.	ota.send.endpoint=ftp://ip-sun/private/ ipdev1/test/inbound
ota.receive. endpoint	Defines the FTP receiving endpoint url. The url is written as follows: ftp://<host name>/<directory path> or file://localhost/<directory path>. The possible values are ftp://<host name>/<directory path>. There is no default value.	ota.receive.endpoint= ftp://ip-sun/private/ ipdev1/test/inbound
ota.type	Defines the type of payload this adapter handles. Possible values are XML and D3L. There is no default value.	ota.type=XML
ota.d3ls	Specifies the list of data definition description language (D3L) XML files used by this bridge. Each business event handled by the bridge must have its own D3L XML file. Whenever a new D3L XML file is imported in iStudio for use by an application using the SMTP adapter, the parameter must be updated and the SMTP adapter restarted. There is no default value.	ota.d3ls=person.xml, person1.xml
file.sender. user	The FTP user name for the outbound FTP server. The possible value is a valid FTP user name. There is no default value.	file.sender.user=joe
file.sender. type	Indicates the file types. The possible values are ASCII or BINARY. The default value is BINARY.	file.sender.type=ASCII
file.sender. proxy_host	The name of the machine that server as the proxy server for the outbound FTP server. The possible value is any correct host name. There is no default value.	file.sender.proxy_host=www-proxy.foo.com
file.sender. proxy_port	The port number of the proxy server for the outbound FTP server. The possible value is any valid port number. There is no default value.	file.sender.proxy_port=80
file.receiver. user	The FTP user name for the inbound FTP server. The possible value is any valid FTP user name. There is no default value.	file.receiver.user=joe
file.receiver. proxy_host	The name of the machine that servers as the proxy server for the inbound FTP server. The possible value is a correct host name. There is no default value.	file.receiver.proxy_host=www-proxy.foo.com
file.receiver. proxy_port	The port number of the proxy server for the inbound FTP server. The possible value is a valid port number. There is no default value.	file.receiver.proxy_port=80
file.receiver. exception_dir	The value of this parameter should be a URL which represents either an FTP directory or a file location. For this release, if an FTP URL can only be specified for the exception directory if the receiving endpoint is also an FTP URL, and furthermore the host name in the URL has to be the same. When a processing exception occurs, the host name, user name, and password of the receiving endpoint will be used to log on to the FTP server to store the messages that are not processed successfully. The user should make sure this directory exists on the FTP server (or the local file system if file URL is used) and is writable by the FTP adapter process.	file.receiver. execption_dir=ftp://acme.com/ private/user/error or file.receiver.exception_dir=file://localhost/ private/user/error