OCCI Classes and Methods, 20 of 22

Statement Class

A Statement object is used for executing SQL statements. The statement may be a query returning result set or a non-query statement returning an update count.

Non-query SQL can be insert, update, or delete statements. Non-query SQL statements can also be DDL statements (such as create, grant, and so on) or stored procedure calls.

A query, insert / update / delete, or stored procedure call statements may have IN bind parameters. A DML returning insert / update / delete statement or stored procedure call may have OUT bind parameters. Finally, a stored procedure call statement may have bind parameters that are both IN and OUT, referred to as IN/OUT parameters.

The Statement class methods are divided into three categories:

Statement methods applicable to all statements
Methods applicable to prepared statements with IN bind parameters
Methods applicable to callable statements and DML returning statements with OUT bind parameters.

To..., use the syntax:

Statement()
enum Status
  {
    UNPREPARED,
    PREPARED,
    RESULT_SET_AVAILABLE,
    UPDATE_COUNT_AVAILABLE,
    NEEDS_STREAM_DATA,
    STREAM_DATA_AVAILABLE
  };

Summary of Statement Methods

Table 8-20 Statement Methods

Method	Description
addIteration()	Add an iteration for execution.
closeResultSet()	Immediately releases a result set's database and OCCI resources instead of waiting for automatic release.
closeStream()	Close the stream specified by the parameter `stream`.
execute()	Execute the SQL statement.
executeArrayUpdate()	Execute insert/update/delete statements which use only the `setDataBuffer()` or stream interface for bind parameters.
executeQuery()	Execute a SQL statement that returns a single `ResultSet`.
executeUpdate()	Execute a SQL statement that does not return a `ResultSet`.
getAutoCommit()	Return the current auto-commit state.
getBfile()	Return the value of a BFILE as a `Bfile` object.
getBlob()	Return the value of a BLOB as a `Blob` object.
getBytes()	Return the value of a SQL BINARY or VARBINARY parameter as `Bytes`.
getCharSet()	Return the character set that is in effect for the specified parameter.
getClob()	Return the value of a CLOB as a `Clob` object.
getConnection()
getCurrentIteration()	Return the iteration number of the current iteration that is being processed.
getCurrentStreamIteration()	Return the current iteration for which stream data is to be read or written.
getCurrentStreamParam()	Return the parameter index of the current output Stream that must be read or written.
getCursor()	Return the `REF CURSOR` value of an OUT parameter as a `ResultSet`.
getDatabaseNCHARParam()	Return whether data is in NCHAR character set.
getDate()	Return the value of a parameter as a `Date` object
getDouble()	Return the value of a parameter as a C++ double.
getFloat()	Return the value of a parameter as a C++ float.
getInt()	Return the value of a parameter as a C++ int.
getIntervalDS()	Return the value of a parameter as a `IntervalDS` object.
getIntervalYM()	Return the value of a parameter as a `IntervalYM` object.
getMaxIterations()	Return the current limit on maximum number of iterations.
getMaxParamSize()	Return the current max parameter size limit.
getNumber()	Return the value of a parameter as a `Number` object.
getObject()	Return the value of a parameter as a `PObject`.
getOCIStatement()	Return the OCI statement handle associated with the `Statement`.
getRef()	Return the value of a REF parameter as `RefAny`
getResultSet()	Return the current result as a `ResultSet`.
getRowid()	Return the rowid param value as a `Bytes` object.
getSQL()	Return the current SQL string associated with the `Statement` object.
getStream()	Return the value of the parameter as a stream.
getString()	Return the value of the parameter as a string.
getTimestamp()	Return the value of the parameter as a `Timestamp` object
getUInt()	Return the value of the parameter as a C++ unsigned int
getUpdateCount()	Return the current result as an update count for non-query statements.
getVector()	Return the specified parameter as a vector.
isNull()	Check whether the parameter is null.
isTruncated()	Check whether the value is truncated.
preTruncationLength()
registerOutParam()	Register the type and max size of the OUT parameter.
setAutoCommit()	Specify auto commit mode.
setBfile()	Set a parameter to a `Bfile` value.
setBinaryStreamMode()	Specify that a column is to be returned as a binary stream.
setBlob()	Set a parameter to a `Blob` value.
setBytes()	Set a parameter to a `Bytes` array.
setCharacterStreamMode()	Specify that a column is to be returned as a character stream.
setCharSet()	Specify the character set for the specified parameter.
setClob()	Set a parameter to a `Clob` value.
setDate()	Set a parameter to a `Date` value.
setDatabaseNCHARParam()	Set to true if the data is to be in the NCHAR character set of the database; set to false to restore the default.
setDataBuffer()	Specify a data buffer where data would be available for reading or writing.
setDataBufferArray()	Specify an array of data buffers where data would be available for reading or writing.
setDouble()	Set a parameter to a C++ double value.
setErrorOnNull()	Enable/disable exceptions for reading of null values.
setErrorOnTruncate()	Enable/disable exception when truncation occurs.
setFloat()	Set a parameter to a C++ float value.
setInt()	Set a parameter to a C++ int value.
setIntervalDS()	Set a parameter to a `IntervalDS` value.
setIntervalYM()	Set a parameter to a `IntervalYM` value.
setMaxIterations()	Set the maximum number of invocations that will be made for the DML statement.
setMaxParamSize()	Set the maximum amount of data that can sent or returned from the parameter.
setNull()	Set a parameter to SQL null.
setNumber()	Set a parameter to a `Number` value.
setObject()	Set the value of a parameter using an object.
setPrefetchMemorySize()	Set the amount of memory that will be used internally by OCCI to store data fetched during each round trip to the server.
setPrefetchRowCount()	Set the number of rows that will be fetched internally by OCCI during each round trip to the server.
setRef()	Set a parameter to a `RefAny` value.
setRowid()	Set a row id bytes array for a bind position.
setSQL()	Associate a new SQL string with a `Statement` object.
setString()	Set a parameter to an string value.
setTimestamp()	Set a parameter to a `Timestamp` value.
setUInt()	Set a parameter to a C++ unsigned int value.
setVector()	Set a parameter to a vector of unsigned int.
status()	Return the current status of the statement. This is useful when there is streamed data to be written.

addIteration()

After specifying set parameters, an iteration is added for execution.

Syntax

void addIteration();

closeResultSet()

In many cases, it is desirable to immediately release a result set's database and OCCI resources instead of waiting for this to happen when it is automatically closed; the closeResultSet method provides this immediate release.

Syntax

void closeResultSet(ResultSet *resultSet);

Parameters

resultSet

The resultset to be closed. The resultset should have been obtained by a call to the getResultSet method on this statement.

closeStream()

Closes the stream specified by the parameter stream.

Syntax

void closeStream(Stream *stream);

Parameters

stream

The stream to be closed.

execute()

Executes a SQL statement that may return either a result set or an update count. The statement may have read-able streams which may have to be written, in which case the results of the execution may not be readily available. The returned value is one of the following:

UNPREPARED
PREPARED
RESULT_SET_AVAILABLE
UPDATE_COUNT_AVAILABLE
NEEDS_STREAM_DATA
STREAM_DATA_AVAILABLE

If RESULT_SET_AVAILABLE is returned, the getResultSet() method must be called to get the result set.

If UPDATE_COUNT_AVAILABLE is returned, the getUpdateCount method must be called to find out the update count.

If NEEDS_STREAM_DATA is returned, output Streams must be written for the streamed IN bind parameters. If there is more than one streamed parameter, call the getCurrentStreamParam method to find out the bind parameter needing the stream. If the statement is executed iteratively, call getCurrentIteration to find out the iteration for which stream needs to be written.

If STREAM_DATA_AVAILABLE is returned, input Streams must be read for the streamed OUT bind parameters. If there is more than one streamed parameter, call the getCurrentStreamParam method to find out the bind parameter needing the stream. If the statement is executed iteratively, call getCurrentIteration to find out the iteration for which stream needs to be read.

If only one OUT value is returned for each invocation of the DML returning statement, iterative executes can be performed for DML returning statements. If output streams are used for OUT bind variables, they must be completely read in order. The getCurrentStreamParam method would indicate which stream needs to be read. Similarly, getCurrentIteration would indicate the iteration for which data is available.

Returns

RESULT_SET_AVAILABLE-- call getResultSet()
UPDATE_COUNT_AVAILABLE -- call getUpdateCount()
NEEDS_STREAM_DATA -- call getCurrentStream() and getCurrentIteration(), and write (or read) stream

Syntax

Status execute(const string &sql = "");

Parameters

sql

The SQL statement to be executed. This can be null if the setSQL method was used to associate the sql with the statement.

executeArrayUpdate()

Executes insert/update/delete statements which use only the setDataBuffer() or stream interface for bind parameters. The bind parameters must be arrays of size arrayLength parameter. The statement may have read-able streams which may have to be written. The returned value is one of the following:

UPDATE_COUNT_AVAILABLE
NEEDS_STREAM_DATA
STREAM_DATA_AVAILABLE
PREPARED
UNPREPARED

If UPDATE_COUNT_AVAILABLE is returned, getUpdateCount() must be called to find out the update count.

If NEEDS_STREAM_DATA is returned, output Streams must be written for the streamed bind parameters. If there is more than one streamed parameter, getCurrentStreamParam() can be called to find out the bind parameter needing the stream. The getCurrentIteration() can be called to find out the iteration for which stream needs to be written.

If STREAM_DATA_AVAIALBE is returned, input Streams must be read for the streamed OUT bind parameters. If there is more than one streamed parameter, getCurrentStreamParam() can be called to find out the bind parameter needing the stream. If the statement is executed iteratively, getCurrentIteration() can be called to find out the iteration for which stream needs to be read.

If only one OUT value is returned for each invocation of the DML returning statement, array executes can be done for DML returning statements also. If output streams are used for OUT bind variables, they must be completely read in order. The getCurrentStreamParam() method would indicate which stream needs to be read. Similarly, getCurrentIteration() would indicate the iteration for which data is available.

Note that you cannot perform array executes for queries or callable statements.

Syntax

Status executeArrayUpdate(unsigned int arrayLength);

Parameters

arrayLength

The number of elements provided in each buffer of bind variables. The statement is executed this many times with each array element used for each iteration. Returns:

UPDATE_COUNT_AVAILABLE -- call getUpdateCount()
NEEDS_STREAM_DATA -- call getCurrentStream() and getCurrentIteration(), and write (or read) stream

executeQuery()

Execute a SQL statement that returns a ResultSet. Should not be called for a statement which is not a query, has streamed parameters. Returns a ResultSet that contains the data produced by the query

Syntax

ResultSet * executeQuery(const string &sql = "");

Parameters

sql

sql statement to be executed. This can be null if setSQL() was used to associate the sql with the statement.

executeUpdate()

Executes a non-query statement such as a SQL INSERT, UPDATE, DELETE statement, a DDL statement such as CREATE/ALTER and so on, or a stored procedure call. Returns either the row count for INSERT, UPDATE or DELETE or 0 for SQL statements that return nothing

Syntax

unsigned int executeUpdate(const string &sql = "");

Parameters

sql

The SQL statement to be executed. This can be null if the setSQL method was used to associate the sql with the statement.

getAutoCommit()

Get the current auto-commit state. Returns Current state of auto-commit mode.

Syntax

bool getAutoCommit() const;

getBfile()

Get the value of a BFILE parameter as a Bfile object. Returns the parameter value.

Syntax

Bfile getBfile(unsigned int paramIndex);

Parameters

paramIndex

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

getBlob()

Get the value of a BLOB parameter as a Blob. Returns the parameter value

Syntax

Blob getBlob(unsigned int paramIndex);

Parameters

paramIndex

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

getBytes()

Get the value of a SQL BINARY or VARBINARY parameter as Bytes. Returns the parameter value; if the value is SQL null, the result is null.

Syntax

Bytes getBytes(unsigned int paramIndex);

Parameters

paramIndex

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

getCharSet()

Returns the character set that is in effect for the specified parameter, 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 CLOB parameter as a Clob. Returns the parameter value.

Syntax

Clob getClob(unsigned int paramIndex);

Parameters

paramIndex

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

getConnection()

Syntax

const Connection* getConnection() const;

getCurrentIteration()

If the prepared statement has any output Streams, this method returns the current iteration of the statement that is being processed by OCCI. If this method is called after all the invocations in the set of iterations has been processed, it returns 0. Returns the iteration number of the current iteration that is being processed. The first iteration is numbered 1 and so on. If the statement has finished execution, a 0 is returned.

Syntax

unsigned int getCurrentIteration() const;

getCurrentStreamIteration()

Returns the current param stream for which data is available.

Syntax

unsigned int getCurrentStreamIteration() const;

getCurrentStreamParam()

If the prepared statement has any output Stream parameters, this method returns the parameter index of the current output Stream that must be written. If no output Stream needs to be written, or there are no output Stream parameters in the prepared statement, this method returns 0.

Returns the parameter index of the current output Stream parameter that must be written.

Syntax

unsigned int getCurrentStreamParam() const;

getCursor()

Get the REF CURSOR value of an OUT parameter as a ResultSet. Data can be fetched from this result set. The OUT parameter must be registered as CURSOR with the Statement.registerOutParam(int paramIndex, CURSOR) method. Note that if there are multiple REF CURSORs being returned due to a batched call, data from each cursor must be completely fetched before retrieving the next REF CURSOR and starting fetch on it. Returns A ResultSet for the OUT parameter value.

Syntax

ResultSet * getCursor(unsigned int paramIndex);

Parameters

paramIndex

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

getDatabaseNCHARParam()

Returns whether data is in NCHAR character set or not.

Syntax

bool getDatabaseNCHARParam(unsigned int paramIndex) const;

Parameters

paramIndex

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

getDate()

Get the value of a SQL DATE parameter as a Date object. Returns the parameter value; if the value is SQL null, the result is null.

Syntax

Date getDate(unsigned int paramIndex) const;

Parameters

paramIndex

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

getDouble()

Get the value of a DOUBLE parameter as a C++ double. Returns the parameter value; if the value is SQL null, the result is 0.

Syntax

double getDouble(unsigned int paramIndex);

Parameters

paramIndex

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

getFloat()

Get the value of a FLOAT parameter as a C++ float. Returns the parameter value; if the value is SQL null, the result is 0.

Syntax

float getFloat(unsigned int paramIndex);

Parameters

paramIndex

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

getInt()

Get the value of an INTEGER parameter as a C++ int. Returns the parameter value; if the value is SQL null, the result is 0

Syntax

unsigned int getInt(unsigned int paramIndex);

Parameters

paramIndex

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

getIntervalDS()

Get the value of a parameter as a IntervalDS object.

Syntax

IntervalDS getIntervalDS(unsigned int paramIndex);

Parameters

paramIndex

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

getIntervalYM()

Get the value of a parameter as a IntervalYM object.

Syntax

IntervalYM getIntervalYM(unsigned int paramIndex);

Parameters

paramIndex

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

getMaxIterations()

Gets the current limit on maximum number of iterations. Default is 1. Returns the current maximum number of iterations.

Syntax

unsigned int getMaxIterations() const;

getMaxParamSize()

The maxParamSize limit (in bytes) is the maximum amount of data sent or returned for any parameter value; it only applies to character and binary types. If the limit is exceeded, the excess data is silently discarded. Returns the current max parameter size limit

Syntax

unsigned int getMaxParamSize(unsigned int paramIndex) const;

Parameters

paramIndex

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

getNumber()

Get the value of a NUMERIC parameter as a Number object. Returns the parameter value; if the value is SQL nullnull, the result is null.

Syntax

Number getNumber(unsigned int paramIndex);

Parameters

paramIndex

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

getObject()

Get the value of a parameter as a PObject. This method returns an PObject whose type corresponds to the SQL type that was registered for this parameter using registerOutParam. Note that this method may be used to read database-specific, abstract data types. Returns A PObject holding the OUT parameter value.

Syntax

PObject * getObject(unsigned int paramIndex);

Parameters

paramIndex

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

getOCIStatement()

Get the OCI statement handle associated with the Statement. Returns the OCI statement handle associated with the Statement

Syntax

LNOCIStmt * getOCIStatement() const;

getRef()

Get the value of a REF parameter as RefAny. Returns the parameter value.

Syntax

RefAny getRef(unsigned int paramIndex);

Parameters

paramIndex

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

getResultSet()

Returns the current result as a ResultSet.

Syntax

ResultSet * getResultSet();

getRowid()

Get the rowid param value as a Bytes

Syntax

Bytes getRowid(unsigned int paramIndex);

Parameters

paramIndex

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

getSQL()

Returns the current SQL string associated with the Statement object.

Syntax

string getSQL() const;

getStream()

Syntax

Stream * getStream(unsigned int paramIndex);

Parameters

paramIndex

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

getString()

Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as an string. Returns the parameter value; if the value is SQL null, the result is empty string.

Syntax

string getString(unsigned int paramIndex);

Parameters

paramIndex

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

getTimestamp()

Get the value of a SQL TIMESTAMP parameter as a Timestamp object. Returns the parameter value; if the value is SQL null, the result is null

Syntax

Timestamp getTimestamp(unsigned int paramIndex);

Parameters

paramIndex

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

getUInt()

Get the value of a BIGINT parameter as a C++ unsigned int. Returns the parameter value; if the value is SQL null, the result is 0

Syntax

unsigned int getUInt(unsigned int paramIndex);

Parameters

paramIndex

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

getUpdateCount()

Returns the current result as an update count.

Syntax

unsigned int getUpdateCount() const;

getVector()

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

Syntax

There are variant of syntax:

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<int> &vect;

void getVector(Statement *stmt,
   unsigned int paramindex,
   vector<string> &vect;

void getVector(Statement *stmt,
   unsigned int index,
   vector<unsigned int> &vect;

void getVector(Statement *stmt,
   unsigned int paramindex,
   vector<float> &vect;

void getVector(Statement *stmt,
   unsigned int paramindex,
   vector<double> &vect;

void getVector(Statement *stmt,
   unsigned int paramindex,
   vector<Date> &vect;

void getVector(Statement *stmt,
   unsigned int paramindex,
   vector<Timestamp> &vect;

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<RefAny> &vect;

void getVector(Statement *stmt,
  unsigned int paramIndex,
   vector<Blob> &vect;

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Clob> &vect;

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Bfile> &vect;

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Number> &vect;

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<IntervalDS> &vect;

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<IntervalYM> &vect;

void getVector(Statement *stmt,
   unsigned int paramIndex,
   vector<T *> &vect);

void getVector(Statement *stmt,
   unsigned int paramIndex,
   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(Statement *stmt,
   unsigned int paramIndex,
   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

statement

paramIndex

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

vect

Reference to the vector (OUT parameter) into which the values should be retrieved.

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(Statement *stmt,
   unsigned int index,
   vector< Ref<T> > &vect);

Parameters

stmt

The statement.

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 recommended to use getVectorOfRefs instead of specialized getVector function for Ref<T>.

isNull()

An OUT parameter may have the value of SQL null; wasNull reports whether the last value read has this special value. Note that you must first call getXXX on a parameter to read its value and then call wasNull() to see if the value was SQL null. Returns true if the last parameter read was SQL null

Syntax

bool isNull(unsigned int paramIndex ) const;

Parameters

paramIndex

The first parameter 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, . . . .

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, . . . .

registerOutParam()

This method registers the type of each out paramater of a PL/SQL stored procedure. Before executing a PL/SQL stored procedure, you must explicitly call this method to register the type of each out parameter. This method should be called for out parameters only. Use the setxxx method for in/out parameters.

When reading the value of an out parameter, you must use the getxxx method that corresponds to the parameter's registered SQL type. For example, use getInt or getNumber when OCCIINT or OCCINumber is the type specified.

If a PL/SQL stored procedure has an out paramater of type ROWID, the type specified in this method should be OCCISTRING. The value of the out parameter can then be retrieved by calling the getString() method.

If a PL/SQL stored procedure has an in/out parameter of type ROWID, call the methods setString() and getString() to set the type and retrieve the value of the in/out parameter.

Syntax

void registerOutParam(unsigned int paramIndex,
   Type type,
   unsigned int maxSize = 0,
   const string &sqltype = "");

Parameters

paramIndex

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

type

SQL type code defined by type; only datatypes corresponding to OCCI data types such as Date, Bytes, and so on.

maxSize

The maximum size of the retrieved value. For datatypes of OCCIBYTES and OCCISTRING, maxSize should be greater than 0.

sqltype

The name of the type in the data base (used for types which have been created with CREATE TYPE)

setAutoCommit()

A Statement can be in auto-commit mode. In this case any statement executed is also automatically committed. By default, the auto-commit mode is turned-off.

Syntax

void setAutoCommit(bool autoCommit);

Parameters

autoCommit

True enables auto-commit; false disables auto-commit.

setBfile()

Set a parameter to a Bfile value.

Syntax

void setBfile(unsigned int paramIndex,
   const Bfile &x);

Parameters

paramIndex

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

x

The parameter value.

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

Column to be bound as a stream. The first column is 1, the second is 2, . . . .

size

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

setBlob()

Set a parameter to a Blob value.

Syntax

void setBlob(unsigned int paramIndex,
   const Blob &x);

Parameters

paramIndex

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

x

The parameter value.

setBytes()

Set a parameter to a Bytes array.

Syntax

void setBytes(unsigned int paramIndex,
   const Bytes &x);

Parameters

paramIndex

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

x

The parameter value.

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 first column is 1, the second is 2, . . . .

size

setCharSet()

Overrides the default character set for the specified parameter. Data is assumed to be in the specified character set and is converted to database character set. For OUT binds, this specifies the character set to which database characters are converted to.

Syntax

void setCharSet(unsigned int paramIndex,
   string charSet);

Parameters

paramIndex

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

charSet

Selected character set, as a string.

setClob()

Set a parameter to a Clob value.

Syntax

void setClob(unsigned int paramIndex,
   const Clob &x);

Parameters

paramIndex

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

x

The parameter value.

setDate()

Set a parameter to a Date value.

Syntax

void setDate(unsigned int paramIndex,
   const Date &x);

Parameters

paramIndex

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

x

The parameter value.

setDatabaseNCHARParam()

If the parameter is going to be inserted in 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 dafault.Returns returns the character set that is in effect for the specified parameter.

Syntax

void setDatabaseNCHARParam(unsigned int paramIndex,
   bool isNCHAR);

Parameters

paramIndex

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

isNCHAR

True if this parameter contains data in Database's NCHAR character set; false otherwise.

setDataBuffer()

Specify a data buffer where data would be available. Also, used for OUT bind parameters of callable statements (and DML returning OUT binds in future).

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.

Note that not all types can be supplied in the buffer. For example, all OCCI allocated types (such as Bytes, Date and so on.) cannot be provided by the setDataBuffer interface. Similarly, C++ Standard Library strings cannot be provided with the setDataBuffer interface either. The type can be any of OCI data types such VARCHAR2, CSTRING, CHARZ and so on.

If setDataBuffer() is used to specify data for iterative or array executes, it should be called only once in the first iteration only. For subsequent iterations, OCCI would assume that data is at buffer + i*size location where i is the iteration number. Similarly the length of the data would be assumed to be at *(length + i).

Syntax

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

Parameters

paramIndex

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

buffer

Pointer to user-allocated buffer; if iterative or array executes are done, it should have numIterations * size bytes in it.

type

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

size

Size of the data buffer; for iterative and array executes, it is the size of each element of the data items

length

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

ind

Indicator. For iterative and array executes, an indicator for every buffer element

rc

Return code -- for iterative and array executes, a return code for every buffer element

setDataBufferArray()

Specify an array of data buffers where data would be available for reading or writing. Used for IN, OUT, and IN/OUT bind parameters for stored procedures which read/write array parameters.

A stored procedure can have an array of values for IN, IN/OUT, or OUT parameters. In this case, the parameter must be specified using the setDataBufferArray() method. The array is specified just as for the setDataBuffer() method for iterative or array executes, but the number of elements in the array is determined by *arrayLength parameter.

For OUT and IN/OUT parameters, the maximum number of elements in the array is specified by the arraySize parameter. Note that for iterative prepared statements, the number of elements in the array is determined by the number of iterations, and for array executes the number of elements in the array is determined by the arrayLength parameter of the executeArrayUpdate() method. However, for array parameters of stored procedures, the number of elements in the array must be specified in the *arrayLength parameter of the setDataBufferArray() method because each parameter may have a different size array.

This is different from prepared statements where for iterative and array executes, the number of elements in the array for each parameter is the same and is determined by the number of iterations of the statement, but a callable statement is executed only once, and each of its parameter can be a varying length array with possibly a different length.

Note that for OUT and IN/OUT binds, the number of elements returned in the array is returned in *arrayLength as well. The client must make sure that it has allocated elementSize * arraySize bytes for the buffer.

Syntax

void setDataBufferArray(unsigned int paramIndex,
   void *buffer,
   Type type,
   ub4 arraySize,
   ub4 *arrayLength,
   sb4 elementSize,
   ub2 *elementLength,
   sb2 *ind = NULL,
   ub2 *rc = NULL);

Parameters

paramIndex

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

buffer

Pointer to user-allocated buffer. It should have size * arraySize bytes in it

type

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

arraySize

Maximum number of elements in the array

arrayLength

Pointer to number of current elements in the array

elementSize

Size of the data buffer for each element

elementLength

Pointer to an array of lengths. elementLength[i] has the current length of the ith element of the array.

ind

Pointer to an array of indicators. An indicator for every buffer element.

rc

Pointer to an array of return codes.

setDouble()

Set a parameter to a C++ double value.

Syntax

void setDouble(unsigned int paramIndex,
   double x);

Parameters

paramIndex

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

x

The parameter value.

setErrorOnNull()

Enables/disables exceptions for reading of null values on paramIndex parameter of the statement. If exceptions are enabled, calling a getxxx on paramIndex parameter would result in an SQLException if the parameter value is null. This call can also be used to disable exceptions.

Syntax

void setErrorOnNUll(unsigned int paramIndex,
   bool causeException);

Parameters

paramIndex

The first parameter 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.

setFloat()

Set a parameter to a C++ float value.

Syntax

void setFloat(unsigned int paramIndex,
   float x);

Parameters

paramIndex

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

x

The parameter value.

setInt()

Set a parameter to a C++ int value.

Syntax

void setInt(unsigned int paramIndex,
   int x);

Parameters

paramIndex

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

x

The parameter value.

setIntervalDS()

Set a parameter to a IntervalDS value.

Syntax

void setIntervalDS(unsigned int paramIndex,
   const IntervalDS &x);

Parameters

paramIndex

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

x

The parameter value.

setIntervalYM()

Set a parameter to a Interval value.

Syntax

void setIntervalYM(unsigned int paramIndex,
   const IntervalYM &x);

Parameters

paramIndex

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

x

The parameter value.

setMaxIterations()

Sets the maximum number of invocations that will be made for the DML statement. This must be called before any parameters are set on the prepared statement. The larger the iterations, the larger the numbers of parameters sent to the server in one round trip. However, a large number causes more memory to be reserved for all the parameters. Note that this is just the maximum limit. Actual number of iterations depends on the number of addIterations() that are done.

Syntax

void setMaxIterations(unsigned int maxIterations);

Parameters

maxIterations

Maximum number of iterations allowed on this statement.

setMaxParamSize()

This method sets the maximum amount of data to be sent or received for the specified parameter. It only applies to character and binary data. If the maximum amount is exceeded, the excess data is discarded. This method can be very useful when working with a LONG column. It can be used to truncate the LONG column by reading or writing it into a string or Bytes data type.

If the setString or setBytes method has been called to bind a value to an IN/OUT parameter of a pl/sql procedure, and the size of the OUT value is expected to be greater than the size of the IN value, then setMaxParamSize should be called.

Syntax

void setMaxParamSize(unsigned int paramIndex,
   unsigned int maxSize);

Parameters

paramIndex

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

maxSize

The new max parameter size limit (> 0) .

setNull()

Set a parameter to SQL null. Note that you must specify the parameter's SQL type.

Syntax

void setNull(unsigned int paramIndex,
   Type type);

Parameters

paramIndex

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

type

SQL type code defined by Type

setNumber()

Set a parameter to a Number value.

Syntax

void setNumber(unsigned int paramIndex,
   const Number &x);

Parameters

paramIndex

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

x

The parameter value.

setObject()

Set the value of a parameter using an object; use the C++.lang equivalent objects for integral values. The OCCI specification specifies a standard mapping from C++ Object types to SQL types. The given parameter C++ object will be converted to the corresponding SQL type before being sent to the database.

Syntax

void setObject(unsigned int paramIndex,
   PObject * x);

Parameters

paramIndex

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

x

The object containing the input parameter value.

setPrefetchMemorySize()

Set the amount of memory that will be 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);

Parameters

bytes

Number of bytes to use for storing data fetched during each round trip to the server.

setPrefetchRowCount()

Set the number of rows that will be 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);

Parameters

rowCount

Number of rows to fetch for each round trip to the server.

setRef()

Set a parameter to a RefAny value.

Syntax

void setRef(unsigned int paramIndex,
   RefAny &x);

Parameters

paramIndex

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

x

The parameter value.

setRowid()

Set a Rowid bytes array for a bind position.

Syntax

void setRowid(unsigned int paramIndex,
   const Bytes &x);

Parameters

paramIndex

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

x

The parameter value.

setSQL()

A new SQL string can be associated with a Statement object by this call. Resources associated with the previous SQL statement are freed. In particular, a previously obtained result set is invalidated. If an empty sql string, "", was used when the Statement was created, a setSQL method with the proper SQL string must be done prior to execution.

Syntax

void setSQL(const string &sql);

Parameters

sql

Any SQL statement.

setString()

Set a parameter to an string value.

Syntax

void setString(unsigned int paramIndex,
   const string &x);

Parameters

paramIndex

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

x

The parameter value.

setTimestamp()

Set a parameter to a Timestamp value.

Syntax

void setTimestamp(unsigned int paramIndex,
   const Timestamp &x);

Parameters

paramIndex

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

x

The parameter value.

setUInt()

Set a parameter to a C++ unsigned int value.

Syntax

void setUInt(unsigned int paramIndex,
   unsigned int x);

Parameters

paramIndex

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

x

The parameter value.

setVector()

This method sets a parameter to a vector. This method should be used when the type is a collection type -- varrays or nested tables. The SQL Type of the elements in the collection should be compatible with the type of the vector. For example, if the collection is a varray of VARCHAR2, use vector<string>

Syntax

There are variants of syntax:

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<int> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<unsigned int> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<double> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<float> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<string> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<RefAny> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Blob> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Clob> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Bfile> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Timestamp> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<IntervalDS> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<IntervalYM> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Date> &vect,
   string sqltype);

void setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Number> &vect,
   string sqltype);

template <class T>
void setVector( Statement *stmt, unsigned int paramIndex,
    const OCCI_STD_NAMESPACE::vector< T > &vect, 
    const OCCI_STD_  NAMESPACE::string &sqltype) ;

template <class T>
void setVector( Statement *stmt, unsigned int paramIndex,
    const OCCI_STD_NAMESPACE::vector<T* > &vect, 
    const OCCI_STD_NAMESPACE::string &sqltype) ;

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 setVector(Statement *stmt,
   unsigned int paramIndex,
   vector<Ref<T>> &vect,
   string sqltype);

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

Parameters

stmt

statement on which parameter is to be set.

paramIndex

parameter index , first parameter is 1, second is 2, ...

vect

vector to be set.

sqltype

sqltype of the parameter/column.

For example, CREATE TYPE num_coll AS VARRAY OF NUMBER. And the column/parameter type is num_coll. The sqltype would be num_coll.

setVectorOfRefs()

This method sets a parameter to a vector . This method should be used when the 
type is a collection of REFs -- varrays or nested tables of REFs

Syntax

template  <class T>
  void setVectorOfRefs(Statement *stmt, unsigned int paramIndex,
  const OCCI_STD_NAMESPACE::vector<Ref<T> > &vect,
  const OCCI_STD_NAMESPACE::string &sqltype) ;

Parameters

stmt

statement on which parameter is to be set.

paramIndex

parameter index , first parameter is 1, second is 2, ...

vect

vector to be set

sqltype

sqltype of the parameter/column.

It is recommened to use setVectorOfRefs insetad of specialised function setVector for Ref<T>.

status()

Returns the current status of the statement. Useful when there is streamed data to be written (or read). Other methods such as getCurrentStreamParam and getCurrentIteration can be called to find out the streamed parameter that needs to be written and the current iteration number for an iterative or array execute.

The status method can be called repeatedly to find out the status of the execution. Returns one of following:

RESULT_SET_AVAILABLE-- call getResultSet()
UPDATE_COUNT_AVAILABLE -- call getUpdateCount()
NEEDS_STREAM_DATA -- call getCurrentStream() and getCurrentIteration(), and write stream
STREAM_DATA_AVAILABLE -- call getCurrentStream() and getCurrentIteration(), and read stream
PREPARED
UNPREPARED

Syntax

Status status() const;