Skip Headers
Oracle® C++ Call Interface Programmer's Guide,
11g Release 2 (11.2)

Part Number E10764-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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.

Table 13-38 Enumerated Values Used by ResultSet Class

Attribute Options
Status
  • DATA_AVAILABLE indicates that data for one or more rows was successfully fetched from the server; up to the requested number of rows (numRows) were returned. When in streamed mode, use the getNumArrayRows() method to determine the exact number of rows retrieved when numRows is greater than 1.

  • STREAM_DATA_AVAILABLE indicates that the application should call the getCurrentStreamColumn() method and read stream.

  • END_OF_FETCH indicates that no data was available for fetching.


Table 13-39 Summary of ResultSet Methods

Method Description

cancel()

Cancels the ResultSet.

closeStream()

Closes the specified Stream.

getBDouble()

Returns the value of a column in the current row as a BDouble.

getBfile()

Returns the value of a column in the current row as a Bfile.

getBFloat()

Returns the value of a column in the current row as a BFloat.

getBlob()

Returns the value of a column in the current row as a Blob object.

getBytes()

Returns the value of a column in the current row as a Bytes array.

getCharSet()

Returns the character set in which data would be fetched.

getCharSetUString()

Returns the character set in which data would be fetched as a UString.

getClob()

Returns the value of a column in the current row as a Clob object.

getColumnListMetaData()

Returns the describe information of the result set columns as a MetaData object.

getCurrentStreamColumn()

Returns the column index of the current readable Stream.

getCurrentStreamRow()

Returns the current row of the ResultSet being processed.

getCursor()

Returns the nested cursor as a ResultSet.

getDate()

Returns the value of a column in the current row as a Date object.

getDatabaseNCHARParam()

Returns whether data is in NCHAR character set or not.

getDouble()

Returns the value of a column in the current row as a C++ double.

getFloat()

Returns the value of a column in the current row as a C++ float.

getInt()

Returns the value of a column in the current row as a C++ int.

getIntervalDS()

Returns the value of a column in the current row as a IntervalDS.

getIntervalYM()

Returns the value of a column in the current row as a IntervalYM.

getMaxColumnSize()

Returns the maximum amount of data to read from a column.

getNumArrayRows()

Returns the actual number of rows fetched in the last array fetch.

getNumber()

Returns the value of a column in the current row as a Number object.

getObject()

Returns the value of a column in the current row as a PObject.

getRef()

Returns the value of a column in the current row as a Ref.

getRowid()

Returns the current ROWID for a SELECT FOR UPDATE statement.

getRowPosition()

Returns the row id of the current row position.

getStatement()

Returns the Statement of the ResultSet.

Footref 0getStream()

Returns the value of a column in the current row as a Stream.

getString()

Returns the value of a column in the current row as a string.

getTimestamp()

Returns the value of a column in the current row as a Timestamp object.

getUInt()

Returns the value of a column in the current row as a C++ unsigned int

getUString()

Returns the value of a column in the current row as a UString.

getVector()

Returns the specified collection parameter as a vector.

getVectorOfRefs()

Returns the column in the current position as a vector of Refs.

isNull()

Checks whether the value is NULL.

isTruncated()

Checks whether truncation has occurred.

next()

Makes the next row the current row in a ResultSet.

preTruncationLength()

Returns the actual length of the parameter before truncation.

setBinaryStreamMode()

Specifies that a column is to be returned as a binary stream.

setCharacterStreamMode()

Specifies that a column is to be returned as a character stream.

setCharSet()

Specifies the character set in which the data is to be returned.

setCharSetUString()

Specifies the character set in which the data is to be returned.

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.

setDataBuffer()

Specifies the data buffer into which data is to be fetched, or the gather and scatter binds and defines made.

setErrorOnNull()

Enables Or Disables exception when NULL value is read.

setErrorOnTruncate()

Enables Or Disables exception when truncation occurs.

setPrefetchMemorySize()

Sets the amount of memory that is used internally by OCCI to store data fetched during each round trip to the server.

setPrefetchRowCount()

Sets the number of rows that are fetched internally by OCCI during each round trip to the server.

setMaxColumnSize()

Specifies the maximum amount of data to read from a column.

status()

Returns 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); 
Parameter Description
stream
The Stream to be closed.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


getCharSet()

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

Syntax

string getCharSet(
   unsigned int colIndex) const;
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


getCharSetUString()

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

Syntax

UString getCharSetUString(
   unsigned int colIndex) const;
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


getDatabaseNCHARParam()

Returns whether data is in NCHAR character set or not.

Syntax

bool getDatabaseNCHARParam(
   unsigned int paramIndex) const;
Parameter Description
paramIndex
Parameter index, first parameter is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


getMaxColumnSize()

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

Syntax

unsigned int getMaxColumnSize(
   unsigned int colIndex) const;
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


getObject()

Returns a pointer to a PObject holding the column value.

Syntax

PObject * getObject(
   unsigned int colIndex);
Parameter Description
colIndex
Column index; first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index; first column is 1, second is 2, and so on.


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 Description
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<BDouble> &vect);
Used for BDouble vectors.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<Bfile> &vect);
Used for Bfile vectors.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<BFloat> &vect);
Used for BFloat vectors.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<Blob> &vect);
Used for Blob vectors.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<Clob> &vect);
Used for Clob vectors.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<Date> &vect);
Used for vectors of Date Class.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<double> &vect);
Used for vectors of double type.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<float> &vect);
Used for vectors of float type.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<int> &vect);
Used for vectors of int type.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<IntervalDS> &vect);
Used for vectors of IntervalDS Class.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<IntervalYM> &vect);
Used for vectors of IntervalYM Class.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<Number> &vect);
Used for vectors of Number Class.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<Ref<T>> &vect);
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.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<RefAny> &vect);
Used for vectors of RefAny Class.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<string> &vect);
Used for vectors of string type.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<T *> &vect);
Intended for use on platforms where partial ordering of function templates is supported.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<T> &vect);
Intended for use on platforms where partial ordering of function templates is not supported, such as Windows NT and z/OS.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<Timestamp> &vect);
Used for vectors of Timestamp Class.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<unsigned int> &vect);
Used for vectors of unsigned int type.
void getVector(
   ResultSet *rs,
   unsigned int colIndex,
   vector<UString> &vect);
Used for vectors of UString Class; globalization enabled.

Parameter Description
rs
The result set
colIndex
Column index, first column is 1, second is 2, and so on.
vect
The reference to the vector (OUT parameter).


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);
Parameter Description
rs
The result set
colIndex
Column index, first column is 1, second is 2, and so on.
vect
The reference to the vector of REFs (OUT parameter).


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;
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.


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;
Parameter Description
paramIndex
Parameter index, first parameter is 1, second is 2, and so on.


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.

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);
Parameter Description
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;
Parameter Description
paramIndex
Parameter index, first parameter is 1, second is 2, and so on.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.
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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.
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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.
charSet
Desired character set, as a string.


setCharSetUString()

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

Syntax

UString setCharSetUString(
   unsigned int colIndex,
   const UString &charSet);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.
charSet
Desired character set, as a string.


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);
Parameter Description
paramIndex
Parameter index, first parameter is 1, second is 2, and so on.
isNCHAR
TRUE or FALSE.


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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.
buffer
Pointer to user-allocated buffer. For array fetches, it should have numRows * size bytes in it. For gather or scatter binds and defines, this structure stores the address of OCIIOVec and the number of OCIIOVec elements that start at that address.
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);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.
causeException
Enable exceptions if TRUE. Disable if FALSE.


setErrorOnTruncate()

This method enables/disables exceptions when truncation occurs.

Syntax

void setErrorOnTruncate(
   unsigned int paramIndex,
   bool causeException);
Parameter Description
paramIndex
Parameter index, first parameter is 1, second is 2, and so on.
causeException
Enable exceptions if TRUE. Disable if FALSE.


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);
Parameter Description
bytes
Number of bytes used for storing data fetched during each server round trip.


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);
Parameter Description
rowCount
Number of rows to fetch for each round trip to the server.


setMaxColumnSize()

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

Syntax

void setMaxColumnSize(
   unsigned int colIndex,
   unsigned int max);
Parameter Description
colIndex
Column index, first column is 1, second is 2, and so on.
max
The maximum amount of data to be read.


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;