7
ORDDoc Reference Information

Oracle interMedia contains information about the ORDDoc type:

Object type -- see Section 7.1.
Constructors -- see Section 7.2.
Methods -- see Section 7.3.
Packages or PL/SQL plug-ins -- see Section 7.4.

The examples in this chapter assume that the test media table TDOC has been created and filled with data. This table was created using the SQL statements described in Section 7.3.1.

Note:

If you manipulate the media data itself (by either directly modifying the BLOB or changing the external source), then you must ensure that the object attributes stay synchronized and the update time is modified; otherwise, the object attributes will not match the media data.

Methods invoked at the ORDSource level that are handed off to the source plug-in for processing have ctx(RAW(4000)) as the first argument. Before calling any of these methods for the first time, the client must allocate the ctx structure, initialize it to NULL, and invoke the openSource( ) method. At this point, the source plug-in can initialize context for this client. When processing is complete, the client should invoke the closeSource( ) method.

Methods invoked from a source plug-in call have the first argument as ctx (RAW(4000)).

Methods invoked at the ORDDoc level that are handed off to the format plug-in for processing have ctx (RAW(4000)) as the first argument. Before calling any of these methods for the first time, the client must allocate the ctx structure and initialize it to NULL.

Note:

In the current release, not all source or format plug-ins will use the ctx argument, but if you code as previously described, your application should work with any current or future source or format plug-in.

You should use any of the individual set methods to set the value of the attribute for an object for formats not natively supported; otherwise, for formats natively supported, use the setProperties( ) method to populate the attributes of the object.

7.1 Object Types

Oracle interMedia describes the ORDDoc object type, which supports the storage and management of any media data including text, image, audio, and video.

ORDDoc Object Type

The ORDDoc object type supports the storage and management of media data. This object type is defined as follows:

CREATE OR REPLACE TYPE ORDDoc
AS OBJECT
(
  -- ATTRIBUTES 
source              ORDSource,
format              VARCHAR(80),
mimeType            VARCHAR(80),
contentLength       INTEGER,
comments            CLOB, 

  -- METHODS 
-- CONSTRUCTORS
--
STATIC FUNCTION init( ) RETURN ORDDoc,
STATIC FUNCTION init(srcType     IN VARCHAR2,
                     srcLocation IN VARCHAR2,
                     srcName     IN VARCHAR2) RETURN ORDDoc,
-- Methods associated with the mimeType attribute
MEMBER FUNCTION getMimeType RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getMimeType, WNDS, WNPS, RNDS, RNPS),
MEMBER PROCEDURE setMimeType(mime IN VARCHAR2),

-- Methods associated with the date attribute
MEMBER FUNCTION getUpdateTime RETURN DATE,
PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS),
MEMBER PROCEDURE setUpdateTime(current_time DATE),

-- Methods associated with the format attribute
MEMBER FUNCTION getFormat RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getFormat, WNDS, WNPS, RNDS, RNPS),
MEMBER PROCEDURE setFormat(format IN VARCHAR2),

-- Methods associated with the source attribute
MEMBER FUNCTION  isLocal RETURN BOOLEAN,
PRAGMA RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS),
MEMBER PROCEDURE  setLocal,
MEMBER PROCEDURE  clearLocal,

MEMBER PROCEDURE setSource(source_type     IN VARCHAR2,
                           source_location IN VARCHAR2,
                           source_name     IN VARCHAR2),
MEMBER FUNCTION getSource RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSource, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION getSourceType RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceType, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION getSourceLocation RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceLocation, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION getSourceName RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceName, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE setProperties(ctx         IN OUT RAW,
                               setComments IN BOOLEAN),

MEMBER FUNCTION getBFILE RETURN BFILE,
PRAGMA RESTRICT_REFERENCES(getBFILE, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE import(ctx      IN OUT RAW,
                        set_prop IN BOOLEAN),
MEMBER PROCEDURE importFrom(ctx             IN OUT RAW,
                            source_type     IN VARCHAR2,
                            source_location IN VARCHAR2, 
                            source_name     IN VARCHAR2
                            set_prop        IN BOOLEAN),
MEMBER PROCEDURE export(ctx             IN OUT RAW,
                        source_type     IN VARCHAR2,
                        source_location IN VARCHAR2,
                        source_name     IN VARCHAR2),

MEMBER FUNCTION openSource(userArg IN RAW, ctx OUT RAW) RETURN INTEGER,
MEMBER FUNCTION closeSource(ctx IN OUT RAW) RETURN INTEGER,
MEMBER FUNCTION trimSource(ctx     IN OUT RAW,
                           newlen  IN INTEGER) RETURN INTEGER,
MEMBER PROCEDURE readFromSource(ctx      IN OUT RAW,
                                startPos IN INTEGER,
                                numBytes IN OUT INTEGER,
                                buffer   OUT RAW), 
MEMBER PROCEDURE writeToSource(ctx      IN OUT RAW,
                               startPos IN INTEGER,
                               numBytes IN OUT INTEGER,
                               buffer   IN RAW), 

MEMBER FUNCTION getContentLength RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE getContentInLob(ctx      IN OUT RAW,
                                dest_lob IN OUT NOCOPY BLOB,
                                mimeType OUT VARCHAR2,
                                format   OUT VARCHAR2),

MEMBER FUNCTION getContent RETURN BLOB,
PRAGMA RESTRICT_REFERENCES(getContent, WNDS, WNPS, RNDS, RNPS),

MEMBER PROCEDURE deleteContent,

MEMBER FUNCTION processSourceCommand(ctx       IN OUT RAW,
                                     cmd       IN VARCHAR2,
                                     arguments IN VARCHAR2,
                                     result    OUT RAW)
                RETURN RAW

);

where:

source: the ORDSource where the media data is found.
format: the format in which the media data is stored.
mimeType: the MIME type information.
contentLength: the length of the media data stored in the source.
comments: the metadata information of the media object.

7.2 Constructors

This section describes the constructor functions.

The interMedia constructor functions are as follows:

init( )
init(srcType,srcLocation,srcName)

init( )

Format

init( ) RETURN ORDDoc;

Description

Allows for easy initialization of instances of the ORDDoc object type.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

This static method initializes all the ORDDoc attributes to NULL with the following exceptions:

source.updateTime is set to SYSDATE
source.local is set to 1 (local)
source.localData is set to empty_blob

You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDDoc object type, especially if the ORDDoc type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.

Examples

Initialize the ORDDoc object attributes:

BEGIN
   INSERT INTO tdoc VALUES (1,ORDSYS.ORDDoc.init());
END;
/

init(srcType,srcLocation,srcName)

Format

init(srcType IN VARCHAR2,

srcLocation IN VARCHAR2,

srcName IN VARCHAR2)

RETURN ORDDoc;

Description

Allows for easy initialization of instances of the ORDDoc object type.

Parameters

srcType

The source type of the media data.

srcLocation

The source location of the media data.

srcName

The source name of the mediamedia data.

Pragmas

None.

Exceptions

None.

Usage Notes

This static method initializes all the ORDDoc attributes to NULL with the following exceptions:

source.updateTime is set to SYSDATE
source.local is set to 0
source.localData is set to empty_blob
source.srcType is set to the input value
source.srcLocation is set to the input value
source.srcName is set to the input value

Examples

Initialize the ORDDoc object attributes.

Note:

You must first create the DOCDIR directory; this is the directory where your media files reside. Create this directory using the following SQL statement and then grant read access to PUBLIC to this directory. Change this directory specification to match the location of your media files.

-- Create the DOCDIR load directory; this is the directory where the media 
-- files reside.

CREATE OR REPLACE DIRECTORY docdir
       as 'e:\oracle\ord\doc\demo';
GRANT READ ON DIRECTORY docdir TO PUBLIC WITH GRANT OPTION;

BEGIN
  INSERT INTO tdoc VALUES (2, ORDSYS.ORDDoc.init('file','DOCDIR','doc1.pdf');
END;
/

7.3 Methods

This section presents reference information on the Oracle interMedia methods used for media data manipulation. These methods are described in the following groupings:

ORDDoc Methods Associated with mimeType Attribute

getMimeType: returns the MIME type of the stored media data. See "getMimeType( )" for information.
setMimeType( ): sets the MIME type of the stored media data. This method is called implicitly by any method that modifies natively supported media formats. See "setMimeType( )" for information.

ORDDoc Methods Associated with the updateTime Attribute

getUpdateTime: returns the time when the media object was last updated. See "getUpdateTime( )" for information.
setUpdateTime( ): sets the update time for the media object. This method is called implicitly by methods that modify natively supported media formats. See "setUpdateTime( )" for information.

ORDDoc Methods Associated with the format Attribute

setFormat( ): sets the object attribute value of the format of the media data. See "setFormat( )" for information.
getFormat: returns the object attribute value of the format in which the media data is stored. See "getFormat".

ORDDoc Methods Associated with the source Attribute

isLocal: returns TRUE if the data is stored locally in a BLOB or FALSE if the data is external. See "isLocal( )" for information.
setLocal: sets a flag to indicate that the data is stored locally in a BLOB. See "setLocal( )" for information.
clearLocal: clears the flag to indicate that the data is stored externally. See "clearLocal( )" for information.
setSource( ): sets the source information to where media data is found. See "setSource( )" for information.
getSource: returns a formatted string containing complete information about the external data source formatted as a URL. See "getSource( )" for information.
getSourceType: returns the external source type of the media data. See "getSourceType( )" for information.
getSourceLocation: returns the external source location of the media data. See "getSourceLocation( )" for information.
getSourceName: returns the external source name of the media data. See "getSourceName( )" for information.
setProperties( ): reads the media data to get the values of the object attributes and then stores them in the object for known format types. If the value for the setComments parameter is TRUE, then the comments field of the object will be populated with an extensive set of format and application properties of the media object in XML form, identical to what is provided by the interMedia Annotator utility. For the known attributes that ORDDoc understands, it sets the properties for these attributes. These include the format of the media data. This method also automatically sets the content length of the media and sets the update time. See "setProperties( )".
import( ): transfers data from an external data source (specified by calling setSourceInformation( )) to the local source (localData) within an Oracle database, setting the value of the local attribute to "1", meaning local, and updating the timestamp. See "import( )".
importFrom( ): transfers data from the specified external data source (source type, location, name) to the local source (localData) within an Oracle database, setting the value of the local attribute to "1", meaning local and updating the timestamp. See "importFrom( )".
export( ): copies data from a local source (localData) within an Oracle database to the specified external data source, and stores source information in the source. See "export( )" for information.

Note:
The export( ) method natively supports only sources of source type file. User-defined sources may support the export( ) method.
getContentLength( ): returns the length of the data source (as number of bytes). See "getContentLength( )".
getContentInLob( ): returns content into a temporary LOB. See "getContentInLob( )" for information.
getContent: returns the handle to the BLOB used to store contents locally. See "getContent( )" for information.
deleteContent: deletes the content of the local BLOB. See "deleteContent( )" for information.
getBFILE: returns the external content as a BFILE. See "getBFILE( )" for information.
processSourceCommand( ): sends a command and related arguments to the source plug-in. See "processSourceCommand( )" for information.

ORDDoc Methods Associated with File Operations

openSource( ): opens a data source or a BLOB. See "openSource( )" for information.
closeSource( ): closes a data source or a BLOB. See "closeSource( )" for information.
trimSource( ): trims a data source or a BLOB. See "trimSource( )" for information.
readFromSource( ): reads a buffer of n bytes from a source beginning at a start position. See "readFromSource( )" for information.
writeToSource( ): writes a buffer of n bytes to a source beginning at a start position. See "writeToSource( )" for information.

For more information on object types and methods, see Oracle9i Database Concepts.

7.3.1 Example Table Definitions

The methods described in this reference chapter show examples based on a test media table TDOC. Refer to the TDOC table definition that follows when reading through the examples:

TDOC Table Definition

CREATE TABLE TDOC(n NUMBER CONSTRAINT n_pk PRIMARY KEY,
                  doc ORDSYS.ORDDOC)
STORAGE (INITIAL 100K NEXT 100K PCTINCREASE 0);

INSERT INTO tdoc VALUES(1, ORDSYS.ORDDoc.init());
INSERT INTO tdoc VALUES(2, ORDSYS.ORDDoc.init());

getContentInLob( )

Format

getContentInLob(

ctx IN OUT RAW,

dest_lob IN OUT NOCOPY BLOB,

mimeType OUT VARCHAR2,

format OUT VARCHAR2);

Description

Copies data from a data source into the specified BLOB. The BLOB must not be the BLOB in source.localData.

Parameters

ctx

The source plug-in context information.

dest_lob

The LOB in which to receive data.

mimeType

The MIME type of the data; this may or may not be returned.

format

The format of the data; this may or may not be returned.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the getContentInLob( ) method and the value of srcType is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the getContentInLob( ) method and this method is not supported by the source plug-in being used.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the getContentInLob( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Get data from a data source and put it into the specified BLOB:

DECLARE
 obj ORDSYS.ORDDoc;
 tempBLob BLOB;
 mimeType VARCHAR2(4000);
 format VARCHAR2(4000);
 ctx RAW(4000) :=NULL;
BEGIN
 SELECT doc INTO obj FROM tdoc WHERE N = 1 ;
 if(obj.isLocal()) then
   DBMS_OUTPUT.put_line('local is true');
 end if;
 DBMS_LOB.CREATETEMPORARY(tempBLob, true, 10);
 obj.getContentInLob(ctx,tempBLob, mimeType,format);
 DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.getLength(tempBLob)));
 EXCEPTION
  WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.put_line('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

getContentLength( )

Format

getContentLength RETURN INTEGER;

Description

Returns the length of the media data content stored in the source.

Parameters

None.

Usage Notes

This method is not supported for all source types. For example, HTTP type sources do not support this method. If you want to implement this call for HTTP type sources, you must define your own modified HTTP source type and implement this method on it.

Pragmas

PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

See the example in import( ).

getFormat

Format

getFormat RETURN VARCHAR2;

Description

Returns the value of the format attribute of the media object.

Parameters

None.

Usage Notes

None.

Pragmas

PRAGMA RESTRICT_REFERENCES(getFormat, WNDS, WNPS, RNDS, RNPS)

Exceptions

INVALID_FORMAT_TYPE

This exception is raised if you call the getFormat( ) method and the value for format is NULL.

Examples

See the example in setProperties( ).

import( )

Format

import(ctx IN OUT RAW

set_prop IN BOOLEAN);

Description

Transfers media data from an external media data source to a local source (localData) within an Oracle database.

Parameters

ctx

The source plug-in context information.This must be allocated. You must call the openSource( ) method; see the introduction to this chapter for more information.

set_prop

If the value is TRUE, then the setProperties( ) method is called to read the media data to get the values of the object attributes and store them in the object attributes, otherwise, if the value is FALSE, the set Properties( ) method is not called. The default value is FALSE.

Usage Notes

Use the setSource( ) method to set the external source type, location, and name prior to calling the import( ) method.

You must ensure that the directory exists or is created before you use this method.

After importing data from an external media data source to a local source (within an Oracle database), the source information remains unchanged (that is, pointing to the source from where the data was imported).

Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the import( ) method and the value of srcType is NULL.

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the import( ) method and the value of dlob is NULL.

ORDSourceExceptionsMETHOD_NOT_SUPPORTED

This exception is raised if you call the import( ) method and the import( ) method is not supported by the source plug-in being used.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the import( ) method within a source plug-in when any other exception is raised.

ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION

This exception is raised if you call the import( ) method and the setProperties( ) method raises an exception from within the media plug-in.

See Appendix H for more information about these exceptions.

Examples

Import media data from an external media data source into the local source:

DECLARE
  obj ORDSYS.ORDDoc;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT doc INTO obj FROM tdoc  WHERE N=1 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('setting and getting source');
  DBMS_OUTPUT.PUT_LINE('--------------------------');
  -- set source to a file
  obj.setSource('file','DOCDIR','testdoc.dat');
  -- get source information
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  -- import data
  obj.import(ctx,FALSE);
  -- check size
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.getLength(obj.getContent())));  
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  DBMS_OUTPUT.PUT_LINE('deleting contents');
  DBMS_OUTPUT.PUT_LINE('-----------------');
  obj.deleteContent();
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.getLength(obj.getContent())));  
  UPDATE tdoc SET doc=obj WHERE N=1;
  COMMIT;
  EXCEPTION
    WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
      DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
    WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
      DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');
END;
/

importFrom( )

Format

importFrom(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2

set_prop IN BOOLEAN);

Description

Transfers media data from the specified external media data source to a local source (localData) within an Oracle database.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the openSource( ) method; see the introduction to this chapter for more information.

source_type

The source type of the media data.

source_location

The location from where the media data is to be imported.

source_name

The name of the media data.

set_prop

Usage Notes

This method is similar to the import( ) method except the source information is specified as parameters to the method instead of separately.

You must ensure that the directory exists or is created before you use this method.

After importing data from an external media data source to a local source (within an Oracle database), the source information (that is, pointing to the source from where the data was imported) is set to the input values.

Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the import( ) method and the value of srcType is NULL.

ORDSourceExceptionsMETHOD_NOT_SUPPORTED

This exception is raised if you call the importFrom( ) method and this method is not supported by the source plug-in being used.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the importFrom( ) method within a source plug-in when any other exception is raised.

ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION

This exception is raised if you call the import( ) method and the setProperties( ) method raises an exception from within the media plug-in.

See Appendix H for more information about these exceptions.

Examples

Import media data from the specified external data source into the local source:

DECLARE
  obj ORDSYS.ORDDoc;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT doc INTO obj FROM tdoc WHERE N=1 FOR UPDATE FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('setting and getting source');
  DBMS_OUTPUT.PUT_LINE('--------------------------');
  -- set source to a file
  -- import data
  obj.importFrom(ctx,'file','DOCDIR','testdoc.dat',FALSE);
  -- check size
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.GETLENGTH(obj.getContent()))); 
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  DBMS_OUTPUT.PUT_LINE('deleting contents');
  DBMS_OUTPUT.PUT_LINE('-----------------');
  obj.deleteContent();
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.GETLENGTH(obj.getContent())));
  UPDATE tdoc SET doc=obj WHERE N=1;
  COMMIT;
  EXCEPTION
    WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
      DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
    WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
      DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');
END;
/

setFormat( )

Format

setFormat(knownFormat IN VARCHAR2);

Description

Sets the format attribute of the media object.

Parameters

knownFormat

The known format of the data to be set in the corresponding media object.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

NULL_INPUT_VALUE

This exception is raised if you call the setFormat method and the value for the knownFormat parameter is NULL.

Examples

Set the format for some media data:

DECLARE
  obj ORDSYS.ORDDoc;
BEGIN
  select doc into obj from tdoc where N =1 for update;
  obj.setFormat('PDF');
  DBMS_OUTPUT.put_line('format: ' || obj.getformat());
  COMMIT;
  EXCEPTION
   WHEN ORDSYS.ORDAudioExceptions.NULL_INPUT_VALUE THEN
    DBMS_OUTPUT.put_line('ORDSourceExceptions.NULL_INPUT_VALUE caught');
   WHEN OTHERS THEN
    DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

setProperties( )

Format

setProperties(ctx IN OUT RAW,

setComments IN BOOLEAN);

Description

Reads the media data to get the values of the object attributes and then stores them in the object attributes. This method sets the properties for the following attributes of the media data: format, MIME type, and content length. It populates the comments field of the object with an extensive set of format and application properties in XML form if the value of the setComments parameter is TRUE.

Note:

Some audio, image, and video formats are supported, but no media formats are supported. This method works for only natively supported formats. See Appendix A, Appendix B, and Appendix C for information on natively supported media formats.

Parameters

ctx

The format plug-in context information.

setComments

If the value is TRUE, then the comments field of the object is populated with an extensive set of format and application properties of the media object in XML form, identical to what is provided by the interMedia Annotator utility; otherwise, if the value is FALSE, the comments field of the object remains unpopulated. The default value is FALSE.

Usage Notes

If the property cannot be extracted from the media source, then the respective attribute is set to NULL.

If the format is set to NULL, then the setProperties( ) method uses the default format plug-in; otherwise, it uses the plug-in specified by the format.

Pragmas

None.

Exceptions

DOC_PLUGIN_EXCEPTION

This exception is raised if you call the setProperties( ) method and the media plug-in raises an exception.

Examples

Example 1: Set the property information for known media attributes:

DECLARE
  obj ORDSYS.ORDDoc;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT doc INTO obj FROM tdoc WHERE N =1 FOR UPDATE;
  obj.setProperties(ctx,FALSE);
  --DBMS_OUTPUT.put_line('format: ' || obj.getformat());
  UPDATE  tdoc SET doc = obj WHERE  N =1 ;
  COMMIT;
  EXCEPTION

   WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
    DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');

   WHEN OTHERS THEN
    DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/

Example 2: Set the property information for known media attributes and store the format and application properties in the comments attribute. Create an extensible index on the contents of the comments attribute using Oracle Text.

DECLARE
  obj ORDSYS.ORDDoc;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT doc INTO obj FROM tdoc WHERE N =1 FOR UPDATE;
  obj.setProperties(ctx,TRUE);
  --DBMS_OUTPUT.put_line('format: ' || obj.getformat());
  UPDATE  tdoc SET doc = obj WHERE  N =1 ;
  COMMIT;
  EXCEPTION

   WHEN ORDSYS.ORDDocExceptions.DOC_PLUGIN_EXCEPTION THEN
    DBMS_OUTPUT.put_line('DOC PLUGIN EXCEPTION caught');

   WHEN OTHERS THEN
    DBMS_OUTPUT.put_line('EXCEPTION caught');
END;
/
-- Must have interMedia text installed on your system.
CREATE INDEX mediaindex ON tdoc(doc.comments) INDEXTYPE IS ctxsys.context;

7.4 Packages or PL/SQL Plug-ins

This section presents reference information on the packages or PL/SQL plug-ins provided. Table 7-1 describes the PL/SQL plug-in packages provided in the ORDPLUGINS schema.

Table 7-1 PL/SQL Plug-ins Provided in the ORDPLUGINS Schema

PL/SQL Plug-in Packages	Media Format	MIME Type
ORDPLUGINS.ORDX_DEFAULT_DOC	<format>	Dependent on file format

Section 7.4.1 describes the ORDPLUGINS.ORDX_DEFAULT_DOC package, the method supported, and the level of support. The method supported and the level of support for the PL/SQL plug-in package is described in Table 7-2.

7.4.1 ORDPLUGINS.ORDX_DEFAULT_DOC Package

Use the following provided ORDPLUGINS.ORDX_DEFAULT_DOC package as a guide in developing your own ORDPLUGINS.ORDX_<format>_DOC media format package. This package sets the mimeType field in the setProperties( ) method with a MIME type value that is dependent on the file format.

CREATE OR REPLACE PACKAGE ORDX_DEFAULT_DOC
authid current_user
AS 

PROCEDURE setProperties(ctx IN OUT RAW, 
                        obj IN OUT NOCOPY ORDSYS.ORDDoc,
                        setComments IN NUMBER := 0);

END;
/

Table 7-2 shows the method supported in the ORDPLUGINS.ORDX_DEFAULT_DOC package and the exception raised if the source is null.

Table 7-2 Method Supported in the ORDPLUGINS.ORDX_DEFAULT_DOC Package

Name of Method	Level of Support
setProperties	Supported; if the source is local, process the local data and set the properties, but if the source is NULL, raise an ORDSYS.ORDSourceExceptions.EMPTY_SOURCE exception; if the source is a BFILE, then process the BFILE and set the properties; if the source is neither local nor a BFILE, get the media content into a temporary LOB, process the data, and set the properties.

7.4.2 Extending interMedia to Support a New Media Data Format

Extending interMedia to support a new media data format consists of four steps:

Design your new media data format.
Implement your new media data format and name it, for example, ORDX_MY_DOC.SQL.
Install your new ORDX_MY_DOC.SQL plug-in in the ORDPLUGINS schema.
Grant EXECUTE privileges on your new plug-in, for example, ORDX_MY_DOC.SQL plug-in, to PUBLIC.

Section 3.2.11 briefly describes how to extend interMedia to support a new media data format and describes the interface. A package body listing is provided in Example 7-1 to assist you in this operation. Add your variables to the places that say "--Your variables go here" and add your code to the places that say "--Your code goes here".

See Section F.2 for more information on installing your own media format plug-in and running the sample scripts provided.

Example 7-1 Show the Package Body for Extending Support to a New Media
Data Format

CREATE OR REPLACE PACKAGE BODY ORDX_MY_DOC
AS
  --DOCUMENT ATTRIBUTES ACCESSORS
  PROCEDURE setProperties(ctx IN OUT RAW,
                          obj IN OUT NOCOPY ORDSYS.ORDDoc,
                          setComments IN NUMBER :=FALSE)
  IS
--Your variables go here
  BEGIN
--Your code goes here
  END;
END;
/
show errors;

7 ORDDoc Reference Information

7.1 Object Types

ORDDoc Object Type

7.2 Constructors

init( )

Format

Description

Parameters

Pragmas

Exceptions

Usage Notes

Examples

init(srcType,srcLocation,srcName)

Format

Description

Parameters

Pragmas

Exceptions

Usage Notes

Examples

7.3 Methods

ORDDoc Methods Associated with mimeType Attribute

ORDDoc Methods Associated with the updateTime Attribute

ORDDoc Methods Associated with the format Attribute

ORDDoc Methods Associated with the source Attribute

ORDDoc Methods Associated with File Operations

7.3.1 Example Table Definitions

TDOC Table Definition

getContentInLob( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getContentLength( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getFormat

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

import( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

importFrom( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

setFormat( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

setProperties( )

Format

Description

Parameters

7
ORDDoc Reference Information

Example 7-1 Show the Package Body for Extending Support to a New Media
Data Format