F
Reference Information

This appendix describes additional reference information presented elsewhere in this guide as part of the demo program. It describes the following:

• ORDAnnotations type and its methods

F.1 Object Types

Oracle8i interMedia makes use of the following object types in its demo program:

• ORDAnnotations: supports the storage of annotation information

---

ORDAnnotations Object Type

The ORDAnnotations object type supports the storage of annotation information.

This object type is defined in the following list:

CREATE OR REPLACE TYPE ORDAnnotations

AS OBJECT

(

  -- TYPE ATTRIBUTES

annotations        ORDAnnotationList,

  -- METHOD DECLARATION

MEMBER PROCEDURE setAnnotation(key   IN VARCHAR2, 

                               value IN VARCHAR2),

MEMBER FUNCTION getAnnotation(key IN VARCHAR2)

                RETURN VARCHAR2,

PRAGMA RESTRICT_REFERENCES(getAnnotation, WNDS, WNPS, RNPS), 



MEMBER PROCEDURE deleteAnnotation(key IN VARCHAR2),

MEMBER PROCEDURE appendToAnnotation(key   IN VARCHAR2, 

                                    value IN VARCHAR2),

MEMBER FUNCTION getAnnotationCount RETURN INTEGER,

PRAGMA RESTRICT_REFERENCES(getAnnotationCount, WNDS, WNPS, RNPS), 



MEMBER FUNCTION getAnnotationObjByPosition(pos IN INTEGER)

                RETURN ORDAnnotation,

PRAGMA RESTRICT_REFERENCES(getAnnotationObjByPosition, WNDS, WNPS, RNPS), 



MEMBER FUNCTION getAnnotationKeyByPosition(pos IN INTEGER)

                RETURN VARCHAR2,

PRAGMA RESTRICT_REFERENCES(getAnnotationKeyByPosition, WNDS, WNPS, RNPS), 



MEMBER FUNCTION getAnnotationValueByPosition(pos IN INTEGER)

                RETURN VARCHAR2,

PRAGMA RESTRICT_REFERENCES(getAnnotationValueByPosition, WNDS, WNPS, RNPS), 

);

where:

• annotations: is an ORDAnnotationList table containing one or more ORDAnnotation objects of which each ORDAnnotation object contains a key defined as a VARCHAR2(256) and a value defined as a VARCHAR2(4000).

F.2 Methods

This section presents reference information on the methods used for annotation manipulation.

The ORDAnnotations methods are described as follows:

ORDAnnotations Methods Associated with the annotations Attribute

• setAnnotation( ): creates the values for the ORDAnnotation object key and value fields.

• getAnnotation( ): returns the value of the value field for the ORDAnnotation object given its key value.

• deleteAnnotation( ): deletes the ORDAnnotation object by its key value.

• appendToAnnotation( ): appends information to the values of the ORDAnnotation object's key and value fields.

• getAnnotationCount: returns the number of ORDAnnotation objects in the ORDAnnotationList table.

• getAnnotationObjByPosition( ): returns the ORDAnnotation object by its position in the ORDAnnotationList table.

• getAnnotationKeyByPosition( ): returns the value of the key field by the ORDAnnotation object's position in the ORDAnnotationList table.

• getAnnotationValueByPosition( ): returns the value of the value field by the ORDAnnotation object's position in the ORDAnnotationList table.

F.2.1 ORDAnnotations Methods Associated with the annotations Attribute

This section presents reference information on the ORDAnnotations methods associated with the annotations attribute.

The methods described in this reference chapter show examples based on a TANNOT table. Refer to the TANNOT table definition that follows when reading through the examples in this chapter:

CREATE TABLE TANNOT(n NUMBER, a ORDSYS.ORDAnnotations)

storage (initial 100K next 100K pctincrease 0),

nested table a.annotations store as base_annot;

INSERT INTO TANNOT VALUES(1, ORDSYS.ORDAnnotations(NULL));

---

setAnnotation( ) Method

Format

setAnnotation(key   IN VARCHAR2,

              value IN VARCHAR2);

Description

Creates or alters the values for the key and value fields for the ORDAnnotation object.

Parameters

key

The value of the key field for the ORDAnnotation object.

value

The value of the value field for the ORDAnnotation object.

Usage

none

Pragmas

none

Exception

none

Example

none

---

getAnnotation( ) Method

Format

getAnnotation(key IN VARCHAR2) RETURN VARCHAR2;

Description

Returns the value of the value field for the ORDAnnotation object based on the value of the key field.

Parameters

key

The value of the key field for the ORDAnnotation object.

Usage

none

Pragmas

Pragma RESTRICT_REFERENCES(getAnnotation, WNDS, WNPS, RNPS)

Exception

If the key cannot be found based on its value, then calling this method raises a KEY_NOT_FOUND exception.

If the value of the annotations attribute is empty (NULL), then calling this method raises a NULL_ANNOTATION_LIST exception.

Example

Return the value of the key and value fields for the first ORDAnnotation object in the ORDAnnotationList table of the ORDAnnotations object:

DECLARE

  mya ORDSYS.ORDAnnotations;

BEGIN

 SELECT T.a INTO mya FROM TANNOT T WHERE N = 1;

 DBMS_OUTPUT.PUT_LINE('Annotation for key: '||mya.getAnnotation('key'));

 DBMS_OUTPUT.PUT_LINE('Annotation for value:'||mya.getAnnotation('note1'));

  EXCEPTION

  WHEN ORDSYS.ORDAnnotationsExceptions.KEY_NOT_FOUND THEN

    DBMS_OUTPUT.PUT_LINE('key does not exist in annotations');

END;

---

deleteAnnotation( ) Method

Format

deleteAnnotation(key IN VARCHAR2);

Description

Deletes the ORDAnnotation object based on the value of its key field.

Parameters

key

The value of the key field for the ORDAnnotation object.

Usage

none

Pragmas

none

Exception

If the key cannot be found based on its value, then calling this method raises a KEY_NOT_FOUND exception.

Example

none

---

appendToAnnotation( ) Method

Format

appendToAnnotation(key   IN VARCHAR2,

                   value IN VARCHAR2);

Description

Appends the specified values for the key and value fields to the ORDAnnotation object's current values.

Parameters

key

The appended value of the key field for the ORDAnnotation object.

value

The appended value of the value field for the ORDAnnotation object.

Usage

none

Pragmas

none

Exception

If the key cannot be found based on its value, then calling this method raises a KEY_NOT_FOUND exception.

If the value of the annotations attribute is empty (NULL), then calling this method raises a NULL_ANNOTATION_LIST exception.

Example

none

---

getAnnotationCount Method

Format

getAnnotationCount RETURN INTEGER;

Description

Returns the number of ORDAnnotation objects in the ORDAnnotationList table.

Parameters

none

Usage

none

Pragmas

Pragma RESTRICT_REFERENCES(getAnnotationCount, WNDS, WNPS, RNPS)

Exception

none

Example

Return the ORDAnnotation object count:

DECLARE

  mya ORDSYS.ORDAnnotations;

BEGIN

 SELECT T.a INTO mya FROM TANNOT T WHERE N = 1;

 DBMS_OUTPUT.PUT_LINE(TO_CHAR(mya.getAnnotationCount));

END;

---

getAnnotationObjByPosition( ) Method

Format

getAnnotationObjByPosition(pos IN INTEGER) RETURN ORDAnnotation;

Description

Returns the ORDAnnotation object by its position in the ORDAnnotationList table.

Parameters

pos

The ORDAnnotation object's position in the ORDAnnotationList table.

Usage

none

Pragmas

Pragma RESTRICT_REFERENCES(getAnnotationObjByPosition, WNDS, WNPS, RNPS)

Exception

If the value of pos is greater than the number of ORDAnnotation objects in the ORDAnnotationList table, then calling this method raises a POSITION_OUT_OF_RANGE exception.

Example

Return the ORDAnnotation object by its position in the ORDAnnotationList table:

DECLARE

  mya ORDSYS.ORDAnnotations;

  obj ORDSYS.ORDAnnotation;

  n   INTEGER;

BEGIN

 SELECT T.a INTO mya FROM TANNOT T WHERE N = 1;

 n := mya.getAnnotationCount;

 FOR i in 1..n LOOP

   obj := mya.getAnnotationObjByPosition(i);

   DBMS_OUTPUT.PUT_LINE('Key '||TO_CHAR(i)||':'||obj.key);

   DBMS_OUTPUT.PUT_LINE('Value: '||obj.value);

   DBMS_OUTPUT.PUT_LINE('---------------------------------------');

 END LOOP;

END;

---

getAnnotationKeyByPosition( ) Method

Format

getAnnotationKeyByPosition(pos IN INTEGER) RETURN VARCHAR2;

Description

Returns the value of the key field by the ORDAnnotation object's position in the ORDAnnotationList table.

Parameters

pos

The ORDAnnotation object's position in the ORDAnnotationList table.

Usage

none

Pragmas

Pragma RESTRICT_REFERENCES(getAnnotationKeyByPosition, WNDS, WNPS, RNPS)

Exception

If the value of pos is greater than the number of ORDAnnotation objects in the ORDAnnotationList table, then calling this method raises a POSITION_OUT_OF_RANGE exception.

Example

Return the value of the key field by the ORDAnnotation object's position in the ORDAnnotationList table:

DECLARE

  mya ORDSYS.ORDAnnotations;

  n   INTEGER;

BEGIN

 SELECT T.a INTO mya FROM TANNOT T WHERE N = 1;

 n := mya.getAnnotationCount;

 FOR i in 1..n LOOP

   DBMS_OUTPUT.PUT_LINE('Key '||TO_CHAR(i)||':'||mya.getAnnotationKeyByPosition(

i));

   DBMS_OUTPUT.PUT_LINE('Value: '||mya.getAnnotationValueByPosition(i));

   DBMS_OUTPUT.PUT_LINE('---------------------------------------');

 END LOOP;

END;

---

getAnnotationValueByPosition( ) Method

Format

getAnnotationValueByPosition(pos IN INTEGER) RETURN VARCHAR2;

Description

Returns the value of the value field by the ORDAnnotation object's position in the ORDAnnotationList table.

Parameters

pos

The ORDAnnotation object's position in the ORDAnnotationList table.

Usage

none

Pragmas

Pragma RESTRICT_REFERENCES(getAnnotationValueByPosition, WNDS, WNPS, RNPS)

Exception

If the value of pos is greater than the number of ORDAnnotation objects in the ORDAnnotationList table, then calling this method raises a POSITION_OUT_OF_RANGE exception.

Example

Return the value of the value field by the ORDAnnotation object's position in the ORDAnnotationList table:

DECLARE

  mya ORDSYS.ORDAnnotations;

  n   INTEGER;

BEGIN

 SELECT T.a INTO mya FROM TANNOT T WHERE N = 1;

 n := mya.getAnnotationCount;

 FOR i in 1..n LOOP

   DBMS_OUTPUT.PUT_LINE('Key '||TO_CHAR(i)||':'||mya.getAnnotationKeyByPosition(

i));

   DBMS_OUTPUT.PUT_LINE('Value: '||mya.getAnnotationValueByPosition(i));

   DBMS_OUTPUT.PUT_LINE('---------------------------------------');

 END LOOP;

END;

---