2 Common Methods for interMedia Object Types

This chapter presents reference information on the common methods used for the following Oracle interMedia ("interMedia") object types:

ORDAudio
ORDDoc
ORDImage
ORDVideo

The examples in this chapter use the ONLINE_MEDIA table in the Product Media sample schema. The examples assume that the table has been populated as shown in examples in Chapter 3, Chapter 5, and Chapter 7.

See Oracle Database Sample Schemas for information about the sample schemas.

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.

2.1 Embedded ORDSource Object

The ORDSource object is embedded within the ORDAudio, ORDDoc, and ORDVideo object types. The ORDSource object type supports access to a variety of sources of multimedia data. It supports access to data sources locally in a BLOB within Oracle Database, externally from a BFILE on a local file system, externally from a URL on an HTTP server, or externally from a user-defined source on another server. See Chapter 9 for details on how the ORDSource object type is defined, including supported values for the ORDSource attributes, which are the following:

localData: the locally stored multimedia data stored as a BLOB within the object. Up to 4 gigabytes of data can be stored as a BLOB.
srcType: the data source type.
srcLocation: the place where data can be found based on the srcType value.
srcName: the data object name.
updateTime: the time at which the data was last updated.
local: a flag that indicates whether the data is local (1 or NULL) or external (0).

2.2 Important Notes

Methods invoked at the ORDSource level that are handed off to a source plug-in for processing have ctx (RAW) as the first argument. Before calling any of these methods for the first time, the client should 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) as the first argument. Before calling any of these methods for the first time, the client should allocate the ctx structure and initialize it to NULL.

Note:

In the current release, none of the plug-ins provided by Oracle and not all source or format plug-ins will use the ctx argument, but if you code as previously described, your application should work with current or future source or format plug-ins.

For ORDAudio, ORDDoc, or ORDVideo object types, you should use any of the individual set methods to set the attribute value for an object for formats not natively supported, or write a format plug-in and call the setProperties( ) method; 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 formats that are not natively supported.

2.3 Methods

This section presents reference information on the interMedia methods that are common to all object types (except Still Image objects).

Other methods, which are particular to a given object type or are implemented differently for each object type, are described in ORDAudio Methods, ORDImage Methods, and ORDVideo Methods.

For more information about object types and methods, see Oracle Database Concepts.

The following methods are presented in this section:

clearLocal( )
closeSource( )
deleteContent( )
export( )
getBFile( )
getContent( )
getMimeType( )
getSource( )
getSourceLocation( )
getSourceName( )
getSourceType( )
getUpdateTime( )
isLocal( )
openSource( )
processSourceCommand( )
readFromSource( )
setLocal( )
setMimeType( )
setSource( )
setUpdateTime( )
trimSource( )
writeToSource( )

clearLocal( )

Format

clearLocal( );

Description

Resets the source.local attribute (of the embedded ORDSource object) to indicate that the data is stored externally. When the source.local attribute is set to 0, media methods look for corresponding data using the source.srcLocation, source.srcName, and source.srcType attributes.

Parameters

None.

Usage Notes

This method sets the source.local attribute to 0, meaning the data is stored externally outside the database.

Pragmas

None.

Exceptions

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Clear the value of the local flag for the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT product_audio INTO obj FROM pm.online_media WHERE product_id=1733 
  FOR UPDATE;
 obj.clearLocal();
 UPDATE pm.online_media SET product_audio=obj WHERE product_id=1733;
 COMMIT;
 END;
 /

closeSource( )

Format

closeSource(ctx IN OUT RAW) RETURN INTEGER;

Description

Closes a data source.

Parameters

ctx: The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.

Usage Notes

The RETURN INTEGER is 0 (zero) for success and greater than 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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the closeSource( ) method and the value for the source.srcType attribute is NULL.

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.

See Appendix G for more information about these exceptions.

Examples

Close an external data source:

DECLARE
 obj ORDSYS.ORDAudio;
 res INTEGER;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT product_audio INTO obj FROM pm.online_media WHERE product_id=1733
  FOR UPDATE;
 res := obj.closeSource(ctx);
 UPDATE pm.online_media SET product_audio=obj WHERE product_id=1733;
 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 BLOB from the source.localData attribute (of the embedded ORDSource object), sets the source.local attribute to zero (to indicate that data is not local), and updates the source.updateTime attribute.

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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Delete the local data from the current local source:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT product_photo INTO image FROM pm.online_media WHERE product_id = 3515 FOR UPDATE;
 -- Delete the local content of the image:
 Image.deleteContent();
COMMIT;
END;
/

export( )

Format

export(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Copies data from the BLOB in the source.localData attribute (of the embedded ORDSource object) to a corresponding external data source.

Note:

The export( ) method provides native support only when the value of the source_type parameter is FILE. In this case, the data is written to a file within a directory that is accessible to Oracle Database. User-defined sources may support the export( ) method to provide WRITE access to other types of data stores.

Parameters

ctx: The source plug-in context information.
source_type: The type of the external source data. This parameter is not case sensitive.
source_location: The location to which the source data is to be exported.
source_name: The name of the object to which the data is to be exported.

Usage Notes

After data is exported, all attributes remain unchanged and source.srcType, source.srcLocation, and source.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 source.localData attribute.

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

The export( ) method for a source type of FILE does not modify data stored in the BLOB.

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.

When the source_type parameter has a value of FILE, the source_location parameter specifies the name of an Oracle directory object, and the source_name parameter specifies the name of the file that will contain the data.

The export( ) method writes only to a database directory object that the user has privilege to access. That is, you can access a directory object that you have created using the SQL CREATE DIRECTORY statement, or one to which you have been granted READ and WRITE access.

For example, the following SQL*Plus commands create a directory object and grant the user, RON, the permission to read and write any file within the directory /mydir/work:

CONNECT SYS/<password> AS SYSDBA
CREATE OR REPLACE DIRECTORY FILE_DIR AS '/mydir/work';
GRANT READ,WRITE ON DIRECTORY FILE_DIR TO RON;

Now, the user, RON, can export an image to the testimg.jpg file in this directory using the export( ) method of the ORDImage object:

img.export('FILE', 'FILE_DIR', testimg.jpg');

Invoking this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.IO_ERROR

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

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.

See Appendix G for more information about these exceptions.

Examples

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

-- Create the directory to which you want users to export data. Then,
-- grant write access to the directory for ORDSYS and the user who will be
-- doing the exporting, in this case the user is Ron.
connect /as sysdba
CREATE OR REPLACE DIRECTORY FILE_DIR as '/mydir/work';
GRANT READ,WRITE ON DIRECTORY FILE_DIR TO 'RON';
BEGIN
-- Connect as the user Ron:
CONNECT RON/RON
set serveroutput on;
set echo on;
DECLARE
 obj ORDSYS.ORDImage;
 ctx RAW(64) :=NULL;
BEGIN
SELECT product_photo INTO obj FROM pm.online_media 
 WHERE product_id = 3515;
obj.export(ctx,'file','FILE_DIR','testimg.jpg');
COMMIT;
EXCEPTION
 WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
  DBMS_OUTPUT.PUT_LINE('Source METHOD_NOT_SUPPORTED 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 (of the embedded ORDSource object). 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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if the source.srcType attribute value is NULL.

ORDSourceExceptions.INVALID_SOURCE_TYPE

This exception is raised if the value of the source.srcType attribute is other than "file".

See Appendix G for more information about these exceptions.

Examples

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

DECLARE
 obj ORDSYS.ORDVideo;
 videobfile BFILE;
BEGIN
 SELECT product_video INTO obj FROM pm.online_media
  WHERE product_id = 2030;
 -- Get the video BFILE.
 videobfile := obj.getBFile();
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN
   DBMS_OUTPUT.PUT_LINE('The source.srcType attribute value is NULL');
  WHEN ORDSYS.ORDSourceExceptions.INVALID_SOURCE_TYPE THEN
   DBMS_OUTPUT.PUT_LINE('The value of srcType is not file');
END;
/

getContent( )

Format

getContent( ) RETURN BLOB;

Description

Returns the BLOB handle to the source.localData attribute (of the embedded ORDSource object).

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Access video data to be put on a Web-based player:

DECLARE
 obj ORDSYS.ORDVideo;
 ctx RAW(64) := NULL;
BEGIN
 SELECT product_video INTO obj FROM pm.online_media WHERE product_id = 2030 FOR UPDATE;
 -- import data
 obj.importFrom(ctx,'file','FILE_DIR','printer.rm');
 -- check size
 DBMS_OUTPUT.PUT_LINE('Length is '||TO_CHAR(DBMS_LOB.GETLENGTH(obj.getContent))); DBMS_OUTPUT.PUT_LINE(obj.getSource());
 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

Get the MIME type for some stored image data:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p 
  WHERE product_id = 3515;
 DBMS_OUTPUT.PUT_LINE('writing mimetype');
 DBMS_OUTPUT.PUT_LINE('----------------');
 DBMS_OUTPUT.PUT_LINE(image.getMimeType);
 COMMIT;
END;
/

getSource( )

Format

getSource( ) RETURN VARCHAR2;

Description

Returns information about the external location of the data in URL format. (This information is the source.srcType, source.srcLocation, and source.srcName attribute values of the embedded ORDSource object.)

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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Get the source of the image data:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image source information:
 DBMS_OUTPUT.PUT_LINE(image.getSource);
 COMMIT;
END;
/

getSourceLocation( )

Format

getSourceLocation( ) RETURN VARCHAR2;

Description

Returns a string containing the value of the external data source location (the value of the source.srcLocation attribute of the embedded ORDSource object).

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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_LOCATION

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

See Appendix G for more information about these exceptions.

Examples

Get the source location information about an image data source:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image source location.
 DBMS_OUTPUT.PUT_LINE('Source location is ' || image.getSourceLocation);
 COMMIT;
END;
/

getSourceName( )

Format

getSourceName( ) RETURN VARCHAR2;

Description

Returns a string containing of the name of the external data source (the value of the source.srcName attribute of the embedded ORDSource object).

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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_NAME

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

See Appendix G for more information about these exceptions.

Examples

Get the source name information about an image data source:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image source name.
 DBMS_OUTPUT.PUT_LINE('Source name is ' ||image.getSourceName);
 COMMIT;
END;
/

getSourceType( )

Format

getSourceType( ) RETURN VARCHAR2;

Description

Returns a string containing the type of the external data source (the value of the source.srcType attribute of the embedded ORDSource object).

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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Get the source type information about a media data source:

DECLARE
 obj ORDSYS.ORDDoc;
BEGIN
 SELECT p.product_testimonials INTO obj FROM pm.online_media p 
  WHERE p.product_id= 3060;
 DBMS_OUTPUT.PUT_LINE('setting and getting source');
 DBMS_OUTPUT.PUT_LINE('--------------------------');
 -- set source to a file
 obj.setSource('file','FILE_DIR','speaker.wav');
 -- get source information
 DBMS_OUTPUT.PUT_LINE('Source is ' || obj.getSource);
 DBMS_OUTPUT.PUT_LINE('Source type is ' || obj.getSourceType);
 DBMS_OUTPUT.PUT_LINE('Source location is ' || obj.getSourceLocation);
 DBMS_OUTPUT.PUT_LINE('Source name is ' || obj.getSourceName);
 COMMIT;
END;
/

getUpdateTime( )

Format

getUpdateTime( ) RETURN DATE;

Description

Returns the time when the object was last updated (the value of the source.updateTime of the embedded ORDSource object).

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Get the updated time of some audio data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id  = 1733;
 DBMS_OUTPUT.PUT_LINE('Update time is:');
 DBMS_OUTPUT.PUT_LINE(TO_CHAR(obj.getUpdateTime(),'MM-DD-YYYY HH24:MI:SS'));
 COMMIT;
END;
/

isLocal( )

Format

isLocal( ) RETURN BOOLEAN;

Description

Returns TRUE if the value of the source.local attribute (of the embedded ORDSource object) is 1, and returns FALSE if the value of the source.local attribute is 0. In other words, returns TRUE if the data is stored in a BLOB in the source.localData attribute or FALSE if the data is stored externally.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Determine whether or not the audio data is local:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
   WHERE p.product_id = 1733;
 IF (obj.isLocal() = TRUE) THEN  DBMS_OUTPUT.PUT_LINE('local is set true');
 ELSE  DBMS_OUTPUT.PUT_LINE('local is set false');
 END IF;
 COMMIT;
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

The return INTEGER is 0 (zero) for success and greater than 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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the openSource( ) method and the value for the source.srcType attribute is NULL.

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.

See Appendix G for more information about these exceptions.

Examples

Open an external data source:

DECLARE
 obj ORDSYS.ORDAudio;
 res INTEGER;
 ctx RAW(64) :=NULL;
 userArg RAW(64);
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733;
 res := obj.openSource(userArg, ctx);
 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

Lets you 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 should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter 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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.METHOD_NOT_SUPPORTED

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

See Appendix G for more information about these exceptions.

Examples

None.

readFromSource( )

Format

readFromSource(ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer OUT RAW);

Description

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

Parameters

ctx: The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter 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, you must request that the entire URL source 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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the readFromSource( ) method and the value of the source.srcType attribute 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.NULL_SOURCE

This exception is raised if you call the readFromSource( ) method and the value of source.local is 1 or NULL (TRUE), but the value of the source.localData attribute is NULL.

See Appendix G for more information about these exceptions.

Examples

Read a buffer from the source:

DECLARE
 obj ORDSYS.ORDAudio;
 buffer RAW(4000);
 i INTEGER;
 ctx RAW(64) :=NULL;
BEGIN
 i := 20;
 SELECT p.product_audio into obj from pm.online_media p 
  WHERE p.product_id = 1733;
 obj.readFromSource(ctx,1,i,buffer);
 DBMS_OUTPUT.PUT_LINE('Length is ' || TO_CHAR(obj.getContentLength(ctx)));
 COMMIT;
 EXCEPTION
 WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
 WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION
 caught');
 WHEN ORDSYS.ORDSourceExceptions.NULL_SOURCE THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.NULL_SOURCE caught');
 WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

setLocal( )

Format

setLocal( );

Description

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

Parameters

None.

Usage Notes

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

Pragmas

None.

Exceptions

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

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Set the flag to local for the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT product_audio INTO obj FROM online_media WHERE product_id = 1733;
 obj.setLocal;
 UPDATE online_media SET product_audio = obj WHERE product_id = 1733;
 COMMIT;
END;
/

setMimeType( )

Format

setMimeType(mime IN VARCHAR2);

Description

Lets you 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 process( ) and processCopy( ) also call this method implicitly.

Pragmas

None.

Exceptions

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

This exception can be raised by ORDAudio, ORDDoc, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Set the MIME type for some stored data:

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733 FOR UPDATE;
 DBMS_OUTPUT.PUT_LINE('writing current mimetype');
 DBMS_OUTPUT.PUT_LINE('----------------');
 DBMS_OUTPUT.PUT_LINE(obj.getMimeType);
 DBMS_OUTPUT.PUT_LINE('setting and writing new mimetype');
 DBMS_OUTPUT.PUT_LINE('----------------');
 obj.setMimeType('audio/basic');
 DBMS_OUTPUT.PUT_LINE(obj.getMimeType);
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 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 type of the external source data. See the ORDSource Object Type definition in Chapter 9 for more information.
source_location: The location of the external source data. See the ORDSource Object Type definition in Chapter 9 for more information.
source_name: The name of the external source data. See the ORDSource Object Type definition in Chapter 9 for more information.

Usage Notes

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

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

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

Pragmas

None.

Exceptions

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

See Appendix G for more information about these exceptions.

Examples

Set the source of the data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733 FOR UPDATE;
 DBMS_OUTPUT.PUT_LINE('setting and getting source');
 DBMS_OUTPUT.PUT_LINE('--------------------------');
 obj.setSource('file','FILE_DIR','audio.au');
 DBMS_OUTPUT.PUT_LINE(obj.getSource());
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 COMMIT;
END;
/

setUpdateTime( )

Format

setUpdateTime(current_time DATE);

Description

Sets the time when the data was last updated (the source.srcUpdateTime attribute of the embedded ORDSource object). 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 this method explicitly.

Parameters

current_time: The time stamp 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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

See Appendix G for more information about these exceptions.

Examples

Set the updated time of some data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
SELECT p.product_audio INTO obj FROM pm.online_media p
 WHERE p.product_id = 1733 FOR UPDATE;
DBMS_OUTPUT.PUT_LINE('current update time:');
DBMS_OUTPUT.PUT_LINE(obj.getUpdateTime);
DBMS_OUTPUT.PUT_LINE('set and get new update time:');
 obj.setUpdateTime(SYSDATE);
 DBMS_OUTPUT.PUT_LINE(obj.getUpdateTime);
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 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 should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
newlen: The trimmed new length.

Usage Notes

Pragmas

None.

Exceptions

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the trimSource( ) method and the value for the source.srcType attribute is NULL.

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.

See Appendix G for more information about these exceptions.

Examples

Trim an external data source:

DECLARE
 obj ORDSYS.ORDAudio;
 res INTEGER;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1733 FOR UPDATE;
 res := obj.trimSource(ctx,0);
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.METHOD_NOT_SUPPORTED caught');
 WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN
   DBMS_OUTPUT.PUT_LINE('ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION 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

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

Parameters

ctx: The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter 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 lets you 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

This exception is raised when the value of the <object-type>.source attribute is NULL.

This exception can be raised by ORDAudio, ORDDoc, ORDImage, or ORDVideo object types. Replace <object-type> with the object type to which you apply this method.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the writeToSource( ) method and the value of the source.srcType attribute 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.NULL_SOURCE

This exception is raised if you call the writeToSource( ) method and the value of source.local is 1 or NULL (TRUE), but the value of the source.localData attribute is NULL.

See Appendix G for more information about these exceptions.

Examples

Write a buffer to the source:

DECLARE
 obj ORDSYS.ORDAudio;
 n INTEGER := 6;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p
  WHERE p.product_id = 1743 FOR UPDATE;
 obj.writeToSource(ctx,1,n,UTL_RAW.CAST_TO_RAW('helloP'));
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1743;
 DBMS_OUTPUT.PUT_LINE('Length is ' || TO_CHAR(obj.getContentLength(ctx)));
 -- Roll back the transaction to keep the sample schema unchanged.
 ROLLBACK;
 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;
/