ANYDATASET TYPE, 2 of 2

Summary of ANYDATASET Subprograms

Table 104-1 ANYDATASET Subprograms

Subprogram	Description
BEGINCREATE Static Procedure	The AnyDataSet needs to be constructed value by value, sequentially.
BEGINCREATE Static Procedure	Creates a new AnyDataSet which can be used to create a set of data values of the given ANYTYPE.
ADDINSTANCE Member Procedure	Adds a new data instance to an AnyDataSet.
PIECEWISE Member Procedure	Sets the MODE of construction, access of the data value to be an attribute at a time (if the data value is of TYPECODE_OBJECT).
SET* Member Procedures	Sets the current data value.
ENDCREATE Member Procedure	Ends Creation of a AnyDataSet. Other creation functions cannot be called after this call.
GETTYPENAME Member Function	Gets the AnyType describing the type of the data instances in an AnyDataSet.
GETTYPE Member Function	Gets the current data value (which should be of appropriate type).
GETINSTANCE Member Function	Gets the next instance in an AnyDataSet.
GET* Member Functions	Gets the current data value (which should be of appropriate type).
GETCOUNT Member Function	Gets the number of data instances in an AnyDataSet.

BEGINCREATE Static Procedure

This procedure creates a new AnyDataSet which can be used to create a set of data values of the given ANYTYPE.

Syntax

STATIC PROCEDURE BeginCreate(
   typecode     IN PLS_INTEGER,
   rtype        IN OUT NOCOPY AnyType,
   aset         OUT NOCOPY AnyDataSet);

Parameters

Table 104-2 BEGINCREATE Procedure Parameter

Parameter	Description
`typecode`	The typecode for the type of the AnyDataSet.
`dtype`	The type of the data values. This parameter is a must for user-defined types like TYPECODE_OBJECT, Collection typecodes, etc.
`aset`	The AnyDataSet being constructed.

Exceptions

DBMS_TYPES.invalid_parameters: dtype is invalid (not fully constructed, etc.)

ADDINSTANCE Member Procedure

This procedure adds a new data instance to an AnyDataSet.

Syntax

MEMBER PROCEDURE AddInstance(
   self          IN OUT NOCOPY AnyDataSet);

Parameters

Table 104-3 ADDINSTANCE Procedure Parameter

Parameter	Description
`self`	The AnyDataSet being constructed.

Exceptions

DBMS_TYPES.invalid_parameters: Invalid parameters.
DBMS_TYPES.incorrect_usage: On incorrect usage.

Usage Notes

The data instances have to be added sequentially. The previous data instance must be fully constructed (or set to NULL) before a new one can be added.

This call DOES NOT automatically set the mode of construction to be piece-wise. The user has to explicitly call PieceWise() if a piece-wise construction of the instance is intended.

PIECEWISE Member Procedure

This procedure sets the MODE of construction, access of the data value to be an attribute at a time (if the data value is of TYPECODE_OBJECT).

It sets the MODE of construction, access of the data value to be a collection element at a time (if the data value is of a collection TYPE). Once this call has been made, subsequent Set*() and Get*() calls will sequentially obtain individual attributes or collection elements.

Syntax

MEMBER PROCEDURE PieceWise(
   self         IN OUT NOCOPY AnyDataSet);

Parameters

Table 104-4 PIECEWISE Procedure Parameter

Parameter	Description
`self`	The AnyDataSet being constructed.

Exceptions

DBMS_TYPES.invalid_parameters 
DBMS_TYPES.incorrect_usage: On incorrect usage.

Usage Notes

The current data value must be of an object or collectyon type before this call can be made. There is no support for piece-wise construction or access of embedded object type attributes or nested collections.

SET* Member Procedures

This procedure sets the current data value.

The type of the current data value depends on the MODE with which we are constructing (depending on how we have invoked the PieceWise() call). The type of the current data should be the type of the AnyDataSet if PieceWise() has NOT been called. The type should be the type of the attribute at the current position if PieceWise() has been called.

Syntax

MEMBER PROCEDURE SetNumber(
   self              IN OUT NOCOPY AnyDataSet,
   num               IN NUMBER,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetDate(
   self              IN OUT NOCOPY AnyDataSet,
   dat               IN DATE,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetChar(
   self              IN OUT NOCOPY AnyDataSet,
   c                 IN CHAR,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetVarchar(
   self              IN OUT NOCOPY AnyDataSet,
   c                 IN VARCHAR,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetVarchar2(
   self              IN OUT NOCOPY AnyDataSet,
   c                 IN VARCHAR2,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetRaw(
   self              IN OUT NOCOPY AnyDataSet,
   r                 IN RAW,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetBlob(
   self              IN OUT NOCOPY AnyDataSet,
   b                 IN BLOB,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetClob(
   self              IN OUT NOCOPY AnyDataSet,
   c                 IN CLOB,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetBfile(
   self              IN OUT NOCOPY AnyDataSet,
   b                 IN BFILE,
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetObject(
   self              IN OUT NOCOPY AnyDataSet,
   obj               IN "<object_type>", 
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetRef(
   self              IN OUT NOCOPY AnyDataSet,
   rf                IN REF "<object_type>",
   last_elem boolean DEFAULT FALSE);
MEMBER PROCEDURE SetCollection(
   self              IN OUT NOCOPY AnyDataSet,
   col               IN "<collection_type>",
   last_elem boolean DEFAULT FALSE);

Parameters

***Table 104-5 SET* Procedure Parameters***

Parameter	Description
`self`	The AnyDataSet being accessed.
`num`	The number, etc., that is to be set.
`last_elem`	Relevant only if `PieceWise()` has been already called (for a collection). Set to TRUE if it is the last element of the collection, FALSE otherwise.

Exceptions

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: Incorrect usage.
DBMS_TYPES.type_mismatch: When the expected type is different from the passed in type.

ENDCREATE Member Procedure

This procedure ends Creation of a AnyDataSet. Other creation functions cannot be called after this call.

Syntax

MEMBER PROCEDURE EndCreate(

self IN OUT NOCOPY AnyDataSet);

Parameters

Table 104-6 ENDCREATE Procedure Parameter

Parameter	Description
`self`	The AnyDataSet being constructed.

GETTYPENAME Member Function

This procedure gets the fully qualified type name for the AnyDataSet.

If the AnyDataSet is based on a built-in, this function will return NUMBER etc.

If it is based on a user defined type, this function will return <schema_name>.<type_name>. e.g. SCOTT.FOO.

If it is based on a transient anonymous type, this function will return NULL.

Syntax

MEMBER FUNCTION GetTypeName(
   self           IN AnyDataSet)
   RETURN         VARCHAR2;

Parameter

Table 104-7 GETTYPENAME Function Parameter

Parameter	Description
`self`	The AnyDataSet being constructed.

Returns

Type name of the AnyDataSet.

GETTYPE Member Function

Gets the AnyType describing the type of the data instances in an AnyDataSet.

Syntax

MEMBER FUNCTION GetType(
   self           IN AnyDataSet,
   typ            OUT NOCOPY AnyType)
   RETURN         PLS_INTEGER;

Parameters

Table 104-8 GETTYPE Function Parameter

Parameter	Description
`self`	The AnyDataSet.
`typ`	The AnyType corresponding to the AnyData. May be NULL if it does not represent a user-defined function.

Returns

The typecode corresponding to the type of the AnyData.

GETINSTANCE Member Function

This function gets the next instance in an AnyDataSet. Only sequential access to the instances in an AnyDataSet is allowed. After this function has been called, the Get*() functions can be invoked on the AnyDataSet to access the current instance. If PieceWise() is called before doing the Get*() calls, the individual attributes (or collection elements) can be accessed.

It is an error to invoke this function before the AnyDataSet is fully created.

Syntax

MEMBER FUNCTION GetInstance(
   self           IN OUT NOCOPY AnyDataSet)
   RETURN         PLS_INTEGER;

Parameters

Table 104-9 GETINSTANCE Function Parameter

Parameter	Description
`self`	The `AnyDataSet` being accessed.

Returns

DBMS_TYPES.SUCCESS or DBMS_TYPES.NO_DATA

DBMS_TYPES.NO_DATA signifies the end of the AnyDataSet (all instances have been accessed).

Usage Notes

This function should be called even before accessing the first instance.

GET* Member Functions

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

The type of the current data value depends on the MODE with which you are accessing it (depending on how we have invoked the PieceWise() call). If PieceWise() has NOT been called, we are accessing the instance in its entirety and the type of the data value should match the type of the AnyDataSet.

If PieceWise() has been called, we are accessing the instance piece-wise. The type of the data value should match the type of the attribute (or collection element) at the current position.

Syntax

MEMBER FUNCTION GetNumber(
   self        IN AnyDataSet,
   num         OUT NOCOPY NUMBER)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetDate(
   self        IN AnyDataSet,
   dat         OUT NOCOPY DATE)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetChar(
   self        IN AnyDataSet,
   c           OUT NOCOPY CHAR)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetVarchar(
   self        IN AnyDataSet,
   c           OUT NOCOPY VARCHAR)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetVarchar2(
   self        IN AnyDataSet,
   c           OUT NOCOPY VARCHAR2)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetRaw(
   self        IN AnyDataSet,
   r           OUT NOCOPY RAW)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetBlob(
   self        IN AnyDataSet,
   b           OUT NOCOPY BLOB)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetClob(
   self        IN AnyDataSet,
   c           OUT NOCOPY CLOB)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetBfile(
   self        IN AnyDataSet,
   b           OUT NOCOPY BFILE)
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetObject(
   self        IN AnyDataSet,
   obj         OUT NOCOPY "<object_type>")
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetRef(
   self        IN AnyDataSet,
   rf          OUT NOCOPY REF "<object_type>")
   RETURN      PLS_INTEGER;
MEMBER FUNCTION GetCollection(
   self        IN AnyDataSet,
   col         OUT NOCOPY "<collection_type>") 
   RETURN      PLS_INTEGER;

Parameters

***Table 104-10 GET* Procedure Parameters***

Parameter	Description
`self`	The `AnyDataSet` being accessed.
`num`	The number, etc., that is to be obtained.

Returns

DBMS_TYPES.SUCCESS or DBMS_TYPES.NO_DATA

The return value is relevant only if PieceWise() has been already called (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.invalid_parameters: Invalid Parameters (if it is not appropriate to add a number at this point in the creation process).

DBMS_TYPES.incorrect_usage: Incorrect usage

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

GETCOUNT Member Function

This function gets the number of data instances in an AnyDataSet.

Syntax

MEMBER FUNCTION GetCount(
   self        IN AnyDataSet) 
   RETURN      PLS_INTEGER;

Parameter

Table 104-11 GETCOUNT Function Parameter

Parameter	Description
`self`	The `AnyDataSet` being accessed.

Returns

The number of data instances.