OCCI Classes and Methods, 18 of 22

ResultSet Class

A ResultSet provides access to a table of data generated by executing a Statement. Table rows are retrieved in sequence. Within a row, column values can be accessed in any order.

A ResultSet maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The next method moves the cursor to the next row.

The get ... () methods retrieve column values for the current row. You can retrieve values either using the index number of the column or the name of the column. In general, using the column index is more efficient. Columns are numbered beginning at 1.

For the get ... () methods, OCCI attempts to convert the underlying data to the specified C++ type and returns a C++ value.

SQL types are mapped to C++ types with the ResultSet::get ... () methods.

The number, types and properties of a ResultSet's columns are provided by the MetaData object returned by the getColumnListMetaData method.

enum Status
{
    END_OF_FETCH = 0,
    DATA_AVAILABLE,
    STREAM_DATA_AVAILABLE
};

ResultSet()

This is the ResultSet constructor.

Syntax

ResultSet()

Summary of ResultSet Methods

Table 8-18 ResultSet Methods

Method	Description
cancel()	Cancel the `ResultSet`.
closeStream()	Close the specified `Stream`.
getBfile()	Return the value of a column in the current row as a `Bfile`.
getBlob()	Return the value of a column in the current row as a `Blob` object.
getBytes()	Return the value of a column in the current row as a `Bytes` array.
getCharSet()	Return the character set in which data would be fetched.
getClob()	Return the value of a column in the current row as a `Clob` object.
getColumnListMetaData()	Return the describe information of the result set columns as a `MetaData` object.
getCurrentStreamColumn()	Return the column index of the current readable `Stream.`
getCurrentStreamRow()	Return the current row of the `ResultSet` being processed.
getCursor()	Return the nested cursor as a `ResultSet`.
getDate()	Return the value of a column in the current row as a `Date` object.
getDatebaseNCHARParam()	Returns whether data is in NCHAR character set or not.
getDouble()	Return the value of a column in the current row as a C++ double.
getFloat()	Return the value of a column in the current row as a C++ float.
getInt()	Return the value of a column in the current row as a C++ int.
getIntervalDS()	Return the value of a column in the current row as a `IntervalDS`.
getIntervalYM()	Return the value of a column in the current row as a `IntervalYM`.
getMaxColumnSize()	Return the maximum amount of data to read from a column.
getNumArrayRows()	Return the actual number of rows fetched in the last array fetch when next(int numRows) returned `END_OF_DATA.`
getNumber()	Return the value of a column in the current row as a `Number` object.
getObject()	Return the value of a column in the current row as a `PObject`.
getRef()	Return the value of a column in the current row as a `Ref`.
getRowid()	Return the current ROWID for a SELECT FOR UPDATE statement.
getRowPosition()	Return the Rowid of the current row position.
getStatement()	Return the `Statement` of the `ResultSet`.
getStream()	Return the value of a column in the current row as a `Stream`.
getString()	Return the value of a column in the current row as a string.
getTimestamp()	Return the value of a column in the current row as a `Timestamp` object.
getUInt()	Return the value of a column in the current row as a C++ unsigned int
getVector()	Return the specified collection parameter as a vector.
getVectorOfRefs()	Return the specified parameter (representing a collection of REFs) as a vector of REFs.
isNull()	Check whether the value is null.
isTruncated()	Check whether truncation has occurred.
next()	Make the next row the current row in a `ResultSet`.
preTruncationLength()
setBinaryStreamMode()	Specify that a column is to be returned as a binary stream.
setCharacterStreamMode()	Specify that a column is to be returned as a character stream.
setCharSet()	Specify the character set in which the data is to be returned.
setDatebaseNCHARParam()	If the parameter is going to be retrieved from a column that contains data in the database's NCHAR character set, then OCCI must be informed by passing a true value.
setDataBuffer()	Specify the data buffer into which data is to be read.
setErrorOnNull()	Enable/disable exception when null value is read.
setErrorOnTruncate()	Enable/disable exception when truncation occurs.
setMaxColumnSize()	Specify the maximum amount of data to read from a column.
status()	Return the current status of the `ResultSet`.

cancel()

This method cancels the result set.

Syntax

void cancel();

closeStream()

This method closes the stream specified by the parameter stream.

Syntax

void closeStream(Stream *stream);

Parameters

stream

The stream to be closed.

getBfile()

This method returns the value of a column in the current row as a Bfile. Returns the column value; if the value is SQL null, the result is NULL.

Syntax

Bfile getBfile(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getBlob()

Get the value of a column in the current row as an Blob. Returns the column value; if the value is SQL null, the result is NULL.

Syntax

Blob getBlob(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getBytes()

Get the value of a column in the current row as a Bytes array. The bytes represent the raw values returned by the server. Returns the column value; if the value is SQL null, the result is null array

Syntax

Bytes getBytes(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getCharSet()

Gets the character set in which data would be fetched, as a string.

Syntax

string getCharSet(unsigned int paramIndex) const;

Parameters

paramIndex

The first parameter is 1, the second is 2, . . . .

getClob()

Get the value of a column in the current row as a Clob. Returns the column value; if the value is SQL null, the result is NULL.

Syntax

Clob getClob(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getColumnListMetaData()

The number, types and properties of a ResultSet's columns are provided by the getMetaData method. Returns the description of a ResultSet's columns. This method will return the value of the given column as a PObject. The type of the C++ object will be the C++ PObject type corresponding to the column's SQL type registered with Environment's map. This method is used to materialize data of SQL user-defined types.

Syntax

vector<MetaData> getColumnListMetaData() const;

getCurrentStreamColumn()

If the result set has any input Stream parameters, this method returns the column index of the current input Stream that must be read. If no output Stream needs to be read, or there are no input Stream columns in the result set, this method returns 0. Returns the column index of the current input Stream column that must be read.

Syntax

unsigned int getCurrentStreamColumn() const;

getCurrentStreamRow()

If the result has any input Streams, this method returns the current row of the result set that is being processed by OCCI. If this method is called after all the rows in the set of array of rows have been processed, it returns 0. Returns the row number of the current row that is being processed. The first row is numbered 1 and so on.

Syntax

unsigned int getCurrentStreamRow() const;

getCursor()

Get the nested cursor as an ResultSet. Data can be fetched from this result set. A nested cursor results from a nested query with a CURSOR(SELECT ... ) clause.

SELECT ename, CURSOR(SELECT  dname, loc FROM dept) FROM emp WHERE ename = 
'JONES'

Note that if there are multiple REF CURSORs being returned, data from each cursor must be completely fetched before retrieving the next REF CURSOR and starting fetch on it. Returns A ResultSet for the nested cursor.

Syntax

ResultSet * getCursor(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getDate()

Get the value of a column in the current row as a Date object. Returns the column value; if the value is SQL null, the result is null

Syntax

Date getDate(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getDatebaseNCHARParam()

Returns whether data is in NCHAR character set or not.

Syntax

bool getDatebaseNCHARPARAM(unsigned int paramIndex) const;

Parameters

paramIndex

Parameter index.

getDouble()

Gets the value of a column in the current row as a C++ double. Returns the column value; if the value is SQL null, the result is 0

Syntax

double getDouble(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getFloat()

Get the value of a column in the current row as a C++ float. Returns the column value; if the value is SQL null, the result is 0.

Syntax

float getFloat(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getInt()

Get the value of a column in the current row as a C++ int. Returns the column value; if the value is SQL null, the result is 0.

Syntax

int getInt(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getIntervalDS()

Get the value of a column in the current row as a IntervalDS object. Returns the column value; if the value is SQL null, the result is null.

Syntax

IntervalDS getIntervalDS(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getIntervalYM()

Get the value of a column in the current row as a IntervalYM object. Returns the column value; if the value is SQL null, the result is null

Syntax

IntervalYM getIntervalYM(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getMaxColumnSize()

Get the maximum amount of data to read for a column.

Syntax

unsigned int getMaxColumnSize(unsigned int colIndex) const;

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getNumArrayRows()

Returns the actual number of rows fetched in the last array fetch when next(int numRows) returned END_OF_DATA. Returns the actual number of rows fetched in the final array fetch

Syntax

unsigned int getNumArrayRows() const;

getNumber()

Get the value of a column in the current row as a Number object. Returns the column value; if the value is SQL null, the result is null

Syntax

Number getNumber(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getObject()

Returns a pointer to a PObject holding the column value.

Syntax

PObject * getObject(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getRef()

Get the value of a column in the current row as a RefAny. Retrieving a Ref value does not materialize the data to which Ref refers. Also the Ref value remains valid while the session or connection on which it is created is open. Returns a RefAny holding the column value.

Syntax

RefAny getRef(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getRowid()

Get the current rowid for a SELECT ... FOR UPDATE statement. The rowid can be bound to a prepared DELETE statement and so on. Returns Current rowid for a SELECT ... FOR UPDATE statement.

Syntax

Bytes getRowid(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getRowPosition()

Get the Rowid of the current row position.

Syntax

Bytes getRowPosition() const

getStatement()

This method returns the Statement of the ResultSet.

Syntax

const Statement* getStatement() const;

getStream()

This method returns the value of a column in the current row as a Stream.

Syntax

Stream * getStream(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getString()

Get the value of a column in the current row as a string. Returns the column value; if the value is SQL null, the result is an empty string.

Syntax

string getString(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getTimestamp()

Get the value of a column in the current row as a Timestamp object. Returns the column value; if the value is SQL null, the result is null.

Syntax

Timestamp getTimestamp(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getUInt()

Get the value of a column in the current row as a C++ int. Returns the column value; if the value is SQL null, the result is 0.

Syntax

unsigned int getUInt(unsigned int colIndex);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

getVector()

This method returns the column in the current position as a vector. The column should be a collection type (varray or nested table). The SQL type of the elements in the collection should be compatible with the data type of the objects in the vector.

Syntax

There are variants of syntax:

void getVector(ResultSet *rs,
   unsigned int index,
   vector<int> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<unsigned int> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<float> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<double> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<string> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<Date> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<Timestamp> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<RefAny> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<Blob> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<Clob> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<Bfile> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<Number> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<IntervalDS> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<IntervalYM> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector< Ref<T> > &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<T *> &vect);

void getVector(ResultSet *rs,
   unsigned int index,
   vector<T> &vect);

In particular, the last two variants are identical. The former is intended for use on platforms where partial ordering of function templates is supported and the latter on those it is not.

Similarly, the variant

void getVector(ResultSet *rs,
   unsigned int index,
   vector< Ref<T> > &vect);

is available only on platforms where partial ordering of function templates is supported. This function may be deprecated in the future. getVectorOfRefs() can be used instead.

Parameters

rs

The result set.

index

The column index (the first column is 1, the second is 2, . . . . ) .

vect

The reference to the vector of objects (OUT parameter).

getVectorOfRefs()

This method returns the column in the current position as a vector of REFs. The column should be a collection type (varray or nested table) of REFs.

Syntax

void getVectorOfRefs(ResultSet *rs,
   unsigned int index,
   vector< Ref<T> > &vect);

Parameters

rs

The result set.

index

The column index (the first column is 1, the second is 2, . . . . ).

vect

The reference to the vector of REFs (OUT parameter).

It is recommened to use this function instead of specialized method getVector for Ref<T>.

isNull()

A column may have the value of SQL null; wasNull() reports whether the last column read had this special value. Note that you must first call getxxx on a column to try to read its value and then call wasNull() to find if the value was the SQL null. Returns true if last column read was SQL null.

Syntax

bool isNull(unsigned int colIndex) const;

Parameters

colIndex

The first column is 1, the second is 2, . . . .

isTruncated()

This method checks whether the value of the parameter is truncated. If the value of the parameter is truncated, then true is returned; otherwise, false is returned.

Syntax

bool isTruncated(unsigned int paramIndex) const;

Parameters

paramIndex

The first parameter is 1, the second is 2, . . . .

next()

A ResultSet is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, and so on. If a read-able stream from the previous row is open, it is implicitly closed. The ResultSet's warning chain is cleared when a new row is read.

For non-streamed mode, next() always returns RESULT_SET_AVAILABLE or END_OF_DATA. Data is available for getxxx method when the RESULT_SET_REMOVE_AVAILABLE status is returned. When this version of next() is used, array fetches are done for data being fetched with the setDataBuffer() interface. This means that getxxx() methods should not be called. The numRows amount of data for each column would materialize in the buffers specified with the setDataBuffer() interface. With array fetches, stream input is allowed, so getxxxStream() methods can also be called (once for each column).

Returns one of following:

DATA_AVAILABLE -- call getxxx() or read data from buffers specified with setDataBuffer()
END_OF_FETCH -- no more data available. This is the last set of rows for array fetches. This value is defined to be 0.
STREAM_DATA_AVAILABLE -- call the getCurrentStreamColumn method and read stream

Syntax

Status next(unsigned int numRows =1);

Parameters

numRows

Number of rows to fetch for array fetches.

preTruncationLength()

Returns the actual length of the parameter before truncation.

Syntax

int preTruncationLength(unsigned int paramIndex) const;

Parameters

paramIndex

The first parameter is 1, the second is 2, . . . .

setBinaryStreamMode()

Defines that a column is to be returned as a binary stream by the getStream method.

Syntax

void setBinaryStreamMode(unsigned int colIndex,
   unsigned int size);

Parameters

colIndex

The position of the column that is to be retrieved as a binary stream (the first column is 1, the second is 2, . . .).

size

The amount of data to be read as a binary stream.

setCharacterStreamMode()

Defines that a column is to be returned as a character stream by the getStream method.

Syntax

void setCharacterStreamMode(unsigned int colIndex,
   unsigned int size);

Parameters

colIndex

The position of the column that is to be retrieved as a character stream (the first column is 1, the second is 2,. . .).

size

The amount of data to be read as a character stream.

setCharSet()

Overrides the default character set for the specified column. Data is converted from the database character set to the specified character set for this column.

Syntax

void setCharSet(unsigned int colIndex,
   string charSet);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

charSet

Desired character set, as a string.

setDatebaseNCHARParam()

If the parameter is going to be retrieved from a column that contains data in the database's NCHAR character set, then OCCI must be informed by passing a true value. A FALSE can be passed to restore the default.

Syntax

void setDatabaseNCHARParam( unsigned int paramIndex, 
    bool isNCHAR);

Parameters

paramIndex

Parameter index.

isNCHAR

TRUE/FALSE.

setDataBuffer()

Specify a data buffer where data would be fetched. The buffer parameter is a pointer to a user allocated data buffer. The current length of data must be specified in the *length parameter. The amount of data should not exceed the size parameter. Finally, type is the data type of the data. Only non OCCI and non C++ specific types can be used i.e STL string, OCCI classes like Bytes and Date cannot be used.

If setDataBuffer() is used to fetch data for array fetches, it should be called only once for each result set. Data for each row is assumed to be at buffer + (i - 1)*size location where i is the row number. Similarly the length of the data would be assumed to be at *(length + (i - 1)).

Syntax

void setDataBuffer(unsigned int colIndex,
   void *buffer,
   Type type,
   sb4 size = 0,
   ub2 *length = NULL,
   sb2 *ind = NULL,
   ub2 *rc = NULL);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

buffer

Pointer to user-allocated buffer; if array fetches are done, it should have numRows * size bytes in it

type

Type of the data that is provided (or retrieved) in the buffer

size

Size of the data buffer; for array fetches, it is the size of each element of the data items

length

Pointer to the length of data in the buffer; for array fetches, it should be an array of length data for each buffer element; the size of the array should be equal to arrayLength

ind

Pointer to an indicator variable or array. (IN/OUT).

rc

Pointer to array of column level return codes (OUT).

setErrorOnNull()

This method enables/disables exceptions for reading of null values on colIndex column of the result set.

Syntax

void setErrorOnNull(unsigned int colIndex,
   bool causeException);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

causeExcetpion

Enable exceptions if true. Disable if false

setErrorOnTruncate()

This method enables/disables exceptions when truncation occurs.

Syntax

void setErrorOnTruncate(unsigned int paramIndex,
   bool causeException);

Parameters

paramIndex

The first parameter is 1, the second is 2, . . . .

causeException

Enable exceptions if true. Disable if false

setMaxColumnSize()

Set the maximum amount of data to read for a column

Syntax

void setMaxColumnSize(unsigned int colIndex,
   unsigned int max);

Parameters

colIndex

The first column is 1, the second is 2, . . . .

max

The maximum amount of data to be read.

status()

Returns the current status of the result set. The status method can be called repeatedly to find out the status of the result. Data is available for getxxx method when the RESULT_SET_AVAILABLE status is returned. Returns one of following:

DATA_AVAILABLE -- call getxxx() or read data from buffers specified with the setDataBuffer method
STREAM_DATA_AVAILABLE -- call getCurrentStream() and read stream
END_OF_FETCH

Syntax

Status status() const;