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 getxxx() methods retrieve column values for the current row. You can retrieve values using the index number of the column. Columns are numbered beginning at 1. For the getxxx() 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::getxxx() methods.

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

Status

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); 

stream

getBDouble()

This method returns the value of a column in the current row as a BDouble. If the value is SQL NULL, the result is NULL.

Syntax

BDouble getBDouble(
   unsigned int colIndex);

colIndex

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);

colIndex

getBFloat()

This method returns the value of a column in the current row as a BFloat. If the value is SQL NULL, the result is NULL.

Syntax

BFloat getBFloat(
   unsigned int colIndex);

colIndex

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);

colIndex

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);

colIndex

getCharSet()

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

Syntax

string getCharSet(
   unsigned int colIndex) const;

colIndex

getCharSetUString()

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

Syntax

UString getCharSetUString(
   unsigned int colIndex) const;

colIndex

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);

colIndex

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 returns the value of the given column as a PObject. The type of the C++ object is 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 must 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 last_name, 
       CURSOR(SELECT  department_name FROM departments) 
FROM employees WHERE last_name = '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);

colIndex

getDatabaseNCHARParam()

Returns whether data is in NCHAR character set or not.

Syntax

bool getDatabaseNCHARParam(
   unsigned int paramIndex) const;

paramIndex

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);

colIndex

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);

colIndex

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);

colIndex

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);

colIndex

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);

colIndex

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);

colIndex

getMaxColumnSize()

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

Syntax

unsigned int getMaxColumnSize(
   unsigned int colIndex) const;

colIndex

getNumArrayRows()

Returns the actual number of rows fetched in the last array fetch. Used in conjunction with the next() method. This method cannot be used for non-array fetches.

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);

colIndex

getObject()

Returns a pointer to a PObject holding the column value.

Syntax

PObject * getObject(
   unsigned int colIndex);

colIndex

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);

colIndex

getRowid()

Get the current row id for a SELECT...FOR UPDATE statement. The row id 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);

colIndex

getRowPosition()

Get the rowid of the current row position.

Syntax

Bytes getRowPosition() const;

getStatement()

This method returns the statement of the ResultSet.

Syntax

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);

colIndex

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);

colIndex

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);

colIndex

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);

colIndex

getUString()

Returns the value as a UString.

This method should be called only if the environment's character set is UTF16, or if setCharset() method has been called to explicitly retrieve UTF16 data.

Syntax

UString getUString(
   unsigned int colIndex);

colIndex

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

rs

colIndex

vect

getVectorOfRefs()

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. It is recommend to use this function instead of specialized method getVector() for Ref<T>.

Syntax

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

rs

colIndex

vect

isNull()

A column may have the value of SQL NULL; isNull() 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 isNull() 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;

colIndex

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;

paramIndex

next()

This method fetches a specified number of rows, numRows, from a previously executed query, and reports the Status of this fetch as defined in Table 13-38.

For non-streamed mode, next() only returns the status of DATA_AVAILABLE or END_OF_FETCH.

• When fetching one row at a time (numRows=1), process the data using getxxx() methods.

• When fetching several rows at once (numRows>1), as in an Array Fetch, you must use the setDataBuffer() method to specify the location of your preallocated buffers before invoking next().

Up to numRows data records would populate the buffers specified by the setDataBuffer() call. To determine exactly how many records were returned, use the getNumArrayRows() method.

Syntax

Status next(
   unsigned int numRows =1);

numRows

preTruncationLength()

Returns the actual length of the parameter before truncation.

Syntax

int preTruncationLength(
   unsigned int paramIndex) const;

paramIndex

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);

colIndex

size

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);

colIndex

size

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);

colIndex

charSet

setCharSetUString()

Specifies the character set value as a UString in which the data is returned.

Syntax

UString setCharSetUString(
   unsigned int colIndex,
   const UString &charSet);

colIndex

charSet

setDatabaseNCHARParam()

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);

paramIndex

isNCHAR

setDataBuffer()

Specifies a data buffer where data would be fetched or bound. 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, such as 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)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);

colIndex

buffer

type

size

length

ind

rc

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);

colIndex

causeException

setErrorOnTruncate()

This method enables/disables exceptions when truncation occurs.

Syntax

void setErrorOnTruncate(
   unsigned int paramIndex,
   bool causeException);

paramIndex

causeException

setPrefetchMemorySize()

Sets the amount of memory that is used internally by OCCI to store data fetched during each round trip to the server. A value of 0 means that the amount of data fetched during the round trip is constrained by the FetchRowCount parameter. If both parameters are nonzero, the smaller of the two is used.

Syntax

void setPrefetchMemorySize(
   unsigned int bytes);

bytes

setPrefetchRowCount()

Sets the number of rows that are fetched internally by OCCI during each round trip to the server. A value of 0 means that the amount of data fetched during the round trip is constrained by the FetchMemorySize parameter. If both parameters are nonzero, the smaller of the two is used. If both of these parameters are zero, row count internally defaults to 1 row and that is the value returned from the getFetchRowCount() method.

Syntax

void setPrefetchRowCount(
   unsigned int rowCount);

rowCount

setMaxColumnSize()

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

Syntax

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

colIndex

max

status()

Returns the current Status of the result set, as defined in Table 13-38. This method can be called repeatedly.

Syntax

Status status() const;