5
Common Methods for interMedia Object Types Reference Information

This chapter presents reference information on the common methods used for the following Oracle interMedia data types:

ORDAudio
ORDDoc
ORDImage
ORDVideo

See Section 5.2 for a list of methods described in this chapter.

The examples in this chapter assume that you have created the test tables as described in Section 6.3.1, Section 7.3.1, Section 8.1.3, and Section 9.3.1.

Note:

The interMedia methods are designed to be internally consistent. If you use interMedia methods (such as import( ) or image process( )) to modify the media data, interMedia will ensure that object attributes remain synchronized with the media data. However, if you manipulate the 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 data.

5.1 Important Notes

Methods invoked at the ORDSource level that are handed off to a 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 at the ORDAudio, ORDDoc, or ORDVideo level that are handed off to a 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 plug-ins and 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 and format plug-in.

For ORDAudio, ORDDoc, or ORDVideo object types, you should use any of the individual set methods to set the value of the attribute for an object for formats not natively supported or write a format plug-in and call setProperties( ); otherwise, for formats natively supported, use the setProperties( ) method to populate the attributes of the object.

For ORDImage object types, use the setProperties( ) method to populate the attributes of the object. Use the setProperties( ) for Foreign Images method for foreign image formats.

5.2 Methods

This section presents reference information on the Oracle interMedia methods that are common to all object types. These common methods are described in the following groupings. Other methods, which are particular to a particular object type or which are implemented differently for the different object types, are described in Section 6.3, Section 7.3, Section 8.1.2, and Section 9.3.

Common Methods Associated with the updateTime Attribute

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

Common Methods Associated with mimeType Attribute

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

Common Methods Associated with the source Attribute

processSourceCommand( ): sends a command and related arguments to the source plug-in. See "processSourceCommand( )" for information.
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 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.
getSourceLocation( ): returns the external source location of the data. See "getSourceLocation( )" for information.
getSourceName( ): returns the external source name of the data. See "getSourceName( )" for information.
getSourceType( ): returns the external source type of the data. See "getSourceType( )" for information.
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.
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.

Common 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.

clearLocal( )

Format

clearLocal( );

Description

Resets the local flag to indicate that the data is stored externally. When the local flag is set to clear, media methods look for corresponding data using the srcLocation, srcName, and srcType attributes.

Parameters

None.

Usage Notes

This method sets the local attribute to a 0, meaning the data is stored externally or outside of Oracle9i.

Pragmas

None.

Exceptions

None.

Examples

Clear the value of the local flag for the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT aud INTO obj FROM TAUD WHERE N = 1 FOR UPDATE;
 obj.clearLocal();
 UPDATE TAUD SET aud=obj WHERE N = 1;
 COMMIT;
END;
/

closeSource( )

Format

closeSource(ctx IN OUT RAW) RETURN INTEGER;

Description

Closes a data source.

Parameters

ctx

The source plug-in context information. You must call the openSource( ) method; see Section 5.1 for more information.

Usage Notes

The return INTEGER is 0 (zero) for success and >0 (for example, 1) for failure. The exact number and the meaning for that number is plug-in defined. For example, for the file plug-in, 1 might mean "File not found," 2 might mean "No such directory," and so forth.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the closeSource( ) method and the value for srcType is NULL and data is not local.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the closeSource( ) 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 closeSource( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Close an external data source:

DECLARE
  obj ORDSYS.ORDAudio;
  res INTEGER;
  ctx RAW(4000) :=NULL;
BEGIN
  SELECT aud INTO obj FROM taud WHERE N =2 FOR UPDATE;
  res := obj.closeSource(ctx);
  UPDATE TAUD SET aud=obj WHERE N=2 ;
  COMMIT;
  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;
/

deleteContent( )

Format

deleteContent( );

Description

Deletes the local data from the current local source (localData).

Parameters

None.

Usage Notes

This method can be called after you export the data from the local source to an external data source and you no longer need this data in the local source.

Call this method when you want to update the object with a new object.

Pragmas

None.

Exceptions

None.

Examples

Delete the local data from the current local source:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe' FOR UPDATE;
    -- delete the local content of the image
    Image.deleteContent();
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

export( )

Format

export(

ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Copies data from a local source (localData) within an Oracle database to a corresponding external data source.

Note:

The export( ) method natively supports only sources of source type file. User-defined sources may support the export( ) method.

Parameters

ctx

The source plug-in context information.

source_type

The source type of the location to where the data is to be exported.

source_location

The location where the data is to be exported.

source_name

The name of the object to where the data is to be exported.

Usage Notes

After exporting data, all attributes remain unchanged and srcType, srcLocation, and srcName are updated with input values. After calling the export( ) method, you can call the clearLocal( ) method to indicate the data is stored outside the database and call the deleteContent( ) method if you want to delete the content of the local data.

This method is also available for user-defined sources that can support the export method.

The export( ) method for a source type of file is similar to a file copy operation in that the original data stored in the BLOB is not touched other than for reading purposes.

The export( ) method is not an exact mirror operation to the import( ) method in that the clearLocal( ) method is not automatically called to indicate the data is stored outside the database, whereas the import( ) method automatically calls the setLocal( ) method.

Call the deleteContent( ) method after calling the export( ) method to delete the content from the database if you no longer intend to manage the multimedia data within the database.

The export( ) method writes only to a directory object that the user has privilege to access. That is, you can access a directory that you have created using the SQL CREATE DIRECTORY statement, or one to which you have been granted READ access. To execute the CREATE DIRECTORY statement, you must have the CREATE ANY DIRECTORY privilege. In addition, you must use the DBMS_JAVA.GRANT_PERMISSION call to specify which files can be written.

For example, the following grants the user, MEDIAUSER, the permission to write to the file named filename.dat:

CALL DBMS_JAVA.GRANT_PERMISSION(
        'MEDIAUSER',
        'java.io.FilePermission',
        '/actual/server/directory/path/filename.dat',
        'write');

See the security and performance section in Oracle9i Java Developer's Guide for more information.

Invoking this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the export( ) 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 export( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

ORDSourceExceptions.IO_ERROR

This exception is raised if the export( ) method encounters an error writing the BLOB data to the file specified.

Examples

Export data from a local source to an external data source.

Note:

You must first create the directory to which you want to export your data. 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 to where you want to export your media files.


-- Create the directory to which you
-- want to export your files.

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

SET ECHO ON;
SET SERVEROUTPUT ON;
CONNECT SYSTEM AS SYSDBA;
BEGIN
  DBMS_JAVA.GRANT_PERMISSION('PUBLIC', 'java.io.FilePermission', 'e:\ORACLE_
HOME>\ord\doc\demo\testdoc.dat',
                             'WRITE');
  COMMIT;
END;
/
DECLARE
  obj ORDSYS.ORDDoc;
  ctx RAW(4000) :=NULL;
BEGIN
   SELECT doc INTO obj FROM tdoc WHERE N = 1 FOR UPDATE;
   obj.export(ctx,'file','DOCDIR','testdoc.dat');
  EXCEPTION
  WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.put_line('Source METHOD_NOT_SUPPORTED caught');
  WHEN ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN
   DBMS_OUTPUT.put_line('SOURCE PLUGIN EXCEPTION caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.put_line('OTHER EXCEPTION caught');
END;
/

getBFILE( )

Format

getBFILE( ) RETURN BFILE;

Description

Returns the LOB locator of the BFILE containing the media.

Parameters

None.

Usage Notes

This method constructs and returns a BFILE using the stored source.srcLocation and source.srcName attribute information. The source.srcLocation attribute must contain a defined directory object. The source.srcName attribute must be a valid file name and source.srcType must be "file".

Pragmas

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

Exceptions

If the source.srcType attribute value is NULL, calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.

If the value of srcType is other than file, then calling this method raises an INVALID_SOURCE_TYPE exception.

Examples

Return the BFILE for the stored source directory and file name attributes:

DECLARE
    obj ORDSYS.ORDVideo;
    videobfile BFILE;
BEGIN
    SELECT vid INTO obj FROM tvid
      WHERE N=1;
    -- get the video BFILE
    videobfile := obj.getBFILE();
END;
/

getContent( )

Format

getContent( ) RETURN BLOB;

Description

Returns a handle to the local BLOB storage, that is the BLOB within the object.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

A client accesses video data to be put on a Web-based player:

DECLARE
  obj ORDSYS.ORDVideo;
BEGIN
  SELECT vid INTO obj FROM TVID  WHERE N=1 FOR UPDATE;
  -- import data
  obj.importFrom(ctx,'file','VIDEODIR','MV1.AVI');
  -- check size
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getContentLength(ctx)));
  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(obj.getContentLength(ctx)));
  UPDATE TVID SET vid=obj WHERE N=1;
  COMMIT;
END;
/

getMimeType( )

Format

getMimeType( ) RETURN VARCHAR2;

Description

Returns the MIME type for the data. This is a simple access method that returns the value of the mimeType attribute.

Parameters

None.

Usage Notes

If the source is an HTTP server, the MIME type information is read from the HTTP header information when the media is imported and stored in the object attribute. If the source is a file or BLOB, the MIME type information is extracted when the setProperties( ) method is called.

For unrecognized file formats, users must call the setMimeType( ) method and specify the MIME type.

Use this method rather than accessing the mimeType attribute directly to protect yourself from potential changes to the internal representation of the object.

Pragmas

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

Exceptions

None.

Examples

Set the MIME type for some stored image data:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- set the image mime type
    Image.setMimeType('image/myformat');
END;
/

getSource( )

Format

getSource( ) RETURN VARCHAR2;

Description

Returns information about the external location of the data in URL format.

Parameters

None.

Usage Notes

Possible return values are:

FILE://<DIR OBJECT NAME>/<FILE NAME> for a file source
HTTP://<URL> for an HTTP source
User-defined source; for example, TYPE://<USER-DEFINED SOURCE LOCATION>/<USER-DEFINED SOURCE NAME>

Pragmas

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

Exceptions

None.

Examples

Get the source of the image data:

DECLARE
    Image ORDSYS.ORDImage;
    SourceInfo VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source information
    SourceInfo := Image.getSource();
END;

getSourceLocation( )

Format

getSourceLocation( ) RETURN VARCHAR2;

Description

Returns a string containing the value of the external data source location.

Parameters

None.

Usage Notes

This method returns a VARCHAR2 string containing the value of the external data location, for example "BFILEDIR".

Pragmas

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

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_LOCATION

This exception is raised if you call the getSourceLocation method and the value of srcLocation is NULL.

Examples

Get the source location information about an image data source:

DECLARE
    Image ORDSYS.ORDImage;
    SourceLocation VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source location
    SourceLocation := Image.getSourceLocation();
END;

getSourceName( )

Format

getSourceName( ) RETURN VARCHAR2;

Description

Returns a string containing of the name of the external data source.

Parameters

None.

Usage Notes

This method returns a VARCHAR2 string containing the name of the external data source, for example "testimg.dat".

Pragmas

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

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_NAME

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

Examples

Get the source name information about an image data source:

DECLARE
    Image ORDSYS.ORDImage;
    SourceName VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source name
    SourceName := Image.getSourceName();
END;

getSourceType( )

Format

getSourceType( ) RETURN VARCHAR2;

Description

Returns a string containing the type of the external data source.

Parameters

None.

Usage Notes

Returns a VARCHAR2 string containing the type of the external data source, for example "file".

Pragmas

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

Exceptions

None.

Examples

Get the source type information about a media data source:

DECLARE
  obj ORDSYS.ORDDoc;
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());
  DBMS_OUTPUT.put_line(obj.getSourceType());
  DBMS_OUTPUT.put_line(obj.getSourceLocation());
  DBMS_OUTPUT.put_line(obj.getSourceName());
  UPDATE TDOC SET doc=obj WHERE N=1;
  COMMIT;
END;
/

getUpdateTime( )

Format

getUpdateTime( ) RETURN DATE;

Description

Returns the time when the object was last updated.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

Get the updated time of some audio data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT aud INTO obj FROM TAUD WHERE N = 1 ;
 DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getUpdateTime(),'MM-DD-YYYY HH24:MI:SS'));
END;
/

isLocal( )

Format

isLocal( ) RETURN BOOLEAN;

Description

Returns TRUE if the data is stored locally in a BLOB or FALSE if the data is stored externally.

Parameters

None.

Usage Notes

If the local attribute is set to 1 or NULL, this method returns TRUE, otherwise this method returns FALSE.

Pragmas

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

Exceptions

None.

Examples

Determine whether or not the audio data is local:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT aud INTO obj FROM TAUD WHERE N = 1 ;
 if(obj.isLocal() = TRUE)  then
    DBMS_OUTPUT.put_line('local is set true');
 else
    DBMS_OUTPUT.put_line('local is set false');
 end if;
END;
/

openSource( )

Format

openSource(userArg IN RAW, ctx OUT RAW) RETURN INTEGER;

Description

Opens a data source.

Parameters

userArg

The user argument. This may be used by user-defined source plug-ins.

ctx

The source plug-in context information.

Usage Notes

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the openSource( ) method and the value for srcType is NULL and data is not local.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the openSource( ) 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 openSource( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Open an external data source:

DECLARE
  obj ORDSYS.ORDAudio;
  res INTEGER;
  ctx RAW(4000) :=NULL;
  userArg RAW(4000);
BEGIN
  SELECT aud INTO obj FROM taud WHERE N =1 FOR UPDATE;
  res := obj.openSource(userArg, ctx);
  UPDATE taud SET aud=obj WHERE N=1 ;
  COMMIT;
  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;
/

processSourceCommand( )

Format

processSourceCommand(

ctx IN OUT RAW,

cmd IN VARCHAR2,

arguments IN VARCHAR2,

result OUT RAW)

RETURN RAW;

Description

Allows you to send any command and its arguments to the source plug-in. This method is available only for user-defined source plug-ins.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the openSource( ) method; see Section 5.1 for more information.

cmd

Any command recognized by the source plug-in.

arguments

The arguments of the command.

result

The result of calling this method returned by the source plug-in.

Usage Notes

Use this method to send any command and its respective arguments to the source plug-in. Commands are not interpreted; they are just taken and passed through to be processed.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the processSourceCommand( ) 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 processSourceCommand( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Process some commands:

DECLARE
  obj ORDSYS.ORDVideo;
  res RAW(4000);
  result RAW(4000);
  command VARCHAR(4000);
  argList VARCHAR(4000);
  ctx RAW(4000) :=NULL;
BEGIN
select vid into obj from TVID where N =1 for UPDATE;
-- assign command
-- assign argList
res := obj.processSourceCommand(ctx, command, argList, result);
UPDATE TVID SET vid=obj WHERE N=1 ;
COMMIT;
  EXCEPTION
        WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
         DBMS_OUTPUT.put_line('Source METHOD_NOT_SUPPORTED caught');
        WHEN ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN
         DBMS_OUTPUT.put_line('SOURCE PLUGIN EXCEPTION caught');
        WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN
         DBMS_OUTPUT.put_line('SOURCE INCOMPLETE_SOURCE_INFORMATION EXCEPTION 
caught');
        WHEN OTHERS THEN
         DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

readFromSource( )

Format

readFromSource(

ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer OUT RAW);

Description

Allows you to read a buffer of n bytes from a source beginning at a start position.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the openSource( ) method; see Section 5.1 for more information.

startPos

The start position in the data source.

numBytes

The number of bytes to be read from the data source.

buffer

The buffer into which the data will be read.

Usage Notes

This method is not supported for HTTP sources.

To successfully read HTTP source types, the entire URL source must be requested to be read. If you want to implement a read method for an HTTP source type, you must provide your own implementation for this method in the modified source plug-in for the HTTP source type.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the readFromSource( ) method and the value of srcType is NULL and data is not local.

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the readFromSource( ) method and the data is local but localData is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the readFromSource( ) 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 readFromSource( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Read a buffer from the source:

DECLARE
  obj ORDSYS.ORDAudio;
  buffer RAW(4000);
  i INTEGER;
  ctx RAW(4000) :=NULL;
BEGIN
  i := 20;
  select aud into obj from TAUD where N =1 ;
  obj.readFromSource(ctx,1,i,buffer);
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getContentLength(ctx)));
  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;

setLocal( )

Format

setLocal( );

Description

Sets the local attribute to indicate that the data is stored internally in a BLOB. When local is set, methods look for corresponding data in the source.localData attribute.

Parameters

None.

Usage Notes

This method sets the local attribute to 1 meaning the data is stored locally in localData.

Pragmas

None.

Exceptions

NULL_LOCAL_DATA

This exception is raised if you call the setLocal method and the source.localData attribute value is NULL.

Examples

Set the flag to local for the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT s INTO obj FROM TAUD WHERE N = 1 FOR UPDATE;
 obj.setLocal();
 UPDATE TAUD SET s=obj WHERE N = 1;
 COMMIT;
END;
/

setMimeType( )

Format

setMimeType(mime IN VARCHAR2);

Description

Allows you to set the MIME type of the data.

Parameters

mime

The MIME type.

Usage Notes

You can override the automatic setting of MIME information by calling this method with a specified MIME value.

Calling this method implicitly calls the setUpdateTime( ) method.

The method setProperties( ) calls this method implicitly.

For image objects, the methods setProperties( ), process( ), and processCopy( ) call this method implicitly.

Pragmas

None.

Exceptions

INVALID_MIME_TYPE

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

Examples

Set the MIME type for some stored data:

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
  SELECT aud INTO obj FROM TAUD  WHERE N=1 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('writing mimetype');
  DBMS_OUTPUT.PUT_LINE('----------------');
  obj.setMimeType('audio/basic');
  DBMS_OUTPUT.PUT_LINE(obj.getMimeType);
  UPDATE TAUD SET aud=obj WHERE N=1;
  COMMIT;
END;
/

setSource( )

Format

setSource(

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Sets or alters information about the external source of the data.

Parameters

source_type

The source type of the external data. See the ORDSource Object Type definition in Appendix I for more information.

source_location

The source location of the external data. See the ORDSource Object Type definition in Appendix I for more information.

source_name

The source name of the external data. See the ORDSource Object Type definition in Appendix I for more information.

Usage Notes

Users can use this method to set the data source to a new BFILE or URL.

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

Calling this method implicitly calls the setUpdateTime( ) method and the clearLocal( ) method.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

Examples

Set the source of the data:

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
  SELECT aud INTO obj FROM TAUD  WHERE N=1 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('setting and getting source');
  DBMS_OUTPUT.PUT_LINE('--------------------------');
  obj.setSource('file','AUDIODIR','audio.au');
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  UPDATE TAUD SET aud=obj WHERE N=1;
  COMMIT;
END;
/

setUpdateTime( )

Format

setUpdateTime(current_time DATE);

Description

Sets the time when the data was last updated. Use this method whenever you modify the data. Methods that modify the object attributes and all set media access methods call this method implicitly. For example, the methods setMimeType( ), setSource( ), and deleteContent( ) call setUpdateTime( ) explicitly.

Parameters

current_time

The timestamp to be stored. Defaults to SYSDATE.

Usage Notes

You must invoke this method whenever you modify the data without using object methods.

Pragmas

None.

Exceptions

None.

Examples

Set the updated time of some data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT aud INTO obj FROM TAUD WHERE N = 1;
 obj.setUpdateTime(SYSDATE);
 UPDATE TAUD SET aud=obj WHERE N = 1;
 COMMIT;
END;

trimSource( )

Format

trim(ctx IN OUT RAW,

newlen IN INTEGER) RETURN INTEGER;

Description

Trims a data source.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the openSource( ) method; see Section 5.1 for more information.

newlen

The trimmed new length.

Usage Notes

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the trimSource( ) method and the value for srcType is NULL and data is not local.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the trimSource( ) 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 trimSource( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Trim an external data source:

DECLARE
  obj ORDSYS.ORDAudio;
  res INTEGER;
  ctx RAW(4000) :=NULL;
BEGIN
  select aud into obj from TAUD where N =1 for UPDATE;
  res := obj.trimSource(ctx,0);
  UPDATE TAUD SET aud=obj WHERE N=1 ;
  COMMIT;
  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;
/

writeToSource( )

Format

writeToSource(

ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer IN RAW);

Description

Allows you to write a buffer of n bytes to a source beginning at a start position.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the openSource( ) method; see Section 5.1 for more information.

startPos

The start position in the source to where the buffer should be copied.

numBytes

The number of bytes to be written to the source.

buffer

The buffer of data to be written.

Usage Notes

This method assumes that the source allows you to write n number of bytes starting at a random byte location. The file and HTTP source types will not permit you to write, and do not support this method. This method will work if data is stored in a local BLOB or is accessible through a user-defined source plug-in.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the writeToSource( ) method and the value of srcType is NULL and data is not local.

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the writeToSource( ) method and the data is local but localData is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the writeToSource( ) 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 writeToSource( ) method within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

Write a buffer to the source:

DECLARE
  obj ORDSYS.ORDAudio;
  n INTEGER := 6;
  ctx RAW(4000) :=NULL;
BEGIN
  select aud into obj from TAUD where N =1 for update;
  obj.writeToSource(ctx,1,n,UTL_RAW.CAST_TO_RAW('helloP'));
  DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getContentLength(ctx)));
  update  TAUD set aud = obj where  N =1 ;
  COMMIT;
  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;
/

5 Common Methods for interMedia Object Types Reference Information

5.1 Important Notes

5.2 Methods

Common Methods Associated with the updateTime Attribute

Common Methods Associated with mimeType Attribute

Common Methods Associated with the source Attribute

Common Methods Associated with File Operations

clearLocal( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

closeSource( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

deleteContent( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

export( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getBFILE( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getContent( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getMimeType( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getSource( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getSourceLocation( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getSourceName( )

5
Common Methods for interMedia Object Types Reference Information