3 ORDAudio

Oracle Multimedia contains the following information about the ORDAudio object type:

ORDAudio Object Type
ORDAudio Constructors
ORDAudio Methods

3.1 ORDAudio Object Examples

The examples in this chapter use the ONLINE_MEDIA table in the Product Media sample schema. To replicate the examples on your own computer, you should begin with the examples shown in the reference pages for the ORDAudio constructors and the import( ) and importFrom( ) methods. Substitute audio files you have for the ones shown in the examples. In addition, for a user ron to use the examples, the following statements must be issued before ron executes the examples, where /mydir/work is the directory where ron will find the audio data:

CONNECT /as sysdba
CREATE OR REPLACE DIRECTORY FILE_DIR as '/mydir/work';
GRANT READ ON DIRECTORY FILE_DIR TO 'ron';

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

Note:

If you manipulate the audio 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 audio data.

3.2 Important Notes

Methods invoked at the ORDSource level that are handed off to the 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 from a source plug-in call have the first argument as ctx (RAW).

Methods invoked at the ORDAudio level that are handed off to the 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.

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

ORDAudio Object Type

The ORDAudio object type supports the storage and management of audio data. This object type is defined as follows in the ordaspec.sql file:

CREATE OR REPLACE TYPE ORDAudio
AS OBJECT
(
  -- ATTRIBUTES 
description         VARCHAR2(4000),
source              ORDSource,
format              VARCHAR2(31),
mimeType            VARCHAR2(4000),
comments            CLOB, 
  -- AUDIO RELATED ATTRIBUTES 
encoding            VARCHAR2(256),
numberOfChannels    INTEGER,
samplingRate        INTEGER,
sampleSize          INTEGER,
compressionType     VARCHAR2(4000),
audioDuration       INTEGER,

  -- METHODS 
-- CONSTRUCTORS
--
STATIC FUNCTION init( ) RETURN ORDAudio,
STATIC FUNCTION init(srcType     IN VARCHAR2,
                     srcLocation IN VARCHAR2,
                     srcName     IN VARCHAR2) RETURN ORDAudio,
--
-- 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 description attribute
MEMBER PROCEDURE setDescription(user_description IN VARCHAR2),
MEMBER FUNCTION getDescription( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getDescription, WNDS, WNPS, RNDS, RNPS),
--
-- 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 source attribute
MEMBER FUNCTION processSourceCommand(ctx       IN OUT RAW,
                                     cmd       IN VARCHAR2,
                                     arguments IN VARCHAR2,
                                     result    OUT RAW)
                RETURN RAW,
--
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 import(ctx IN OUT RAW),
MEMBER PROCEDURE importFrom(ctx             IN OUT RAW,
                            source_type     IN VARCHAR2,
                            source_location IN VARCHAR2, 
                            source_name     IN VARCHAR2),
MEMBER PROCEDURE export(ctx             IN OUT RAW,
                        source_type     IN VARCHAR2,
                        source_location IN VARCHAR2,
                        source_name     IN VARCHAR2),
--
MEMBER FUNCTION  getContentLength RETURN INTEGER,
--
MEMBER FUNCTION getContentLength(ctx IN OUT RAW) RETURN INTEGER,
--
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( ),
--
-- Methods associated with file operations on the source
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), 
--
-- Methods associated with audio attributes accessors
MEMBER PROCEDURE setFormat(knownformat IN VARCHAR2),
MEMBER FUNCTION getFormat( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getFormat, WNDS, WNPS, RNDS, RNPS),
--
MEMBER PROCEDURE setEncoding(knownEncoding IN VARCHAR2),
MEMBER FUNCTION getEncoding( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getEncoding, WNDS, WNPS, RNDS, RNPS),
--
MEMBER PROCEDURE setNumberOfChannels(knownNumberOfChannels IN INTEGER),
MEMBER FUNCTION getNumberOfChannels( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getNumberOfChannels, WNDS, WNPS, RNDS, RNPS),
--
MEMBER PROCEDURE setSamplingRate(knownSamplingRate IN INTEGER),
MEMBER FUNCTION getSamplingRate( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getSamplingRate, WNDS, WNPS, RNDS, RNPS),
--
MEMBER PROCEDURE setSampleSize(knownSampleSize IN INTEGER),
MEMBER FUNCTION getSampleSize( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getSampleSize, WNDS, WNPS, RNDS, RNPS),
--
MEMBER PROCEDURE setCompressionType(knownCompressionType IN VARCHAR2),
MEMBER FUNCTION getCompressionType( ) RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getCompressionType, WNDS, WNPS, RNDS, RNPS),
--
MEMBER PROCEDURE setAudioDuration(knownAudioDuration IN INTEGER),
MEMBER FUNCTION getAudioDuration( ) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getAudioDuration, WNDS, WNPS, RNDS, RNPS),
--
MEMBER FUNCTION getBFILE( ) RETURN BFILE,
PRAGMA RESTRICT_REFERENCES(getBFILE, WNDS, WNPS, RNDS, RNPS),
--
MEMBER PROCEDURE setKnownAttributes(knownFormat IN VARCHAR2,
                                    knownEncoding IN VARCHAR2,
                                    knownNumberOfChannels IN INTEGER,
                                    knownSamplingRate IN INTEGER,
                                    knownSampleSize IN INTEGER,
                                    knownCompressionType IN VARCHAR2,
                                    knownAudioDuration IN INTEGER),
--
-- Methods associated with setting all the properties
MEMBER PROCEDURE setProperties(ctx IN OUT RAW),
MEMBER PROCEDURE setProperties(ctx         IN OUT RAW,
                               setComments IN BOOLEAN),
MEMBER FUNCTION checkProperties(ctx IN OUT RAW) RETURN BOOLEAN,
--
MEMBER FUNCTION getAttribute(ctx  IN OUT RAW,
                             name IN VARCHAR2) RETURN VARCHAR2,
--
MEMBER PROCEDURE getAllAttributes(ctx        IN OUT RAW, 
                                  attributes IN OUT NOCOPY CLOB), 
--
-- Methods associated with audio processing
MEMBER FUNCTION processAudioCommand(
                                    ctx       IN OUT RAW, 
                                    cmd       IN VARCHAR2, 
                                    arguments IN VARCHAR2, 
                                    result    OUT RAW)
                RETURN RAW
);

where:

description: the description of the audio object.
source: the ORDSource where the audio data is to be found.
format: the format in which the audio data is stored.
mimeType: the MIME type information.
comments: the metadata information of the audio object.
encoding: the encoding type of the audio data.
numberOfChannels: the number of audio channels in the audio data.
samplingRate: the rate in Hz at which the audio data was recorded.
sampleSize: the sample width or number of samples of audio in the data.
compressionType: the compression type of the audio data.
audioDuration: the total duration of the audio data stored.

Note:

The comments attribute is populated by the setProperties( ) method when the setComments parameter is TRUE. Oracle recommends that you not write to this attribute directly.

ORDAudio Constructors

This section describes the ORDAudio constructor functions, which are the following:

init( ) for ORDAudio
init(srcType,srcLocation,srcName) for ORDAudio

init( ) for ORDAudio

Format

init( ) RETURN ORDAudio;

Description

Initializes instances of the ORDAudio object type.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

This constructor is a static method that initializes all the ORDAudio 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 ORDAudio object type, especially if the ORDAudio 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 ORDAudio object attributes:

BEGIN
 INSERT INTO pm.online_media (product_id, product_audio) 
 VALUES (1729, ORDSYS.ORDAudio.init());
 COMMIT;
END;
/

init(srcType,srcLocation,srcName) for ORDAudio

Format

init(srcType IN VARCHAR2,

srcLocation IN VARCHAR2,

srcName IN VARCHAR2)

RETURN ORDAudio;

Description

Initializes instances of the ORDAudio object type.

Parameters

srcType: The source type of the audio data.
srcLocation: The source location of the audio data.
srcName: The source name of the audio data.

Pragmas

None.

Exceptions

None.

Usage Notes

This constructor is a static method that initializes all the ORDAudio 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 ORDAudio object attributes:

BEGIN
   INSERT INTO pm.online_media (product_id, product_audio) 
  VALUES (1733, ORDSYS.ORDAudio.init('FILE', 'FILE_DIR','speaker.au')); 
 COMMIT;
END;
/

ORDAudio Methods

This section presents reference information on the Oracle Multimedia methods used specifically for audio data manipulation.

Chapter 2 presents reference information on the Oracle Multimedia methods that are common to ORDAudio, ORDDoc, ORDImage, and ORDVideo. Use the methods presented in both chapters to get and set attributes, and to perform metadata extractions.

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

The following methods are presented in this section:

checkProperties( )
getAllAttributes( )
getAttribute( )
getAudioDuration( )
getCompressionType( )
getContentLength( )
getContentInLob( )
getDescription( )
getEncoding( )
getFormat( )
getNumberOfChannels( )
getSampleSize( )
getSamplingRate( )
import( )
importFrom( )
processAudioCommand( )
setAudioDuration( )
setCompressionType( )
setDescription( )
setEncoding( )
setFormat( )
setKnownAttributes( )
setNumberOfChannels( )
setProperties( )
setSamplingRate( )
setSampleSize( )

checkProperties( )

Format

checkProperties(ctx IN OUT RAW) RETURN BOOLEAN;

Description

Checks the properties of the stored audio data, including the following audio attributes: sample size, sample rate, number of channels, format, and encoding type.

Parameters

ctx: The format plug-in context information.

Usage Notes

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

The checkProperties( ) method does not check the MIME type because a file can have multiple correct MIME types.

Pragmas

None.

Exceptions

ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

Check property information for known audio attributes:

DECLARE
 obj ORDSYS.ORDAudio;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
 WHERE p.product_id  = 1729;
 IF ( obj.checkProperties(ctx) =  TRUE ) THEN 
  DBMS_OUTPUT.PUT_LINE('true');
 ELSE
  DBMS_OUTPUT.PUT_LINE('false');
 END IF;
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION THEN
   DBMS_OUTPUT.PUT_LINE('ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

getAllAttributes( )

Format

getAllAttributes(ctx IN OUT RAW,

attributes IN OUT NOCOPY CLOB);

Description

Returns a formatted string for convenient client access. For natively supported formats, the string includes the following list of audio data attributes separated by a comma (,): fileFormat, mimeType, encoding, numberOfChannels, samplingRate, sampleSize, compressionType, and audioDuration. For user-defined formats, the string is defined by the format plug-in.

Parameters

ctx: The format plug-in context information.
attributes: The attributes.

Usage Notes

Generally, these audio data attributes are available from the header of the formatted audio data.

Pragmas

None.

Exceptions

ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

Return all audio attributes for audio data stored in the database:

DECLARE
 obj ORDSYS.ORDAudio;
 tempLob   CLOB;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 1729;
 DBMS_OUTPUT.PUT_LINE('getting comma separated list of all attributes');
 DBMS_OUTPUT.PUT_LINE('-------------------------------------------');
 DBMS_LOB.CREATETEMPORARY(tempLob, FALSE, DBMS_LOB.CALL);
 obj.getAllAttributes(ctx,tempLob);
 DBMS_OUTPUT.PUT_LINE(DBMS_LOB.substr(tempLob, DBMS_LOB.getLength(tempLob),1));
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION THEN
   DBMS_OUTPUT.PUT_LINE('ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION caught');
END;
/

getAttribute( )

Format

getAttribute(ctx IN OUT RAW,

name IN VARCHAR2)

RETURN VARCHAR2;

Description

Returns the value of the requested attribute from audio data for user-defined formats only.

Parameters

ctx: The format plug-in context information.
name: The name of the attribute.

Usage Notes

Generally, the audio data attributes are available from the header of the formatted audio data.

Audio data attribute information can be extracted from the audio data itself. You can extend support to a format not understood by the ORDAudio object by implementing an ORDPLUGINS.ORDX_<format>_AUDIO package that supports that format. See Oracle Multimedia User's Guide for more information.

Pragmas

None.

Exceptions

ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

Return information for the specified audio attribute for audio data stored in the database. (Because this example uses a supported data format, rather than a user-written plug-in, an exception will be raised.)

DECLARE
 obj ORDSYS.ORDAudio;
 res VARCHAR2(4000);
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 1733;
 DBMS_OUTPUT.PUT_LINE('getting audio sample size');
 DBMS_OUTPUT.PUT_LINE('---------------------');
 res := obj.getAttribute(ctx,'sample_size');
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION THEN
   DBMS_OUTPUT.PUT_LINE('AUDIO PLUGIN EXCEPTION caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

getAudioDuration( )

Format

getAudioDuration( ) RETURN INTEGER;

Description

Returns the value of the audioDuration attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

See the example in setKnownAttributes( ).

getCompressionType( )

Format

getCompressionType( ) RETURN VARCHAR2;

Description

Returns the value of the compressionType attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

See the example in setKnownAttributes( ).

getContentLength( )

Format

getContentLength(ctx IN OUT RAW) RETURN INTEGER;

Description

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

Parameters

ctx: The source plug-in context information.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

See Appendix H for more information about these exceptions.

Examples

See the example in import( ).

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 the source.localData attribute (of the embedded ORDSource object).

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute 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.

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.ORDAudio;
 tempBLob BLOB;
 mimeType VARCHAR2(4000);
 format VARCHAR2(31);
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 1733;
 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('Length is ' || TO_CHAR(DBMS_LOB.getLength(tempBLob)));
 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;
/

getDescription( )

Format

getDescription( ) RETURN VARCHAR2;

Description

Returns the description of the audio data.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

ORDAudioExceptions.DESCRIPTION_IS_NOT_SET

This exception is raised if you call the getDescription( ) method and the description is not set.

See Appendix H for more information about this exception.

Examples

Get the description attribute for some audio data:

DECLARE
  obj ORDSYS.ORDAudio;
BEGIN
-- This example assumes that the setDescription method has already been applied.
  SELECT p.product_audio INTO obj FROM pm.online_media p 
    WHERE p.product_id  = 1733 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('Current description is:');
  DBMS_OUTPUT.PUT_LINE('-------------');
  DBMS_OUTPUT.PUT_LINE(obj.getDescription());
  COMMIT;
END;
/

getEncoding( )

Format

getEncoding( ) RETURN VARCHAR2;

Description

Returns the value of the encoding attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

See the example in setProperties( ).

getFormat( )

Format

getFormat( ) RETURN VARCHAR2;

Description

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

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

ORDAudioExceptions.AUDIO_FORMAT_IS_NULL

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

See Appendix H for more information about this exception.

Examples

See the example in setProperties( ).

getNumberOfChannels( )

Format

getNumberOfChannels( ) RETURN INTEGER;

Description

Returns the value of the numberOfChannels attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

See the example in setProperties( ).

getSampleSize( )

Format

getSampleSize( ) RETURN INTEGER;

Description

Returns the value of the sampleSize attribute of the audio object.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

See the example in setProperties( ).

getSamplingRate( )

Format

getSamplingRate( ) IN INTEGER;

Description

Returns the value of the samplingRate attribute of the audio object. The unit is Hz.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

See the example in setProperties( ).

import( )

Format

import(ctx IN OUT RAW);

Description

Transfers audio data from an external audio data source to the source.localData attribute (of the embedded ORDSource object).

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, call the openSource( ) method. See Section 3.2 for more information.

Usage Notes

Use the setSource( ) method to set the source.srcType, source.srcLocation, and source.srcName attributes (of the embedded ORDSource object) for the external source prior to calling the import( ) method.

You must ensure that the directory for the external source location exists or is created before you use this method when the source.srcType attribute value is "file".

After importing data from an external audio data source to a local source (within 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.

This method is invoked at the ORDSource level, which uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on Linux and UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package will use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server will not be used for URLs in the specified domain.

See Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_HTTP PL/SQL package.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.METHOD_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.NULL_SOURCE

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

See Appendix H for more information about these exceptions.

Examples

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

DECLARE
  obj ORDSYS.ORDAudio;
  ctx RAW(64) := NULL;
BEGIN
   SELECT p.product_audio INTO obj FROM pm.online_media p 
     WHERE p.product_id  = 1733 FOR UPDATE;
  DBMS_OUTPUT.PUT_LINE('getting source');
  DBMS_OUTPUT.PUT_LINE('--------------------------');
  -- get source information
  DBMS_OUTPUT.PUT_LINE(obj.getSource());
  -- import data
  obj.import(ctx);
  -- check size
  DBMS_OUTPUT.PUT_LINE('Length is ' || TO_CHAR(obj.getContentLength(ctx)));
  UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
  COMMIT;
END;
/

importFrom( )

Format

importFrom(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Transfers audio data from the specified external audio data source to the source.localData attribute (of the embedded ORDSource object type) within the database.

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, call the openSource( ) method. See Section 3.2 for more information.
source_type: The type of the source audio data.
source_location: The location from which the source audio data is to be imported.
source_name: The name of the source audio data.

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 indicated by the source_location parameter exists or is created before you use this method with a source_type parameter value of "file".

After importing data from an external audio data source to a local source (within 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.

See Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_HTTP PL/SQL package.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

ORDSourceExceptions.METHOD_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.NULL_SOURCE

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

See Appendix H for more information about these exceptions.

Examples

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

DECLARE
 obj ORDSYS.ORDAudio;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 1729 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','FILE_DIR','birds.wav');
 -- check size
 DBMS_OUTPUT.PUT_LINE('Length is ' || TO_CHAR(obj.getContentLength(ctx)));
 DBMS_OUTPUT.PUT_LINE(obj.getSource());
 UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1729;
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.PUT_LINE('Source not specified');
 END;
/

processAudioCommand( )

Format

processAudioCommand(ctx IN OUT RAW,

cmd IN VARCHAR2,

arguments IN VARCHAR2,

result OUT RAW)

RETURN RAW;

Description

Lets you send a command and related arguments to the format plug-in for processing.

Note:

This method is supported only for user-defined format plug-ins.

Parameters

ctx: The format plug-in context information.
cmd: Any command recognized by the format plug-in.
arguments: The arguments of the command.
result: The result of calling this method returned by the format plug-in.

Usage Notes

Use this method to send any audio commands and their respective arguments to the format plug-in. Commands are not interpreted; they are taken and passed through to a format plug-in to be processed.

To use your user-defined format plug-in, you must set the format attribute to a user-defined format for which you have implemented a plug-in that supports the processAudioCommand( ).

You can extend support to a format that is not understood by the ORDAudio object by preparing an ORDPLUGINS.ORDX_<format>_AUDIO package that supports that format. See Oracle Multimedia User's Guide for more information.

Pragmas

None.

Exceptions

ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

None.

setAudioDuration( )

Format

setAudioDuration(knownAudioDuration IN INTEGER);

Description

Sets the value of the audioDuration attribute of the audio object.

Parameters

knownAudioDuration: A known audio duration.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_INPUT_VALUE

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

See the example in setFormat( ).

setCompressionType( )

Format

setCompressionType(knownCompressionType IN VARCHAR2);

Description

Sets the value of the compressionType attribute of the audio object.

Parameters

knownCompressionType: A known compression type.

Usage Notes

The value of the compressionType always matches that of the encoding value because in many audio formats, encoding and compression type are tightly integrated. See Appendix A for more information.

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_INPUT_VALUE

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

See the example in setFormat( ).

setDescription( )

Format

setDescription (user_description IN VARCHAR2);

Description

Sets the description of the audio data.

Parameters

user_description: The description of the audio data.

Usage Notes

Each audio object may need a description to help some client applications. For example, a Web-based client can show a list of audio descriptions from which a user can select one to access the audio data.

Web-access components and other client components provided with Oracle Multimedia make use of this description attribute to present audio data to users.

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about this exception.

Examples

Set the description attribute for some audio 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 new title');
  DBMS_OUTPUT.PUT_LINE('-------------');
  obj.setDescription('This is audio for product 1733');
  DBMS_OUTPUT.PUT_LINE(obj.getDescription());
  UPDATE pm.online_media p SET p.product_audio = obj WHERE p.product_id = 1733;
  COMMIT;
END;
/

setEncoding( )

Format

setEncoding(knownEncoding IN VARCHAR2);

Description

Sets the value of the encoding attribute of the audio object.

Parameters

knownEncoding: A known encoding type.

Usage Notes

The value of encoding always matches that of the compressionType value because in many audio formats, encoding and compression type are tightly integrated. See Appendix A for more information.

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_INPUT_VALUE

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

See the example in setFormat( ).

setFormat( )

Format

setFormat(knownFormat IN VARCHAR2);

Description

Sets the format attribute of the audio object.

Parameters

knownFormat: The known format of the audio data to be set in the audio object.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_INPUT_VALUE

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

Set the format (and other attributes) for some audio data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 1733 FOR UPDATE;
 obj.setFormat('AUFF');
 obj.setEncoding('MULAW');
 obj.setNumberOfChannels(1);
 obj.setSamplingRate(8);
 obj.setSampleSize(8);
 obj.setCompressionType('8BITMONOAUDIO');
 obj.setAudioDuration(16);
 DBMS_OUTPUT.PUT_LINE('format: ' || obj.getFormat());
 DBMS_OUTPUT.PUT_LINE('encoding: ' || obj.getEncoding());
 DBMS_OUTPUT.PUT_LINE(
                      'numberOfChannels: ' || TO_CHAR(obj.getNumberOfChannels()));
 DBMS_OUTPUT.PUT_LINE('samplingRate: ' || TO_CHAR(obj.getSamplingRate()));
 DBMS_OUTPUT.PUT_LINE('sampleSize: ' || TO_CHAR(obj.getSampleSize()));
 DBMS_OUTPUT.PUT_LINE('compressionType : ' || obj.getCompressionType());
 DBMS_OUTPUT.PUT_LINE('audioDuration: ' || TO_CHAR(obj.getAudioDuration()));
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.NULL_INPUT_VALUE THEN
   DBMS_OUTPUT.PUT_LINE('ORDAudioExceptions.NULL_INPUT_VALUE caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

setKnownAttributes( )

Format

setKnownAttributes(knownFormat IN VARCHAR2,

knownEncoding IN VARCHAR2,

knownNumberOfChannels IN INTEGER,

knownSamplingRate IN INTEGER,

knownSampleSize IN INTEGER,

knownCompressionType IN VARCHAR2,

knownAudioDuration IN INTEGER);

Description

Sets the known audio attributes for the audio object.

Parameters

knownFormat: The known format.
knownEncoding: The known encoding type.
knownNumberOfChannels: The known number of channels.
knownSamplingRate: The known sampling rate.
knownSampleSize: The known sample size.
knownCompressionType: The known compression type.
knownAudioDuration: The known audio duration.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about this exception.

Examples

Set the known attributes for the audio data:

DECLARE
 obj ORDSYS.ORDAudio;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 1733 FOR UPDATE;
 obj.setKnownAttributes('AUFF','MULAW', 1, 8, 8, '8BITMONOAUDIO',16);
 DBMS_OUTPUT.PUT_LINE('format: ' || obj.getFormat());
 DBMS_OUTPUT.PUT_LINE('encoding: ' || obj.getEncoding());
 DBMS_OUTPUT.PUT_LINE(
                   'numberOfChannels: ' || TO_CHAR(obj.getNumberOfChannels()));
 DBMS_OUTPUT.PUT_LINE('samplingRate: ' || TO_CHAR(obj.getSamplingRate()));
 DBMS_OUTPUT.PUT_LINE('sampleSize: ' || TO_CHAR(obj.getSampleSize()));
 DBMS_OUTPUT.PUT_LINE('compressionType : ' || obj.getCompressionType());
 DBMS_OUTPUT.PUT_LINE('audioDuration: ' || TO_CHAR(obj.getAudioDuration()));
 UPDATE pm.online_media p SET p.product_audio = obj 
   WHERE  p.product_id = 1733;
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.PUT_LINE('ORDAudioExceptions.METHOD_NOT_SUPPORTED caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

setNumberOfChannels( )

Format

setNumberOfChannels(knownNumberOfChannels IN INTEGER);

Description

Sets the value of the numberOfChannels attribute for the audio object.

Parameters

knownNumberOfChannels: A known number of channels.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_INPUT_VALUE

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

See the example in setFormat( ).

setProperties( )

Format

setProperties(ctx IN OUT RAW,

setComments IN BOOLEAN);

Description

Reads the audio data to get the values of the object attributes and then stores them in the object attributes. This method sets the properties for each of the following attributes of the audio data for which values are available: compression type, duration, encoding type, format, mime type, number of channels, sampling rate, and sample size. It populates the comments field of the object with a rich set of format and application properties in XML form if the value of the setComments parameter is TRUE.

Parameters

ctx: The format plug-in context information.
setComments: A Boolean value that indicates whether or not the comments field of the object is populated. If the value is TRUE, then the comments field of the object is populated with a rich set of format and application properties of the audio object in XML form; 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 the NULL value.

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

Pragmas

None.

Exceptions

ORDAudioExceptions.AUDIO_PLUGIN_EXCEPTION

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Example

Set the property information for known audio attributes:

DECLARE
 obj ORDSYS.ORDAudio;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_audio INTO obj FROM pm.online_media p 
  WHERE p.product_id = 1729 FOR UPDATE;
 obj.setProperties(ctx,FALSE);
 DBMS_OUTPUT.PUT_LINE('format: ' || obj.getformat);
 DBMS_OUTPUT.PUT_LINE('encoding: ' || obj.getEncoding);
 DBMS_OUTPUT.PUT_LINE(
                 'numberOfChannels: ' || TO_CHAR(obj.getNumberOfChannels));
 DBMS_OUTPUT.PUT_LINE('samplingRate: ' || TO_CHAR(obj.getSamplingRate));
 DBMS_OUTPUT.PUT_LINE('sampleSize: ' || TO_CHAR(obj.getSampleSize));
 UPDATE  pm.online_media p set p.product_audio = obj 
   WHERE  p.product_id = 1729;
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDAudioExceptions.METHOD_NOT_SUPPORTED THEN
   DBMS_OUTPUT.PUT_LINE('ORDAudioExceptions.METHOD_NOT_SUPPORTED caught');
  WHEN OTHERS THEN
   DBMS_OUTPUT.PUT_LINE('EXCEPTION caught');
END;
/

setSamplingRate( )

Format

setSamplingRate(knownSamplingRate IN INTEGER);

Description

Sets the value of the samplingRate attribute of the audio object. The unit is Hz.

Parameters

knownSamplingRate: A known sampling rate.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_INPUT_VALUE

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

See the example in setFormat( ).

setSampleSize( )

Format

setSampleSize(knownSampleSize IN INTEGER);

Description

Sets the value of the sampleSize attribute of the audio object.

Parameters

knownSampleSize: A known sample size.

Usage Notes

Calling this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDAudioExceptions.NULL_INPUT_VALUE

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

ORDAudioExceptions.NULL_SOURCE

This exception is raised when the value of the ORDAudio.source attribute is NULL.

See Appendix H for more information about these exceptions.

Examples

See the example in setFormat( ).