iopc::Cursor Class Reference
[iopcdb]

Executes SQL statements and fetches the results. More...

#include <cursor.h>

List of all members.

Public Types

enum  State
 State of the cursor. More...

Public Member Functions

void addInParam (const int pos, const void *varAddr, const Type &varType, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Adds a new IN parameter. Accepts Type::IOPC_TYPECLASS_STRING, Type::IOPC_TYPECLASS_SIMPLE as well as Type::IOPC_TYPECLASS_ENHANCED.
void addEnhancedInParam (const int pos, EnhancedTypeBase &obj, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Adds a new Enhanced data type IN parameter.
void addNullInParam (const int pos, const Type &type, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Adds an database NULL IN parameter.
void addOutParam (const int pos, const void *varAddr, const Type &varType, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Adds a new OUT parameter. Accepts Type::IOPC_TYPECLASS_STRING, Type::IOPC_TYPECLASS_SIMPLE as weel as Type::IOPC_TYPECLASS_ENHANCED.
void addEnhancedOutParam (const int pos, EnhancedTypeBase &obj, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Adds a new Enhanced data type OUT parameter.
void addParam (Parameter::ParamType direction, const int pos, const void *varAddr, const Type &varType, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Adds a new parameter. Accepts Type::IOPC_TYPECLASS_STRING, Type::IOPC_TYPECLASS_SIMPLE as weel as Type::IOPC_TYPECLASS_ENHANCED data types.
void addEnhancedParam (Parameter::ParamType direction, const int pos, EnhancedTypeBase &obj, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Adds a new Enhanced data type parameter.
bool isOpened ()
 Returns true if the Cursor state is not Cursor::CLOSED.
State getState ()
 Returns the current state of the Cursor.
CursorImplgetImplementation ()
 Returns the driver-side part of the Cursor implemenation.
void open ()
 Opens the cursor.
void prepare ()
 Prepares the SQL statement for execution.
void preExecBindNull (const int pos, const Type &varType, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Binds a database NULL parameter to a place in the prepared statement.
void preExecBind (const int pos, const void *varAddr, const unsigned int size, const Type &varType, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Binds a parameter to a place in the prepared statement.
void execute ()
 Executes the SQL statement.
void preFetchBind (const int pos, const void *varAddr, const unsigned int size, const Type &varType, bool *isNull=NULL, const MetadataHolder &attributes=MetadataHolder::emptyMeta)
 Binds an output parameter to a place in the result set.
bool fetchNext ()
 Fetches next result from the result set.
bool fetchPrev ()
 Fetches previous result from the result set.
long getPosition ()
 Returns current position in the result set.
void close ()
 Closes the cursor.


Detailed Description

Executes SQL statements and fetches the results.

Also allows user to bind input parameters to parametrised queries and output parameters into which the execution results will be fetched.

This class is NOT thread safe and is not intended to be used concurrently.


Member Enumeration Documentation

State of the cursor.

Cursor is created as CLOSED, The open() method changes its state to Cursor::OPENED, prepare() method changes its state to Cursor::PREPARED and execute() to Cursor::EXECUTED. Then the cursor can be Cursor::PREPARED again or Cursor::CLOSED.


Member Function Documentation

void iopc::Cursor::addInParam ( const int  pos,
const void *  varAddr,
const Type varType,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Adds a new IN parameter. Accepts Type::IOPC_TYPECLASS_STRING, Type::IOPC_TYPECLASS_SIMPLE as well as Type::IOPC_TYPECLASS_ENHANCED.

If the varType is of Type::IOPC_TYPECLASS_ENHANCED, the EnhancedTypeParameter is created. SimpleTypeParameter is created for Type::IOPC_TYPECLASS_SIMPLE and Type::IOPC_TYPECLASS_ENHANCED type classes.

If string types (Type::IOPC_TYPECLASS_STRING, EString or EWString), the [db.type.length] metadata must be specified either in the varType metadata or provided in the attributes input parameter.

Exceptions:
IopcIncorrectUsageException if other type than Type::IOPC_TYPECLASS_ENHANCED, Type::IOPC_TYPECLASS_SIMPLE or Type::IOPC_TYPECLASS_ENHANCED is specified.
Parameters:
pos Position of the parameter in the prepared statement, starting from 1. If a parameter already exists on the pos position, it is overwritten.
varAddr Pointer to the value being bound. The pointer must remain valid as long as the cursor is used. If Type::IOPC_TYPECLASS_STRING type is used, this pointer must point to a buffer containing standard, zero-terminated C string representation. So even if the varType is TypeDesc<std::string> the varAddr must point to a standard C string. If EString or EWString is used, the pointer should point to their instances.
varType Parameter data type
attributes Additional attributes or driver-dependent data.
  • [db.type.length] - For the EString and EWString types it specifies the (maximum) length of the externalized string buffer - see the externalize methods in EnhancedTypeBase. For the Type::IOPC_TYPECLASS_STRING types it specifies the maximum allocated length (in characters without the trailing zero) for the input buffers.

void iopc::Cursor::addEnhancedInParam ( const int  pos,
EnhancedTypeBase obj,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Adds a new Enhanced data type IN parameter.

Parameters:
pos Position of the parameter in the prepared statement, starting from 1. If a parameter already exists on the pos position, it is overwritten.
obj Reference to the value being bound. The reference must be valid as long as the cursor is used.
attributes Additional attributes or driver-dependent data.
  • [db.type.length] - For the EString and EWString types it specifies the (maximum) length of the externalized string buffer - see the externalize methods in EnhancedTypeBase.
If EString or EWString type is used, the [db.type.length] metadata must be specified either in the TypeDesc<EString>::getType() or in the TypeDesc<EWString>::getType metadata or provided in the attributes input parameter.

void iopc::Cursor::addNullInParam ( const int  pos,
const Type type,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Adds an database NULL IN parameter.

Parameters:
pos Position of the parameter in the prepared statement or in the result set, starting from 1. Note that some drivers (like the IopcOracle10g driver) require the parameters to be bound as a sequence so that no positions are skipped.
type Data type of the parameter. Enhanced as well as simple types may be used.
attributes Additional attributes or driver-dependent data.

void iopc::Cursor::addOutParam ( const int  pos,
const void *  varAddr,
const Type varType,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Adds a new OUT parameter. Accepts Type::IOPC_TYPECLASS_STRING, Type::IOPC_TYPECLASS_SIMPLE as weel as Type::IOPC_TYPECLASS_ENHANCED.

If the varType is of Type::IOPC_TYPECLASS_ENHANCED, the EnhancedTypeParameter is created. SimpleTypeParameter is created for Type::IOPC_TYPECLASS_SIMPLE and Type::IOPC_TYPECLASS_ENHANCED type classes.

If string types (Type::IOPC_TYPECLASS_STRING, EString or EWString), the [db.type.length] metadata must be specified either in the varType metadata or provided in the attributes input parameter.

Exceptions:
IopcIncorrectUsageException if other type than Type::IOPC_TYPECLASS_ENHANCED, Type::IOPC_TYPECLASS_SIMPLE or Type::IOPC_TYPECLASS_ENHANCED is specified.
Parameters:
pos Position of the parameter in the prepared statement or in the result set, starting from 1. Note that some drivers (like the IopcOracle10g driver) require the OUT parameters to be bound as a sequence so that no positions are skipped. If a parameter already exists on the pos position, it is overwritten.
varAddr Pointer to the value being bound. The pointer must remain valid as long as the cursor is used. If Type::IOPC_TYPECLASS_STRING type is used, this pointer must point to a buffer into which a standard C string will be fetched. So even if the varType is TypeDesc<std::string> the varAddr will point to a standard C string. If EString or EWString is used, the pointer should point to their instances.
varType Parameter data type
attributes Additional attributes or driver-dependent data.
  • [db.type.length] - For the EString and EWString types it specifies the (maximum) length of the externalized string buffer - see the externalize methods in EnhancedTypeBase. For the Type::IOPC_TYPECLASS_STRING types it specifies the maximum allocated length (in characters without the trailing zero) for the output buffers.

void iopc::Cursor::addEnhancedOutParam ( const int  pos,
EnhancedTypeBase obj,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Adds a new Enhanced data type OUT parameter.

Parameters:
pos Position of the parameter in the prepared statement, starting from 1. If a parameter already exists on the pos position, it is overwritten.
obj Reference to the value being bound. The reference must be valid as long as the cursor is used.
attributes Additional attributes or driver-dependent data.
  • [db.type.length] - For the EString and EWString types it specifies the (maximum) length of the externalized string buffer - see the externalize methods in EnhancedTypeBase.
If EString or EWString type is used, the [db.type.length] metadata must be specified either in the TypeDesc<EString>::getType() or in the TypeDesc<EWString>::getType metadata or provided in the attributes input parameter.

void iopc::Cursor::addParam ( Parameter::ParamType  direction,
const int  pos,
const void *  varAddr,
const Type varType,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Adds a new parameter. Accepts Type::IOPC_TYPECLASS_STRING, Type::IOPC_TYPECLASS_SIMPLE as weel as Type::IOPC_TYPECLASS_ENHANCED data types.

If the varType is of Type::IOPC_TYPECLASS_ENHANCED, the EnhancedTypeParameter is created. SimpleTypeParameter is created for Type::IOPC_TYPECLASS_SIMPLE and Type::IOPC_TYPECLASS_ENHANCED type classes.

If string types (Type::IOPC_TYPECLASS_STRING, EString or EWString), the [db.type.length] metadata must be specified either in the varType metadata or provided in the attributes input parameter.

Exceptions:
IopcIncorrectUsageException if other type than Type::IOPC_TYPECLASS_ENHANCED, Type::IOPC_TYPECLASS_SIMPLE or Type::IOPC_TYPECLASS_ENHANCED is specified.
Parameters:
direction Parameter direction
pos Position of the parameter in the prepared statement or in the result set, starting from 1. Note that some drivers (like the IopcOracle10g driver) require the parameters to be bound as a sequence so that no positions are skipped. If a parameter already exists on the pos position, it is overwritten.
varAddr Pointer to the value being bound. The pointer must remain valid as long as the cursor is used. If Type::IOPC_TYPECLASS_STRING type is used, this pointer must point to a buffer containing standard, zero-terminated C string representation [IN] or to a buffer into which a standard C string will be fetched [OUT]. So even if the varType is TypeDesc<std::string> the varAddr must point [IN] or will point [OUT] to a standard C string. If EString or EWString is used, the pointer should point to their instances.
varType Parameter data type
attributes Additional attributes or driver-dependent data.
  • [db.type.length] - For the EString and EWString types it specifies the (maximum) length of the externalized string buffer - see the externalize methods in EnhancedTypeBase. For the Type::IOPC_TYPECLASS_STRING types it specifies the maximum allocated length (in characters without the trailing zero) for the input and output buffers.

void iopc::Cursor::addEnhancedParam ( Parameter::ParamType  direction,
const int  pos,
EnhancedTypeBase obj,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Adds a new Enhanced data type parameter.

Parameters:
direction Parameter direction
pos Position of the parameter in the prepared statement, starting from 1. If a parameter already exists on the pos position, it is overwritten.
obj Reference to the value being bound. The reference must be valid as long as the cursor is used.
attributes Additional attributes or driver-dependent data.
  • [db.type.length] - For the EString and EWString types it specifies the (maximum) length of the externalized string buffer - see the externalize methods in EnhancedTypeBase.
If EString or EWString type is used, the [db.type.length] metadata must be specified either in the TypeDesc<EString>::getType() or in the TypeDesc<EWString>::getType metadata or provided in the attributes input parameter.

State iopc::Cursor::getState (  )  [inline]

Returns the current state of the Cursor.

See also:
State

void iopc::Cursor::open (  ) 

Opens the cursor.

Database driver allocates all resources needed for the cursor execution

Changes the cursor state to Cursor::OPENED

Exceptions:
IopcDbException If the cursor is not in the Curosr::CLOSED state

void iopc::Cursor::prepare (  ) 

Prepares the SQL statement for execution.

Changes the cursor state to Cursor::PREPARED

If the cursor satate is Cursor::CLOSED, it is opened by calling open().

void iopc::Cursor::preExecBindNull ( const int  pos,
const Type varType,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Binds a database NULL parameter to a place in the prepared statement.

Prepare() must be invoked before calling this method

Parameters:
pos Position of the parameter in the prepared statement
varType Data type of the parameter. varType must refer only to basic datatypes (IOPC_TYPECLASS_SIMPLE) or to string datatypes (IOPC_TYPECLASS_STRING).
attributes Additional driver dependent parameters.
Exceptions:
IopcDbException If the cursor is not in Cursor::PREPARED state

void iopc::Cursor::preExecBind ( const int  pos,
const void *  varAddr,
const unsigned int  size,
const Type varType,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Binds a parameter to a place in the prepared statement.

Prepare() must be invoked before calling this method

Parameters:
pos Position of the parameter in the prepared statement
varAddr Address of the parameter value to be bound
size Memory size of the parameter in bytes
varType Data type of the parameter. varType must refer only to basic datatypes (IOPC_TYPECLASS_SIMPLE) or to string datatypes (IOPC_TYPECLASS_STRING). If the IOPC_TYPECLASS_STRING type is specified, the varAddr refers to standard zero-terminaded C string representation.
attributes Additional driver dependent parameters.
Exceptions:
IopcDbException If the cursor is not in Cursor::PREPARED state

void iopc::Cursor::execute (  ) 

Executes the SQL statement.

Performs the following steps:

  1. If the cursor state is Cursor::CLOSED, the cursor is opened and prepared. If the cursor state is Cursor::OPENED or Cursor::EXECUTED, the cursor is prepared.
  2. Parameter::preExec() is invoked on all IN parameters
  3. The SQL statement is executed
  4. Cursor state is changed to Cursor::EXECUTED
  5. Parameter::postExec() is invoked on all IN parameters

void iopc::Cursor::preFetchBind ( const int  pos,
const void *  varAddr,
const unsigned int  size,
const Type varType,
bool *  isNull = NULL,
const MetadataHolder attributes = MetadataHolder::emptyMeta 
)

Binds an output parameter to a place in the result set.

Parameters:
pos Position of the parameter in the result set
varAddr Address of the output buffer where the fetched value will be stored.
size Buffer size allocated to hold the fetched value in bytes
varType Data type of the parameter. varType refers only to basic datatypes (IOPC_TYPECLASS_SIMPLE) or to string datatypes (IOPC_TYPECLASS_STRING).
isNull Pointer to an indicator variable which will be set to true if the fetched value is database NULL. A NULL pointer may be passed to ignore the database NULL value notifiaction.
attributes Additional driver dependent parameters.

bool iopc::Cursor::fetchNext (  ) 

Fetches next result from the result set.

Performs the following steps:

  1. Before first fetch after Cursor::execute() is performed, Parameter::preFetch() is invoked on all OUT parameters.
  2. Next result is fetched, output parameters and NULL indicators are updated.
  3. Parameter::postFetch() is invoked on all OUT parameters.

Returns:
true if a row was fetched. Otherwise, the OUT parameters are not updated and the method returns false.
Exceptions:
IopcDbException if the cursor is not in the Cursor::EXECUTED state

bool iopc::Cursor::fetchPrev (  ) 

Fetches previous result from the result set.

At least one call to fetchNext() must be performed before calling fetchPrev. Output parameters and NULL indicators are updated and Parameter::postFetch() is invoked on all OUT parameters.

Exceptions:
IopcDbException if the cursor is not in the Cursor::EXECUTED state
IopcNotSupportedException if this operation is not supported by the database driver.

void iopc::Cursor::close (  ) 

Closes the cursor.

Database driver release all resources allocated in the Cursor::open() method Changes the Cursor state to Cursor::CLOSED


The documentation for this class was generated from the following files:

Generated on Tue Apr 14 16:46:39 2009 for IOPC 2 by  doxygen 1.5.6