Oracle Multimedia ORDSource Object Type

12 Oracle Multimedia ORDSource Object Type

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

It supports access to data sources locally in a BLOB within the database, externally from a BFILE on a local file system, externally from a URL on an HTTP server, or externally from a user-defined source on another server.

The ORDSource object type is defined in the ordsrcsp.sql file. After installation, this file is available in the Oracle home directory at:

<ORACLE_HOME>/ord/im/admin (on Linux and UNIX)

<ORACLE_HOME>\ord\im\admin (on Windows)

Note:

The ORDSource object type is used only by other Oracle Multimedia objects. This information is for reference use, only. Oracle recommends that you not use this type directly.

12.1 Important Notes for ORDSource Methods

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 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 must 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).

Note:

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

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.

12.2 ORDSource Object Type

The ORDSource object type supports access to a variety of sources of multimedia data. The attributes for this object type are defined as follows in the ordsrcsp.sql file:

  -------------------
  -- TYPE ATTRIBUTES
  -------------------
  localData           BLOB,
  srcType             VARCHAR2(4000),
  srcLocation         VARCHAR2(4000),
  srcName             VARCHAR2(4000),
  updateTime          DATE,
  local               NUMBER,

where:

localData: the locally stored multimedia data stored as a BLOB within the object. Depending on the block size, up to 8 terabytes (TB) to 128 TB of data can be stored as a BLOB within Oracle Database, and is protected by the Oracle security and transaction environment.
srcType: the data source type. (See Table 7-1 for the list of valid values.)
srcLocation: the place where data can be found based on the srcType value. (See Table 7-2 for the list of valid values.)
srcName: the data object name. (See Table 7-3 for the list of valid values.)
updateTime: the time at which the data was last updated.
local: a flag that indicates whether the data is local. The valid values are:
- 1: the data is in the BLOB.
- 0: the data is in external sources.
- NULL: the data is local. This value may indicate a default state when you first insert an empty row.

See Also:

Oracle Database SecureFiles and Large Objects Developer's Guide for more information about using BLOBs

12.3 ORDSource Methods

The following ORDSource methods are designed for source data manipulation.

See Also:

Oracle Database Concepts for more information about object types and methods

12.3.1 clearLocal( )

Format

clearLocal( );

Description

Resets the local attribute value from 1, meaning the source of the data is stored locally in a BLOB in the database, to 0, meaning the source of the data is stored externally.

Parameters

None.

Usage Notes

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

Pragmas

None.

Exceptions

None.

Examples

None.

12.3.2 close( )

Format

close(ctx IN OUT RAW) RETURN INTEGER;

Description

Closes a data source.

Parameters

ctx: The source plug-in context information. (See Important Notes for ORDSource Methods.)

Usage Notes

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

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

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.3 deleteLocalContent( )

Format

deleteLocalContent( );

Description

Deletes the local data from the localData attribute.

Parameters

None.

Usage Notes

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

Pragmas

None.

Exceptions

None.

Examples

None.

12.3.4 export( )

Format

export(ctx              IN OUT RAW,
       source_type      IN VARCHAR2,
       source_location  IN VARCHAR2,
       source_name      IN VARCHAR2);

Description

Copies data from the localData attribute within the database to an external data source.

Note:

The export( ) method provides native support only for a source.srcType value of FILE. In this case, the data is exported to a file in a directory that is accessible to Oracle Database. User-defined sources can support the export( ) method to provide WRITE access to other types of data stores.

Parameters

ctx: The source plug-in context information. (See Important Notes for ORDSource Methods.)
source_type: The type of the external source data. This parameter is not case-sensitive. (See Table 7-1.)
source_location: The location to which the source data is to be exported. (See Table 7-2.)
source_name: The name of the object to which the source data is to be exported. (See Table 7-3.)

Usage Notes

This method exports data from the localData attribute to the external data source specified by the input parameters.

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

After exporting data, all attributes remain unchanged except the srcType, srcLocation, and srcName attributes, which are updated with input parameter values. After calling the export( ) method, you can call the clearLocal( ) method to indicate that the data is stored outside the database, and then call the deleteLocalContent( ) method to delete the content of the local data in the localData attribute.

When the source_type parameter has a value of FILE, the source_location parameter specifies the name of an Oracle directory object, and the source_name parameter specifies the name of the file in which the data is to be contained.

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

For example, the following SQL*Plus commands create a directory object and grant the user ron permission to read and write to any file within the directory c:\mydir\work. Before executing these commands, you must be connected as a user with privileges to create a directory object.

CREATE OR REPLACE DIRECTORY FILE_DIR AS 'c:\mydir\work';
GRANT READ,WRITE ON DIRECTORY FILE_DIR TO ron;

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

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

Invoking this method implicitly calls the setUpdateTime( ) method.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.METHOD_NOT_SUPPORTED

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.5 getBFile( )

Format

getBFile( ) RETURN BFILE;

Description

Returns a BFILE handle, if the value of the srcType attribute is FILE.

Parameters

None.

Usage Notes

This method can be used only for a srcType of FILE.

Pragmas

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

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.INVALID_SOURCE_TYPE

This exception is raised if you call the getBFile( ) method and the value of the srcType attribute is other than FILE.

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.6 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 is to be allocated and initialized as a part of this call.

Parameters

ctx

The source plug-in context information. (See Important Notes for ORDSource Methods.)

tempLob

An uninitialized BLOB locator, which is to be allocated in this call.

mimeType

An output parameter to receive the MIME type of the data, for example, audio/basic.

format

An output 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:

DBMS_LOB.CALL

DBMS_LOB.TRANSACTION

DBMS_LOB.SESSION

cache

A Boolean value that indicates whether 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. (There is no ORD<object-type>Exceptions prefix to this exception because it is a predefined PL/SQL exception.)

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.7 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 the localData attribute, 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. (See Important Notes for ORDSource Methods.)

Usage Notes

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

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.8 getLocalContent( )

Format

getLocalContent( ) RETURN BLOB;

Description

Returns the content or BLOB handle of the localData attribute.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

None.

12.3.9 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 implemented only for user-defined sources.

Parameters

ctx: The source plug-in context information. (See Important Notes for ORDSource Methods.)
userData: User input 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 must 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 Fusion Middleware.

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

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

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

12.3.11 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

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.INCOMPLETE_SOURCE_LOCATION

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.12 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

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.INCOMPLETE_SOURCE_NAME

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

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

12.3.14 getUpdateTime( )

Format

getUpdateTime( ) RETURN DATE;

Description

Returns the time stamp of when the object was last changed, or what the user explicitly set by calling the setUpdateTime( ) method. (This method returns the value of the updateTime attribute.)

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

None.

12.3.15 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 the localData attribute within the database.

Parameters

ctx: The source plug-in context information. This information is passed along uninterpreted to the source plug-in handling the import( ) call. (See Important Notes for ORDSource Methods.)
mimeType: The output parameter to receive the MIME type of the data, if any, for example, audio/basic.
format: The output parameter to receive the format of the data, if any, for example, AUFF.

Usage Notes

Before calling this method, call setSourceInformation( ) method to set the srcType, srcLocation, and srcName attribute values to describe where the data source is located.

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

After importing data from an external 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).

If the value of the srcType attribute is FILE, the srcLocation attribute contains the name of a database directory object which contains the file to be imported, and the srcName attribute contains the name of the file to be imported. You must ensure that the directory for the external source location exists or is created before you use this method.

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

For example, the following SQL*Plus commands create a directory object and grant the user ron permission to read any file within the directory c:\mydir\work. Before executing these commands, you must be connected as a user with privileges to create a directory object.

CREATE OR REPLACE DIRECTORY FILE_DIR AS 'c:\mydir\work';
GRANT READ ON DIRECTORY FILE_DIR TO ron;

If the value of the srcType attribute is HTTP, the srcLocation attribute contains the base URL needed to find the source directory that contains the object to be imported, and the srcName attribute contains the name of the object to be imported.

This method 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 must 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 not be used for URLs in the specified domain.

See Also:

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

If the value of the source.srcType attribute is a user-defined name, the source.srcLocation attribute contains an identifier string required to access the user-defined object to be imported, and the source.srcName attribute contains the name of the object to be imported.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

ORDSourceExceptions.NULL_SOURCE

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.16 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 the localData attribute within the 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. (See Important Notes for ORDSource Methods.)
mimeType: The output parameter to receive the MIME type of the data, if any, for example, audio/basic.
format: The output parameter to receive the format of the data, if any, for example, AUFF.
source_type: The type of the source data to be imported. This also sets the srcType attribute. (See Table 7-1.)
source_location: The location from which the source data is to be imported. This also sets the srcLocation attribute. (See Table 7-2.)
source_name: The name of the source data to be imported. This also sets the srcName attribute. (See Table 7-3.)

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. This method is a combination of a setSourceInformation( ) method followed by an import( ) method.

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

If the value of the source_type parameter is FILE, the source_location parameter contains the name of a database directory object that contains the file to be imported, and the source_name parameter contains the name of the file to be imported. You must ensure that the directory indicated by the source_location parameter exists or is created before you use this method.

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

CREATE OR REPLACE DIRECTORY FILE_DIR AS 'c:\mydir\work';
GRANT READ ON DIRECTORY FILE_DIR TO ron;

If the value of the source_type parameter is HTTP, the source_location parameter contains the base URL needed to find the source directory that contains the object to be imported, and the source_name parameter contains the name of the object to be imported.

See Also:

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

If the value of the source_type parameter is a user-defined name, the source_location parameter contains an identifier string required to access the user-defined object to be imported, and the source_name parameter contains the name of the object to be imported.

Pragmas

None.

Exceptions

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 localData attribute is NULL.

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.17 isLocal( )

Format

isLocal( ) RETURN BOOLEAN;

Description

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

Parameters

None.

Usage Notes

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

Pragmas

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

Exceptions

None.

Examples

None.

12.3.18 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-defined input parameter.
ctx: The source plug-in context information. (See Important Notes for ORDSource Methods.)

Usage Notes

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

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.19 processCommand( )

Format

processCommand(ctx      IN OUT RAW,
               command  IN VARCHAR2,
               arglist  IN VARCHAR2,
               result   OUT RAW) RETURN RAW;

Description

Lets you 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. (See Important Notes for ORDSource Methods.)
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

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.20 read( )

Format

read(ctx       IN OUT RAW,
     startPos  IN INTEGER,
     numBytes  IN OUT INTEGER,
     buffer    OUT RAW);

Description

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

Parameters

ctx: The source plug-in context information. (See Important Notes for ORDSource Methods.)
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 is to 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. 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

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

ORDSourceExceptions.NULL_SOURCE

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.21 setLocal( )

Format

setLocal( );

Description

Sets the local attribute to indicate that the BLOB data is stored in the localData attribute within the database.

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.

12.3.22 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 attributes that describes the external data source.

Parameters

source_type: The type of the external source data. (See Table 7-1.)
source_location: The location of the external source data. (See Table 7-2.)
source_name: The name of the external source data. See Table 7-3.)

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 indicated by the source_location parameter exists or is created before you use this method.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

See Exceptions for Oracle Multimedia Objects for more information about this exception.

Examples

None.

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

12.3.24 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. (See Important Notes for ORDSource Methods.)
newlen: The trimmed new length.

Usage Notes

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

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.

12.3.25 write( )

Format

write(ctx       IN OUT RAW,
      startPos  IN INTEGER,
      numBytes  IN OUT INTEGER,
      buffer    IN RAW);

Description

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

Parameters

ctx: The source plug-in context information. (See Important Notes for ORDSource Methods.)
startPos: The start position in the source to where the buffer is to be copied.
numBytes: The number of bytes to be written to the source.
buffer: The buffer of data to be written.

Usage Notes

This method assumes that the source lets you write numBytes at a random byte location. For example, the FILE and HTTP source types cannot be written to and do not support this method.

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

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

ORDSourceExceptions.NULL_SOURCE

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

See Exceptions for Oracle Multimedia Objects for more information about these exceptions.

Examples

None.