Release 8.1.5
A67299-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i interMedia Audio, Image, and Video User's Guide and Reference Release 8.1.5 A67299-01 |
|
Oracle8i interMedia contains the following information about the ORDSource type:
This object is used only by other Oracle8i interMedia objects. You can use this as an embedded object to implement source mechanisms for your own objects.
The examples in this chapter assume that the test source table TS has been created and filled with data. This table was created using the SQL statements described in Section 6.2.1.
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)).
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, ORDImage, and ORDVideo objects all maintain consistency of their included ORDSource object.
Oracle8i interMedia provides the ORDSource object type, which supports access to a variety of sources of multimedia data.
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, dlob IN OUT NOCOPY BLOB, mimetype OUT VARCHAR2, format OUT VARCHAR2), MEMBER PROCEDURE importFrom( ctx IN OUT RAW, dlob IN OUT NOCOPY BLOB, 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:
| srcType | Source Type |
|---|---|
|
"FILE" |
A BFILE on a local file system |
|
"HTTP" |
An HTTP server |
|
"<name>" |
User-defined |
| 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 |
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.
This section presents ORDSource reference information on the Oracle8i interMedia methods provided for source data manipulation. These methods are described in the following groupings:
For more information on object types and methods, see the Oracle8i Concepts manual.
The methods described in this reference chapter show examples based on a test source table TS. Refer to the TS table definition that follows when reading through the examples in Section 6.2.2 through Section 6.2.9:
CREATE TABLE TS(n NUMBER, s ORDSYS.ORDSOURCE); INSERT INTO TS VALUES(1, ORDSYS.ORDSOURCE(EMPTY_BLOB(), NULL, NULL, NULL, SYSDATE, NULL)); INSERT INTO TS VALUES(2, ORDSYS.ORDSOURCE(EMPTY_BLOB(), NULL, NULL, NULL, SYSDATE, NULL)); INSERT INTO TS VALUES(3, ORDSYS.ORDSOURCE(EMPTY_BLOB(), NULL, NULL, NULL, SYSDATE, NULL)); INSERT INTO TS VALUES(4, ORDSYS.ORDSOURCE(EMPTY_BLOB(), NULL, NULL, NULL, SYSDATE, NULL));
This section presents reference information on the ORDSource methods associated with the local attribute.
setLocal;
Sets the local attribute to indicate that the data is stored in a BLOB within Oracle8i.
none
This method sets the local attribute to 1, meaning the data is stored locally in the localData attribute.
none
none
Set the flag to local for the data:
DECLARE SRC ORDSYS.ORDSource; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.setLocal; UPDATE TS SET S=SRC WHERE N = 1; COMMIT; END; /
clearLocal;
Resets the flag value from local, meaning the source of the data is stored locally in a BLOB in Oracle8i, to nonlocal meaning the source of the data is stored externally.
none
This method sets the local attribute to a 0, meaning the data is stored externally or outside of Oracle8i.
none
none
Clear the value of the local flag for the data:
DECLARE SRC ORDSYS.ORDSource; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.clearLocal; UPDATE TS SET S=SRC WHERE N = 1; COMMIT; END; /
isLocal RETURN BOOLEAN;
Returns TRUE if the data is stored locally in a BLOB in Oracle8i or FALSE if the data is stored externally.
none
If the local attribute is set to1 or NULL, this method returns TRUE, otherwise this method returns FALSE.
Pragma RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS)
none
Determine whether or not the data is local:
DECLARE SRC ORDSYS.ORDSource; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 ; if(SRC.isLocal = TRUE) then DBMS_OUTPUT.put_line('local is set true'); else DBMS_OUTPUT.put_line('local is set false'); end if; END; /
This section presents reference information on the ORDSource methods associated with the updateTime attribute.
getUpdateTime RETURN DATE;
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.
none
none
Pragma RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS)
none
Get the current value of the updateTime attribute for some data:
DECLARE SRC ORDSYS.ORDSource; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.setUpdateTime(SYSDATE); UPDATE TS SET S=SRC WHERE N = 1; COMMIT; SELECT S INTO SRC FROM TS WHERE N = 1 ; DBMS_OUTPUT.PUT_LINE(TO_CHAR(SRC.getUpdateTime,'MM-DD-YYYY HH24:MI:SS')); END; /
setUpdateTime(current_time DATE);
Sets the value of the updateTime attribute to the time you specify.
The update time.
If current_time is NULL, updateTime is set to SYSDATE (the current time).
none
none
See the example in getUpdateTime Method
This section presents reference information on the ORDSource methods associated with the srcType, srcLocation, and srcName attributes.
setSourceInformation( source_type IN VARCHAR2, source_location IN VARCHAR2, source_name IN VARCHAR2);
Sets the provided subcomponent information for the srcType, srcLocation, and srcName that describes the external data source.
The source type of the external data. See the "ORDSource Object Type" definition in this chapter for more information.
The source location of the external data. See the "ORDSource Object Type" definition in this chapter for more information.
The source name of the external data. See the "ORDSource Object Type" definition in this chapter for more information.
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.
none
If the value for source_type is NULL, then this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
Set the source to point to a file:
DECLARE SRC ORDSYS.ORDSource; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.setSourceInformation('FILE','AUDIODIR','testaud.dat'); DBMS_OUTPUT.PUT_LINE(SRC.getSourceInformation); DBMS_OUTPUT.PUT_LINE(SRC.getSourceType); DBMS_OUTPUT.PUT_LINE(SRC.getSourceLocation); DBMS_OUTPUT.PUT_LINE(SRC.getSourceName); UPDATE TS SET S=SRC WHERE N = 1; COMMIT; END; /
getSourceInformation RETURN VARCHAR2;
Returns a URL formatted string containing complete information about the external data source.
none
This method returns a VARCHAR2 string formatted as: <srcType>://<srcLocation>/<srcName>, where srcType, srcLocation, and srcName are the ORDSource attribute values.
Pragma RESTRICT_REFERENCES(getSourceInformation, WNDS, WNPS, RNDS, RNPS)
none
See the example in setSourceInformation( ) Method.
getSourceType RETURN VARCHAR2;
Returns the external data source type.
none
This method returns the current value of the srcType attribute, for example 'FILE'.
Pragma RESTRICT_REFERENCES(getSourceType, WNDS, WNPS, RNDS, RNPS)
none
See the example in setSourceInformation( ) Method.
getSourceLocation RETURN VARCHAR2;
Returns the external data source location.
none
This method returns the current value of the srcLocation attribute, for example 'BFILEDIR'.
Pragma RESTRICT_REFERENCES(getSourceLocation, WNDS, WNPS, RNDS, RNPS)
If the value of srcLocation is NULL, then calling this method raises an INCOMPLETE_SOURCE_LOCATION exception.
See the example in setSourceInformation( ) Method.
getSourceName RETURN VARCHAR2;
Returns the external data source name.
none
This method returns the current value of the srcName attribute, for example 'testaud.dat'.
Pragma RESTRICT_REFERENCES(getSourceName, WNDS, WNPS, RNDS, RNPS)
If the value of srcName is NULL, then calling this method raises an INCOMPLETE_SOURCE_NAME exception.
See the example in setSourceInformation( ) Method.
getBFile RETURN BFILE;
Returns a BFILE handle, if the srcType is 'FILE'.
none
This method can only be used for a srcType of 'FILE' or BFILE sources.
Pragma RESTRICT_REFERENCES(getBFile, WNDS, WNPS, RNDS, RNPS)
If the value of srcType is NULL, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the value of srcType is other than FILE, then calling this method raises an INVALID_SOURCE_TYPE exception.
Get a BFILE:
DECLARE SRC ORDSYS.ORDSource; file_handle BFILE; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 ; src.setSourceInformation('FILE','BFILEDIR','testaud.dat'); file_handle := SRC.getBFile; DBMS_OUTPUT.put_line(DBMS_LOB.GETLENGTH(file_handle)); END; /
This section presents reference information on the ORDSource methods associated with import and export operations.
import( ctx IN OUT RAW, dlob IN OUT NOCOPY BLOB, mimetype OUT VARCHAR2, format OUT VARCHAR2);
Transfers data from an external data source (specified by first calling setSourceInformation( )) to a local source within an Oracle database.
The source plug-in context information.This information is passed along uninterpreted to the source plug-in handling the import( ) call.
The destination large object or data object.
Out parameter to receive the MIME type of the data, if any, for example, 'audio/basic'.
Out parameter to receive the format of the data, if any, for example, 'AUFF'.
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.
none
If the value of srcType is NULL, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the value of dlob is NULL, then calling this method raises a NULL_SOURCE exception.
If the import( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Import data from an external data source into the local source and check for exceptions:
DECLARE SRC ORDSYS.ORDSource; mType VARCHAR2(4000); format VARCHAR2(4000); dblob BLOB; ctx RAW(4000) :=NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.setSourceInformation('FILE','BFILEDIR','testaud.dat'); SRC.import(ctx,dblob,mType,format); COMMIT; EXCEPTION WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN DBMS_OUTPUT.put_line('Source METHOD_NOT_SUPPORTED caught'); WHEN ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN DBMS_OUTPUT.put_line('SOURCE PLUGIN EXCEPTION caught'); WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE('OTHER EXCEPTION caught'); END; /
importFrom( ctx IN OUT RAW, dlob IN OUT NOCOPY BLOB, mimetype OUT VARCHAR2, format OUT VARCHAR2 source_type IN VARCHAR2, source_location IN VARCHAR2, source_name IN VARCHAR2);
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.
The source plug-in context information.This information is passed along uninterpreted to the source plug-in handling the importFrom( ) call.
The destination large object or data object.
Out parameter to receive the MIME type of the data, if any, for example, 'audio/basic'.
Out parameter to receive the format of the data, if any, for example, 'AUFF'.
Source type from where the data is to be imported. This also sets the srcType attribute.
Source location from where the data is to be imported. This also sets the srcLocation attribute.
Name of the source to be imported. This also sets the srcName attribute.
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.
none
If the value of dlob is NULL, then calling this method raises a NULL_SOURCE exception.
If the importFrom( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Import data from the specified data source into a BLOB "l":
DECLARE SRC ORDSYS.ORDSource; mType VARCHAR2(4000); format VARCHAR2(4000); l BLOB; ctx RAW(4000) :=NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.importFrom(ctx, l, mType, format,'FILE','AUDIODIR','testaud.dat'); DBMS_OUTPUT.PUT_LINE(TO_CHAR(SRC.getContentLength(ctx))); UPDATE TS SET S=SRC WHERE N=1; COMMIT; END;
export( ctx IN OUT RAW, source_type IN VARCHAR2, source_location IN VARCHAR2, source_name IN VARCHAR2);
Transfers data from a local source (localData) within an Oracle database to an external data source.
The source plug-in context information.
The source type of the location to where data is to be exported.
The location where the data is to be exported.
The name of the object to where the data is to be exported.
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 deleteLocalContent method to delete the content of the local data if you want to delete the contents of the localData attribute.
none
If the value of srcType is NULL, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the export( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Export data from a local source to an external data source:
DECLARE obj ORDSYS.ORDSource; ctx RAW(4000) :=NULL; BEGIN SELECT S INTO obj FROM TS WHERE N = 1; obj.export(ctx,'FILE','AUDIODIR','testaud.dat'); EXCEPTION WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN DBMS_OUTPUT.put_line('Source METHOD_NOT_SUPPORTED caught'); WHEN ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN DBMS_OUTPUT.put_line('SOURCE PLUGIN EXCEPTION caught'); WHEN OTHERS THEN DBMS_OUTPUT.put_line('OTHER EXCEPTION caught'); END; /
This section presents reference information on the ORDSource methods associated with the localData attribute.
getContentLength(ctx IN OUT RAW) RETURN INTEGER;
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.
The source plug-in context information.
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.
Pragma RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS)
If the value of srcType is NULL and data is not stored locally in the BLOB, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Get the length of the data content stored in the source:
DECLARE SRC ORDSYS.ORDSource; ctx RAW(4000) :=NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1; DBMS_OUTPUT.PUT_LINE(SRC.getSourceInformation); DBMS_OUTPUT.PUT_LINE(TO_CHAR(SRC.getContentLength(ctx))); EXCEPTION WHEN ORDSYS.ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION THEN DBMS_OUTPUT.PUT_LINE('Source not specified'); END; /
getSourceAddress(ctx IN OUT RAW, userData IN VARCHAR2) RETURN VARCHAR2;
Returns the source address for data located in an external data source. This method is only implemented for user-defined sources.
The source plug-in context information.
Information input by the user needed by some sources to obtain the desired source address.
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 Real Networks server sources or URLs containing data sources located on Oracle Application Server.
Calling this method uses the ORDPLUGINS.ORDX_<srcType>_SOURCE plug-in package.
Pragma RESTRICT_REFERENCES(getSourceAddress, WNDS, WNPS, RNDS, RNPS)
If the value of srcType is NULL, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Get the source address for the external source:
DECLARE SRC ORDSYS.ORDSource; ctx RAW(4000) :=NULL; userData VARCHAR2(4000); BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; -- process tempBlob SRC.setSourceInformation('FILE','AUDIODIR','testaud.dat'); userData :=NULL; DBMS_OUTPUT.PUT_LINE(SRC.getSourceAddress(ctx,userData)); COMMIT; END; /
getLocalContent RETURN BLOB;
Returns the content or BLOB handle of the local data.
none
none
Pragma RESTRICT_REFERENCES(getLocalContent, WNDS, WNPS, RNDS, RNPS)
none
Get the local content for a local source prior to an import operation:
DECLARE SRC ORDSYS.ORDSource; l BLOB; mimeType VARCHAR2(4000); format VARCHAR2(4000); ctx RAW(4000) := NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; l := SRC.getLocalContent; SRC.importFrom(ctx, 1, mimeType, format,'FILE','AUDIODIR','testaud.dat'); DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.GETLENGTH(1))); UPDATE TS SET S=SRC WHERE N=1; COMMIT; END;
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);
Transfers data from the current data source into a temporary LOB, which will be allocated and initialized as a part of this call.
The source plug-in context information.
Uninitialized BLOB locator, which will be allocated in this call.
Out parameter to receive the MIME type of the data, for example, 'audio/basic'.
Out parameter to receive the format of the data, for example, 'AUFF'.
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
Whether or not you want to keep the data cached. The value is either TRUE or FALSE. The default is TRUE.
none
none
When working with temporary LOBs, a NO_DATA_FOUND exception can be raised for looping read operations that reach the end of the LOB, and there are no more bytes to be read from the LOB.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Get data from an external data source into a temporary LOB on the local source:
DECLARE SRC ORDSYS.ORDSource; userData VARCHAR2(4000); l BLOB; tempBLob BLOB; mimeType VARCHAR2(4000); format VARCHAR2(4000); ctx RAW(4000) := NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.importFrom(ctx, src.localData, mimeType, format,'FILE','AUDIODIR','testaud.dat'); SRC.getContentInTempLob(ctx,tempBlob, mimeType,format, 0,FALSE); -- process tempBlob DBMS_OUTPUT.PUT_LINE(TO_CHAR(SRC.getContentLength(ctx))); DBMS_OUTPUT.PUT_LINE(SRC.getSourceAddress(ctx,userData)); DBMS_OUTPUT.PUT_LINE(TO_CHAR(DBMS_LOB.GETLENGTH(tempBlob))); UPDATE TS SET S=SRC WHERE N=1; COMMIT; END; /
deleteLocalContent;
Deletes the local data from the current local source (localData).
none
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.
none
none
Delete the local data from the current local source:
DECLARE SRC ORDSYS.ORDSource; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; SRC.deleteLocalContent; UPDATE TS SET S=SRC WHERE N=1; COMMIT; END; /
This section presents reference information on the ORDSource methods associated with accessing an external data source.
open(userArg IN RAW, ctx OUT RAW) RETURN INTEGER;
Opens a data source. It is recommended that this method be called before invoking any other methods that accept the ctx parameter.
The user argument.
The source plug-in context information.
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.
none
If the value for srcType is NULL and data is not local, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the open( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Open an external data source:
DECLARE SRC ORDSYS.ORDSource; res INTEGER; ctx RAW(4000) :=NULL; userArg RAW(4000); BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; res := SRC.open(userArg, ctx); -- manipulate the source res := SRC.close(ctx); EXCEPTION WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN DBMS_OUTPUT.PUT_LINE('Source not specified'); WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE('Exception caught'); END; /
close(ctx IN OUT RAW) RETURN INTEGER;
Closes a data source.
The source plug-in context information.
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.
none
If the value for srcType is NULL and data is not local, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the close( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Close an external data source:
DECLARE SRC ORDSYS.ORDSource; res INTEGER; ctx RAW(4000) :=NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; res := SRC.close(ctx); UPDATE TS SET S=SRC WHERE N=1; COMMIT; EXCEPTION WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN DBMS_OUTPUT.PUT_LINE('Source not specified'); WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE('Exception caught'); END; /
trim(ctx IN OUT RAW, newlen IN INTEGER) RETURN INTEGER;
Trims a data source.
The source plug-in context information.
The trimmed new length.
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.
none
If the value for srcType is NULL and data is not local, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the trim( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Trim an external data source:
DECLARE SRC ORDSYS.ORDSource; res INTEGER; ctx RAW(4000) :=NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; res := SRC.trim(ctx,0); UPDATE TS SET S=SRC WHERE N=1; COMMIT; EXCEPTION WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN DBMS_OUTPUT.PUT_LINE('Source not specified'); WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE('Exception caught'); END; /
This section presents reference information on the ORDSource methods associated with read/write operations.
read( ctx IN OUT RAW, startPos IN INTEGER, numBytes IN OUT INTEGER, buffer OUT RAW);
Allows you to read a buffer of numBytes from a source beginning at a start position (startPos).
The source plug-in context information.
The start position in the data source.
The number of bytes to be read from the data source.
The buffer to where the data will be read.
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.
none
If data is stored locally and localData is NULL, then calling this method raises a NULL_SOURCE exception.
If the value of srcType is NULL and data is not local, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the read( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Read a buffer from the source:
DECLARE SRC ORDSYS.ORDSource; i INTEGER; buffer RAW(4000); ctx RAW(4000) :=NULL; BEGIN i := 20; SELECT S INTO SRC FROM TS WHERE N = 1 ; SRC.read(ctx, 1, i, buffer); END; /
write( ctx IN OUT RAW, startPos IN INTEGER, numBytes IN OUT INTEGER, buffer IN RAW);
Allows you to write a buffer of numBytes to a source beginning at a start position (startPos).
The source plug-in context information.
The start position in the source to where the buffer should be copied.
The number of bytes to be written to the source.
The buffer of data to be written.
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.
none
If local is 1 or NULL and localData is NULL, then calling this method raises a NULL_SOURCE exception.
If the value of srcType is NULL and data is not local, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the write( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Write a buffer to the source:
DECLARE SRC ORDSYS.ORDSource; n INTEGER := 6; ctx RAW(4000) :=NULL; BEGIN SELECT S INTO SRC FROM TS WHERE N = 1 FOR UPDATE; DBMS_OUTPUT.PUT_LINE(SRC.getSourceInformation); SRC.write(ctx, 1, n, UTL_RAW.CAST_TO_RAW('helloP')); DBMS_OUTPUT.PUT_LINE(TO_CHAR(SRC.getContentLength(ctx))); COMMIT; END; /
This section presents reference information on the ORDSource methods associated with processing commands to the external source.
processCommand( ctx IN OUT RAW, command IN VARCHAR2, arglist IN VARCHAR2, result OUT RAW) RETURN RAW;
Allows you to send commands and related arguments to the source plug-in. This method is supported only for user-defined sources.
The source plug-in context information.
Any command recognized by the source plug-in.
The arguments for the command.
The result of calling this method returned by the plug-in.
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.
none
If the value of srcType is NULL, then calling this method raises an INCOMPLETE_SOURCE_INFORMATION exception.
If the processCommand( ) method is not supported by the source plug-in being used, a METHOD_NOT_SUPPORTED exception is raised.
Calling this method within a source plug-in when any other exception is raised, raises a SOURCE_PLUGIN_EXCEPTION exception.
Process some commands:
DECLARE obj ORDSYS.ORDSource ; res RAW(4000); result RAW(4000); command VARCHAR2(4000); argList VARCHAR2(4000); ctx RAW(4000) :=NULL; BEGIN select s into obj from TS where N =1 for UPDATE; command := 'xxx '; argList := 'yyy '; res := obj.processCommand(ctx, command, argList, result); UPDATE TS SET s=obj WHERE N=1 ; COMMIT; EXCEPTION WHEN ORDSYS.ORDSourceExceptions.METHOD_NOT_SUPPORTED THEN DBMS_OUTPUT.put_line('Source METHOD_NOT_SUPPORTED caught'); WHEN ORDSYS.ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION THEN DBMS_OUTPUT.put_line('SOURCE PLUGIN EXCEPTION caught'); WHEN OTHERS THEN DBMS_OUTPUT.put_line('OTHER EXCEPTION caught'); END; /
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 6.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).
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, dlob IN OUT NOCOPY BLOB, mimetype OUT VARCHAR2, format OUT 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_FILE_SOURCE; /
Table 6-1 shows the methods supported in the ORDX_FILE_SOURCE package and the exceptions raised if you call a method that is not supported.
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, dlob IN OUT NOCOPY BLOB, mimetype OUT VARCHAR2, format OUT 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 6-2 shows the methods supported in the ORDX_HTTP_SOURCE package and the exceptions raised if you call a method that is not supported.
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.
Extending interMedia to support a new data source consists of four steps:
Section 2.4 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 6-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".
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, 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, 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;
