I
ORDSource Reference Information

Oracle interMedia contains the following information about the ORDSource type:

Object type -- see Section I.1.
Methods -- see Section I.2.
Packages or PL/SQL plug-ins -- see Section I.3.

This object is used only by other Oracle interMedia objects. The information in this chapter is included for reference only. Oracle Corporation does not recommend that you use this type.

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

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

Note:

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

The ORDSource object does not attempt to maintain consistency, for example, with local and upDateTime attributes. It is up to you to maintain consistency. ORDAudio, ORDDoc, ORDImage, and ORDVideo objects all maintain consistency of their included ORDSource object.

I.1 Object Types

Oracle interMedia provides the ORDSource object type, which supports access to a variety of sources of multimedia data.

ORDSource Object Type

The ORDSource object type supports access to data sources locally in a BLOB within an Oracle database, externally from a BFILE on a local file system, externally from a URL on an HTTP server (within the firewall), or externally from a user-defined source on another server. This object type is defined as follows:

CREATE OR REPLACE TYPE ORDsource
AS OBJECT
(
  -- ATTRIBUTES
localData           BLOB,
srcType             VARCHAR2(4000),
srcLocation         VARCHAR2(4000),
srcName             VARCHAR2(4000),
updateTime          DATE,
local               NUMBER,
  -- METHODS 
-- Methods associated with the local attribute
MEMBER PROCEDURE setLocal,
MEMBER PROCEDURE clearLocal,
MEMBER FUNCTION isLocal RETURN BOOLEAN,
PRAGMA RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS),
-- Methods associated with the updateTime attribute
MEMBER FUNCTION getUpdateTime RETURN DATE,
PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS),
MEMBER PROCEDURE setUpdateTime(current_time DATE),
-- Methods associated with the source information 
MEMBER PROCEDURE setSourceInformation(
                                      source_type     IN VARCHAR2,
                                      source_location IN VARCHAR2,
                                      source_name     IN VARCHAR2),
MEMBER FUNCTION getSourceInformation RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceInformation, 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 FUNCTION getBFile RETURN BFILE,
PRAGMA RESTRICT_REFERENCES(getBFile, WNDS, WNPS, RNDS, RNPS),

-- Methods associated with source import/export operations
MEMBER PROCEDURE import(
                        ctx      IN OUT RAW,
                        mimetype OUT VARCHAR2,
                        format   OUT VARCHAR2),
MEMBER PROCEDURE importFrom(
                             ctx             IN OUT RAW,
                             mimetype        OUT VARCHAR2,
                             format          OUT VARCHAR2,
                             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),
-- Methods associated with source content-related operations
MEMBER FUNCTION getContentLength(ctx IN OUT RAW) RETURN INTEGER,
PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION getSourceAddress(ctx IN OUT RAW, 
                                 userData IN VARCHAR2)
                RETURN VARCHAR2,
PRAGMA RESTRICT_REFERENCES(getSourceAddress, WNDS, WNPS, RNDS, RNPS),

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

MEMBER PROCEDURE getContentInTempLob(
                                     ctx      IN OUT RAW, 
                                     tempLob  IN OUT NOCOPY BLOB, 
                                     mimetype OUT VARCHAR2, 
                                     format   OUT VARCHAR2, 
                                     duration IN PLS_INTEGER := 10, 
                                     cache    IN BOOLEAN := TRUE),
MEMBER PROCEDURE deleteLocalContent,

-- Methods associated with source access methods
MEMBER FUNCTION open(userArg IN RAW, ctx OUT RAW) RETURN INTEGER,
MEMBER FUNCTION close(ctx IN OUT RAW) RETURN INTEGER,
MEMBER FUNCTION trim(ctx     IN OUT RAW,
                     newlen  IN INTEGER) RETURN INTEGER,

-- Methods associated with content read/write operations
MEMBER PROCEDURE read(
                      ctx      IN OUT RAW,
                      startPos IN INTEGER,
                      numBytes IN OUT INTEGER,
                      buffer   OUT RAW), 
MEMBER PROCEDURE write(
                       ctx      IN OUT RAW,
                       startPos IN INTEGER,
                       numBytes IN OUT INTEGER,
                       buffer   IN RAW), 
-- Methods associated with any commands to be sent to the external source
MEMBER FUNCTION processCommand(
                               ctx     IN OUT RAW,
                               command IN VARCHAR2,
                               arglist IN VARCHAR2,
                               result  OUT RAW) 
                RETURN RAW
);

where:

localData: contains the locally stored multimedia data stored as a BLOB within the object. Up to 4 gigabytes of data can be stored as a BLOB within an Oracle database and is protected by the Oracle security and transaction environment.

srcType: identifies the data source type. Supported values for srcType are:

srcType	Source Type
"file"	A BFILE on a local file system
"HTTP"	An HTTP server
"<name>"	User-defined

Note:

The keyword file for the plug-in is a reserved word for the BFILE source provided by Oracle Corporation. To implement for your own file plug-in, select a different name, for example, MYFILE.

srcLocation: identifies the place where data can be found based on the srcType value. Valid srcLocation values for corresponding srcType values are:

srcType	Location Value
"file"	<DIR> or name of the directory object
"HTTP"	<SourceBase> or URL needed to find the base directory
"<name>"	<iden> or identifier string required to access a user-defined source

srcName: identifies the data object name. Valid srcName values for corresponding srcType values are:

srcType Name Value

"file"

<file> or name of the file

"HTTP"

<Source> or name of the object

"<name>"

<object name> or name of the object
updateTime: the time at which the data was last updated.
local: a flag to determine whether or not the data is local:

1 means the data is in the BLOB.

0 means the data is in external sources.

NULL, which may be a default state when you first insert an empty row, is assumed to mean data is local.

srcType	Name Value
"file"	<file> or name of the file
"HTTP"	<Source> or name of the object
"<name>"	<object name> or name of the object

I.2 Methods

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

ORDSource Methods Associated with the local Attribute

setLocal: sets the flag value for the local attribute to "1", meaning that the source of the data is local.
clearLocal: resets the flag value for the local attribute to "0", meaning that the source of the data is external.
isLocal: returns TRUE to indicate that the source of the data is local or in the BLOB, or FALSE, meaning the data is in an external source. The value of the local attribute is used to determine the return value.

ORDSource Methods Associated with the updateTime Attribute

getUpdateTime: returns the value of the updateTime attribute.
setUpdateTime: sets the value of the updateTime attribute to the specified time provided in the argument.

ORDSource Methods Associated with the srcType, srcLocation, and srcName Attributes

setSourceInformation( ): sets or alters information about the source of the data.
getSourceInformation: returns a formatted string containing complete information about the data source formatted as a URL.
getSourceType: returns the external source type of the data.
getSourceLocation: returns the external source location of the data.
getSourceName: returns the external source name of the data.
getBFile: returns the external content as a BFILE, if srcType is of type file.

ORDSource Methods Associated with import and export Operations

import( ): transfers data from an external data source (specified by calling setSourceInformation( )) to the local source (localData) within an Oracle database.
importFrom( ): transfers data from the specified external data source (source, location, name) to the local source (localData) within an Oracle database.
export( ): copies data from a local source (localData) within an Oracle database to the specified external data source.

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

ORDSource Methods Associated with the localData Attribute

getContentLength( ): returns the length of the data source (as number of bytes).
getSourceAddress( ): returns the address of the data source.
getLocalContent: returns the handle to the BLOB used to store contents locally.
getContentInTempLob( ): returns content into a temporary LOB.
deleteLocalContent: deletes the content of the local BLOB.

ORDSource Methods Associated with Source Input/Output Operations

open( ): opens a data source.
close( ): closes a data source.
trim( ): trims a data source.
read( ): reads a buffer of n bytes from a source beginning at a start position.
write( ): writes a buffer of n bytes to a source beginning at a start position.

ORDSource Methods Associated with Processing Commands to the External Source

processCommand( ): process as any command to the external source. This method is supported only for user-defined sources.

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

clearLocal

Format

clearLocal;

Description

Resets the flag value from local, meaning the source of the data is stored locally in a BLOB in Oracle, to nonlocal meaning the source of the data is stored externally.

Parameters

None.

Usage Notes

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

Pragmas

None.

Exceptions

None.

Examples

None.

close( )

Format

close(ctx IN OUT RAW) RETURN INTEGER;

Description

Closes a data source.

Parameters

ctx

The source plug-in context information.

Usage Notes

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

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

INCOMPLETE_SOURCE_INFORMATION

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

METHOD_NOT_SUPPORTED

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

deleteLocalContent

Format

deleteLocalContent;

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.

Pragmas

None.

Exceptions

None.

Examples

None.

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 an 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 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

This method exports data out of the localData to another source.

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

After exporting data, the srcType, srcLocation, and srcName attributes are updated with input parameter values. After calling the export( ) method, call the
clearLocal( ) method to indicate the data is stored outside the database and call the deleteLocalContent 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 only server-side native support for the export method is for the srcType file.

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 deleteLocalContent 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 to 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

INCOMPLETE_SOURCE_INFORMATION

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

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.

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

getBFile

Format

getBFile RETURN BFILE;

Description

Returns a BFILE handle, if the srcType is file.

Parameters

None.

Usage Notes

This method can only be used for a srcType of file or BFILE sources.

Pragmas

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

Exceptions

INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the getBFILE method and the value of srcType is NULL.

INVALID_SOURCE_TYPE

This exception is raised if you call the getBFile method and the value of srcType is other than file.

Examples

None.

getContentInTempLob( )

Format

getContentInTempLob(

ctx IN OUT RAW,

tempLob IN OUT NOCOPY BLOB,

mimetype OUT VARCHAR2,

format OUT VARCHAR2,

duration IN PLS_INTEGER := 10,

cache IN BOOLEAN := TRUE);

Description

Transfers data from the current data source into a temporary LOB, which will be allocated and initialized as a part of this call.

Parameters

ctx

The source plug-in context information.

tempLob

Uninitialized BLOB locator, which will be allocated in this call.

mimetype

Out parameter to receive the MIME type of the data, for example, 'audio/basic'.

format

Out parameter to receive the format of the data, for example, 'AUFF'.

duration

The life of the temporary LOB to be allocated. The life of the temporary LOB can be for the duration of the call, the transaction, or for the session. The default is DBMS_LOB.SESSION. Valid values for each duration state are as follows:

DBMS_LOB.CALL

DBMS_LOB.TRANSACTION

DBMS_LOB.SESSION

cache

Whether or not you want to keep the data cached. The value is either TRUE or FALSE. The default is TRUE.

Usage Notes

None.

Pragmas

None.

Exceptions

NO_DATA_FOUND

This exception is raised if you call the getContentInLob( ) method when working with temporary LOBs for looping read operations that reach the end of the LOB, and there are no more bytes to be read from the LOB.

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

getContentLength( )

Format

getContentLength(ctx IN OUT RAW) RETURN INTEGER;

Description

Returns the length of the data content stored in the source. For a file source and for data in a local BLOB data source, the length is returned as a number of bytes. The unit type of the returned value is defined by the plug-in that implements this method.

Parameters

ctx

The source plug-in context information.

Usage Notes

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

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

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

Exceptions

INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the getContentLength( ) method and the value of srcType is NULL and data is not stored locally in the BLOB.

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

getLocalContent

Format

getLocalContent RETURN BLOB;

Description

Returns the content or BLOB handle of the local data.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

None.

getSourceAddress( )

Format

getSourceAddress(ctx IN OUT RAW,

userData IN VARCHAR2) RETURN VARCHAR2;

Description

Returns the source address for data located in an external data source. This method is only implemented for user-defined sources.

Parameters

ctx

The source plug-in context information.

userData

Information input by the user needed by some sources to obtain the desired source address.

Usage Notes

Use this method to return the address of an external data source when the source needs to format this information in some unique way. For example, call the getSourceAddress( )method to obtain the address for RealNetworks server sources or URLs containing data sources located on Oracle Application Server.

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

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

Exceptions

INCOMPLETE_SOURCE_INFORMATION

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

getSourceInformation

Format

getSourceInformation RETURN VARCHAR2;

Description

Returns a URL formatted string containing complete information about the external data source.

Parameters

None.

Usage Notes

This method returns a VARCHAR2 string formatted as: <srcType>://<srcLocation>/<srcName>, where srcType, srcLocation, and srcName are the ORDSource attribute values.

Pragmas

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

Exceptions

None.

Examples

None.

getSourceLocation

Format

getSourceLocation RETURN VARCHAR2;

Description

Returns the external data source location.

Parameters

None.

Usage Notes

This method returns the current value of the srcLocation attribute, for example BFILEDIR.

Pragmas

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

Exceptions

INCOMPLETE_SOURCE_LOCATION

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

Examples

None.

getSourceName

Format

getSourceName RETURN VARCHAR2;

Description

Returns the external data source name.

Parameters

None.

Usage Notes

This method returns the current value of the srcName attribute, for example
testaud.dat.

Pragmas

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

Exceptions

INCOMPLETE_SOURCE_NAME

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

Examples

None.

getSourceType

Format

getSourceType RETURN VARCHAR2;

Description

Returns the external data source type.

Parameters

None.

Usage Notes

This method returns the current value of the srcType attribute, for example file.

Pragmas

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

Exceptions

None.

Examples

None.

getUpdateTime

Format

getUpdateTime RETURN DATE;

Description

Returns the value of the updateTime attribute for the ORDSource object. This is the timestamp when the object was last changed, or what the user explicitly set by calling the setUpdateTime( ) method.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

None.

import( )

Format

import(

ctx IN OUT RAW,

mimetype OUT VARCHAR2,

format OUT VARCHAR2);

Description

Transfers data from an external data source (specified by first calling setSourceInformation( )) to a local source within an Oracle database.

Parameters

ctx

The source plug-in context information.This information is passed along uninterpreted to the source plug-in handling the import( ) call.

mimetype

Out parameter to receive the MIME type of the data, if any, for example, 'audio/basic'.

format

Out parameter to receive the format of the data, if any, for example, 'AUFF'.

Usage Notes

Call setSourceInformation( ) to set the srcType, srcLocation, and srcName attribute information to describe where the data source is located prior to calling the
import( ) method.

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

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

None.

Exceptions

INCOMPLETE_SOURCE_INFORMATION

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

NULL_SOURCE

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

METHOD_NOT_SUPPORTED

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

importFrom( )

Format

importFrom(

ctx IN OUT RAW,

mimetype OUT VARCHAR2,

format OUT VARCHAR2

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Transfers data from the specified external data source (type, location, name) to a local source within an Oracle database, and resets the source attributes and the timestamp.

Parameters

ctx

The source plug-in context information.This information is passed along uninterpreted to the source plug-in handling the importFrom( ) call.

mimetype

Out parameter to receive the MIME type of the data, if any, for example, 'audio/basic'.

format

Out parameter to receive the format of the data, if any, for example, 'AUFF'.

source_type

Source type from where the data is to be imported. This also sets the srcType attribute.

source_location

Source location from where the data is to be imported. This also sets the srcLocation attribute.

source_name

Name of the source to be imported. This also sets the srcName attribute.

Usage Notes

This method describes where the data source is located by specifying values for the type, location, and name parameters, which set the srcType, srcLocation, and srcName attribute values, respectively, after the importFrom operation succeeds.

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

This method is a combination of a setSourceInformation( ) call followed by an import( ) call.

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

None.

Exceptions

NULL_SOURCE

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

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.

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

isLocal

Format

isLocal RETURN BOOLEAN;

Description

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

Parameters

None.

Usage Notes

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

Pragmas

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

Exceptions

None.

Examples

None.

open( )

Format

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

Description

Opens a data source. It is recommended that this method be called before invoking any other methods that accept the ctx parameter.

Parameters

userArg

The user argument.

ctx

The source plug-in context information.

Usage Notes

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

None.

Exceptions

INCOMPLETE_SOURCE_INFORMATION

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

METHOD_NOT_SUPPORTED

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

processCommand( )

Format

processCommand(

ctx IN OUT RAW,

command IN VARCHAR2,

arglist IN VARCHAR2,

result OUT RAW)

RETURN RAW;

Description

Allows you to send commands and related arguments to the source plug-in. This method is supported only for user-defined sources.

Parameters

ctx

The source plug-in context information.

command

Any command recognized by the source plug-in.

arglist

The arguments for the command.

result

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

Usage Notes

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

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

None.

Exceptions

INCOMPLETE_SOURCE_INFORMATION

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

METHOD_NOT_SUPPORTED

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

read( )

Format

read(

ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer OUT RAW);

Description

Allows you to read a buffer of numBytes from a source beginning at a start position (startPos).

Parameters

ctx

The source plug-in context information.

startPos

The start position in the data source.

numBytes

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

buffer

The buffer to where 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.

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

None.

Exceptions

NULL_SOURCE

This exception is raised if you call the read( ) method and the data is stored locally and localData is NULL.

INCOMPLETE_SOURCE_INFORMATION

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

METHOD_NOT_SUPPORTED

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

setLocal

Format

setLocal;

Description

Sets the local attribute to indicate that the data is stored in a BLOB within Oracle9i.

Parameters

None.

Usage Notes

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

Pragmas

None.

Exceptions

None.

Examples

None.

setSourceInformation( )

Format

setSourceInformation(

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Sets the provided subcomponent information for the srcType, srcLocation, and srcName that describes the external data source.

Parameters

source_type

The source type of the external data. See the "ORDSource Object Type" definition in this chapter for more information.

source_location

The source location of the external data. See the "ORDSource Object Type" definition in this chapter for more information.

source_name

The source name of the external data. See the "ORDSource Object Type" definition in this chapter for more information.

Usage Notes

Before you call the import( ) method, you must call the setSourceInformation( ) method to set the srcType, srcLocation, and srcName attribute information to describe where the data source is located. If you call the importFrom( ) or the export( ) method, then these attributes are set after the importFrom( ) or export( ) call succeeds.

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

Pragmas

None.

Exceptions

INCOMPLETE_SOURCE_INFORMATION

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

Examples

None.

setUpdateTime( )

Format

setUpdateTime(current_time DATE);

Description

Sets the value of the updateTime attribute to the time you specify.

Parameters

current_time

The update time.

Usage Notes

If current_time is NULL, updateTime is set to SYSDATE (the current time).

Pragmas

None.

Exceptions

None.

Examples

None.

trim( )

Format

trim(ctx IN OUT RAW,

newlen IN INTEGER) RETURN INTEGER;

Description

Trims a data source.

Parameters

ctx

The source plug-in context information.

newlen

The trimmed new length.

Usage Notes

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

None.

Exceptions

INCOMPLETE_SOURCE_INFORMATION

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

METHOD_NOT_SUPPORTED

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

write( )

Format

write(

ctx IN OUT RAW,

startPos IN INTEGER,

numBytes IN OUT INTEGER,

buffer IN RAW);

Description

Allows you to write a buffer of numBytes to a source beginning at a start position (startPos).

Parameters

ctx

The source plug-in context 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 writable source allows you to write numBytes at a random byte location. For example, the file and HTTP source types are not writable sources and do not support this method.

Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.

Pragmas

None.

Exceptions

NULL_SOURCE

This exception is raised if you call the write( ) method and local is 1 or NULL and localData is NULL.

INCOMPLETE_SOURCE_INFORMATION

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

METHOD_NOT_SUPPORTED

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

SOURCE_PLUGIN_EXCEPTION

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

Examples

None.

I.3 Packages or PL/SQL Plug-ins

This section presents reference information on the packages or PL/SQL plug-ins provided.

Any method invoked from a source plug-in call has the first argument as obj (ORDSource) and the second argument as ctx (RAW).

Plug-ins must be named as ORDX_<name>_<module_name> where the <module_name> is SOURCE for ORDSource. For example, the file plug-in described in Section I.3.1, is named ORDX_FILE_SOURCE and <name> is the source type.

Exceptions must be raised from and recorded in a package named as ORD_<module_name>Exceptions. For example, ORDSource exceptions are raised and recorded in a package named ORDSourceExceptions (see Appendix H).

I.3.1 ORDPLUGINS.ORDX_FILE_SOURCE Package

The ORDPLUGINS.ORDX_FILE_SOURCE package or PL/SQL plug-in is provided.

CREATE OR REPLACE PACKAGE ORDX_FILE_SOURCE AS
  -- functions/procedures
  FUNCTION processCommand(obj     IN OUT NOCOPY ORDSYS.ORDSource,
                          ctx     IN OUT RAW,
                          cmd     IN VARCHAR2,
                          arglist IN VARCHAR2,
                          result  OUT RAW)
           RETURN RAW;
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   dlob     IN OUT NOCOPY BLOB,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       dlob     IN OUT NOCOPY BLOB,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE export(obj  IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx  IN OUT RAW,
                   slob IN OUT NOCOPY BLOB,
                   loc  IN VARCHAR2,
                   name IN VARCHAR2);
  FUNCTION  getContentLength(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW),
            RETURN INTEGER;
  PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS);
  FUNCTION  getSourceAddress(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW,
                             userData IN VARCHAR2)
            RETURN VARCHAR2;
  PRAGMA RESTRICT_REFERENCES(getSourceAddress, WNDS, WNPS, RNDS, RNPS);
  
  FUNCTION open(obj IN OUT NOCOPY ORDSYS.ORDSource, 
           userArg IN RAW, 
           ctx OUT RAW) RETURN INTEGER;
  FUNCTION close(obj IN OUT NOCOPY ORDSYS.ORDSource, ctx IN OUT RAW) 
         RETURN INTEGER;
  FUNCTION trim(obj IN OUT NOCOPY ORDSYS.ORDSource, 
                ctx IN OUT RAW,
                newlen IN INTEGER) RETURN INTEGER;
PROCEDURE read(obj     IN OUT NOCOPY ORDSYS.ORDSource,
               ctx      IN OUT RAW,
               startPos IN INTEGER,
               numBytes IN OUT INTEGER,
               buffer   OUT RAW);
PROCEDURE write(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                ctx      IN OUT RAW,
                startPos IN INTEGER,
                numBytes IN OUT INTEGER,
                buffer   OUT RAW);
END ORDX_FILE_SOURCE;
/

Table I-1 shows the methods supported in the ORDX_FILE_SOURCE package and the exceptions raised if you call a method that is not supported.

Table I-1 Methods Supported in the ORDPLUGINS.ORDX_FILE_SOURCE Package

Name of Method	Level of Support
processCommand	Not supported - raises exception: METHOD_NOT_SUPPORTED
import	Supported
import	Supported
importFrom	Supported
importFrom	Supported
export	Supported
getContentLength	Supported
getSourceAddress	Supported
open	Supported
close	Supported
trim	Not supported - raises exception: METHOD_NOT_SUPPORTED
read	Supported
write	Not supported - raises exception: METHOD_NOT_SUPPORTED

I.3.2 ORDPLUGINS.ORDX_HTTP_SOURCE Package

The ORDPLUGINS.ORDX_HTTP_SOURCE package or PL/SQL plug-in is provided.

CREATE OR REPLACE PACKAGE ORDX_HTTP_SOURCE AS
  -- functions/procedures
  FUNCTION processCommand(obj     IN OUT NOCOPY ORDSYS.ORDSource,
                          ctx     IN OUT RAW,
                          cmd     IN VARCHAR2,
                          arglist IN VARCHAR2,
                          result  OUT RAW)
           RETURN RAW;
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE import(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx      IN OUT RAW,
                   dlob     IN OUT NOCOPY BLOB,
                   mimetype OUT VARCHAR2,
                   format   OUT VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE importFrom(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx      IN OUT RAW,
                       dlob     IN OUT NOCOPY BLOB,
                       mimetype OUT VARCHAR2,
                       format   OUT VARCHAR2,
                       loc      IN VARCHAR2,
                       name     IN VARCHAR2);
  PROCEDURE export(obj  IN OUT NOCOPY ORDSYS.ORDSource,
                   ctx  IN OUT RAW,
                   dlob IN OUT NOCOPY BLOB,
                   loc  IN VARCHAR2,
                   name IN VARCHAR2);
  FUNCTION  getContentLength(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW)
            RETURN INTEGER;
  PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS);
  FUNCTION  getSourceAddress(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW,
                             userData IN VARCHAR2) 
            RETURN VARCHAR2;
  PRAGMA RESTRICT_REFERENCES(getSourceAddress, WNDS, WNPS, RNDS, RNPS);
  FUNCTION open(obj IN OUT NOCOPY ORDSYS.ORDSource, userArg IN RAW,
           ctx OUT RAW) RETURN INTEGER;
  FUNCTION close(obj IN OUT NOCOPY ORDSYS.ORDSource, ctx IN OUT RAW) 
           RETURN INTEGER;
  FUNCTION trim(obj IN OUT NOCOPY ORDSYS.ORDSource, 
           ctx IN OUT RAW,
           newlen IN INTEGER) RETURN INTEGER;
  PROCEDURE read(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                 ctx      IN OUT RAW,
                 startPos IN INTEGER,
                 numBytes IN OUT INTEGER,
                 buffer   OUT RAW);
  PROCEDURE write(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                  ctx      IN OUT RAW,
                  startPos IN INTEGER,
                  numBytes IN OUT INTEGER,
                  buffer   OUT RAW);
END ORDX_HTTP_SOURCE;
/

Table I-2 shows the methods supported in the ORDX_HTTP_SOURCE package and the exceptions raised if you call a method that is not supported.

Table I-2 Methods Supported in the ORDPLUGINS.ORDX_HTTP_SOURCE Package

Name of Method	Level of Support
processCommand	Not supported - raises exception: METHOD_NOT_SUPPORTED
import	Supported
import	Supported
importFrom	Supported
importFrom	Supported
export	Not supported - raises exception: METHOD_NOT_SUPPORTED
getContentLength	Supported
getSourceAddress	Supported
open	Supported
close	Supported
trim	Not supported - raises exception: METHOD_NOT_SUPPORTED
read	Not supported - raises exception: METHOD_NOT_SUPPORTED
write	Not supported - raises exception: METHOD_NOT_SUPPORTED

I.3.3 ORDPLUGINS.ORDX_<srcType>_SOURCE Package

Use the ORDPLUGINS.ORDX_<srcType>_SOURCE package or PL/SQL plug-in as a template to create your own source type. Use the
ORDPLUGINS.ORDX_FILE_SOURCE and ORDPLUGINS.ORDX_HTTP_SOURCE packages as a guide in developing your new source type package.

I.3.4 Extending interMedia to Support a New Data Source

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

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

Section 3.5 briefly describes how to extend interMedia to support a new data source for audio and video data and describe the interfaces. A package body listing is provided in Example I-1 to assist you in this operation. Add your variables to the places that say "--Your variables go here" and add your code to the places that say "--Your code goes here".

Example I-1 Show the Package Body for Extending Support to a New Data Source

CREATE OR REPLACE PACKAGE BODY ORDX_MY_SOURCE
AS
  -- functions/procedures
  FUNCTION processCommand(
                    obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    cmd  IN VARCHAR2,
                    arglist IN VARCHAR2,
                    result OUT RAW)
  RETURN RAW
  IS
   --Your variables go here  
  BEGIN
  --Your code goes here
  END processCommand;
  PROCEDURE import( obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    mimetype OUT VARCHAR2,
                    format   OUT VARCHAR2)
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END import;
  PROCEDURE import( obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    dlob IN OUT NOCOPY BLOB,
                    mimetype OUT VARCHAR2,
                    format   OUT VARCHAR2)
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END import;
  PROCEDURE importFrom( obj      IN OUT NOCOPY ORDSYS.ORDSource,
                        ctx      IN OUT RAW,
                        mimetype OUT VARCHAR2,
                        format   OUT VARCHAR2,
                        loc      IN VARCHAR2,
                        name     IN VARCHAR2)
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END importFrom;
  PROCEDURE importFrom( obj      IN OUT NOCOPY ORDSYS.ORDSource,
                        ctx      IN OUT RAW,
                        dlob     IN OUT NOCOPY BLOB,
                        mimetype OUT VARCHAR2,
                        format   OUT VARCHAR2,
                        loc      IN VARCHAR2,
                        name     IN VARCHAR2)
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END importFrom;
  PROCEDURE export( obj  IN OUT NOCOPY ORDSYS.ORDSource,
                    ctx  IN OUT RAW,
                    dlob IN OUT NOCOPY BLOB,
                    loc  IN VARCHAR2,
                    name IN VARCHAR2)
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END export;
  
  FUNCTION  getContentLength( obj  IN ORDSYS.ORDSource,
                              ctx  IN OUT RAW)
  RETURN INTEGER
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END getContentLength;
  FUNCTION  getSourceAddress(obj  IN ORDSYS.ORDSource,
                             ctx  IN OUT RAW,
                             userData IN VARCHAR2)
  RETURN VARCHAR2
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END getSourceAddress;
  FUNCTION open(obj IN OUT NOCOPY ORDSYS.ORDSource, userArg IN RAW, ctx OUT RAW)
  RETURN INTEGER
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END open;
  FUNCTION close(obj IN OUT NOCOPY ORDSYS.ORDSource, ctx IN OUT RAW)
  RETURN INTEGER
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END close;
  FUNCTION trim(obj    IN OUT NOCOPY ORDSYS.ORDSource,
                       ctx    IN OUT RAW,
                       newlen IN INTEGER)
  RETURN INTEGER
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END trim;
  PROCEDURE read(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                 ctx      IN OUT RAW,
                 startPos IN INTEGER,
                 numBytes IN OUT INTEGER,
                 buffer   OUT RAW)
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END read;
  PROCEDURE write(obj      IN OUT NOCOPY ORDSYS.ORDSource,
                  ctx      IN OUT RAW,
                  startPos IN INTEGER,
                  numBytes IN OUT INTEGER,
                  buffer   OUT RAW)
  IS
  --Your variables go here
  BEGIN
  --Your code goes here
  END write;
END ORDX_MY_SOURCE;
/
show errors;

I ORDSource Reference Information

I.1 Object Types

ORDSource Object Type

I.2 Methods

ORDSource Methods Associated with the local Attribute

ORDSource Methods Associated with the updateTime Attribute

ORDSource Methods Associated with the srcType, srcLocation, and srcName Attributes

ORDSource Methods Associated with import and export Operations

ORDSource Methods Associated with the localData Attribute

ORDSource Methods Associated with Source Input/Output Operations

ORDSource Methods Associated with Processing Commands to the External Source

clearLocal

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

close( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

deleteLocalContent

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

getContentInTempLob( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getContentLength( )

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getLocalContent

Format

Description

Parameters

Usage Notes

Pragmas

Exceptions

Examples

getSourceAddress( )

Format

Description

Parameters

Usage Notes

I
ORDSource Reference Information