 Copyright (c) Oracle Corporation 1997,1998, 1999, 2000. All Rights Reserved.

  NAME
     	README.txt -  ORACLE VISUAL INFORMATION RETRIEVAL 
                      RELEASE INFORMATION

     	VERSION=8.1.7.0.0 README FILE
 
			=======================

Contents
=======================
        IMPORTANT - Changes Coming in the Next Version
	Important - Listener Must be Running
        Oracle Visual Information Retrieval Release 8.1.7
        For More Information
        Oracle Technology Network
        Oracle Visual Information Retrieval Documentation
	Warnings
	Upgrade Notes
        Installing Oracle Visual Information Retrieval
	Running the Demos
        Downgrade Notes
        Deinstall Notes
        Dropping Visual Information Retrieval Types
        Using the Visual Information Retrieval Java Classes
        Important Information for Ensuring Future Compatibility
	Problems Fixed in This Release
	Features Added in This Release
        Known Problems in This Release
        Deprecated Features: 
            3rd Party Facial Recognition no Longer Supported
            ORDImgB and ORDImgF Object Types Will Be Dropped


IMPORTANT - Changes Coming in the Next Version
==============================================
Oracle plans to change the implementation of Visual Information Retrieval
in the next version of Oracle.  It is our intention that this image content
based retrieval functionality will be layered on the new interMedia image
functionality.

In the next version, we plan to include a Visual Information Retrieval
compatible API for the ORDVir object.  This should require no application 
changes for applications that use the ORDVir object, methods and operators.  
However, it is expected that image signatures will have to be regenerated, 
and the image signature index will have to be recreated.

As has always been the case in the past, it is possible that image comparison
results may vary due to changes and improvements in the image comparison
algorithms.  Variations in image matching results are to be expected as 
image content based retrieval technology improves over time.

IMPORTANT - Listener Must be Running
====================================
The listener must be running in order to use this option. See
section 3.3 below.

Oracle Visual Information Retrieval Release 8.1.7
=================================================

Provides for the storage, retrieval, processing, and content-based 
searching of two dimensional, static bit-mapped images. Provides 
support for building an index for content-based searching.  Images 
are stored efficiently using popular compression schemes in industry 
standard desktop publishing image interchange formats.

For More Information
========================================================================
VIR technology is licensed from Virage, Inc. For more information about 
Virage, see their websight at http://www.virage.com. 

Oracle Technology Network
=========================
For the most recent information about Oracle8i interMedia and related
products, and for free downloads of interMedia utilities and plugins, 
please go to the interMedia section of Oracle Technology Network:

   http://technet.oracle.com 
   
Follow the links to Products > Internet Servers > interMedia.

Oracle Visual Information Retrieval Documentation
===================================================
Complete online documentation is available with Oracle8i.

Warnings:
=======================
Visual Information Retrieval is installed under the database user ORDSYS. This
user is created during installation and is subject to change in future 
beta or production releases.  

THE FUNCTIONS, PACKAGES AND TYPES SUPPLIED BY THIS PACKAGE AND ITS EXTERNAL 
INTERFACE ARE RESERVED BY ORACLE AND ARE SUBJECT TO CHANGE IN FUTURE RELEASES. 
THIS PACKAGE MUST NOT BE MODIFIED BY THE CUSTOMER.  DOING SO 
COULD CAUSE INTERNAL ERRORS AND SECURITY VIOLATIONS IN THE DBMS.   


Upgrade Notes:
=======================
This is Visual Information Retrieval release 8.1.7.  There are upgrade 
scripts to help you upgrade from 8.0.x and 8.1.x to 8.1.7.  Before
following these instructions however, you have to upgrade to 
interMedia 8.1.7.  For information on upgrading to interMedia 8.1.7
see <ORACLE_HOME>/ord/im/admin/README.txt on UNIX, 
<ORACLE_HOME>\ord\im\admin\README.TXT on Windows NT.  

When you are ready to upgrade to Visual Information Retrieval 8.1.7:

1) invoke virdbma to decide whether or not you need to upgrade.

   Start server manager (svrmgrl on UNIX and Windows NT)

   ->  % svrmgrl

       Connect as SYSDBA

   -> SVRMGRL> connect / as SYSDBA

   -> SVRMGRL> @<ORACLE_HOME>/ord/vir/admin/virdbma.sql (on UNIX)
               @<ORACLE_HOME>\ord\vir\admin\virdbma.sql (on Windows NT)
               (where <ORACLE_HOME> is the Oracle home directory)

      This script will output one of the following strings: 
	 NOT_INSTALLED - if no prior Visual Information Retrieval
			 release was installed on your system.
			 You can do an install rather than an upgrade.
         INSTALLED     - if Visual Information Retrieval 8.1.7 is 
			 already installed
         u080xxx0.sql  
                       - the script for upgrade.  xxx is the version of
			 Visual Information Retrieval that you have
			 currently installed.  For example, u0800050.sql
			 will upgrade from Visual Information Retrieval
			 version 8.0.5.0.0.  Note, virdbma cannot distinguish
                         between 8.0 versions of Visual Information Retrieval.
                         If you have an 8.0 version installed, the 8.0.5
                         script will always be chosen.

2) if an upgrade is required, perform the upgrade:

   Start server manager

   -> % svrmgrl
      
	Connect as ORDSYS

   -> SVRMGRL> @<ORACLE_HOME>/ord/vir/admin/u080xxx0.sql (on UNIX)
               @<ORACLE_HOME>\ord\vir\admin\u080xxx0.sql (on Windows NT)
        where u080xxx0.sql is the upgrade script output by step 1
	if an upgrade is necessary.


Installing Oracle Visual Information Retrieval
================================================
Prior to installing Oracle Visual Information Retrieval, you must first 
install Oracle8i Enterprise Edition and Oracle interMedia. If you installed 
Oracle Visual Information Retrieval during the same installation as Oracle8i
Enterprise Edition, you do not have to perform the procedures in this section;
Oracle Visual Information Retrieval was automatically configured for you.

Oracle Visual Information Retrieval is an option of Oracle8i Enterprise 
Edition that provides image storage, retrieval, format conversion, and 
content based searching capabilities through an object data type (ODT).
 
        1 Installation Decisions
        2 Pre-Installation Steps
        3 Installation Steps
 
1 Installation Decisions
------------------------
 
  During the installation process you will create the ORDSYS user.
  This user ID is the standard Oracle database account with special 
  privileges for options.
 
  Decision: Decide on a password for the ORDSYS user.

  The default password for the ORDSYS user during default installation is
  'ORDSYS'.
 
2 Pre-Installation Steps
------------------------
 
  Perform the following pre-installation tasks prior to installing
  Oracle Visual Information Retrieval.  For instructions, please see the 
  Installation Guide for your operating system:
 
	2.1 Install the Oracle8i Enterprise Edition, 
	    including the PL/SQL option and the objects option.
	2.2 Create the database.
	2.3 Start up the database.
	2.4 Install Oracle interMedia, Version 8.1.7.0.0 or later.
 
3 Installation Steps
------------------------
 
  Perform the following mandatory installation steps. Remember, you
  only need to do this if you are manually installing Visual Information
  Retrieval.  You do NOT need to do this if you use the Database 
  Configuration Assistant.
 
 
3.1 Install the non-database components for the Visual Information Retrieval,
    using the Oracle Universal Installer.
 
3.2 Create Visual Information Retrieval.

    Start server manager (svrmgrl on UNIX and Windows NT)

->  % svrmgrl

    Connect as SYSDBA

->    SVRMGRL> connect / as SYSDBA

    Invoke virinst.sql
 
->    SVRMGRL> @<ORACLE_HOME>/ord/vir/admin/virinst.sql (on UNIX)
               @<ORACLE_HOME>\ord\vir\admin\virinst.sql (on Windows NT)
    where <ORACLE_HOME> is the ORACLE_HOME directory.

3.3    Start the Listener

    The listener must be configured to use external
    procedure calls. Check your tnsnames.ora file for
    an entry called extproc_connection_data and in the
    listener.ora file for an entry called extproc.

    See your network documentation for details. If this is
    not done properly, Visual Information Retrieval will NOT work.

Once this has been completed, Oracle Visual Information Retrieval
is usable.

 
			=======================

Running the Demos
=================

Once you have installed Oracle Visual Information Retrieval, you may choose
to run the Oracle Visual Information Retrieval demos. For information on
running the OCI demo, see the following:

<ORACLE_HOME>/ord/vir/demo/README.txt (on UNIX), and
<ORACLE_HOME>\ord\vir\demo\README.txt (on Windows NT), where
<ORACLE_HOME> is the ORACLE_HOME directory.

See the following for information on running the Java demo:

<ORACLE_HOME>/ord/vir/demo/java/README.txt (on UNIX), and
<ORACLE_HOME>\ord\vir\demo\java\README.txt (on Windows NT), where
<ORACLE_HOME> is the ORACLE_HOME directory.


Downgrade Notes
===============

In order to prepare for the downgrade of Oracle Visual Information
Retrieval, perform the following steps:

1) start server manager (svrmgrl on UNIX and Windows NT)

2) Invoke the appropriate script.
   on UNIX:
   -> SVRMGRL> @<ORACLE_HOME>/ord/vir/admin/d080xxx0.sql
   on Windows NT:
      SVRMGRL> @<ORACLE_HOME>\ord\vir\admin\d080xxx0.sql

   where xxx is the version of Visual Information Retrieval you wish
   to downgrade to.  For example, d0800050.sql will prepare for a 
   downgrade to Oracle Visual Information Retrieval 8.0.5.  Note - this
   script will prompt for passwords for ORDSYS.

Deinstall Notes
===============

The following steps will render Oracle Visual Information Retrieval
inactive:

1) start server manager (svrmgrl on UNIX and Windows NT)

2) Invoke the script virdins.sql
   on UNIX:
   -> SVRMGRL> @<ORACLE_HOME>/ord/vir/admin/virdins.sql
   on Windows NT:
      SVRMGRL> @<ORACLE_HOME>\ord\vir\admin\virdins.sql

   Note - this script will prompt for passwords for ORDSYS.

Dropping Visual Information Retrieval Types
===========================================

After you have deinstalled Visual Information Retrieval and dropped all
tables and types which depend on Visual Information Retrieval objects,
you can drop the Visual Information Retrieval types by invoking the
following script from server manager:

    on UNIX:
 -> SVRMGRL> @<ORACLE_HOME>/ord/vir/admin/virdtyp.sql
    on Windows NT:
    SVRMGRL> @<ORACLE_HOME>\ord\vir\admin\virdtyp.sql


Using the Visual Information Retrieval Java Classes
===================================================
In 8.1.7 we introduce new Visual Information Retrieval Java Classes.  See
"Features Added in This Release" for more information on these new classes.

To use the 8.1.7 Visual Information Retrieval Java Classes,  your Java 
environment must be correct and set up to compile and run Java programs.  
In addition, the following setup is required.
 
The environment variable CLASSPATH must contain the jdk classes, the
interMedia Java library, the Visual Information Retrieval Java library,
and the JDBC and SQLJ runtime libraries.  The libraries are located as 
follows (note, the location of the jdk classes is version and installation 
dependent and not mentioned here):
    Unix:
        <ORACLE_HOME>/jdbc/lib/classes111.zip or classes12.zip
        <ORACLE_HOME>/ord/jlib/ordim817.zip
        <ORACLE_HOME>/ord/jlib/ordvir817.zip
        <ORACLE_HOME>/sqlj/lib/runtime.zip
    Windows NT:
        <ORACLE_HOME>\jdbc\lib\classes111.zip or classes12.zip
        <ORACLE_HOME>\ord\jlib\ordim817.zip
        <ORACLE_HOME>\ord\jlib\ordvir817.zip
        <ORACLE_HOME>\sqlj\lib/runtime.zip

The location of the JDBC OCI shared library must be specified in
LD_LIBRARY_PATH (for UNIX) or PATH (for Windows NT).  Note that this
library may already be specified since the same shared library location 
must be specified to use other client applications such as SQL*Plus.
    Unix:
        <ORACLE_HOME>/lib (for libocijdbc8.so)
    Windows NT:
        <ORACLE_HOME>\bin (for ocijdbc8.dll)

The 8.1.5 Visual Information Retrieval Java library is still shipped.
If you do not wish to use the new Visual Information Retrieval Java 
Classes, the 8.1.5 Java Classes can still be used.

To use the 8.1.5 Visual Information Retrieval Java Classes, ensure the 
setup described above with the exception of ordim817.zip and ordvir817.zip
in CLASSPATH.  Instead, confirm that CLASSPATH includes ordim.zip (the 
interMedia 8.1.5 library) and ordvir.zip (the Visual Information Retrieval
8.1.5 library).


Important Information for Ensuring Future Compatibility
=========================================================

IMPORTANT - We may evolve the Visual Information Retrieval object type
(ORDVir) by adding new object attributes in a future release of Visual
Information Retrieval.  Client-side applications that wish to maintain 
compatibility to the "8.1.7" version of the ORDVir object type even after 
a server upgrade which evolves the object types are advised to do the 
following:

 - Make a call to the compatibility initialization function
   at the beginning of the application if necessary (see below).

 - Do not use default constructors since insert statements using the
   default constructor may fail if the ORDVir object type has
   evolved to add new attributes. Instead, the application can use the 
   new static constructor function provided in 8.1.7.  See the
   "Features Added in This Release" section below for details.

When and How to Call the Compatibility Initialization Function
--------------------------------------------------------------
NOTE : - Only client-side applications that statically understand the 
structure of the ORDVir object type need to make a call to the 
compatibility initialization function. Server-side stored procedures will 
automatically use the newly installed (and potentially evolved) ORDVir 
object type after an upgrade so do not need to call the compatibility
initialization function.  Client-side applications that do not statically 
(at compile time) understand the structure of the ORDVir object type do 
not need to call the compatibility initialization function.  OCI 
applications that determine the structure of the ORDVir object type at
runtime via the OCIDescribeAny call do not need to call the compatibility
initialization function.

Client-side applications written in OCI that have been compiled with the C
structure of the ORDVir object type (generated by OTT) should make a call 
to the server-side PL/SQL function, ORDSYS.VIR.compatibilityInit, at the 
beginning of the application.

  FUNCTION compatibilityInit(release IN     VARCHAR2,
                             errmsg  OUT    VARCHAR2)
                             return NUMBER;
  
  This PL/SQL function takes a string input parameter representing the 
  version of Oracle Visual Information Retrieval being used by your 
  application.  This string should be set to '8.1.7' to allow your 8.1.7 
  application to work (without upgrading) with a potential future version
  of Oracle with an evolved ORDVir object type.  The second parameter is a 
  string output parameter.  If the function returns a status other 
  than 0, this errmsg string will contain the reason for the failure.


Client-side applications written in Java using the Visual Information 
Retrieval Java Classes for 8.1.7 should call the 
OrdMediaUtil.virCompatibilityInit function after connecting to Oracle.

  public static void virCompatibilityInit(OracleConnection con) 
         throws Exception

  This Java function takes an OracleConnection as argument.  The included
  Visual Information Retrieval 8.1.7 Java Classes will ensure that your 
  8.1.7 application will work (without upgrading) with a potential future
  version of Visual Information Retrieval with an evolved object type.

There is not yet a way for client-side PL/SQL applications to maintain 
compatibility to the 8.1.7 version of the ORDVir object if the object
is evolved to add new attributes in a future release.

Please see the "Oracle8i Visual Information Retrieval User's
Guide and Reference Release 8.1.7" and the "Oracle8i Visual Information
Retrieval Java Client User's Guide and Reference, Release 8.1.7"
for further information along with detailed descriptions and examples.
Both will be available on the Oracle Technology Network.


Problems Fixed in This Release
==============================
1) The export() method now works for srcType 'FILE'.  The semantics for
   export() are as such:
    o export() is similar to a file copy operation.  That is, the
	original data stored in the BLOB is not touched other
	than for reading purposes.
    o export() is not an exact mirror operation to import() in that
	clearLocal() is not called automatically by export() whereas
	import() calls setLocal().
    o if your intent is to no longer manage the multimedia data
	within the database after the export() method is used but
	you do intend to continue to reference the multimedia data
	(e.g. as a BFILE) then you should call deleteContent() to
	free up the BLOB storage.

  The ability to write a file on the database server is a powerful
  one.  This ability could potentially be used in malicious ways.
  One might attempt to overwrite critical database files or simply
  write large or numerous files in order to fill the server's disks.

  Because of these possibilities certain privileges must be in place
  before export() will work for a user.
    o First export() will only write to a directory object the user has
	privilege to access.  That is, a directory the user has either
	created themselves with the SQL "CREATE DIRECTORY" command or
	one that they have been granted READ on.

	In order to execute the CREATE DIRECTORY command one must
	have the CREATE ANY DIRECTORY privilege.
    o Second, to further restrict which files can be written to
	the DBMS_JAVA.GRANT_PERMISSION must be used to specify
	which files are allowed to be written to.  E.g.
	CALL DBMS_JAVA.GRANT_PERMISSION(
		'MEDIAUSER',
		'java.io.FilePermission',
		'/actual/server/directory/path/filename.dat',
		'write');
        See the Oracle8i Java Developer's Guide, Security
        and Performance for more information on
        DBMS_JAVA.GRANT_PERMISSION.

2) An additional ORDSource.import method has been defined:
      MEMBER PROCEDURE import(
                          SELF     IN OUT NOCOPY ORDSource,
                          ctx      IN OUT RAW,
                          mimetype OUT VARCHAR2,
                          format   OUT VARCHAR2)
    This import method is nearly identical to the existing import
    method except that the destination BLOB is not passed in as
    a separate (redundant) parameter.  It is likely that the
    import method with the redundant destination BLOB parameter
    will be deprecated in a future release.

3) The deleteContent() method was unintentionally setting most
   of ORDVir's metadata attributes to NULL.  deleteConent() no longer
   touches the metadata attributes.



Features Added in This Release
==============================

1) Static Methods for easy Initialization

  Static methods have been added which allow for easy initialization
  of instances of the ORDVir type. The method is called "init" and
  can be used in one of two variations.

  The first init takes no parameters and initializes all the media
  type's attributes to NULL with the following exceptions:
    image.source.updateTime is set to SYSDATE
    image.source.local is set to 1
    image.source.localData is set to empty_blob()

  The second variation on "init" takes three string parameters which
  are directly mapped to source.srcType, source.srcLocation, and
  source.srcName.  All of the other attributes are set to NULL with
  the following exceptions:
    image.source.updateTime is set to SYSDATE
    image.source.local is set to 0
    image.source.localData is set to empty_blob()

  **IMPORTANT** We strongly recommend that you begin using the init
  method as soon as possible.  We may evolve the ORDVir type in the future.
  If we add attributes to the ORDVir type in a future version, insert
  statements using the default constructor (which initializes each object
  attribute) will fail.

  Example Uses:
    SQL:
        INSERT INTO VIRTABLE_A VALUES ( ORDSYS.ORDVIR.init(), ... );
        INSERT INTO VIRTABLE_B VALUES (
                ORDSYS.ORDVIR.init('FILE','IMGDIR','product3154.jpg'), ... );

    PL/SQL:
        DECLARE
          myImgA ORDSYS.ORDVIR;
          myImgB ORDSYS.ORDVIR;
        BEGIN
          myImgA := ORDSYS.ORDVir.init;
          myImgB := ORDSYS.ORDVir.init('FILE','IMGDIR','product3154.jpg');
          ...
          INSERT INTO MEDIATABLE VALUES ( myImgA, myImgB, .... );
        END;

2) New Visual Information Retrieval Java Classes for Image Content

  Oracle Visual Information Retrieval Java Classes enable Java 
  applications on any tier (client, application server or database 
  server) to manipulate and modify image data stored in Oracle8i.  

  Applications connect to the database, select the media object, copy 
  that object from the database, perform various operations and store 
  the new media object in Oracle8i.

  Visual Information Retrieval Java Classes support JDBC access to 
  image content. This support enables applications to select and operate 
  on a result set that contains sets of ORDVir columns plus other 
  relational data. These classes also enable access to object attributes 
  and invocation of object methods. 

  The new Visual Information Retrieval Java Classes will work with Oracle8i 
  Server (8.1.5 or higher) and Oracle8i Client (8.1.6 or higher). 
 
  To support JDBC, changes have been made to the Visual Information
  Retrieval Java Classes' syntax and semantics.

  It is no longer necessary to explicitly bind an application's copy of the 
  object to a database object.  It is also no longer necessary to refresh 
  and flush the application's copy of the object to synchronize it with the
  corresponding database object.  Instead, users retrieve ORDVir objects
  in their Java programs using the standard JDBC executeQuery() function call.
  Rather than flushing the application's copy of the object to the database,
  an explicit update is performed by executing a standard SQL update 
  statement using the JDBC API. 

  Another fundamental change is that all methods, with the exception of
  those that load data from an external data source into the BLOB, change
  the state of the application's copy of the object.  The user must perform 
  an explicit update as mentioned above in order to propagate changes to 
  the database object.

  In addition, some APIs have been dropped from the new Java classes and 
  some have been changed in minor ways.

  Please visit the Oracle Technology Network for detailed documentation
  on the new Java Classes.

3) The digital camera format known as "Exif" is now recognized by
  Visual Information Retrieval.  The Exif format is essentially a 
  variation on the JFIF format and as such the ORDVir.setProperties 
  method sets the fileFormat attribute to JFIF.


Known Problems in This Release
==============================
	Importing Visual Information Retrieval signature data across hardware 
        platforms with different endian characteristics could silently corrupt
        the data.  Users are advised to invoke the Convert() function to 
        rectify the signatures after import.

========
        Using the "process" method with progressively encode JPEG files will 
        fail.

========
        There is a performance bug in this release which causes the new 
        operators, VIRSimilar and VIRScore, to be suboptimal in their
        performance when a domain index HAS NOT been created for Visual 
        Information Retrieval.  Hence, if for some reason a domain index 
        has not been created we recommend that you use the older 
        operators, vir.similar and vir.score (for usage please refer to
        Appendix E in the Visual Information Retrieval documentation).  

        Wherever possible, create an index and use the operators 
        VIRSimilar and VIRScore for best possible performance.
        If an index cannot be created, use the older operators instead
        of the new operators.

========

	The operators VIRSimilar and VIRScore cannot be used in
	PL/SQL constructs (for example in an IF statement).  They can
	be used in all SQL constructs (WHERE clause, SELECT clause,
	ORDER BY clause are few examples).  Note that all the SQL
	constructs with the operators VIRSimilar and VIRScore can
	be used in a PL/SQL procedure.

========
        Using the "process" method with progressively encode JPEG files 
        will fail.


Deprecated Features
===================
         3rd Party Facial Recognition no Longer Supported
         ------------------------------------------------

         In prior releases, Visual Information Retrieval supported facial
         signature conversion and image comparison from 3rd party facial 
         recognition technology.  Effective in 8.1.7, this support is no 
         longer available.

         ORDImgB and ORDImgF Object Types Will Be Dropped
         ------------------------------------------------

         The deprecated object types, ORDVirB and ORDVirF will not be shipped 
         in versions after 8.1.7.
=======================
END OF README.txt
