Copyright (c) Oracle Corporation 1998, 1999, 2000. All Rights Reserved. NAME README.txt - ORACLE interMedia RELEASE INFORMATION VERSION=8.1.7.0.0 README FILE ======================= Contents ======================= IMPORTANT Getting Started Oracle interMedia Release 8.1.7 Oracle Technology Network Oracle interMedia Documentation Warnings Upgrade Notes Installing Oracle interMedia Running the Demos Downgrade Notes Deinstall Notes Dropping interMedia Types Using the interMedia Java Classes Important Information for Ensuring Future Compatibility Problems Fixed in This Release Features Added in This Release Known Problems in This Release Deprecated Object Types Will Be Dropped Obsolete methods IMPORTANT ======================= The Oracle listener must be running in order to use this option. See section 3.4 below for more information. Getting Started =============== This document describes both general release information on Oracle interMedia and specific release information on Oracle interMedia Image, Audio and Video components. Oracle interMedia Release 8.1.7 ================================= Oracle interMedia enables Oracle8i to manage image, audio, video, text and locator functions in an integrated fashion with other enterprise information. Oracle interMedia extends Oracle8i reliability, availability, and data management to multimedia content in Internet, electronic commerce, and media-rich applications. The capabilities of interMedia encompass the storage, retrieval, management, and manipulation of multimedia data managed by Oracle8i. Oracle interMedia Image provides for the storage, retrieval, and processing of two dimensional, static bit-mapped images. Images are stored efficiently using popular compression schemes in industry standard desktop publishing image interchange formats. Oracle interMedia Audio and interMedia Video provide for the storage and retrieval of various audio and video file formats. Oracle Technology Network ========================= For the most recent information about interMedia, 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 interMedia Documentation ================================= Complete online documentation is available with Oracle8i. Check the Oracle Technology Network for updates to interMedia documentation. Warnings: ======================= Oracle interMedia 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: ======================= There are upgrade scripts to help you upgrade from 8.0.x and 8.1.x to 8.1.7 interMedia. These scripts upgrade the Image, Audio and Video components of interMedia only. The Text and Locator components of interMedia are not upgraded via these scripts. Please refer to the Spatial User's Guide for information on upgrading interMedia Locator, and the interMedia Text documentation for information on upgrading interMedia Text. Note - before upgrading interMedia, you must upgrade your database. Please consult the Oracle Migration Guide to determine how to upgrade your database, including how to upgrade your Oracle JVM. After upgrading your database, perform the following steps to upgrade interMedia: 1) if you have Oracle8 Image, Audio or Video installed, and you wish to install Oracle interMedia version 8.1.7, invoke imdbma to decide whether or not you need to upgrade: Start server manager (svrmgrl on UNIX and Windows NT) -> % svrmgrl Connect as SYS as SYSDBA -> SVRMGRL> connect SYS/ as SYSDBA -> SVRMGRL> @/ord/im/admin/imdbma.sql (on UNIX) @\ord\im\admin\imdbma.sql (on Windows NT) (where is the Oracle home directory) This script will output one of the following strings: NOT_INSTALLED - if no prior versions of interMedia components were installed on your system. You can do an install rather than an upgrade. INSTALLED - if interMedia 8.1.7 is already installed MANUAL - if an upgrade is required If an upgrade is required, go on to step 2. 2) invoke imuphelp to determine if your system is ready for an interMedia upgrade. Start server manager (svrmgrl on UNIX and Windows NT) -> % svrmgrl Connect as SYS as SYSDBA -> SVRMGRL> connect SYS/ as SYSDBA -> SVRMGRL> @/ord/im/admin/imuphelp.sql (on UNIX) @\ord\im\admin\imuphelp.sql (on Windows NT) (where is the ORACLE_HOME directory) This script will tell you: - if an earlier version of Audio must be deinstalled before upgrading - if an earlier version of Video must be deinstalled before upgrading Correct any problems found by imuphelp.sql before proceeding. 3) if an upgrade is required and your system is ready for an upgrade, perform the upgrade. 3a) first upgrade ORD. invoke /ord/admin/u08xxx0.sql Start server manager -> % svrmgrl Connect SYS/ as SYSDBA -> SVRMGRL> @/ord/admin/u080xxx0.sql (on UNIX) @\ord\admin\u080xxx0.sql (on Windows NT) where xxx is the version of interMedia or Image Cartridge you currently have installed. For example, u0800030.sql will upgrade ORD from Oracle8 Image version 8.0.3.0.0. Note - this script will prompt for a password for ORDSYS. 3b) then upgrade interMedia. invoke /ord/im/admin/u08xxx0.sql Start server manager -> % svrmgrl -> SVRMGRL> @/ord/im/admin/u080xxx0.sql (on UNIX) @\ord\im\admin\u080xxx0.sql (on Windows NT) where xxx is the version of interMedia or Image Cartridge you currently have installed. For example, u0800030.sql will upgrade from Oracle8 Image version 8.0.3.0.0. Note - this script will prompt for passwords for ORDPLUGINS and ORDSYS. 4) invoke imchk.sql to verify the upgrade: -> % svrmgrl Connect as ORDSYS -> SVRMGRL> @/ord/im/admin/imchk.sql (on UNIX) @\ord\im\admin\imchk.sql (on Windows NT) Installing Oracle interMedia ============================== Prior to installing Oracle interMedia, you must first install Oracle8i. If you installed Oracle interMedia during the same installation as Oracle8i, you do not have to perform the procedures in this section; Oracle interMedia was automatically configured for you. 1 Installation Decisions 2 Pre-Installation Steps 3 Installation Steps 1 Installation Decisions ------------------------ During the installation process you will create the ORDSYS, ORDPLUGINS and MDSYS users. These user IDs are the standard Oracle database account with special privileges for options. Decision: Decide on passwords for the ORDSYS, ORDPLUGINS, and MDSYS users. The installation will choose default passwords for ORDSYS and ORDPLUGINS. You will have to change these passwords after the installation completes. The default password for the ORDSYS user during automatic installation is 'ORDSYS', and for ORDPLUGINS is 'ORDPLUGINS'. 2 Pre-Installation Steps ------------------------ Perform the following pre-installation tasks prior to installing Oracle interMedia. For instructions, please see the Installation Guide for your operating system: 2.1 Install Oracle8i, including the PL/SQL and JServer option. 2.2 Create the database. 2.3 Start up the database. 3 Installation Steps -------------------- Perform the following mandatory installation steps. Remember, you only need to do this if you are manually installing Oracle interMedia. You do NOT need to do this if you use the Database Configuration Assistant. Note, the following steps install the Image, Audio, Video and Locator components of interMedia. The Text component is not installed via these steps. 3.1 Install the non-database components for Oracle interMedia, using the Oracle Universal Installer. 3.2 Create the users and grant privileges. Start Server Manager. (svrmgrl on UNIX and Windows NT) -> % svrmgrl Connect as SYS as SYSDBA. -> SVRMGRL> connect SYS/ as SYSDBA. where is the password for the SYS user. Invoke ordinst.sql -> SVRMGRL> @/ord/admin/ordinst.sql (on UNIX) @\ord\admin\ordinst.sql (on Windows NT) where is the ORACLE_HOME directory 3.3 Create Oracle interMedia. -> SVRMGRL> @/ord/im/admin/iminst.sql (on UNIX) @\ord\im\admin\iminst.sql (on Windows NT) where is the ORACLE_HOME directory 3.4 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, Oracle interMedia will NOT work. Once this has been completed, Oracle interMedia is usable. ======================= Running the Demos ================= Once you have installed Oracle interMedia, you may choose to run the Oracle interMedia demos. This section contains references to the interMedia demos. 1 Oracle interMedia Image Demos ------------------------------- For the interMedia Image OCI demo, see the README.txt file at /ord/img/demo/README.txt (on UNIX), and \ord\img\demo\README.txt (on Windows NT), where is the ORACLE_HOME directory. For the interMedia Image Java demo, see the README.txt file at /ord/img/demo/java/README.txt (on UNIX), and \ord\img\demo\java\README.txt (on Windows NT), where is the ORACLE_HOME directory. 2 Oracle interMedia Audio Demos ------------------------------- For the interMedia Audio SQL demo, see the README.txt file at /ord/aud/demo/README.txt (on UNIX) \ord\aud\demo\README.txt (on Windows NT) For the interMedia Audio Java demo, see the README.txt file at /ord/aud/demo/java/README.txt (on UNIX) \ord\aud\demo\java\README.txt (on Windows NT) 3 Oracle interMedia Video Demos ------------------------------- For the interMedia Video SQL demo, see the README.txt file at /ord/vid/demo/README.txt (on UNIX) \ord\vid\demo\README.txt (on Windows NT) For the interMedia Video Java demo, see the README.txt file at /ord/vid/demo/java/README.txt (on UNIX) \ord\vid\demo\java\README.txt (on Windows NT) 4 Oracle interMedia Locator Demo -------------------------------- For interMedia Locator, //doc/README.doc (on UNIX) \\doc\README.doc (on Windows NT) Downgrade Notes =============== In order to prepare for the downgrade of Oracle interMedia, perform the following steps: 1) change directory to /ord/im/admin (on UNIX) \ord\im\admin (on Windows NT) 2) start server manager (svrmgrl on UNIX and Windows NT) 3) @d080xxx0.sql where xxx is the version of interMedia or Image Cartridge you wish to downgrade to. For example, d0800030.sql will prepare for downgrade to Oracle8 Image version 8.0.3.0.0. Note - this script will prompt for passwords for ORDPLUGINS and ORDSYS. Deinstall Notes =============== The following steps will render Oracle interMedia inactive: 1) change directory to /ord/im/admin (on UNIX) \ord\im\admin (on Windows NT) 2) start server manager (svrmgrl on UNIX and Windows NT) 3) @imdinst.sql. Note - this script will prompt for passwords for MDSYS, ORDPLUGINS, and ORDSYS. Dropping interMedia types ========================= After you have deinstalled interMedia and dropped all tables and types which depend upon interMedia objects, you can drop the interMedia Image, Audio and Video types by invoking the following script from server manager: @/ord/im/admin/imdtyp.sql (on UNIX) @\ord\im\admin\imdtyp.sql (on Windows NT) Using the interMedia Java Classes ================================= In 8.1.7 we introduce new interMedia Java Classes. See "Features added in this release" for more information on these new classes. To use the 8.1.7 interMedia 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, 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: /jdbc/lib/classes111.zip or classes12.zip /ord/jlib/ordim817.zip /sqlj/lib/runtime.zip Windows NT: \jdbc\lib\classes111.zip or classes12.zip \ord\jlib\ordim817.zip \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: /lib (for libocijdbc8.so) Windows NT: \bin (for ocijdbc8.dll) If you do not wish to use new interMedia Java Classes, the 8.1.5 API can still be used. To use the 8.1.5 interMedia Java Classes, ensure the setup described above with the exception of ordim817.zip in CLASSPATH. Instead, confirm that CLASSPATH includes ordim.zip (the 8.1.5 library). Important Information for Ensuring Future Compatibility ========================================================= IMPORTANT - We may evolve the interMedia object types (ORDAudio, ORDImage, ORDVideo, and ORDSource) by adding new object attributes in a future release of interMedia. Client-side applications that wish to maintain compatibility to the "8.1.7" version of the interMedia object types 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 interMedia object types have evolved to add new attributes. Instead, the application can use the new static constructor functions 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 interMedia object types need to make a call to the compatibility initialization function. Server-side stored procedures will automatically use the newly installed (and potentially evolved) interMedia object types 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 interMedia object types do not need to call the compatibility initialization function. OCI applications that determine the structure of the interMedia object types 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 an interMedia object type (generated by OTT) should make a call to the server-side PL/SQL function, ORDSYS.IM.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 interMedia 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 evolved interMedia object types. 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 interMedia Java Classes for 8.1.7 should call the OrdMediaUtil.imCompatibilityInit function after connecting to Oracle. public static void imCompatibilityInit(OracleConnection con) throws Exception This Java function takes an OracleConnection as argument. The included interMedia 8.1.7 Java API will ensure that your 8.1.7 application will work (without upgrading) with a potential future version of interMedia with evolved object types. There is not yet a way for client-side PL/SQL applications to maintain compatibility to the 8.1.7 version of the interMedia objects if the objects are evolved to add new attributes in a future release. Please see the "Oracle8i interMedia Audio, Image, and Video User's Guide and Reference Release 8.1.7" and the "Oracle8i interMedia Audio, Image, and Video 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 Oracle interMedia Source 8.1.7 Problems Fixed ----------------------------------------------- 1.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. 1.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. 2 Oracle interMedia Image 8.1.7 Problems Fixed ---------------------------------------------- 2.1 The deleteContent() method was unintentionally setting most of ORDImage's metadata attributes to NULL. deleteConent() no longer touches the metadata attributes. 3 Oracle interMedia Audio 8.1.7 Problems Fixed ---------------------------------------------- None. 4 Oracle interMedia Video 8.1.7 Problems Fixed ---------------------------------------------- None. 5 Oracle interMedia Locator 8.1.7 Problems Fixed ------------------------------------------------ For interMedia Locator information, see: //doc/README.doc (on UNIX) \\doc\README.doc (on Windows NT) Features Added in This Release ============================== 1 New 8.1.7 interMedia Image, Audio and Video Features ------------------------------------------------------ 1.1 Static methods have been added to each of the media types (ORDImage, ORDAudio, ORDVideo) which allow for easy initialization of instances of these types. 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: source.updateTime is set to SYSDATE source.local is set to 1 any BLOBs or CLOBs are set to empty_blob or empty_clob respectively. 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: source.updateTime is set to SYSDATE source.local is set to 0 any BLOBs or CLOBs are set to empty_blob or empty_clob respectively. **IMPORTANT** We strongly recommend that you begin using the init method as soon as possible. We may evolve the interMedia object types in the future. If we add attributes to the interMedia objects in a future version, insert statements using the default constructors (which initializes each object attribute) will fail. Example Uses: SQL: INSERT INTO AUDIOTABLE VALUES ( ORDSYS.ORDAudio.init(), ... ); INSERT INTO IMAGETABLE VALUES ( ORDSYS.ORDImage.init('FILE','IMGDIR','product3154.jpg'), ... ); PL/SQL: DECLARE myImage ORDSYS.ORDImage; myVideo ORDSYS.ORDVideo; BEGIN myImage := ORDSYS.ORDImage.init; myVideo := ORDSYS.ORDVideo.init('FILE','VIDDIR','interMedia.rm'); ... INSERT INTO MEDIATABLE VALUES ( myImage, myVideo, .... ); END; 1.2 New interMedia Java Classes for Rich content Oracle interMedia Java Classes enable Java applications on any tier (client, application server or database server) to manipulate and modify audio, image, and video data 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. interMedia Java Classes support JDBC access to rich content. This support enables applications to select and operate on a result set that contains sets of interMedia columns plus other relational data. These classes also enable access to object attributes and invocation of object methods. The new interMedia 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 interMedia 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 interMedia 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 API. 2 New 8.1.7 interMedia Image Features ------------------------------------- 2.1 The digital camera format known as "Exif" is now recognized by interMedia Image. The Exif format is essentially a variation on the JFIF format and as such the ORDImage.setProperties method sets the fileFormat attribute to JFIF. 3 New 8.1.7 interMedia Audio and Video Features ----------------------------------------------- None. 4 New 8.1.7 interMedia Locator Features --------------------------------------- For interMedia Locator information, see: //doc/README.doc (on UNIX) \\doc\README.doc (on Windows NT) Known Problems in This Release ============================== 1 Oracle interMedia Image 8.1.7 Known Problems ---------------------------------------------- Using the "process" method with progressively encode JPEG files will fail. 2 Oracle interMedia Audio 8.1.7 Known Problems ---------------------------------------------- None. 3 Oracle interMedia Video 8.1.7 Known Problems ---------------------------------------------- None. 4 Oracle interMedia Locator 8.1.7 Known Problems ------------------------------------------------ For interMedia Locator, //doc/README.doc (on UNIX) \\doc\README.doc (on Windows NT) Deprecated Object Types Will Be Dropped ======================================= The deprecated image object types, ORDImgB and ORDImgF will not be shipped in versions after 8.1.7. The new image object type, ORDImage, must be used in future versions. Obsolete Methods ================ The following ORDAudio and ORDVideo get methods that accept a ctx parameter were deprecated in 8.1.6: ORDAudio: getFormat(ctx IN OUT RAW) RETURN VARCHAR2 getEncoding(ctx IN OUT RAW) RETURN VARCHAR2 getNumberOfChannels(ctx IN OUT RAW) RETURN INTEGER getSamplingRate(ctx IN OUT RAW) RETURN INTEGER getSampleSize(ctx IN OUT RAW) RETURN INTEGER getCompressionType(ctx IN OUT RAW) RETURN VARCHAR2 getAudioDuration(ctx IN OUT RAW) RETURN INTEGER ORDVideo: getFormat(ctx IN OUT RAW) RETURN VARCHAR2 getFrameSize(SELF IN OUT NOCOPY ORDVideo, ctx IN OUT RAW, retWidth OUT INTEGER, retHeight OUT INTEGER) getFrameResolution(ctx IN OUT RAW) RETURN INTEGER getFrameRate(ctx IN OUT RAW) RETURN INTEGER getVideoDuration(ctx IN OUT RAW) RETURN INTEGER getNumberOfFrames(ctx IN OUT RAW) RETURN INTEGER getCompressionType(ctx IN OUT RAW) RETURN VARCHAR2 getNumberOfColors(ctx IN OUT RAW) RETURN INTEGER getBitRate(ctx IN OUT RAW) RETURN INTEGER These methods will be shipped in 8.1.7, but they won't be enhanced and they may be removed in a future version. Each of the above methods reads the media data to extract the desired attribute. Rather than reading the media data for each attribute, we suggest calling the setProperties method. This method extracts attributes from the media and populates the object attributes. The getxxx methods (with no ctx parameter) return the values stored in object attributes. These are the recommended methods for 8.1.7 and beyond. ======================= END OF README.txt