Skip Headers

Oracle C++ Call Interface Programmer's Guide
Release 2 (9.2)

Part Number A96583-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to beginning of chapter Go to next page

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:

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:

Syntax
Status status() const;

Go to previous page Go to beginning of chapter Go to next page
Oracle
Copyright © 2001, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback