Copyright (c) 2003 Oracle Corporation. All rights reserved.
----------------------------------------------------------

========================================
SAMPLE PROGRAMS FOR ORACLE9i DATA MINING
========================================
Oracle9i Data Mining (ODM) includes sample input data and sample Java programs
that illustrate techniques available with ODM's Java API. This file contains
instructions for compiling and executing these sample programs.

The input data used by the sample programs is created as part of the ODM 
install; the data is available in the odm_mtr schema.

You can compile and execute the sample programs using provided scripts; you
can also compile and execute the sample programs in JDeveloper using a 
JDeveloper project that you can download from Oracle Technology Network
(http://otn.oracle.com). For information about installing and using the
JDeveloper project for ODM, see the README that is included in the download.

The rest of this file describes the sample programs and the provided scripts.

The script compileSampleCode compiles any or all of the sample programs; the
script executeSampleCode executes any one or all of the sample programs at once,
except for Sample_NaiveBayesBuild_short.java and 
Sample_NaiveBayesApply_short.java.

The sample programs use two property files, Sample_Global.property
and a property file specific to the sample program. The two short sample
programs, Sample_NaiveBayesBuild_short.java and
Sample_NaiveBayesApply_short.java, do not require any property files.


REQUIREMENTS

The ODM user schema must be configured with or upgraded to Oracle9i 9.2.0.1
release.

The RDBMS patchset 9.2.0.3 must be applied prior to this ODM patchset application.

The ODM user and ODM_MTR accounts must be unlocked if locked.

You will be required to provide the host name, TCP/IP port, and Oracle SID of
the database to which you want to connect. Additionally, you will also need
to know the password for ODM user on that database. Contact your database
administrator if you do not know what those values are.


INSTRUCTIONS FOR COMPILING AND EXECUTING SAMPLE PROGRAMS

1. Set your ORACLE_HOME environment variable.

2. Ensure that you have installed JDK 1.3.1 or above. JDK 1.3.1 may also be 
   available in ORACLE_HOME with your installation. Set your JAVA_HOME
   environment variable; it should point to your installed JDK directory or the
   one available in ORACLE_HOME. 

3. If you are using the scripts provided to compile and execute the sample
   programs, CLASSPATH is already defined in these scripts. If you are not using
   the scripts, you must set your CLASSPATH environment variable so that it 
   includes the following Oracle9i Java Archive files:

      $ORACLE_HOME/jdbc/lib/classes12.jar
      $ORACLE_HOME/lib/xmlparserv2.jar
      $ORACLE_HOME/rdbms/jlib/jmscommon.jar
      $ORACLE_HOME/rdbms/jlib/aqapi.jar
      $ORACLE_HOME/rdbms/jlib/xsu12.jar
      $ORACLE_HOME/dm/lib/odmapi.jar

   If you use a database character set that is not US7ASCII, WE8DEC,
   WE8ISO8859P1, or UTF8, you must also include the following in your CLASSPATH:
      
      $ORACLE_HOME/jdbc/lib/nls_charset12.zip

4. To execute the short programs, Sample_NaiveBayesBuild_short.java and
   Sample_NaiveBayesApply_short.java, you will need to provide the database URL
   (DB_URL) and the password for the ODM user. The database URL is a string that
   specifies the type of JDBC driver used and database details. Oracle9i Data
   Mining supports the JDBC thin driver which requires a database URL in form of
   "jdbc:oracle:thin:@<host_name>:<port_number>:<sid>".

   To specify the data mining server, substitute appropriate values for DB_URL
   and ODM password in the following line in both short sample programs:

      dms = new DataMiningServer("DB_URL", "odm", "ODM password");

   The location access data has already been specified in both programs for your
   convenience.
     
5. To execute the rest of the programs, you will need to edit the
   Sample_Global.property file to provide the database URL, ODM user name, and
   the password for ODM user. Replace the strings MyHost, MyPort, MySid, MyName
   MyPW with the appropriate values for your system. MyName refers to the odm 
   user and it must be replaced with odm. For MyPW, use the password specified
   during ODM configuration or while unlocking the ODM user account. By default
   the password is odm.

   For example:
      miningServer.url=jdbc:oracle:thin:@odmserver.company.com:1521:orcl
      miningServer.userName=odm
      miningServer.password=odm
      inputDataSchemaName=odm_mtr
      outputSchemaName=odm

6. You can compile each ODM sample program or all of them at once by running
   one of the provided scripts. To compile a specific sample program, execute
   one of the following scripts as shown:

   On UNIX platforms:
      /usr/bin/sh compileSampleCode.sh <filename>
      Example: /usr/bin/sh compileSampleCode.sh Sample_ModelSeeker.java

   On Windows platforms:
      compileSampleCode.bat <filename>
      Example: compileSampleCode.bat Sample_ModelSeeker.java

   To compile all of the programs at once, use one of the scripts with the
   parameter "all":

   On UNIX platforms:
      /usr/bin/sh compileSampleCode.sh all

   On Windows platforms:
      compileSampleCode.bat all

7. Before you execute a sample program, log in to the ODM user schema in the 
   database and type "exec odm_start_monitor" to turn on the ODM task monitor.
   Generally, you will not have to start the monitor again unless you manually
   stop it or the job associated with the task monitor turns broken. If you
   do not start the task monitor, any data mining tasks pending for execution
   will be hanging.

8. Each of the sample programs uses Sample_Global.property and a program
   specific property file. For example, Sample_ModelSeeker.java 
   requires Sample_ModelSeeker.property. To execute a specific sample program 
   use one of the provided scripts. If you do not specify a property file, the
   script assumes the default property file for the specified program except
   for Sample_AssociationRules.java which has a choice of two distinct property
   files; the desired property file for this sample program must be specified
   explicitly. To execute a specific sample program, execute one of the scripts
   as shown:

   On UNIX platforms:
      /usr/bin/sh executeSampleCode.sh <classname> [<property file>]

   Example:
      /usr/bin/sh executeSampleCode.sh Sample_ModelSeeker
      /usr/bin/sh executeSampleCode.sh Sample_ModelSeeker myFile.property

   On Windows platforms:
      executeSampleCode.bat <classname> [<property file>]

   Example:
      executeSampleCode.bat Sample_ModelSeeker
      executeSampleCode.bat Sample_ModelSeeker myFile.property

   To  execute all of the programs (except for Sample_NaiveBayesBuild_short.java
   and Sample_NaiveBayesApply_short.java) at once, use one of the scripts with
   the parameter "all":

    On UNIX platforms:
      /usr/bin/sh executeSampleCode.sh all

    On Windows platforms:
      executeSampleCode.bat all

   
NOTES

ODM Sample Programs
-------------------

1. The sample programs for Naive Bayes and Adaptive Bayes Network models require
   that any record to which you apply the models has either an integer or string
   attribute. You cannot apply the models to records that have a continuous 
   numeric attribute.

2. For a given model type, the sample build program must be executed before 
   test, apply, or PMML export can be executed. For discretization, 
   Sample_Discretization_CreateBinBoundaryTables must be executed before 
   Sample_Discretization_UseBinBoundaryTables.

ODM Programming Notes
---------------------

1. Any table that you score (apply a model to) must have the same format as the 
   table used to build the model. If you build a model using a table that is in 
   transactional format, any table that you apply that model to must be in 
   transactional format. Similarly, if the table used to build the model was in 
   nontransactional format, any table to which you apply the model must be in 
   nontransactional format.

2. When you create a mining function specification for a classification
   problem, you must specify an algorithm, that is, the MiningAlgorithmSettings 
   cannot have a null value.
