Oracle8iCursor Class Reference

Class that implements "cursor" functions using Oracle 8i OCI - preparing and executing of SQL statements, fetching data from database and so on. More...

#include <Oracle8iCursor.h>

Inheritance diagram for Oracle8iCursor:

[legend]Collaboration diagram for Oracle8iCursor:

[legend]List of all members.


Public Member Functions
virtual	~Oracle8iCursor ()
Protected Member Functions
	Oracle8iCursor (class Connection *connection)
virtual bool	_Open ()
virtual bool	_Prepare (const char *const sqlCommand)
virtual bool	_PreExecBind (const char varName, const int pos, const void varAddr, const int varLen, const IopcDataType varType, bool null=false)
virtual bool	_Execute ()
virtual bool	_PreFetchBind (const int position, const void varAddr, const int varLen, const IopcDataType varType, bool null=NULL)
virtual bool	_FetchNext ()
virtual bool	_FetchPrev ()
virtual long	_Position ()
virtual bool	_Close ()
virtual bool	_PreExecBind (const char varName, const void varAddr, const int varLen, const char varType, short *varInd=NULL)
virtual bool	_PreFetchBind (const int position, const void varAddr, const int varLen, const char varType, short varInd=NULL)
int	processOCIError (int ociRetVal, const char ociFunctionName, const char myFunctionName, bool useEnvHandle=0)
void	clear ()
Static Protected Member Functions
ub2	getVarTypeAndLength (int &varLen, const IopcDataType varType, const void *varAddr, bool preExecBind)
IopcDataType	oldTypeToIopcType (const char oldType)
void	logDebugMessage (const char formatString, const char param1="", int mask=0)
Protected Attributes
OCIStmt *	stmtHandle
bool	isSelectStatement
OCIEnv *	ociEnvironment
OCIError *	errorHandle
OCISvcCtx *	serviceContext
unsigned int	position
bool *	autoCommit
std::list< IndicatorStruct >	indicatorVariables
Friends
int	processOCIErrorGlobal (Oracle8iClassType classType, OCIEnv ociEnvironment, OCIError errorHandle, sword ociRetVal, const char ociFunctionName, const char myFunctionName, bool useEnvHandle)

Detailed Description

Class that implements "cursor" functions using Oracle 8i OCI - preparing and executing of SQL statements, fetching data from database and so on.

Oracle 8i doesn't use cursors for SQL queries processing, It uses statement handles (stmtHandle) instead.

Methods of this class return true if OK, in case of error throw ObjLibException_ConnectionError (if not said something different).

Constructor & Destructor Documentation

Oracle8iCursor::Oracle8iCursor ( class Connection * connection ) [protected]

Simple constructor.

Oracle8iCursor::~Oracle8iCursor ( ) [virtual]

Destructor - destroys indicatorVariables.

Member Function Documentation

bool Oracle8iCursor::_Open ( ) [protected, virtual]

"Opens the cursor." Oracle8i doesn't use cursors, statement handle (stmtHandle) is used instead. So this function only initializes some variables.
Reimplemented from Cursor.

bool Oracle8iCursor::_Prepare ( const char *const sqlCommand ) [protected, virtual]

Prepares sqlCommand to be executed by Oracle (as a result stmtHandle is initialized).

Parameters:

sqlCommand SQL statement to be processed.

Implements Cursor.

bool Oracle8iCursor::_PreExecBind ( const char * varName,

const int pos,

const void * varAddr,

const int varLen,

const IopcDataType varType,

bool null = false

) [protected, virtual]

Binds an input variable of previously prepared SQL command. If varName is not NULL variable is bound by name (varName), if it is NULL, variable is bound by position (pos). This function is called once for every input variable in SQL statement -> typically more than once per statement.

Note:
Binding by name is used only by old POLiTe-style persistence system. If you don't need to support POLiTe-style persistent classes, you can implement only binding by position.

Parameters:

varName Name of the variable in appropriate SQL statement. Can be NULL.

pos Position of the variable in the SQL statement (first variable -> pos = 1). Ignored if varName is set.

varAddr Address of the variable.

varLen Length of the variable (0 if it should be distinguished from varType).

varType Type of the variable.

null Should the variable value be set to NULL ? (If set, varAddr, varLen and varType are ignored.)

See also:
getVarTypeAndLength()

Implements Cursor.

bool Oracle8iCursor::_Execute ( ) [protected, virtual]

Executes SQL statement, that has been already prepared and its input variables (if any) have been bound.

Note:
Throws exception ObjLibException_DatabaseLock if SQL statement failed due to some lock (see ORA_RESOURCE_BUSY), in case of another error throws ObjLibException_SqlError.

Implements Cursor.

bool Oracle8iCursor::_PreFetchBind ( const int position,

const void * varAddr,

const int varLen,

const IopcDataType varType,

bool * null = NULL

) [protected, virtual]

Binds an output variable of executed SQL statement. This function is called once for every output variable in SQL statement -> typically more than once per statement.

Parameters:

position Position of the variable in appropriate SQL statement.

varAddr Address of the variable.

varLen Length of the variable (0 if it should be distinguished from varType).

varType Type of the variable.

null Address of indicator variable - set to true if received value is NULL, otherwise set to false.

See also:
getVarTypeAndLength()

Implements Cursor.

bool Oracle8iCursor::_FetchNext ( ) [protected, virtual]

Fetches next row for SQL statement, that has been already executed and its output variables have been bound.
Implements Cursor.

bool Oracle8iCursor::_FetchPrev ( ) [protected, virtual]

Fetches previous row - Oracle v. 8i doesn't support this, so this function always throws ObjLibException_NotSupported.
Implements Cursor.

long Oracle8iCursor::_Position ( ) [protected, virtual]

Returns actual position in the query - it means how many rows have been already fetched.

Implements Cursor.

bool Oracle8iCursor::_Close ( ) [protected, virtual]

"Closes the cursor." Frees statement handle (stmtHandle).

Reimplemented from Cursor.

bool Oracle8iCursor::_PreExecBind ( const char * varName,

const void * varAddr,

const int varLen,

const char varType,

short * varInd = NULL

) [protected, virtual]

Obsolete version of _PreExecBind used by POLiTe-style persistent classes. Use _PreExecBind(const char *,const int,const void *,const int,const IopcDataType,bool) instead.
Converts varType to IopcDataType (oldTypeToIopcType()) and calls _PreExecBind(const char *,const int,const void *,const int,const IopcDataType,bool).

Parameters:

varName Name of the variable in appropriate SQL statement.

varAddr Address of the variable.

varLen Length of the variable (0 if it should be distinguished from varType).

varType POLiTe-style type of the variable (TYPE_INT etc.)

varInd Indicator variable to be used.

See also:
getVarTypeAndLength()

Implements Cursor.

bool Oracle8iCursor::_PreFetchBind ( const int position,

const void * varAddr,

const int varLen,

const char varType,

short * varInd = NULL

) [protected, virtual]

Obsolete version of _PreFetchBind used by POLiTe-style persistent classes. Use _PreFetchBind(const int,const void *,const int,const IopcDataType,bool *) instead.
Converts varType to IopcDataType (oldTypeToIopcType()) and calls _PreFetchBind(const int,const void *,const int,const IopcDataType,bool *).

Parameters:

position Position of the variable in appropriate SQL statement.

varAddr Address of the variable.

varLen Length of the variable (0 if it should be distinguished from varType).

varType POLiTe-style type of the variable (TYPE_INT etc.)

varInd Indicator variable to be used.

See also:
getVarTypeAndLength()

Implements Cursor.

int Oracle8iCursor::processOCIError ( int ociRetVal,

const char * ociFunctionName,

const char * myFunctionName,

bool useEnvHandle = 0

) [inline, protected]

Arbitrary function for error handling - calls processOCIErrorGlobal() passing it given parameters and some class specific values.

Parameters:

ociRetVal Return value of OCI function to handle its (possible) error.

ociFunctionName Name of the OCI function.

myFunctionName Name of the member, who called the OCI function.

useEnvHandle Set if OCIErrorGet() is to be called on ociEnvironment instead of on errorHandle.

Returns:
Return value from processOCIErrorGlobal()

ub2 Oracle8iCursor::getVarTypeAndLength ( int & varLen,

const IopcDataType varType,

const void * varAddr,

bool preExecBind

) [static, protected]

Arbitrary function - returns Oracle external data type of variable specified by arguments and updates length of the variable (varLen)

Note:
varLen is updated only if it was 0 or in case described in following note.
Old version of library (POLiTe) in some cases (POLiTe example test013) sends invalid length in varLen for input strings (these bound by _PreExecBind()) - this causes OCIStmtExecute() to return "ORA-01480: trailing null missing from STR bind value". So in case of preExecBind we ignore varLen for strings and compute it always using strlen().

Parameters:

varAddr Address of the variable.

varLen Length of the variable (0 if it should be distinguished using varType).

varType Type of the variable.

preExecBind Set if called from _PreExecBind() - to ignore varLen for strings - see note above.

Returns:
Oracle OCI type of host variable (f.e. SQLT_INT), UNKNOWN_DATA_TYPE if data type is unknown.

IopcDataType Oracle8iCursor::oldTypeToIopcType ( const char oldType ) [static, protected]

Convert old (POLiTe style) type specification to IopcDataType.
Used by _PreExecBind(const char *const,const int,const void *,const int,const IopcDataType,bool) and _PreFetchBind(const int,const void *,const int,const IopcDataType, bool *).

void Oracle8iCursor::clear ( ) [protected]

Clears indicatorVariables - called from _Close() and from destructor.

void Oracle8iCursor::logDebugMessage ( const char * formatString,

const char * param1 = "",

int mask = 0

) [inline, static, protected]

Logs (using logmsg()) given message if C_ORACLECURSOR_TRACE is set, otherwise does nothing.

Parameters:

formatString String with message to be logged - can contains only one "%s" specifier for inserting string param1.

param1 Optional string to be inserted into formatString

mask Mask (see TL_INFO_SQL etc.) to be passed to logmsg()

Friends And Related Function Documentation

int processOCIErrorGlobal ( Oracle8iClassType classType,

OCIEnv * ociEnvironment,

OCIError * errorHandle,

sword ociRetVal,

const char * ociFunctionName,

const char * myFunctionName,

bool useEnvHandle

) [friend]

According to type of ociRetVal creates error message (typically it's necessary to call OCIErrorGet()) and calls logDebugMessage() method of class specified by classType to log the message.

Parameters:

classType Type of Oracle8i* class this function was called from.

ociEnvironment Pointer to OCI environment handle.

errorHandle Pointer to OCI error handle.

ociRetVal Return value of OCI function to handle its (possible) error.

ociFunctionName Name of the OCI function.

myFunctionName Name of member function of specified class, which was the OCI function called from.

useEnvHandle Set if OCIErrorGet() is to be called on ociEnvironment instead of errorHandle.

Return values:

0 OK, no error occured.

-1 Some error occured, OCIErrorGet() hasn't been called.

Other ORA-????? error code (acquired from OCIErrorGet()).

Member Data Documentation

OCIStmt* Oracle8iCursor::stmtHandle [protected]

OCI statement handle - used for SQL statement processing.

bool Oracle8iCursor::isSelectStatement [protected]

Are we processing a SELECT or some other SQL statement (passed from _Prepare() to _Execute() for setting parameter 'iters' in OCIStmtExecute())?

OCIEnv* Oracle8iCursor::ociEnvironment [protected]

Pointer to OCI Environment handle (see OciEnvCreate() in Oracle documentation).

Note:
Created in Oracle8iDatabase::Orecle8iDatabase() and copied here in constructor of this class.

OCIError* Oracle8iCursor::errorHandle [protected]

Pointer to OCI Error handle to be passed to OCIErrorGet() for diagnostic information in the event of an error.

Note:
Created in Oracle8iDatabase::Orecle8iDatabase() and copied here in constructor of this class.

OCISvcCtx* Oracle8iCursor::serviceContext [protected]

The service context pointer.

Note:
Created in Oracle8iDatabase::Orecle8iDatabase() and copied here in constructor of this class.

unsigned int Oracle8iCursor::position [protected]

Position of cursor in query results (how many rows have been already fetched).

bool* Oracle8iCursor::autoCommit [protected]

Perform autocommit ? (Pointer to Oracle8iConnection::autoCommit.).

std::list<IndicatorStruct> Oracle8iCursor::indicatorVariables [protected]

Used to set bool given as parameter null in _PreFetchBind(const int,const void *,const int,const IopcDataType,bool *) to appropriate value after fetching values from database.. The list is filled in _PreFetchBind(const int,const void *,const int,const IopcDataType,bool *) and processed in _FetchNext().

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

Generated on Wed Aug 11 22:36:06 2004 for IOPC by Doxygen 1.3.6

Oracle8iCursor Class Reference

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation