Oracle interMedia Audio, Image, and Video User's Guide and Reference
Release 8.1.7

Part Number A85336-01

Library

Product

Contents

Index

Go to previous page Go to next page

5
ORDImage Reference Information

Oracle interMedia contains the following information about the ORDImage type:

The examples in this chapter assume that the test image tables EMP and OLD_IMAGE have been created and filled with data. These tables were created using the SQL statements described in Section 5.3.1.


Note:

If you manipulate the image data itself (by either directly modifying the BLOB or changing the external source), then you must ensure that the object attributes stay synchronized and the update time is modified; otherwise, the object attributes will not match the image data. 


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 source.open( ) method. At this point, the source plug-in can initialize the context for this client. When processing is complete, the client should invoke the source.close( ) method.

Methods invoked from a source plug-in call have the first 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. 


5.1 Object Types

Oracle interMedia describes the ORDImage object type, which supports the storage, management, and manipulation of image data.


ORDImage Object Type

The ORDImage object type supports the storage and management of image data. This object type is defined as follows:

CREATE OR REPLACE TYPE ORDImage
AS OBJECT
(
  -------------------
  -- TYPE ATTRIBUTES
  -------------------
  source              ORDSource,
  height              INTEGER,
  width               INTEGER,
  contentLength       INTEGER,
  fileFormat          VARCHAR2(4000),
  contentFormat       VARCHAR2(4000),
  compressionFormat   VARCHAR2(4000),
  mimeType            VARCHAR2(4000),

---------------------
-- METHOD DECLARATION
---------------------
-- CONSTRUCTORS
--
STATIC FUNCTION init( ) RETURN ORDImage,
STATIC FUNCTION init(srcType     IN VARCHAR2,
                     srcLocation IN VARCHAR2,
                     srcName     IN VARCHAR2) RETURN ORDImage,

  -- Methods associated with copy operations 
  MEMBER PROCEDURE copy(dest IN OUT ORDImage),
	
  -- Methods associated with image process operations 
  MEMBER PROCEDURE process(command IN VARCHAR2),

  MEMBER PROCEDURE processCopy(command IN     VARCHAR2, 
                               dest    IN OUT ORDImage),

  -- Methods associated with image property set and check operations
  MEMBER PROCEDURE setProperties,

  MEMBER PROCEDURE setProperties(description IN VARCHAR2),

  MEMBER FUNCTION checkProperties RETURN BOOLEAN,

  -- Methods associated with image attributes accessors
  MEMBER FUNCTION getHeight RETURN INTEGER,
  PRAGMA RESTRICT_REFERENCES(getHeight, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getWidth RETURN INTEGER,
  PRAGMA RESTRICT_REFERENCES(getWidth, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getContentLength RETURN INTEGER,
  PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getFileFormat RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getFileFormat, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getContentFormat RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getContentFormat, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getCompressionFormat RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getCompressionFormat, WNDS, WNPS, RNDS, RNPS), 

  -- 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 date attribute
  MEMBER FUNCTION  getUpdateTime RETURN DATE,
  PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS),
  MEMBER PROCEDURE setUpdateTime(current_time DATE),

  -- Methods associated with the mimeType attribute
  MEMBER FUNCTION  getMimeType RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getMimeType, WNDS, WNPS, RNDS, RNPS),
  MEMBER PROCEDURE setMimeType(mime IN VARCHAR2),

  -- Methods associated with the source attribute
  MEMBER FUNCTION  getContent RETURN BLOB,
  PRAGMA RESTRICT_REFERENCES(getContent, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION getBFILE RETURN BFILE,
  PRAGMA RESTRICT_REFERENCES(getBFILE, WNDS, WNPS, RNDS, RNPS),

  MEMBER PROCEDURE deleteContent,

  MEMBER PROCEDURE setSource(source_type     IN VARCHAR2,
                             source_location IN VARCHAR2,
                             source_name     IN VARCHAR2),
  MEMBER FUNCTION  getSource RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSource, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION  getSourceType RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSourceType, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION  getSourceLocation RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSourceLocation, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION  getSourceName RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSourceName, WNDS, WNPS, RNDS, RNPS),

  MEMBER PROCEDURE import(ctx IN OUT RAW),
  MEMBER PROCEDURE importFrom(ctx         IN OUT RAW,
                          source_type     IN VARCHAR2,
                          source_location IN VARCHAR2,
                          source_name     IN VARCHAR2),
  MEMBER PROCEDURE export(ctx             IN OUT RAW,
                          source_type     IN VARCHAR2,
                          source_location IN VARCHAR2,
                          source_name     IN VARCHAR2),

  -- Methods associated with image migration
  MEMBER PROCEDURE migrateFromORDImgB(old_object  ORDImgB),
  MEMBER PROCEDURE migrateFromORDImgF(old_object  ORDImgF)
);

where:

5.2 Constructors

This section describes the constructor functions.

The interMedia image constructor functions are as follows:


init( ) Method

Format

init( ) RETURN ORDImage;

Description

Allows for easy initialization of instances of the ORDImage object type.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

This static method initializes all the ORDImage attributes to NULL with the following exceptions:

You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDImage object type, especially if the ORDImage type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.

Examples

Initialize the ORDImage object attributes:

DECLARE
  myImage ORDSYS.ORDImage;
BEGIN
  myImage := ORDSYS.ORDImage.init( );
INSERT INTO emp VALUES (myImage);
END;
/

init(srcType,srcLocation,srcName) Method

Format

init(srcType IN VARCHAR2,

srcLocation IN VARCHAR2,

srcName IN VARCHAR2)

RETURN ORDImage;

Description

Allows for easy initialization of instances of the ORDImage object type.

Parameters

srcType

The source type of the image data.

srcLocation

The source location of the image data.

srcName

The source name of the image data.

Pragmas

None.

Exceptions

None.

Usage Notes

This static method initializes all the ORDImage attributes to NULL with the following exceptions:

You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDImage object type, especially if the ORDImage type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.

Examples

Initialize the ORDImage object attributes:

DECLARE
  myImage ORDSYS.ORDImage;
BEGIN
  myImage := ORDSYS.ORDImage.init('FILE','IMGDIR','image1.gif');
INSERT INTO emp VALUES (myImage);
END;
/

5.3 Methods

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

ORDImage Methods Associated with copy Operations

ORDImage Methods Associated with process Operations

ORDImage Methods Associated with properties set and check Operations

ORDImage Methods Associated with image Attributes

ORDImage Methods Associated with the local Attribute

ORDImage Methods Associated with the date Attribute

ORDImage Methods Associated with the mimeType Attribute

ORDImage Methods Associated with the source Attribute

ORDImage Methods Associated with Image Migration

5.3.1 Example Table Definitions

The methods described in this chapter show examples based on a test image table EMP. Refer to the EMP table definition that follows when reading through the examples in Section 5.3.2 through Section 5.3.9:

EMP Table Definition

CREATE TABLE emp (
  ename VARCHAR2(50),
  salary NUMBER,
  job VARCHAR2(50),
  department INTEGER,
  photo ORDSYS.ORDImage,
  large_photo ORDSYS.ORDImage);
DECLARE
  Image ORDSYS.ORDImage;
BEGIN
  INSERT INTO emp VALUES ('John Doe', 24000, 'Technical Writer', 123,
      ORDSYS.ORDImage.imit('file','ORDIMGDIR','jdoe.gif'));
  INSERT INTO emp VALUES ('Jane Doe', 24000, 'Technical Writer', 456,
      ORDSYS.ORDImage.init('file','ORDIMGDIR','jadoe.gif'));
  SELECT large_photo INTO Image FROM emp
         WHERE ename = 'John Doe' FOR UPDATE;
  Image.setProperties;
  UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
  COMMIT;
  SELECT large_photo INTO Image FROM emp
         WHERE ename = 'Jane Doe' FOR UPDATE;
  Image.setProperties;
  UPDATE emp SET large_photo = Image WHERE ename = 'Jane Doe';
  COMMIT;
END;
/

Refer to the EMP and OLD_IMAGES table definitions that follow when reading through the examples in Section 5.3.10.

EMP and OLD_IMAGES Table Definitions

CREATE TABLE emp (
  ename VARCHAR2(50),
  salary NUMBER,
  job VARCHAR2(50),
  department INTEGER,
  large_photo ORDSYS.ORDImage);
CREATE TABLE old_images (
  id NUMBER,
  imageb ORDSYS.ORDIMGB,
  imagef ORDSYS.ORDIMGF);
DECLARE
  blobimage ORDSYS.ORDIMGB;
  bfileimage ORDSYS.ORDIMGF;
BEGIN
  INSERT INTO old_images values
      (1, ORDSYS.ORDIMGB(empty_blob(),NULL,NULL,NULL,NULL,NULL,NULL),
       ORDSYS.ORDIMGF(bfilename('ORDIMGDIR','jdoe.gif'),
                      NULL,NULL,NULL,NULL,NULL,NULL));
  SELECT imageb, imagef INTO blobimage, bfileimage
     FROM old_images WHERE id = 1 FOR UPDATE;
  bfileimage.copyContent(blobimage.content);
  blobimage.setProperties;
  bfileimage.setProperties;
  UPDATE old_images SET imageb=blobimage, imagef=bfileimage WHERE id = 1;
  INSERT INTO emp values
    ( 'John Doe', 24000, 'Technical Writer', 123,
     ORDSYS.ORDImage.init());
  COMMIT;
end;
/

5.3.2 ORDImage Methods Associated with Copy Operations

This section presents reference information on the ORDImage method associated with the copy operation.


copy( ) Method

Format

copy(dest IN OUT ORDImage);

Description

Copies an image without changing it.

Parameters

dest

The destination of the new image.

Usage Notes

This method copies the image data, as is, including all source and image attributes, into the supplied local destination image.

If the data is stored locally in the source, then calling this method copies the BLOB to the destination source.localData attribute.

Calling this method copies the external source information to the external source information of the new image whether or not source data is stored locally.

Calling this method implicitly calls the setUpdateTime method on the destination object to update its timestamp information.

Pragmas

None.

Exceptions

NULL_LOCAL_DATA

This exception is raised if you call the copy( ) method and the destination source.localData attribute is not initialized.

This exception is raised if you call the copy( ) method and the source.isLocal attribute value is 1 and the source.localData attribute value is NULL.

Examples

Create a copy of the image:

DECLARE
    Image_1 ORDSYS.ORDImage;
    Image_2 ORDSYS.ORDImage;
BEGIN
    SELECT photo, large_photo
       INTO Image_2, Image_1
       FROM emp
       WHERE ename = 'John Doe' FOR UPDATE;
    -- copy the data from Image_1 to Image_2
    Image_1.copy(Image_2);
    UPDATE emp SET photo = Image_2
        WHERE ename = 'John Doe';
END;
/

5.3.3 ORDImage Methods Associated with Process Operations

This section presents reference information on the ORDImage methods associated with the process operation.


process( ) Method

Format

process(command IN VARCHAR2);

Description

Performs one or more image processing operations on a BLOB, writing the image back on to itself.

Parameters

command

A list of image processing operations to perform on the image.

Usage Notes

You can change one or more of the image attributes shown in Table 5-1. Table 5-2 shows additional changes that can be made only to raw pixel and foreign images.

Table 5-1 Image Processing Operators 
Operator Name  Usage  Values 

compressionFormat 

Compression type/format 

JPEG, SUNRLE, BMPRLE, TARGARLE, LZW, LZWHDIFF, FAX3, FAX4, HUFFMAN3, Packbits, GIFLZW 

compressionQuality 

Compression quality 

MAXCOMPRATIO, MAXINTEGRITY, LOWCOMP, MEDCOMP, HIGHCOMP 

contentFormat 

Image type/pixel/data format 

MONOCHROME, 8BITGRAYSCALE, 8BITGREYSCALE, 8BITLUT, 24BITRGB  

cut 

Window to cut or crop (origin.x origin.y width height) 

(Integer Integer Integer Integer)
maximum value is 65535 

fileFormat 

File format of the image 

BMPF, CALS, GIFF, JFIF, PICT, RASF, RPIX, TGAF, TIFF 

fixedScale 

Scale to a specific size in pixels (width, height) 

(INTEGER INTEGER) 

maxScale 

Scale to a specific size in pixels, while maintaining the aspect ratio (maxWidth, maxHeight) 

(INTEGER INTEGER) 

scale 

Scale factor (for example, 0.5 or 2.0) 

<FLOAT> positive 

xScale 

X-axis scale factor (default is 1) 

<FLOAT> positive 

yScale 

Y-axis scale factor (default is 1) 

<FLOAT> positive 

Table 5-2 Additional Image Processing Operators for Raw Pixel and Foreign Images 
Operator Name  Usage  Values 

channelOrder 

Indicates the relative position of the red, green, and blue channels (bands) within the image. 

RGB (default), RBG, GRB, GBR, BRG, BGR 

inputChannels 

For multiband images, specify either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third). Note that this parameter affects the source image, not the destination. 

INTEGER or
INTEGER INTEGER INTEGER 

interleave 

Controls band layout within the image:
Band Interleaved by Pixel
Band Interleaved by Line
Band Sequential 

BIP (default), BIL, BSQ 

pixelOrder 

If NORMAL, then the leftmost pixel appears first in the image. 

NORMAL (default), REVERSE 

scanlineOrder 

If NORMAL, then the top scanline appears first in the image. 

NORMAL (default), INVERSE 


Note:

When specifying values that include floating-point numbers, you must use double quotation marks ("") around the value. If you do not, the wrong values may be passed and you will get incorrect results. 


There is no implicit import( ) or importFrom( ) call performed when you call this method; if data is external, you must first call import( ) or importFrom( ) to make the data local before you can process it.

Implicit setProperties( ), setUpdateTime( ), and setMimeType( ) methods are done after the process( ) method is called.

See Appendix D for more information on process( ) method operators.

Pragmas

None.

Exceptions

DATA_NOT_LOCAL

This exception is raised if you call the process( ) method and the data is not local or the source.localData attribute is not initialized.

Examples

Example 1: Change the file format of image1 to GIF:

image1.process('fileFormat=GIFF');

Example 2: Change image1 to use lower quality JPEG compression and double the length of the image along the X-axis:

image1.process('compressionFormat=JPEG, compressionQuality=MAXCOMPRATIO, 
xScale="2.0"'); 

Note that changing the length on only one axis (for example, xScale=2.0) does not affect the length on the other axis, and would result in image distortion. Also, only the xScale and yScale parameters can be combined in a single operation. Any other combinations of scale operators result in an error.

The maxScale and fixedScale operators are especially useful for creating thumbnail images from various-sized originals. The following line creates at most a 32-by-32 pixel thumbnail image, preserving the original aspect ratio:

image1.process('maxScale=32 32');

Example 3: Convert the image to TIFF:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT photo INTO Image FROM emp
        WHERE ename = 'John Doe' FOR UPDATE;
        Image.process('fileFormat=TIFF');
    UPDATE emp SET photo = Image WHERE ename = 'John Doe';
END;
/


processCopy( ) Method

Format

processCopy(command IN VARCHAR2,

dest IN OUT ORDImage);

Description

Copies an image stored internally or externally to another image stored internally in a BLOB.

Parameters

command

A list of image processing changes to make for the image in the new copy.

dest

The destination of the new image.

Usage Notes

See Table 5-1, "Image Processing Operators" and Table 5-2, "Additional Image Processing Operators for Raw Pixel and Foreign Images".

You cannot specify the same BLOB as both the source and destination.

Calling this method processes the image into the destination BLOB from any source (local or external).

Implicit setProperties( ), setUpdateTime( ), and setMimeType( ) methods are done on the destination image after the processCopy( ) method is called.

See Appendix D for more information on processCopy operators.

Pragmas

None.

Exceptions

NULL_DESTINATION

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

DATA_NOT_LOCAL

This exception is raised if you call the processCopy( ) method and the dest.source.isLocal attribute value is FALSE, (the destination image must be local).

NULL_LOCAL_DATA

This exception is raised if you call the processCopy( ) method and the dest.source.localData attribute value is NULL (destination image must be initialized).

This exception is raised if you call the processCopy( ) method and the source.isLocal attribute value is 1 and the source.localData attribute value is NULL.

Examples

Copy an image, changing the file format, compression format, and data format in the destination image:

DECLARE
    Image_1 ORDSYS.ORDImage;
    Image_2 ORDSYS.ORDImage;
    mycommand VARCHAR2(400);
BEGIN
    SELECT photo, large_photo
        INTO Image_2, Image_1
        FROM emp
        WHERE ename = 'John Doe' FOR UPDATE;
    mycommand := 'fileFormat=tiff compressionFormat=packbits
                contentFormat = 8bitlut';
    Image_1.processCopy(mycommand, Image_2);
    UPDATE emp SET photo = Image_2 WHERE ename = 'John Doe';
END;
/

5.3.4 ORDImage Methods Associated with Properties Set and Check Operations

This section presents reference information on the ORDImage methods associated with the properties set and check operations.


setProperties Method

Format

setProperties;

Description

Reads the image data to get the values of the object attributes, then stores them into the appropriate attribute fields. The image data can be stored in the database in a BLOB, or externally in a BFILE or URL. If the data is stored externally in anything other than a BFILE, the data is read into a temporary BLOB in order to determine the image characteristics.

This method should not be called for foreign images. Use the setProperties(description) method for foreign images.

Parameters

None.

Usage Notes

After you have copied, stored, or processed a native format image, call this method to set the current characteristics of the new content, except when this method is called implicitly.

This method sets the following information about an image:

Calling this method implicitly calls the setUpdateTime( ) and the setMimeType( ) methods.

Pragmas

None.

Exceptions

NULL_LOCAL_DATA

This exception is raised if you call the setProperties( ) method and the source.isLocal attribute value is 1 and the source.localData attribute value is NULL.

Examples

Select the image, and then set the attributes using the setProperties method:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    INSERT INTO emp VALUES ('John Doe', 24000, 'Technical Writer', 123,
      ORDSYS.ORDImage(ORDSYS.ORDSource(empty_blob(),'file','ORDIMGDIR',
                                       'jdoe.gif',SYSDATE,0),
                      NULL,NULL,NULL,NULL,NULL,NULL,NULL));
    -- select the newly inserted row for update
    SELECT large_photo INTO Image FROM emp
           WHERE ename = 'John Doe' FOR UPDATE;
    -- set property attributes for the image data
    Image.setProperties;
    DBMS_OUTPUT.PUT_LINE('image width = ' || image.getWidth);
    DBMS_OUTPUT.PUT_LINE('image height = ' || image.getHeight);
    DBMS_OUTPUT.PUT_LINE('image size = ' || image.getContentLength);
    DBMS_OUTPUT.PUT_LINE('image file type = ' || image.getFileFormat);
    DBMS_OUTPUT.PUT_LINE('image type = ' || image.getContentFormat);
    DBMS_OUTPUT.PUT_LINE('image compression = ' || image.getCompressionFormat);
    DBMS_OUTPUT.PUT_LINE('image mime type = ' || image.getMimeType);
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
 END;
/

Example output:

image width = 360
image height = 490
image size = 66318
image file type = JFIF
image type = 24BITRGB
image compression = JPEG
image mime type = image/jpeg

setProperties( ) Method for Foreign Images

Format

setProperties(description IN VARCHAR2);

Description

Allows you to write the characteristics of a foreign image into the appropriate attribute fields.

Parameters

description

Specifies the image characteristics to set for the foreign image.

Usage Notes


Note:

Once you have set the properties for a foreign image, it is up to you to keep the properties consistent. If interMedia image detects an unknown file format, it will not implicitly set the properties. 


After you have copied, stored, or processed a foreign image, call this method to set the characteristics of the new image content. Unlike the native image types described in Appendix E, foreign images either do not contain information on how to interpret the bits in the file or, interMedia image does not understand the information. In this case, you must set the information explicitly.

You can set the following image characteristics for foreign images, as shown in Table 5-3.

Table 5-3 Image Characteristics for Foreign Files 
Field  Data Type  Description 

CompressionFormat 

STRING 

Value must be CCITG3, CCITG4, or NONE (default). 

DataOffset 

INTEGER 

The offset allows the image to have a header that interMedia image does not try to interpret. Set the offset to avoid any potential header. The value must be a positive integer less than the LOB length. Default is zero. 

DefaultChannelSelection 

INTEGER 

For multiband images, specify either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third). For example, DefaultChannelSelection = 1 for single-band images and DefaultChannelSelection = 1, 2, 3 for triple-band images. 

Height 

INTEGER 

Height of the image in pixels. Value must be a positive integer. There is no default, thus a value must be specified. 

Interleaving 

STRING 

Band layout within the image. Valid styles are:

  • BIP (default) Band Interleaved by Pixel

  • BIL Band Interleaved by Line

  • BSQ Band Sequential

 

NumberOfBands 

INTEGER 

Value must be a positive integer less than 255 describing the number of color bands in the image. Default is 3. 

PixelOrder 

STRING 

If NORMAL (default), the leftmost pixel appears first in the file. If REVERSE, the rightmost pixel appears first. 

ScanlineOrder 

STRING 

If NORMAL (default), the top scanline appears first in the file. If INVERSE, then the bottom scanline appears first. 

UserString 

STRING 

A 4-character descriptive string. If used, the string is stored in the fileFormat field, appended to the file format ("OTHER:"). Default is blank and fileFormat is set to "OTHER". 

Width 

INTEGER 

Width of the image in pixels. Value must be a positive integer. There is no default, thus a value must be specified. 

MimeType 

STRING 

Value must be a MIME type, such as img/gif. 

The values supplied to setProperties( ) are written to the existing ORDImage data attributes. The fileFormat is set to "OTHER" and includes the user string, if supplied; for example, 'OTHER: LANDSAT'.

Pragmas

None.

Exceptions

NULL_PROPERTIES_DESCRIPTION

This exception is raised if you call the setProperties( ) method for Foreign Images and the description attribute value is NULL.

Examples

Select the foreign image and then set the properties for the image:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp
           WHERE ename = 'John Doe' FOR UPDATE;
    -- set property attributes for the image data
    Image.setProperties('width=123 height=321 compressionFormat=NONE' ||
                        ' userString=DJM dataOffset=128' ||
                        ' scanlineOrder=INVERSE pixelOrder=REVERSE' ||
                        ' interleaving=BIL numberOfBands=1' ||
                        ' defaultChannelSelection=1');
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/


checkProperties Method

Format

checkProperties RETURN BOOLEAN;

Description

Verifies that the properties stored in attributes of the image object match the properties of the image. This method should not be used for foreign images.

Parameters

None.

Usage Notes

Use this method to verify that the image attributes match the actual image.

Pragmas

None.

Exceptions

None.

Examples

Check the image attributes:

DECLARE
    Image ORDSYS.ORDImage;
    properties_match BOOLEAN;
BEGIN
    SELECT large_photo INTO Image FROM emp
        WHERE ename = 'John Doe' FOR UPDATE;
    -- check that properties match the image
    properties_match := Image.checkProperties;
    IF properties_match THEN
        DBMS_OUTPUT.PUT_LINE('Check Properties succeeded');
    END IF;
END;
/

5.3.5 ORDImage Methods Associated with Image Attributes

This section presents reference information on the ORDImage methods associated with the image attributes.


getHeight Method

Format

getHeight RETURN INTEGER;

Description

Returns the height of an image in pixels. This method does not actually read the image; it is a simple accessor method that returns the value of the height attribute.

Parameters

None.

Usage Notes

Use this method rather than accessing the height attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

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

Exceptions

None.

Examples

Get the height of an image:

DECLARE
    Image ORDSYS.ORDImage;
    Height INTEGER;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image height
    Height := Image.getHeight;
END;
/


getWidth Method

Format

getWidth RETURN INTEGER;

Description

Returns the width of an image in pixels. This method does not actually read the image; it is a simple accessor method that returns the value of the width attribute.

Parameters

None.

Usage Notes

Use this method rather than accessing the width attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

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

Exceptions

None.

Examples

Get the width of an image:

DECLARE
    Image ORDSYS.ORDImage;
    Width INTEGER;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image width
    Width := Image.getWidth;
END;
/


getContentLength Method

Format

getContentLength RETURN INTEGER;

Description

Returns the length of the image data content stored in the source. This method does not actually read the image; it is a simple access method that returns the value of the content length attribute.

Parameters

None.

Usage Notes

Use this method rather than accessing the contentLength attribute directly to protect from potential future changes to the internal representation of the ORDImage object.

Pragmas

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

Exceptions

None.

Examples

Get the length of the image data content stored in the source:

DECLARE
    Image ORDSYS.ORDImage;
    ContentLength INTEGER;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image size
    ContentLength := Image.getContentLength;
END;

getFileFormat Method

Format

getFileFormat RETURN VARCHAR2;

Description

Returns the file type of an image (such as TIFF or JFIF). This method does not actually read the image; it is a simple accessor method that returns the value of the fileFormat attribute.

Parameters

None.

Usage Notes

Use this method rather than accessing the fileFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

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

Exceptions

None.

Examples

Get the file type of an image:

DECLARE
    Image ORDSYS.ORDImage;
    FileFormat VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image file format
    FileFormat := Image.getFileFormat;
END;

getContentFormat Method

Format

getContentFormat RETURN VARCHAR2;

Description

Returns the content type of an image (such as monochrome or 8-bit grayscale). This method does not actually read the image; it is a simple accessor method that returns the value of the contentFormat attribute.

Parameters

None.

Usage Notes

Use this method rather than accessing the contentFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

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

Exceptions

None.

Examples

Get the type of an image:

DECLARE
    Image ORDSYS.ORDImage;
    ContentFormat VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image content format
    ContentFormat := Image.getContentFormat;
END;

getCompressionFormat Method

Format

getCompressionFormat RETURN VARCHAR2;

Description

Returns the compression type of an image. This method does not actually read the image, it is a simple accessor method that returns the value of the compressionFormat attribute.

Parameters

None.

Usage Notes

Use this method rather than accessing the compressionFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

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

Exceptions

None.

Examples

Get the compression type of an image:

DECLARE
    Image ORDSYS.ORDImage;
    CompressionFormat VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image compression format
    CompressionFormat := Image.getCompressionFormat;
END;

5.3.6 ORDImage Methods Associated with the local Attribute

This section presents reference information on the ORDImage methods associated with the local attribute.


setLocal Method

Format

setLocal;

Description

Sets the local attribute to indicate that the data is stored internally in a BLOB. When local is set, image methods look for image data in the source.localData attribute.

Parameters

None.

Usage Notes

Sets the local attribute to 1, meaning the data is stored locally in the localData attribute.

Pragmas

None.

Exceptions

NULL_LOCAL_DATA

This exception is raised if you call the setLocal method and the source.localData attribute value is NULL.

Examples

Set the flag to local for the data:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
    -- set local so we look for the image in the database
    Image.setLocal;
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

clearLocal Method

Format

clearLocal;

Description

Resets the local flag to indicate that the data is stored externally. When the local flag is set to clear, image methods look for image data using the srcLocation, srcName, and srcType attributes.

Parameters

None.

Usage Notes

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

Pragmas

None.

Exceptions

None.

Examples

Clear the value of the local flag for the data:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
    -- clear local so we look for image externally
    Image.clearLocal;
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/


isLocal Method

Format

isLocal RETURN BOOLEAN;

Description

Returns TRUE if the data is stored locally in a BLOB 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

Determine whether or not the data is local:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe';
    -- check to see if image is stored locally
    IF Image.isLocal THEN
        DBMS_OUTPUT.PUT_LINE('Image is stored locally');
    ELSE
        DBMS_OUTPUT.PUT_LINE('Image is stored externally');
    END IF;
END;
/

5.3.7 ORDImage Methods Associated with the date Attribute

This section presents reference information on the ORDImage methods associated with the date attribute.


getUpdateTime Method

Format

getUpdateTime RETURN DATE;

Description

Returns the time when the object was last updated.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

Get the updated time of some image object:

DECLARE
    Image ORDSYS.ORDImage;
    UpdateTime DATE;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image update time
    UpdateTime := Image.getUpdateTime;
END;
/


setUpdateTime( ) Method

Format

setUpdateTime(current_time DATE);

Description

Sets the time when the image data was last updated. Use this method whenever you modify the image data. The methods copy( ), process( ), processCopy( ), setProperties, setMimeType( ), and export( ) call this method implicitly.

Parameters

current_time

The timestamp to be stored. Default is SYSDATE.

Usage Notes

You must invoke this method any time you modify the image data yourself.

Pragmas

None.

Exceptions

None.

Examples

Set the updated time of some image data:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- set the image update time
    Image.setUpdateTime(SYSDATE);
END;
/

5.3.8 ORDImage Methods Associated with the mimeType Attribute

This section presents reference information on the ORDImage methods associated with the mimeType attribute.


getMimeType Method

Format

getMimeType RETURN VARCHAR2;

Description

Returns the MIME type for the image data. This is a simple accessor method that returns the value of the mimeType attribute.

Parameters

None.

Usage Notes

Use this method rather than accessing the mimeType attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object. If the source is a file or BLOB, the MIME type information is generated.

For unrecognized file formats, users must call the setMimeType( ) method and specify the MIME type.

Pragmas

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

Exceptions

None.

Examples

Return the MIME type:

DECLARE
    Image ORDSYS.ORDImage;
    MimeType VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image mime type
    MimeType := Image.getMimeType;
END;
/


setMimeType( ) Method

Format

setMimeType(mime IN VARCHAR2);

Description

Allows you to set the MIME type of the image data.

Parameters

mime

The MIME type.

Usage Notes

You can override the automatic setting of MIME information by calling this method with a specified MIME value.

You must call this method to set the MIME type for foreign images.

Calling this method implicitly calls the setUpdateTime( ) method.

The methods setProperties, process( ), and processCopy( ) call this method implicitly.

The MIME type is extracted from the HTTP header on import for HTTP sources.

Pragmas

None.

Exceptions

None.

Examples

Set the MIME type for some stored image data:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- set the image mime type
    Image.setMimeType('image/bmp');
END;

5.3.9 ORDImage Methods Associated with the source Attribute

This section presents reference information on the ORDImage methods associated with the source attribute.


getContent Method

Format

getContent RETURN BLOB;

Description

Returns a handle to the local LOB storage, that is the BLOB within the ORDImage object.

Parameters

None.

Usage Notes

None.

Pragmas

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

Exceptions

None.

Examples

A client accesses image data:

DECLARE
    Image ORDSYS.ORDImage;
    localData BLOB;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image BLOB
    localData := Image.getContent;
END;
/


getBFILE Method

Format

getBFILE RETURN BFILE;

Description

Returns the LOB locator of the BFILE containing the image.

Parameters

None.

Usage Notes

This method constructs and returns a BFILE using the stored source.srcLocation and source.srcName attribute information. The source.srcLocation attribute must contain a defined directory object. The source.srcName attribute must be a valid file name.

Pragmas

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

Exceptions

If the source.srcType attribute value is NULL, 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.

Examples

Return the BFILE for the stored source directory and file name attributes:

DECLARE
    Image ORDSYS.ORDImage;
    imagebfile BFILE;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image BFILE
    imagebfile := Image.getBFILE;
END;

deleteContent Method

Format

deleteContent;

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 image data source and you no longer need this data in the local source.

Call this method when you want to update the object with a new object.

Pragmas

None.

Exceptions

None.

Examples

Delete the local data from the current local source:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe' FOR UPDATE;
    -- delete the local content of the image
    Image.deleteContent;
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

setSource( ) Method

Format

setSource(source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Sets or alters information about the external source of the image data.

Parameters

source_type

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

source_location

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

source_name

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

Usage Notes

Users can use this method to set the image data source to a new BFILE or URL. Calling this method implicitly calls the setUpdateTime( ) method and the clearLocal method.

Pragmas

None.

Exceptions

None.

Examples

Set the source of the image data:

DECLARE
    Image ORDSYS.ORDImage;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- set source information for the image
    Image.setSource('file',
                    'ORDIMGDIR',
                    'jdoe.gif');
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/


getSource Method

Format

getSource RETURN VARCHAR2;

Description

Returns information about the external location of the image data in URL format.

Parameters

None.

Usage Notes

Possible return values are:

Pragmas

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

Exceptions

None.

Examples

Get the source of the image data:

DECLARE
    Image ORDSYS.ORDImage;
    SourceInfo VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source information
    SourceInfo := Image.getSource;
END;

getSourceType Method

Format

getSourceType RETURN VARCHAR2;

Description

Returns a string containing the type of the external image data source.

Parameters

None.

Usage Notes

This method returns a VARCHAR2 string containing the type of the external image data source, for example 'FILE'.

Pragmas

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

Exceptions

None.

Examples

Get the source type information about an image data source:

DECLARE
    Image ORDSYS.ORDImage;
    SourceType VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source type
    SourceType := Image.getSourceType;
END;
/

getSourceLocation Method

Format

getSourceLocation RETURN VARCHAR2;

Description

Returns a string containing the value of the external image data source location.

Parameters

None.

Usage Notes

This method returns a VARCHAR2 string containing the value of the external image data location, for example 'BFILEDIR'.

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

Pragmas

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

Exceptions

If the value of srcLocation is NULL, then calling this method raises an ORDSourceExceptions.INCOMPLETE_SOURCE_LOCATION exception.

Examples

Get the source location information about an image data source:

DECLARE
    Image ORDSYS.ORDImage;
    SourceLocation VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source location
    SourceLocation := Image.getSourceLocation;
END;

getSourceName Method

Format

getSourceName RETURN VARCHAR2;

Description

Returns a string containing the name of the external image data source.

Parameters

None.

Usage Notes

Returns a VARCHAR2 string containing the name of the external data source, for example 'testimg.dat'.

Pragmas

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

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_NAME

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

Examples

Get the source name information about an image data source:

DECLARE
    Image ORDSYS.ORDImage;
    SourceName VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source name
    SourceName := Image.getSourceName;
END;

import( ) Method

Format

MEMBER PROCEDURE import(ctx IN OUT RAW);

Description

Transfers image data from an external image data source to a local source (localData) within an Oracle database.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the source.open( ) method; see the introduction to this chapter for more information.

Usage Notes

Use the setSource( ) method to set the external source type, location, and name prior to calling the import( ) method.

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

After importing data from an external image data source to a local source (within an Oracle database), the source information remains unchanged (that is, pointing to the source from where the data was imported).

Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.

If the file format of the imported image is not previously set to a string beginning with "OTHER", the setProperties( ) method is also called. Set the file format to a string preceded by "OTHER" for foreign image formats; calling the setProperties( ) method for Foreign Images does this for you.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

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

ORDSourceExceptions.NULL_SOURCE

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

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

See Appendix H for more information about these exceptions.

Examples

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

DECLARE
    Image ORDSYS.ORDImage;
    ctx RAW(4000) :=NULL;
BEGIN
    -- select the image to be imported
    SELECT large_photo INTO Image FROM emp
           WHERE ename = 'John Doe' FOR UPDATE;
    -- import the image into the database
    Image.import(ctx);
    -- update the image object
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/


importFrom( ) Method

Format

importFrom(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Transfers image data from the specified external image data source to a local source (localData) within an Oracle database.

Parameters

ctx

The source plug-in context information. This must be allocated. You must call the source.open( ) method; see the introduction to this chapter for more information.

source_type

The source type of the image data.

source_location

The location from where the image data is to be imported.

source_name

The name of the image data.

Usage Notes

This method is similar to the import( ) method except the source information is specified as parameters to the method instead of separately.

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

After importing data from an external image data source to a local source (within an Oracle database), the source information (that is, pointing to the source from where the data was imported) is set to the input values.

Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.

If the file format of the imported image is not previously set to a string beginning with "OTHER", the setProperties( ) method is also called. Set the file format to a string preceded by "OTHER" for foreign image formats; calling the setProperties( ) method for Foreign Images does this for you.

Pragmas

None.

Exceptions

ORDSourceExceptions.NULL_SOURCE

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

ORDSourceExceptions.METHOD_NOT_SUPPORTED

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

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

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

See Appendix H for more information about these exceptions.

Examples

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

DECLARE
    Image ORDSYS.ORDImage;
    ctx RAW(4000) :=NULL;
BEGIN
    -- select the image to be imported
    SELECT large_photo INTO Image FROM emp
           WHERE ename = 'John Doe' FOR UPDATE;
    -- import the image into the database
    Image.importFrom(ctx,
                     'FILE',
                     'ORDIMGDIR',
                     'jdoe.gif');
    -- update the image object
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;

export( ) Method

Format

export(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Copies image data from a local source (localData) within an Oracle database to an external image 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 the data is to be exported.

source_location

The location to where the image data is to be exported.

source_name

The name of the image object to where the data is to be exported.

Usage Notes

After exporting image data, all image attributes remain unchanged and srcType, srcLocation, and srcName are updated with input values. After calling the export( ) method, you can call the clearLocal( ) method to indicate the data is stored outside the database and call the deleteContent 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 deleteContent 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 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 the Oracle8i Java Developer's Guide for more information.

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 srcType 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 within a source plug-in when any other exception is raised.

See Appendix H for more information about these exceptions.

Examples

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

DECLARE
  obj ORDSYS.ORDImage;
  ctx RAW(4000) :=NULL;
BEGIN
   SELECT large_photo INTO obj FROM emp WHERE ename = 'John Doe';
   obj.export(ctx,'FILE','ORDIMGDIR','testimg.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;
/

5.3.10 ORDImage Methods Associated with Image Migration

This section presents reference information on the ORDImage methods associated with image migration relative to converting old ORDImgB images and ORDImgF images to new ORDImage images.


migrateFromORDImgB( ) Method

Format

migrateFromORDImgB(old_object ORDImgB);

Description

Allows you to migrate old ORDImgB images to the new ORDImage object.

Parameters

old_object

The old ORDImgB image.

Usage Notes

This method copies from the source BLOB to the destination BLOB, copies all the image attributes from the old object to the new object, and sets the update time and local attribute.

Pragmas

None.

Exceptions

NULL_SOURCE

This exception is raised if you call the migrateFromORDImgB( ) method and the value of src (old_object) is NULL.

NULL_DESTINATION

This exception is raised if you call the migrateFromORDImgB( ) method and the value of dest is NULL (ORDImage).

NULL_CONTENT

This exception is raised if you call the migrateFromORDImgB( ) method and the value of src.content is NULL (old.object content attribute).

NULL_LOCAL_DATA

This exception is raised if you call the migrateFromORDImgB( ) method and the dest.source.localData value is NULL (dest ORDImage source.localData).

Examples

Migrate an old ORDImgB image to a new ORDImage image:

DECLARE
    Image ORDSYS.ORDImage;
    old_image ORDSYS.ORDIMGB;
BEGIN
    -- Select the old image
    SELECT imageb INTO old_image FROM old_images WHERE id = 1;
    -- Select the new image
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
    -- Migrate from the old to the new
    Image.migrateFromORDImgB(old_image);
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/


migrateFromORDImgF( ) Method

Format

migrateFromORDImgF(old_object ORDImgF);

Description

Allows you to migrate old ORDImgF images to the new ORDImage object.

Parameters

old_object

The old ORDImgF image.

Usage Notes

This method extracts the directory name and file name from the source and copies them to the srcLocation and srcName attributes of the destination. It also copies all image attributes from the old image object to the new image object, sets the
updateTime attribute, and clears the local attribute.

Pragmas

None.

Exceptions

None.

Examples

Migrate an old ORDImgF image to a new ORDImage image:

DECLARE
    Image ORDSYS.ORDImage;
    old_image ORDSYS.ORDIMGF;
BEGIN
    -- Select the old image
    SELECT imagef INTO old_image FROM old_images WHERE id = 1;
    -- Select the new image
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
    -- Migrate from the old to the new
    Image.migrateFromORDImgf(old_image);
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/


Go to previous page Go to next page
Oracle
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index