Static Methods Common to All Object Types

The examples in this section assume that you have created the test tables as described in Example Audio Table Definition, Example Media Table Definition, Example Image Table Definition, and Example Video Table Definition, respectively for each object type.

This section presents reference information on the interMedia common static methods used for the relational interface.

export( )

Format

export(ctx IN OUT RAW,

local_data IN BLOB,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Copies data from a local source (local_data) within the database to an external data source.

Note:

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

Parameters

ctx: The source plug-in context information.
local_data: The BLOB location that is being exported.
source_type: The type of the source data that is being exported.
source_location: The location to which the source data is to be exported.
source_name: The name of the object to where the source data is to be exported.

Usage Notes

After calling the export( ) method, you can issue a SQL DELETE statement or call the DBMS_LOB.TRIM procedure to delete the content stored locally, if desired.

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 writes only to a database 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 the user and ORDSYS can write. The user must be granted the write permission so that he or she can write to the file; ORDSYS must be granted the write permission so that it can export the file on behalf of the user. (The installation procedure creates the ORDSYS user by default during installation. See Oracle interMedia User's Guide for more information.)

For example, the following SQL*Plus commands grant the user, MEDIAUSER, and ORDSYS the permission to write to the file named filmtrack1.au:

CALL DBMS_JAVA.GRANT_PERMISSION(
        'MEDIAUSER',
        'java.io.FilePermission',
        '/audio/movies/filmtrack1.au',
        'write');
CALL DBMS_JAVA.GRANT_PERMISSION(
        'ORDSYS',
        'java.io.FilePermission',
        '/audio/movies/filmtrack1.au',
        'write');

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

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

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

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

ORDSourceExceptions.IO_ERROR

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

See Appendix F for more information about these exceptions.

Examples

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

Note:

e:/mydir/work/testaud.dat must be replaced with the file specification of your test file and <system-password> with the system password.

CONNECT SYSTEM/<system-password>;
CREATE OR REPLACE DIRECTORY AUDIODIR AS 'e:/mydir/work';
GRANT READ ON DIRECTORY AUDIODIR TO PUBLIC WITH GRANT OPTION;

CALL DBMS_JAVA.GRANT_PERMISSION(
    'MEDIAUSER',
    'java.io.FilePermission',
    'e:/mydir/work/testaud.dat',
    'write');
CALL DBMS_JAVA.GRANT_PERMISSION(
  'ORDSYS',
  'java.io.FilePermission',
  '/private1/adetwork/istuart_imedt/work/testaud.dat',
  'write');

CONNECT MEDIAUSER/MEDIAUSER;
DECLARE
  audio_data BLOB;
  ctx RAW(64) :=NULL;
BEGIN
  SELECT aud INTO audio_data FROM taud WHERE N = 1;
  ORDSYS.ORDAudio.export(ctx,audio_data,'file','AUDIODIR','testaud.dat');
EXCEPTION
  WHEN OTHERS THEN
  RAISE;
END;
/

importFrom( )

Format

importFrom(ctx IN OUT RAW,

local_data IN OUT NOCOPY BLOB,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

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

Parameters

ctx: The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
local_data: The BLOB location to receive the data.
source_type: The type of the source data.
source_location: The location from which the source data is to be imported.
source_name: The name of the source data.

Usage Notes

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

Pragmas

None.

Exceptions

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the importFrom( ) method and the value of the local_data parameter is NULL or has not been initialized.

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

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

See Appendix F for more information about these exceptions.

Examples

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

Note:

<ORACLE_HOME> must be replaced with your Oracle home and <system-password> with the system password.

CONNECT system/<system-password>;
CREATE OR REPLACE DIRECTORY DOCDIR AS 'e:\<ORACLE_HOME>\ord\doc\demo';
GRANT READ ON DIRECTORY DOCDIR TO PUBLIC WITH GRANT OPTION;

CONNECT MEDIAUSER/MEDIAUSER;

DECLARE
  document_data BLOB;
  ctx RAW(64) :=NULL;
BEGIN
   SELECT document INTO document_data FROM tdoc WHERE N = 1 FOR UPDATE;
   ORDSYS.ORDDoc.importFrom(ctx,document_data,'file','DOCDIR','testimg.dat');
   UPDATE tdoc SET document = document_data WHERE N = 1;
   COMMIT;
   SELECT document INTO document_data FROM tdoc WHERE N = 2 FOR UPDATE;
   ORDSYS.ORDDoc.importFrom(ctx,document_data,'file','DOCDIR','testaud.dat');
   UPDATE tdoc SET document = document_data WHERE N = 2;
   COMMIT;
   SELECT document INTO document_data FROM tdoc WHERE N = 3 FOR UPDATE;
   ORDSYS.ORDDoc.importFrom(ctx,document_data,'file','DOCDIR','testvid.dat');
   UPDATE tdoc SET document = document_data WHERE N = 3;
   COMMIT;
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/

importFrom( ) (all attributes)

Format

importFrom(ctx IN OUT RAW,

local_data IN OUT NOCOPY BLOB,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2,

format OUT VARCHAR2,

mime_type OUT VARCHAR2);

Description

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

Parameters

ctx: The source plug-in context information.
local_data: The BLOB location to receive the data.
source_type: The type of the source data.
source_location: The location from which the source data is to be imported.
source_name: The name of the source data.
format: The format of the data. The value is returned if it is available (from HTTP sources).
mime_type: The MIME type of the data. The value is returned if it is available (from HTTP sources).

Usage Notes

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

Pragmas

None.

Exceptions

ORDSourceExceptions.NULL_SOURCE

This exception is raised if you call the importFrom( ) method and the value of the local_data parameter is NULL or has not been initialized.

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

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

See Appendix F for more information about these exceptions.

Examples

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

Note:

<ORACLE_HOME> must be replaced with your Oracle home and <system-password> with the system password.

CONNECT system/<system-password>;
CREATE OR REPLACE DIRECTORY IMAGEDIR AS 'e:\<ORACLE_HOME>\ord\img\demo';
GRANT READ ON DIRECTORY IMAGEDIR TO PUBLIC WITH GRANT OPTION;

DECLARE
  image_data BLOB;
  ctx RAW(64) :=NULL;
  img_format     VARCHAR2(32)  := NULL;
  img_mime_type  VARCHAR2(80);
BEGIN
   SELECT img INTO image_data FROM timg WHERE N = 1 FOR UPDATE;
   ORDSYS.ORDImage.importFrom(ctx,image_data,'file','IMAGEDIR','testimg.dat',img_format,img_mime_type);
   UPDATE timg SET img = image_data WHERE N = 1;
   COMMIT;
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/