168
ANYDATA TYPE

An ANYDA TA TYPE contains an instance of a given type, plus a description of the type. In this sense, an ANYDATA is self-d escribing. An ANYDATA can be persistently stored in the database.

This chapter contains the following topics:

• Us ing ANYDATA TYPE
  • Restrictions< /a>
  • Operational Notes
• Summary of ANYDATA Subprograms

Using ANYDATA TYPE

Restriction s

Persistent storage of ANYDATA instances whose type contains embedded LOBs other than BFILEs is not currently supported.

Operational Notes

• Construction
• Access

Construction

There are 2 ways to construct an ANYDATA. The CONVERT* calls enable construction of the ANYDATA in its entirety with a single call. They serve as explicit CA ST functions from any type in the Oracle ORDBMS to ANYDATA.

STATIC FUNCTION Con
vertBDouble(dbl IN BINARY_DOUBLE) return ANYDATA,
STATIC FUNCTION ConvertBfile(b IN BFILE) RETURN ANYDATA,
STATIC FUNCTION ConvertBFloat(fl IN BINARY_FLOAT) return ANYDATA,
STATIC FUNCTION ConvertBlob(b
IN BLOB) RETURN ANYDATA,
STATIC FUNCTION ConvertChar(c IN CHAR) RETURN ANYDATA,
STATIC FU
NCTION ConvertClob(c IN CLOB) RETURN ANYDATA,
STATIC FUNCTION ConvertCollection(col IN "collection_type") RETUR
N ANYDATA,
STATIC FUNCTION ConvertDate(dat IN DATE) RETURN ANYDATA,
STATIC FUNCTION Conver
tIntervalDS(inv IN INTERVAL DAY TO SECOND) return ANYDATA,
STATIC FUNCTION ConvertIntervalYM(invIN INTERVAL YEA
R TO MONTH) return ANYDATA,
STATIC FUNCTION ConvertNchar(nc IN NCHAR) return ANYDATA,
STA
TIC FUNCTION ConvertNClob(nc IN NCLOB) return ANYDATA,
STATIC FUNCTION ConvertNumber(num IN NUMBER) RETURN ANYDA
TA,
STATIC FUNCTION ConvertNVarchar2(nc IN NVARCHAR2) return ANYDATA,
STATIC FUNCTION Conv
ertObject(obj IN "<object_type>") RETURN ANYDATA,
STATIC FUNCTION ConvertRaw(r IN RAW) RETURN ANYDATA,
STATIC FUNCTION ConvertRef(rf IN REF "<object_type>") RETURN ANYDATA,
STATIC FUNCTION C
onvertTimestamp(ts IN TIMESTAMP) return ANYDATA,
STATIC FUNCTION ConvertTimestampTZ(ts IN TIMESTAMP WITH TIMEZO
NE) return 
ANYDATA,
STATIC FUNCTION ConvertTimestampLTZ(ts IN TIMESTAMP WITH LOCAL TIMEZONE) return 
ANYDATA,
STATIC FUNCTION ConvertURowid(rid IN UROWID) return ANYDATA,
STATIC FUNCTION ConvertVarcha
r(c IN VARCHAR) RETURN ANYDATA,
STATIC FUNCTION ConvertVarchar2(c IN VARCHAR2) RETURN ANYDATA,

The second way to construct an ANYDATA is a piece by piece approach. T he BEGINCREATE Static Procedure call begins the construction process and ENDCREATE Member Procedure call finishes the construction process. In between these two calls, the individual attributes of an object type or the elements of a collection can be set using SET* calls. For piece by piece access of the attributes of objects and elements of collections, the PIECEWISE Member Procedure should be invoked prior to < code>GET* calls.

Note: The ANYDATA has to be constructed or accessed seq uentially starting from its first attribute (or collection element). The BEGINCREATE call automatically begins the const ruction in a piece-wise mode. There is no need to call PIECEWISE immediately after BEGINCREATE. ENDCR EATE should be called to finish the construction process (before which any access calls can be made).

Access functions are available based on SQL. These functions do not throw exceptions on type-mismatch. Instead, they return N ULL if the type of the ANYDATA does not correspond to the type of access. If you wish to use only ANYDATA functions of the appropriate types returned in a query, you should use a WHERE clause which uses GETTYPENAME and choose the type you are interested in (say "SYS.NUMBER"). Each of these functions returns the v alue of a specified datatype inside a SYS.ANYDATA wrapper.

MEMBER FUNCTION Acc
essBDouble(self IN ANYDATA) return BINARY_DOUBLE
   DETERMINISTIC,
MEMBER FUNCTION Access
Bfile(self IN ANYDATA) return BFILE,
MEMBER FUNCTION AccessBFloat(self IN ANYDATA) return BINARY_FLOAT
   DETERMINISTIC,
MEMBER FUNCTION AccessBlob(self IN ANYDATA) return BLOB,

MEMBER FUNCTION AccessChar(self IN ANYDATA) return CHAR,
MEMBER FUNCTION AccessClob(self IN ANYDATA) return CLO
B,
MEMBER FUNCTION AccessDate(self IN ANYDATA) return DATE,
MEMBER FUNCTION AccessInterva
lYM(self IN ANYDATA) return INTERVAL YEAR TO MONTH,
MEMBER FUNCTION AccessIntervalDS(self IN ANYDATA) return IN
TERVAL DAY TO SECOND,
MEMBER FUNCTION AccessNchar(self IN ANYDATA) return NCHAR,
MEMBER F
UNCTION AccessNClob(self IN ANYDATA) return NCLOB
MEMBER FUNCTION AccessNumber(self IN ANYDATA) return NUMBER,
MEMBER FUNCTION AccessNVarchar2(self IN ANYDATA) return NVARCHAR2,
MEMBER FUNCTION Access
Raw(self IN ANYDATA) return RAW,
MEMBER FUNCTION AccessTimestamp(self IN ANYDATA) return TIMESTAMP,
MEMBER FUNCTION AccessTimestampLTZ(self IN ANYDATA) return TIMESTAMP WITH LOCAL 
   TIMEZONE,
MEMBER FUNCTION AccessTimestampTZ(self IN ANYDATA) return TIMESTAMP WITH 
   TIMEZONE,
MEMBER FUNCTION AccessURowid(self IN ANYDATA) return UROWID DETERMINISTIC
MEMBER FUNCTION AccessV
archar(self IN ANYDATA) return VARCHAR,
MEMBER FUNCTION AccessVarchar2(self IN ANYDATA) return VARCHAR2,

Get the fully qualified type name for the ANYDATA

PIECEWISE Member Procedure

Sets the MODE of access of the current data value to be an attribute at a time (if the data v alue is of TYPECODE_OBJECT)

SET* Member Procedures

Sets the current data value.

BEGINCREATE Static Procedure

This procedure begins the creation process on a new ANYDATA.

STATIC PROCEDURE BeginCreate(
   dtype          IN OUT NOCOPY AnyType,
   adata
OUT NOCOPY ANYDATA);

Paramete rs

Table 168-2 BEGINCREATE Procedure Parameters

Exception

DBMS_TYPES.INVALID_PARAM ETERS: dtype is invalid (not fully constructed, and similar deficits.)

Usage Notes

There is no need to call PIECEWISE immediately after this call. The construction process begins in a piece-wise manner automatically.

ENDCREATE Member Pro cedure

This procedure ends creation of an ANYDATA. Other creation func tions cannot be called after this call.

Syntax

MEMBER PROCEDURE EndCreate(
   self         I
N OUT NOCOPY ANYDATA);

Param eters

T able 168-3 ENDCREATE Procedure Parameter

GET* Member Functions

These functions get the current data value (whi ch should be of appropriate type).

The type of the current data value depends on the MODE wi th which we are accessing (depending on whether we have invoked the PIECEWISE call).

If PIECEWISE has NOT been called, we are accessing the ANYDATA in its entirety and the type of the da ta value should match the type of the ANYDATA.

If PIECEWISE has be en called, we are accessing the ANYDATA piece-wise. The type of the data value should match the type of the attribute (o r collection element) at the current position.

Syntax

MEMBER FUNCTION GetBDouble(
   self
    IN ANYDATA,
   dbl          OUT NOCOPY BINARY_DOUBLE)
RETURN PLS_INTEGER;

MEMBER FUNCTION GetBfile(
   self         IN ANYDATA,
   b
         OUT NOCOPY BFILE)
   RETURN       PLS_INTEGER;

MEMBER FUNCTI
ON GetBFloat(
   self         IN ANYDATA,
   fl           OUT NOCOPY BINARY_FLOAT)
RETURN PLS_INTEGER;

MEMBER FUNCTION GetBlob(
   self
     IN ANYDATA,
   b            OUT NOCOPY BLOB)
   RETURN       PLS_INTEGER;

MEMBER FUNCTION GetChar(
   self         IN ANYDATA,
   c
         OUT NOCOPY CHAR)
   RETURN       PLS_INTEGER;

MEMBER FUNCTIO
N GetClob(
   self         IN ANYDATA,
   c            OUT NOCOPY CLOB)
   RETURN       PLS_INTEGER;

MEMBER FUNCTION GetCollection(
   self
         IN ANYDATA,
   col          OUT NOCOPY "<collection_type>")
   RETURN
PLS_INTEGER;

MEMBER FUNCTION GetDate(
   self         IN ANYDATA,
   dat          OUT NOCOPY DATE)
   RETURN       PLS_INTEGER;

MEMBER FUNCTION GetIntervalDS(
   self         IN ANYDATA,
   inv          OU
T NOCOPY INTERVAL DAY TO SECOND) 
 RETURN         PLS_INTEGER;

MEM
BER FUNCTION GetIntervalYM(
   self         IN ANYDATA,
   inv          OUT NOCOPY INTERV
AL YEAR TO MONTH) 
 RETURN         PLS_INTEGER;

MEMBER FUNCTION Ge
tNchar(
   self         IN ANYDATA, 
   nc           OUT NOCOPY NCHAR) 
 RETURN         PLS_INTEGER;

MEMBER FUNCTION GetNClob(
   sel
f         IN ANYDATA, 
   nc           OUT NOCOPY NCLOB) 
 RETURN         PLS_INTEGER;

MEMBER FUNCTION GetNumber(
   self         IN ANYDATA,
   num          OUT NOCOPY NUMBER)
   RETURN       PLS_INTEGER;

MEMBER FUNCTION GetNVarchar2(
   self         IN ANYDATA, 
   nc           OUT NOCOPY N
VARCHAR2) 
 RETURN         PLS_INTEGER;

MEMBER FUNCTION GetObject(
   self         IN ANYDATA,
   obj          OUT NOCOPY "<object_type>")
   RETURN       PLS_INTEGER;

MEMBER FUNCTION GetRaw(
   self
        IN ANYDATA,
   r            OUT NOCOPY RAW)
   RETURN       PLS_INTEGER;

MMEMBER FUNCTION GetRef(
   self         IN ANYDATA,
   rf
           OUT NOCOPY REF "<object_type>")
   RETURN       PLS_INTEGER;

MEMBER FUNCTION GetTimestamp(
   self         IN ANYDATA, 
   ts           OUT
NOCOPY TIMESTAMP)
 RETURN PLS_INTEGER;

MEMBER FUNCTION GetTimestam
pTZ(
   self         IN ANYDATA, 
   ts           OUT NOCOPY TIMESTAMP WITH TIME ZONE) 
<
a name="1000601"> RETURN PLS_INTEGER;

MEMBER FUNCTION GetTimestampLTZ(
   self         IN ANYDATA,
   ts           OUT NOCOPY TIMESTAMP WITH LOCAL TIME ZONE) 
 RETURN PLS_INTEGER;

MEMBER FUNCTION GetVarchar(
   self
     IN ANYDATA,
   c            OUT NOCOPY VARCHAR)
   RETURN       PLS_INTEGER;

MEMBER FUNCTION GetVarchar2(
   self         IN ANYDATA,

   c            OUT NOCOPY VARCHAR2)
   RETURN       PLS_INTEGER;

Parameters

Table 168-4 GET* Function Parameter

Return Val ues

DBMS_TYPES.SUCCESS or DBMS_TYPES.NO _DATA

The return value is relevant only if PIECEWISE has been already ca lled (for a collection). In such a case, DBMS_TYPES.NO_DATA signifies the end of the collection when all elements have been accessed.

Exceptions

DBMS_TYPES.TYPE_MISMATCH: When the expected type is different from the passed in type.

DBMS_TYPES.INVALID_PARAMETERS: Invalid Parameters (if it is not appropriate to add a number at this point in the creation process).

DBMS_TYPES.INCORRECT_USAGE: In correct usage.

GETTYPE Member Function

This function gets the typecode of the ANYDATA.

MEMBER FUNCTION GETTYPE(
   self          IN ANYDATA,
   typ
          OUT NOCOPY AnyType)
   RETURN        PLS_INTEGER;

MEMBER FUNCTION GETTYPENAME(
   self
     IN ANYDATA)
   RETURN       VARCHAR2;

MEMBER PROCEDURE PIECEWISE(
   self         IN OUT NOCOPY ANYDATA);

MEMBER PROCEDURE SETBDOUBLE(
   self        IN OUT NOCOPY ANYDATA,
   dbl         IN BINARY_DOUBLE,
   last
_elem   IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETBFILE(
   self
        IN OUT NOCOPY ANYDATA,
   b           IN BFILE,
   last_elem   IN boolean DEFAULT F
ALSE);

MEMBER PROCEDURE SETBFLOAT(
   self        IN OUT NOCOPY AN
YDATA, 
   fl          IN            BINARY_FLOAT,
   last_elem   IN            boolean DEF
AULT FALSE);

MEMBER PROCEDURE SETBLOB(
   self        IN OUT NOCOPY A
NYDATA, 
   b           IN BLOB,
   last_elem   IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETCHAR(
   self        IN OUT NOCOPY ANYDATA, 
   c           IN CHAR,
   last_elem   IN boolean DEFAULT FALSE);

ME
MBER PROCEDURE SETCLOB(
   self        IN OUT NOCOPY ANYDATA,
   c           IN CLOB,
   last_elem   IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETCOLLECTION(
   self        IN OUT NOCOPY ANYDATA,
   col         IN "<collectyion_type>",
   last_elem   IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETDATE(
   self        IN OUT NOCOPY ANYDATA, 
   dat         IN DATE,
   last_elem
IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETINTERVALDS(
   self
       IN OUT NOCOPY ANYDATA,
   inv         IN INTERVAL DAY TO SECOND,
   last_elem IN b
oolean DEFAULT FALSE);
  
MEMBER PROCEDURE SETINTERVALYM(
   self
      IN OUT NOCOPY ANYDATA,
   inv         IN INTERVAL YEAR TO MONTH,
   last_elem   IN
boolean DEFAULT FALSE);
  
MEMBER PROCEDURE SETNCHAR(
   self
  IN OUT NOCOPY ANYDATA,
   nc          IN NCHAR, 
   last_elem   IN boolean DEFAULT FALS
E);
  
MEMBER PROCEDURE SETNCLOB(
   self        IN OUT NOCOPY ANYD
ATA,
   nc          IN NClob, 
   last_elem   IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETNUMBER(
   self        IN OUT NOCOPY ANYDATA, 

   num         IN NUMBER,
   last_elem   IN boolean DEFAULT FALSE);


MEMBER PROCEDURE SETNVARCHAR2(
   self        IN OUT NOCOPY ANYDATA,
   nc          I
N NVarchar2, 
   last_elem   IN boolean DEFAULT FALSE),
  
MEMBER PR
OCEDURE SETOBJECT(
   self        IN OUT NOCOPY ANYDATA,
   obj         IN "<object_type
>",
   last_elem   IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SET
RAW(
   self        IN OUT NOCOPY ANYDATA, 
   r           IN RAW,

last_elem   IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETREF(
   se
lf        IN OUT NOCOPY ANYDATA,
   rf          IN REF "<object_type>",
   last_elem
  IN boolean DEFAULT FALSE);

MEMBER PROCEDURE SETTIMESTAMP(
   self
       IN OUT NOCOPY ANYDATA, 
   ts         IN TIMESTAMP,
   last_elem  IN BOOLEAN DEFAU
LT FALSE);
  
MEMBER PROCEDURE SETTIMESTAMPTZ(self IN OUT NOCOPY ANYDATA, 
   ts          IN TIMESTAMP WITH TIME ZONE,
   last_elem   IN BOOLEAN DEFAULT FALSE);
  
MEMBER PROCEDURE SETTIMESTAMPLTZ(
   self IN OUT NOCOPY ANYDATA,
   ts IN TIMESTAMP WITH LOCAL TIME ZONE,
   last_elem IN boolean DEFAULT FALSE),


MEMBER PROCEDURE SETVARCHAR(
   self        IN OUT NOCOPY ANYDATA, 

  c           IN VARCHAR,
   last_elem   IN boolean DEFAULT FALSE);

M
EMBER PROCEDURE SETVARCHAR2(
   self        IN OUT NOCOPY ANYDATA,
   c           IN VARCHA
R2, 
   last_elem   IN boolean DEFAULT FALSE);