Instances of this class correspond to the cursors in an RDBMS. More...

#include <ildblink/ildreq.h>

Inheritance diagram for IldRequest:

Public Member Functions
virtual	~IldRequest ()
	This virtual destructor is invoked when an instance of `IldRequest` is destroyed. More...

virtual IldRequest &	bindCol (IlUShort index, IldColumnType type, IlAny buffer, IlUInt size=0, short *indicators=0)=0
	Set or change a result set column description according to its arguments. More...

virtual IldRequest &	bindCol (const char columnName, IldColumnType type, IlAny buffer, IlUInt size=0, short indicators=0)=0
	Set or change the column description of a column in the result set. More...

virtual IldRequest &	bindParam (IlUShort index, IldColumnType type, IlInt size=-1, IlAny buffer=0, short indicators=0, IlBoolean out=IlFalse, IlUShort arrSize=0, IldADTDescriptor adt=0)=0
	Sets the descriptor (in the sense of the SQL statement `describe`) of an input variable for the current query. More...

virtual IldRequest &	bindParam (const char varName, IldColumnType type, IlInt size=-1, IlAny buffer=0, short indicators=0, IlBoolean out=IlFalse, IlUShort arrSize=0, IldADTDescriptor *adt=0)=0
	Set the descriptor (in the sense of the SQL statement `describe`) of an input variable for the current query. More...

virtual IldRequest &	closeCursor ()=0
	Empty the current result set, whether there are still rows to be fetched or not. More...

virtual IldRequest &	execute (IlInt *rowCount=0, IlInt count=-1)=0
	Execute a previously parsed query. More...

virtual IldRequest &	execute (const char query, IlInt rowCount=0)=0
	Directly execute a statement. More...

virtual IldRequest &	fetch ()=0
	Get the next batch of rows from the result set. More...

virtual IldRequest &	fetchScroll (IlInt fetchOrientation=IldFetchDirectionNext, IlInt fetchOffset=0)=0
	Fetch the data using scroll mode. More...

virtual IldADTValue *	getColADTValue (IlUShort col, IlUInt row=0)=0
	Get a user defined type column value as an object. More...

virtual IlUInt	getColArraySize () const =0
	Tell the size of the fetch array. More...

virtual IldBytes	getColBinaryValue (IlUShort col, IlUInt row=0)=0
	Get a binary column value. More...

virtual IlUChar	getColByteValue (IlUShort col, IlUInt row=0)=0
	Get a byte column value. More...

virtual IlUShort	getColCount () const =0
	Find the number of columns in the result set. More...

virtual IldDateTime	getColDateTimeValue (IlUShort col, IlUInt row=0)=0
	Get a date time column value as an object. More...

virtual IldDateTime	getColDateTimeValue (const unsigned char *b)=0
	Make an instance of `IldDateTime` from the string form. More...

virtual const char *	getColDateValue (IlUShort col, IlUInt row=0)=0
	Get a date column value as a string. More...

virtual IldAppDescriptor *	getColDescriptor (IlUShort col)=0
	Get the descriptor of a column from the result set. More...

virtual short	getColIndex (const char *colName)=0
	Find the index of a named column from the result set. More...

virtual IlInt	getColIntegerValue (IlUShort col, IlUInt row=0)=0
	Get an integer column value. More...

virtual const char *	getColLongTextValue (IlUShort col, IlUInt row=0, IlInt *size=0)=0
	Get a long text column value. More...

virtual double	getColMoneyValue (IlUShort col, IlUInt row=0)=0
	Get a money column value. More...

virtual const char *	getColName (IlUShort index)=0
	Find the name of a column form the result set. More...

virtual IlNumeric	getColNumericValue (IlUShort col, IlUInt row=0)=0
	Get a numeric column value as an object. More...

virtual double	getColRealValue (IlUShort col, IlUInt row=0)=0
	Get a floating point column value. More...

virtual IldBytes	getColRefValue (IlUShort col, IlUInt row=0)=0
	Get a reference column value. More...

virtual const char *	getColRTrimedStringValue (IlUShort col, IlUInt row=0)=0
	Get a string column value trimed from balnks on the right. More...

virtual IlUInt	getColSize (IlUShort index) const =0
	Find the size of a column from the result set. More...

virtual short	getColSQLType (IlUShort index) const =0
	Find the SQL type code of a column from the result set. More...

virtual const char *	getColSQLTypeName (IlUShort index) const =0
	Find the SQL type name of a column from the result set. More...

virtual const char *	getColStringValue (IlUShort col, IlUInt row=0)=0
	Get a string column value. More...

virtual IldColumnType	getColType (IlUShort index) const =0
	Find the type of column from the result set. More...

virtual const char *	getCursorName () const =0
	Get the name of the cursor. More...

virtual IldDbms &	getDbms () const =0
	Get the attached to `IldDbms` object. More...

virtual IldErrorReporter *	getErrorReporter () const =0
	Find the current user error reporter. More...

virtual IlAny	getHook () const =0
	Get the statement hook. More...

virtual IldRequest &	getLargeObject (const char tableName, const char columnName, const char whereCond, const char fileName)=0
	Retrieve a large object from the database into a file. More...

virtual IldRequest &	getLargeObjectChunk (IlUInt size, IlUChar data, IlUInt offset)=0
	Get a chunck from a large object. More...

virtual IldADTValue *	getParamADTValue (IlUShort index, IlUInt row=0)=0
	Find the user defined type value of a parameter. More...

virtual IlUInt	getParamArraySize () const =0
	Tell the size of the bind array. More...

virtual IldBytes	getParamBinaryValue (IlUShort index, IlUInt row=0)=0
	Find the binary value of a parameter. More...

virtual IlUInt	getParamBufferSize (IlUShort index) const =0
	Find the size (in number of bytes) of the buffer that manages input for a parameter. More...

virtual IlUChar	getParamByteValue (IlUShort index, IlUInt row=0)=0
	Find the byte value of a parameter. More...

virtual IlUShort	getParamCount () const =0
	Get the number of columns in the parameter set. More...

virtual IldRequest *	getParamCursorValue (IlUShort index, IlUInt row=0)=0
	Find the cursor value of a parameter. More...

virtual IldDateTime	getParamDateTimeValue (IlUShort index, IlUInt row=0)=0
	Find the date time value of a parameter. More...

virtual const char *	getParamDateValue (IlUShort index, IlUInt row=0)=0
	Find the date value of a parameter. More...

virtual IldAppDescriptor *	getParamDescriptor (IlUShort index)=0
	Get a parameter descriptor. More...

virtual short	getParamIndex (const char *varName)=0
	Get the index of a parameter from its name. More...

virtual IlInt	getParamIntegerValue (IlUShort index, IlUInt row=0)=0
	Find the integer value of a parameter. More...

virtual const char *	getParamLongTextValue (IlUShort index, IlUInt row=0)=0
	Find the text value of a parameter. More...

virtual double	getParamMoneyValue (IlUShort index, IlUInt row=0)=0
	Find the floating point value of a parameter. More...

virtual const char *	getParamName (IlUShort index)=0
	Find the name of a parameter. More...

virtual IlNumeric	getParamNumericValue (IlUShort index, IlUInt row=0)=0
	Find the numeric value of a parameter. More...

virtual double	getParamRealValue (IlUShort index, IlUInt row=0)=0
	Find the floating point value of a parameter. More...

virtual IldBytes	getParamRefValue (IlUShort index, IlUInt row=0)=0
	Find the reference value of a parameter. More...

virtual IlUInt	getParamSize (IlUShort index) const =0
	Find the size (in number of bytes) of a parameter. More...

virtual short	getParamSQLType (IlUShort index) const =0
	Find the type code of a parameter. More...

virtual const char *	getParamSQLTypeName (IlUShort index) const =0
	Find the SQL type name of a parameter. More...

virtual const char *	getParamStringValue (IlUShort index, IlUInt row=0)=0
	Find the string value of a parameter. More...

virtual IldColumnType	getParamType (IlUShort index) const =0
	Find the type of a parameter. More...

virtual IlUInt	getRowPos () const =0
	Find the index in the fetch array. More...

virtual IlUInt	getRowProcessedCount () const =0
	Tell how many rows where actually fetched at once. More...

virtual IlInt	getStatus () const =0
	Find the status of the last executed statement. More...

virtual IlBoolean	hasTuple () const =0
	Find if results were retrieved by the last fetch. More...

virtual IldRequest &	insertBinary (IldBytes &binaryData, const char tableName, const char columnName, const char *where=0)=0
	Update an existing record of a table, to store a long binary value. More...

virtual IldRequest &	insertLongText (const char text, IlUInt textSize, const char tableName, const char columnName, const char where=0)=0
	Update an existing record of a table, to store a long text value. More...

virtual IlBoolean	isColNull (IlUShort col, IlUInt row=0)=0
	Check if a column conatins a null value. More...

virtual IlBoolean	isCompleted () const =0
	Find if a statement related command has completed. More...

virtual IlBoolean	isCursorModeOn () const =0
	Find if the request is using cursor mode. More...

virtual IlBoolean	isFree ()=0
	Tell if the object is free to process statements. More...

virtual IlBoolean	isNullIndicatorOn (short *buffer, IlUInt row=0) const =0
	Tell if a parameter null indicator is set. More...

virtual IlBoolean	isParamNull (IlUShort index, IlUInt row=0)=0
	Tell if a parameter null indicator is set. More...

virtual IlBoolean	isReadOnly () const =0
	Find the read-only status of the request. More...

virtual IlBoolean	isScrollable () const =0
	Find the current scroll cursor mode status. More...

virtual IldRequest &	parse (const char *query)=0
	Prepare a statement for execution. More...

virtual IldRequest &	release ()=0
	Free the invoking object. More...

virtual IldRequest &	removeColArraySize ()=0
	Turn off the array fetch mode. More...

virtual IldRequest &	removeParamArraySize ()=0
	Turn off the array bind mode. More...

virtual IldRequest &	setColArraySize (IlUInt size)=0
	Turn on the array fetch mode. More...

virtual IldRequest &	setCursorModeOn (IlBoolean flag=IlTrue)=0
	Activate (or deactivate) cursor use to run select commands. More...

virtual IldRequest &	setCursorName (const char *cursName)=0
	Set the cursor name. More...

virtual IldRequest &	setErrorReporter (IldErrorReporter *rep)=0
	Set the user error reporter. More...

virtual IldRequest &	setParamArraySize (IlUInt size)=0
	Turn on the array bind mode. More...

virtual IldRequest &	setParamNullInd (IlUShort col, IlUInt row=0)=0
	Set the null indicator of the parameter. More...

virtual IldRequest &	setParamValue (char value, IlUShort col, IlUInt row=0)=0
	Sets the char value of a parameter. More...

virtual IldRequest &	setParamValue (IlInt value, IlUShort col, IlUInt row=0)=0
	Sets the integer value of a parameter. More...

virtual IldRequest &	setParamValue (double value, IlUShort col, IlUInt row=0)=0
	Sets the floating point value of a parameter. More...

virtual IldRequest &	setParamValue (const char *value, IlUShort col, IlUInt row=0)=0
	Sets the string value of a parameter. More...

virtual IldRequest &	setParamValue (IldBytes &value, IlUShort col, IlUInt row=0)=0
	Sets the binary value of a parameter. More...

virtual IldRequest &	setParamValue (const IldDateTime *value, IlUShort col, IlUInt row=0)=0
	Sets the date time value of a parameter. More...

virtual IldRequest &	setParamValue (const IlNumeric *value, IlUShort col, IlUInt row=0)=0
	Sets the numeric value of a parameter. More...

virtual IldRequest &	setParamValue (const IldADTValue *value, IlUShort col, IlUInt row=0)=0
	Sets a user defined value to a parameter. More...

virtual IldRequest &	setReadOnly (IlBoolean flag=IlTrue)=0
	Set the read-only mode. More...

virtual IldRequest &	setRowPos (IlUInt pos)=0
	Set the fetch index. More...

virtual IldRequest &	setScrollable (IlBoolean flag=IlTrue)=0
	Set the scrollable cursor mode. More...

virtual IldRequest &	startGetLargeObject (const char tableName, const char columnName, const char *whereCond)=0
	Initiate the retrieval of a large object from the database in several pieces. More...

Public Member Functions inherited from IldIldBase
virtual	~IldIldBase ()
	Destructor for the base class of DB Link session and cursor classes. More...

void	clearDiagnostics ()
	Set diagnostic flags to false. More...

virtual const IldDiagnostic *	getError () const =0
	Get the error container. More...

virtual IlInt	getErrorCode () const =0
	Get the error code. More...

virtual const char *	getErrorConnection () const =0
	Get the conneciton string. More...

virtual const char *	getErrorMessage () const =0
	Get the error message text. More...

virtual const char *	getErrorName () const =0
	Get the error object name. More...

virtual IldErrorOrigin	getErrorOrigin () const =0
	Get the error origin. More...

virtual const char *	getErrorSqlstate () const =0
	Get the SQL state. More...

virtual const IldDiagnostic *	getInformation () const =0
	Get the information container. More...

virtual IlInt	getInformationCode () const =0
	Get the information code. More...

virtual const char *	getInformationMessage () const =0
	Get the information message. More...

virtual IlBoolean	isErrorRaised () const =0
	Tell if an error was raised. More...

virtual IlBoolean	isInformationRaised () const =0
	Tell if a warning was raised. More...

virtual int	operator! () const =0
	Tell if an error was raised. More...

virtual void	setError (IldDiagnostic *diag)=0
	Set the diagnostic container provided as the error container. More...

virtual void	setInformation (IldDiagnostic *)=0
	Set the diagnostic container provided as the warning container. More...

virtual void	setNumericUse (IlBoolean flag)=0
	Turn the numeric-as-objects feature ON or OFF. More...

virtual void	setStringDateUse (IlBoolean flag=IlTrue)=0
	Turn the date-as-string feature ON or OFF. More...

virtual void	setStringNumericUse (IlBoolean flag=IlTrue)=0
	Turn the number-as-string feature ON or OFF. More...

virtual IlBoolean	useNumeric () const =0
	Tell if numeric data is handled as objects. More...

virtual IlBoolean	useStringDate () const =0
	Tell if date values will be sent and retrieved as strings. More...

virtual IlBoolean	useStringNumeric () const =0
	Tell if numeric are handled as strings. More...

Detailed Description

Instances of this class correspond to the cursors in an RDBMS.

Library: dbkernel

A cursor becomes important when an SQL query of type select is executed, and, likewise, when a stored procedure is called and executed. The results of such a query may be vectors of heterogeneous values; these vectors are called tuples. Your application must explicitly unstack the tuple(s) from the cursor in order to access the data contained in it(them).

The functional interface of IldRequest enables you to:

Communicate with the IldDbms object that actually creates instances of this class.
Execute DML (SQL Data Manipulation Language) statements.
Retrieve data through specialized accessors that act as intermediaries between your application and the RDBMS.
Bind application memory space to the RDBMS API.
Recover gracefully from errors.

Every time your application executes an SQL DML command, it uses one of these IldRequest objects. Objects of this class are created using an instance of the class IldDbms. Since a given IldRequest object is created using a particular IldDbms object, we say that the instance of IldRequest depends on the instance of IldDbms. We also say that the IldDbms object refers to the IldRequest objects that it creates. The maximum number of IldRequest objects that can be created by an IldDbms object depends on the RDBMS.

In this class, member functions with Col in their name deal with output or results set columns. Likewise, member functions with Param in their name deal with input parameters.

Note: As most RDBMSs do not have the "describe input" capability, the input parameter functions, in most cases, do not really allow you to retrieve parameter descriptor attributes before the parameter is bound.

Warning: Accessing the value of a NULL column yields undefined results and an error is raised.

See Also: IldADTValue, IldColumnType, IldDateTime, IldErrorReporter, IlNumeric, "Array Fetch", "Extending the IldRequest Class", and "Array Bind" in the Rogue Wave DB Link User's Manual.

Constructor & Destructor Documentation

virtual IldRequest::~IldRequest ( )

virtual

This virtual destructor is invoked when an instance of IldRequest is destroyed.

As a user, you do not need to call this destructor. In most cases, you should use the member function IldRequest::release instead.

However, applications can explicitly delete an IldRequest object because, when this destructor is called, the current IldDbms object is notified.

Member Function Documentation

virtual IldRequest& IldRequest::bindCol	(	IlUShort	index,
		IldColumnType	type,
		IlAny	buffer,
		IlUInt	size = `0`,
		short *	indicators = `0`
	)

pure virtual

Set or change a result set column description according to its arguments.

Parameters

index	The column index in the result set.
type	The column type.
buffer	The application allocated buffer.
size	The buffer size.
indicators	The null indicators.

Returns: The current object by reference.

The column type, in the DB Link sense, is indicated by type. The place to store a value coming from the RDBMS is indicated by buffer. The parameter size passes the size of one element. If the feature array fetch is on, buffer must be allocated for the value of getColArraySize elements of size bytes. If that argument is not given, DB Link assumes that buffer is large enough to hold the result, whatever its size. The argument indicators is a pointer to a short (or to an array of short if array fetch mode is on) where the null indicator will be fetched.

This function can raise the following errors:

ILD_BAD_VARIABLE_SIZE
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::bindCol	(	const char *	columnName,
		IldColumnType	type,
		IlAny	buffer,
		IlUInt	size = `0`,
		short *	indicators = `0`
	)

pure virtual

Set or change the column description of a column in the result set.

Parameters

columnName	The name of the column.
type	The column type.
buffer	The application allocated buffer to store the returned data.
size	The buffer size.
indicators	The null indicator.

Returns: The current object by reference.

This member function is equivalent to the previous one, except that it identifies the column by its name instead of its position within the results set.

The name of the column is indicated by columnName. It is used to retrieve the column index in the result set.

Warning: DB Link is case-sensitive in columnName. Some RDBMSs are also case-sensitive, whereas others recognize only uppercase characters.

The type of the column, in the DB Link sense, is indicated by the type parameter. The place to store a value coming from the RDBMS is indicated by buffer. The argument size is the size of one element. If the feature array fetch is on, buffer must be allocated for getColArraySize elements of size bytes.

If the size argument is not provided, DB Link assumes that buffer is large enough to hold the result, whatever its size. The argument indicators is a pointer to a short (or to an array of short if array fetch mode is on) where the null indicator will be fetched.

This function can raise the following errors:

ILD_BAD_COLUMN_NAME
ILD_BAD_VARIABLE_SIZE
ILD_TYPE_MISMATCH
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::bindParam	(	IlUShort	index,
		IldColumnType	type,
		IlInt	size = `-1`,
		IlAny	buffer = `0`,
		short *	indicators = `0`,
		IlBoolean	out = `IlFalse`,
		IlUShort	arrSize = `0`,
		IldADTDescriptor *	adt = `0`
	)

pure virtual

Sets the descriptor (in the sense of the SQL statement describe) of an input variable for the current query.

Parameters

index	The parameter number.
type	The data type of the parameter.
size	Optionally, the size of the `buffer` parameter (if supplied) or the amount to reserve in DB Link internal buffers.
buffer	Optionally, the address of the memory allocated by your application.
indicators	Optionally, the address of an array of `short` values.
out	Optionally, indicates that the variable has an output status. It is set to `IlTrue` if the database server returns a value for that parameter, or `IlFalse` (default value) otherwise. This parameter is used only in Sybase and ODBC ports.
arrSize	Optionally, the number of elements in the array that holds the parameter values. This argument is to be used in Oracle ports when the parsed query is a PL/SQL block containing array parameters. This is used in the case of a stored procedure call, for instance.
adt	Optionally, required for ORDBMS if the parameter type is either `IldCollectionType` or `IldObjectType`. With these types of parameters, the argument must be the abstract type descriptor corresponding to the actual type in the database.

Returns: The current object by reference.

Note: The ORDBMSs currently supported are Oracle and Informix Universal Server. IBM DB2 is also an ORDBMS, but it does not provide the API to handle objects in DB Link, so abstract data type handling is not supported with IBM DB2.

This function can raise the following errors:

ILD_BAD_VARIABLE_SIZE
ILD_MEMORY_EXHAUSTED
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
Any error detected by the RBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::bindParam	(	const char *	varName,
		IldColumnType	type,
		IlInt	size = `-1`,
		IlAny	buffer = `0`,
		short *	indicators = `0`,
		IlBoolean	out = `IlFalse`,
		IlUShort	arrSize = `0`,
		IldADTDescriptor *	adt = `0`
	)

pure virtual

Set the descriptor (in the sense of the SQL statement describe) of an input variable for the current query.

Parameters

varName	The parameter name.
type	The data type of the parameter.
size	Optionally, the size of the `buffer` parameter (if supplied) or the amount to reserve in DB Link internal buffers.
buffer	Optionally, the address of the memory allocated by your application.
indicators	Optionally, the address of an array of `short` values.
out	Optionally, indicates that the variable has an output status. It is set to `IlTrue` if the database server returns a value for that parameter, or `IlFalse` (default value) otherwise. This parameter is used only in Sybase and ODBC ports.
arrSize	Optionally, the number of elements in the array that holds the parameter values. This argument is to be used in Oracle ports when the parsed query is a PL/SQL block containing array parameters. This is used in the case of a stored procedure call, for instance.
adt	Optionally, required for ORDBMS if the parameter type is either `IldCollectionType` or `IldObjectType`. With these types of parameters, the argument must be the abstract type descriptor corresponding to the actual type in the database.

Returns: The current object by reference.

This function can raise the following errors:

ILD_BAD_VARIABLE_SIZE
ILD_MEMORY_EXHAUSTED
ILD_TYPE_MISMATCH
Any error detected by the RBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::closeCursor ( )

pure virtual

Empty the current result set, whether there are still rows to be fetched or not.

Returns: The current object by reference.

By default, DB Link does not close a cursor even after all rows have been fetched.

This member function can raise the following errors:

Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::execute	(	IlInt *	rowCount = `0`,
		IlInt	count = `-1`
	)

pure virtual

Execute a previously parsed query.

Parameters

rowCount	Optionally, on output, contains the number of altered rows.
count	Optionally, in array bind mode, the actual number of parameter rows.

Returns: The current object by reference.

The default value of count is the size of the parameter array. If the given value is greater than the parameter array size, an error ILD_BAD_EXECUTE_COUNT is raised.

See the section "Array Bind" in the Rogue Wave DB Link User's Manual for database-specific details.

When the optional argument rowCount is provided, it will be set to the number of modified rows when the execution succeeds. It is set to 0 (zero) if an error occurs.

It can raise the following errors:

ILD_BAD_EXECUTE_COUNT
ILD_MEMORY_EXHAUSTED
ILD_NOT_IMPLEMENTED which means here that this multiple-execution feature is not available with the current RDBMS.
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::execute	(	const char *	query,
		IlInt *	rowCount = `0`
	)

pure virtual

Directly execute a statement.

Parameters

query	The statement to submit to the RDBMS.
rowCount	Optionally, on output, will contain the number of altered rows.

Returns: The current object by reference.

When the optional argument rowCount is provided, it is set to the number of rows affected by the statement query. This information is useful especially if the query is of type insert, update, or delete.

If the query is null, this function does nothing and does not raise any errors. Otherwise, it can raise the following errors:

ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::fetch ( )

pure virtual

Get the next batch of rows from the result set.

Returns: The current object by reference.

When the result set selected by the most recent select command has been exhausted, this function has no effect. A call to this function must be followed by a call to the predicate hasTuple(), which indicates whether a row has actually been brought into the current object.

See the section "Array Fetch" in the Rogue Wave DB Link User's Manual for details on using this function.

This function can raise the following errors:

ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::fetchScroll	(	IlInt	fetchOrientation = `IldFetchDirectionNext`,
		IlInt	fetchOffset = `0`
	)

pure virtual

Fetch the data using scroll mode.

Parameters

fetchOrientation	The direction to move in into the result set.
fetchOffset	The offest from the begining of the result set.

Returns: The current object by reference.

fetchOrientation can only be one of:

IldFetchDirectionNext: fetch next record (equivalent to IldRequest::fetch),
IldFetchDirectionFirst: fetch the first row of the results set,
IldFetchDirectionLast: fetch the last row,
IldFetchDirectionPrior: fetch previous row,
IldFetchDirectionAbsolute: fetch from position fetchOffset
IldFetchDirectionRelative: fetch from position fetchOffset relative to the current position.

To use a fetchOrientation different from IldFetchDirectionNext, you must first activate the scrollable cursor mode by calling IldRequest::setScrollable(IlTrue).

This function can raise the following errors:

ILD_MEMORY_EXHAUSTED
ILD_NOT_SCROLL_MODE
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldADTValue* IldRequest::getColADTValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a user defined type column value as an object.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: An instance of IldADTValue.

This function is supported only for database management systems that have object capabilities. An IldADTValue object is a generic container for values of object and collection types.

Warning: Only Oracle and Informix drivers do support abstract datatypes. For any other driver, this function will raise the error ILD_NOT_IMPLEMENTED

This function can raise the following errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the ORDBMS itself.

In case of error, the value returned by this function is null.

Implemented in IldRequestModel.

virtual IlUInt IldRequest::getColArraySize ( ) const

pure virtual

Tell the size of the fetch array.

Returns: The number of rows that will be fetched at a time by a call to the function fetch.

Implemented in IldRequestModel.

virtual IldBytes IldRequest::getColBinaryValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a binary column value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: A large binary value.

Warning: The amount of memory that DB Link allocates internally for a large binary value is limited to 64 kilobytes.

This function can raise the following errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlUChar IldRequest::getColByteValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a byte column value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: The value in the form of an IlUChar.

That byte represents the value located at the position indicated by col and row in the current result set.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlUShort IldRequest::getColCount ( ) const

pure virtual

Find the number of columns in the result set.

Returns: The size (in number of columns) of the current result set activated by the function fetch for the current object.

Since this number corresponds to the number of items selected, this size will vary from one SQL select query to another. The return value is not meaningful if the current request is not an SQL select query.

Implemented in IldRequestModel.

virtual IldDateTime IldRequest::getColDateTimeValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a date time column value as an object.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: An instance of IldDateTime.

This object represents the value located at the position indicated by col and row in the current result set.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

In case of error, the values in the data members of the object returned by this function are not meaningful.

Implemented in IldRequestModel.

virtual IldDateTime IldRequest::getColDateTimeValue ( const unsigned char * b )

pure virtual

Make an instance of IldDateTime from the string form.

Parameters

b	The date time value in string form.

Returns: An instance of IldDateTime.

This member function is useful when you have allocated a buffer but you need DB Link to translate the contents of buffer. The argument buffer must be the address you passed to the member function IldRequest::bindCol.

This function can raise the errors:

ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getColDateValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a date column value as a string.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: A constant character string representing the value located at the position col and row in the current tuple.

Your application should copy this string because the current object modifies the string during the execution of the member function IldRequest::fetch. It deallocates the string when the current object itself is destroyed.

DB Link does not use a specific date format. The format used is the one set by the user at the session level or the RDBMS default format.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this member function is not meaningful.

Implemented in IldRequestModel.

virtual IldAppDescriptor* IldRequest::getColDescriptor ( IlUShort col )

pure virtual

Get the descriptor of a column from the result set.

Parameters

col	The column index.

Returns: The application row descriptor of column col from the current result set.

This function can raise the error:

ILD_OUT_OF_RANGE

In case of error, a null pointer is returned.

Implemented in IldRequestModel.

virtual short IldRequest::getColIndex ( const char * colName )

pure virtual

Find the index of a named column from the result set.

Parameters

colName The column name.

Returns: The column index.

This function accepts the name of a column and returns its index in the current results set.

If no column called colName exists, this member function returns -1.

Warning: Some RDBMSs allow only uppercase characters in column names, while others are case-sensitive, allowing both upper and lowercase characters. You can check which applies by querying the server using the IldDbms::getInfo function with type set to IldIdentifierCase.

This function can raise the error:

ILD_BAD_COLUMN_NAME

Implemented in IldRequestModel.

virtual IlInt IldRequest::getColIntegerValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get an integer column value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: A long integer in the form of IlInt.

That integer represents the value located at the position indicated by col and row in the current results set.

Warning: If the actual column type is IldRealType, the value will be cast to IlInt regardless of a possible overflow.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this member function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getColLongTextValue	(	IlUShort	col,
		IlUInt	row = `0`,
		IlInt *	size = `0`
	)

pure virtual

Get a long text column value.

Parameters

col	The column index.
row	Optionally, the row index.
size	Optionally, the maximum size to retrieve.

Returns: A string of a large piece of text located at the position indicated by col and row into memory.

Warning: The amount of memory that DB Link allocates internally for a large text value is limited to 64 kilobytes.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual double IldRequest::getColMoneyValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a money column value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: A double precision floating-point number.

That number represents the value located at the position indicated by col and row in the current result set.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this member function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getColName ( IlUShort index )

pure virtual

Find the name of a column form the result set.

Parameters

index The column index.

Returns: The name of the column located at the position indicated by index in the current results set.

Your application should copy this character string because the current object modifies the string during execution of an SQL select query and deallocates the string when the current object itself is destroyed.

This function can raise the error:

ILD_OUT_OF_RANGE

In case of error, a null pointer is returned.

Implemented in IldRequestModel.

virtual IlNumeric IldRequest::getColNumericValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a numeric column value as an object.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: An instance of the IlNumeric class.

This object represents the value located at the position indicated by col and row in the current result set.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

In case of error, the values in the data members of the object returned by this function are not meaningful.

Implemented in IldRequestModel.

virtual double IldRequest::getColRealValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a floating point column value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: A double precision floating-point number.

That number represents the value located at the position indicated by col and row in the current result set.

Warning: If the actual type of the column is IldIntegerType, the value will be cast to a double.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this member function is not meaningful.

Implemented in IldRequestModel.

virtual IldBytes IldRequest::getColRefValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a reference column value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: An IldBytes structure that contains the binary representation of the reference value.

This function is supported only for database management systems that have object capabilities.

Warning: Only Oracle and Informix drivers do support abstract datatypes. For any other driver, this function will raise the error ILD_NOT_IMPLEMENTED

This function can raise the following errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the ORBMS itself.

In case of error, the value returned by this function is an empty structure.

Implemented in IldRequestModel.

virtual const char* IldRequest::getColRTrimedStringValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a string column value trimed from balnks on the right.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: A character string that represents the value located at the position indicated in the current result set by col and row, with trailing blanks trimmed.

This member function is similar to the function getColStringValue except that it removes trailing blanks at the end of the string.

The string is right-trimmed. In other words, this function physically modifies the string returned by the function getColStringValue

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlUInt IldRequest::getColSize ( IlUShort index ) const

pure virtual

Find the size of a column from the result set.

Parameters

index The column index.

Returns: The size (in number of bytes) of the column located at the position indicated by index in the current result set.

This information is useful for formatting values in fields of character-string types.

This function can raise the error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this member function is not meaningful.

Implemented in IldRequestModel.

virtual short IldRequest::getColSQLType ( IlUShort index ) const

pure virtual

Find the SQL type code of a column from the result set.

Parameters

index The column index.

Returns: The type code of the given column.

This type code will be one of the SQL CLI-compliant values listed in section Enumeration values of the file ildconst.h.

This function can raise the error:

ILD_OUT_OF_RANGE

Implemented in IldRequestModel.

virtual const char* IldRequest::getColSQLTypeName ( IlUShort index ) const

pure virtual

Find the SQL type name of a column from the result set.

Parameters

index The column index.

Returns: The SQL type name of column at position index.

This name depends on the target RDBMS.

This function can raise the error:

ILD_OUT_OF_RANGE

Implemented in IldRequestModel.

virtual const char* IldRequest::getColStringValue	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Get a string column value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: A character string that represents the value located at the position indicated in the current result set by col and row.

The application should copy this character string because the current object modifies the string during execution of an SQL select command, and deallocates the string when the current object itself is destroyed.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IldColumnType IldRequest::getColType ( IlUShort index ) const

pure virtual

Find the type of column from the result set.

Parameters

index The column index.

Returns: The type of the column located at the position indicated by index in the current results set.

This member function returns one of the values from the enumeration IldColumnType. When you do not know the type of values in the current tuple beforehand, this function is useful for selecting the appropriate accessor to retrieve those values.

Accordingly, if the function getColType returns IldStringType for the value of a given position in the current result set, you can use the function getColStringValue for this position in a row of the result set. If any other accessor is used (for example, if the function getColRealValue was used inadvertently), DB Link raises the error ILD_TYPE_MISMATCH.

This function can raise the error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this member function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getCursorName ( ) const

pure virtual

Get the name of the cursor.

Returns: The current name of the cursor.

Most RDBMSs require the cursors to be named. However, some do not and in that case, an empty string is returned.

Implemented in IldRequestModel.

virtual IldDbms& IldRequest::getDbms ( ) const

pure virtual

Get the attached to IldDbms object.

Returns: A reference to the IldDbms object on which the invoking object depends.

Implemented in IldRequestModel.

virtual IldErrorReporter* IldRequest::getErrorReporter ( ) const

pure virtual

Find the current user error reporter.

Returns: The error reporter currently set by the application. If none has been set, it returns the null pointer.

Warning: The default reporter is hidden. An application will never obtain its address.

Implements IldIldBase.

Implemented in IldRequestModel.

virtual IlAny IldRequest::getHook ( ) const

pure virtual

Get the statement hook.

Returns: The hook for the cursor into the current RDBMS.

The structure of this hook varies according to the RDBMS. As a consequence, an appropriate cast must be applied before using it. See the section "Extending the IldRequest Class" in the Rogue Wave DB Link User's Manual for details about this cast.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::getLargeObject	(	const char *	tableName,
		const char *	columnName,
		const char *	whereCond,
		const char *	fileName
	)

pure virtual

Retrieve a large object from the database into a file.

Parameters

tableName	The table to retrieve from.
columnName	The column to retrieve from.
whereCond	The restriction clause.
fileName	The path to the file where to store the returned value.

Returns: The current object by reference.

This member function executes an SQL select command based on the whereCond parameter in the relation indicated by tableName and column indicated by columnName. If that query executes successfully, the function puts the retrieved results into the file indicated by fileName.

There is no limit set by DB Link on the size of the objects that can be retrieved. This function can be used for values of type IldLongTextType, IldBinaryType, IldCLOBType, or IldBLOBType.

The whereCond argument must pass a valid SQL where clause reduced to its predicates (that is, without the keyword where). If the condition does not narrow the selectable rows enough, only the first one will be retrieved.

The parameter fileName must indicate the full path name of the file where DB Link should put the retrieved data.

This function can raise the following errors:

ILD_BAD_FILE
ILD_TYPE_MISMATCH
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::getLargeObjectChunk	(	IlUInt	size,
		IlUChar *	data,
		IlUInt *	offset
	)

pure virtual

Get a chunck from a large object.

Parameters

size	The size of the chunk to retrieve.
data	The place to store the retrieved data in.
offset	Optionally, the offset from the begining of the object to start the retrieval.

Returns: The current object by reference.

This function continues the retrieval initiated by aprevious call to startGetLargeObject.

This member function can be used iteratively. The argument data is the address of a preallocated memory block that you pass to the function to set the memory limitation yourself.

The third argument, offset, is optional. It is used only in RDBMSs that allow a fetch from any offset in a column value. On output, this argument is increased by the total number of bytes read.

This function can be used for values of type IldLongTextType , IldBinaryType, IldCLOBType, or IldBLOBType.

It can raise the following errors:

ILD_NO_MORE_TUPLES
ILD_NOT_IMPLEMENTED
ILD_TYPE_MISMATCH
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldADTValue* IldRequest::getParamADTValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the user defined type value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The parameter value as an instance of IldADTValue.

Warning: This function is supported only for database management systems that have object capabilities. An IldADTValue is a generic container for values of object and collection types.

This function can raise the following errors:

ILD_NOT_IMPLEMENTED
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the ORDBMS itself.

In case of error, the value returned by this function is null.

Implemented in IldRequestModel.

virtual IlUInt IldRequest::getParamArraySize ( ) const

pure virtual

Tell the size of the bind array.

Returns: The number of input rows when the current object is in array bind mode (that is, how many rows will be input at one time).

Implemented in IldRequestModel.

virtual IldBytes IldRequest::getParamBinaryValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the binary value of a parameter.

Parameters

index	The parameter index in the curent set.
row	Optionally, the row index.

Returns: The binary value as an IldBytes structure.

Warning: The amount of memory that DB Link allocates internally for a large binary value is limited to 64 kilobytes.

This function can raise the following errors:

ILD_MEMORY_EXHAUSTED
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

Implemented in IldRequestModel.

virtual IlUInt IldRequest::getParamBufferSize ( IlUShort index ) const

pure virtual

Find the size (in number of bytes) of the buffer that manages input for a parameter.

Parameters

index The parameter index in the current set.

Returns: The parameter buffer size.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlUChar IldRequest::getParamByteValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the byte value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index of the parameter value.

Returns: The value of the parameter as a byte.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlUShort IldRequest::getParamCount ( ) const

pure virtual

Get the number of columns in the parameter set.

Returns: The number of parameters in the current parameter set.

Since this number corresponds to the number of parameters in the prepared query, it varies from one SQL statement to another. The return value is not meaningful if the current request has not been prepared.

Implemented in IldRequestModel.

virtual IldRequest* IldRequest::getParamCursorValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the cursor value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The parameter value as a fetch-ready IldRequest object.

This function is only supported by the Oracle drivers. With any other driver, it will raise the error ILD_NOT_IMPLEMENTED.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

In case of error, the value returned by this function is an empty structure.

Implemented in IldRequestModel.

virtual IldDateTime IldRequest::getParamDateTimeValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the date time value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The parameter value as an instance of the class IldDateTime.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

In case of error, the values in the data members of the object returned by this function are not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getParamDateValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the date value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The parameter date value as a character string.

Unless the parameter was bound to an application-allocated memory space, the application should copy this string because the current object modifies the string during the execution of the member function execute. It deallocates the string when the current object itself is released.

Note: The format of the value depends on the current locale.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IldAppDescriptor* IldRequest::getParamDescriptor ( IlUShort index )

pure virtual

Get a parameter descriptor.

Parameters

index The parameter index.

Returns: The application parameter descriptor of parameter.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, a null pointer is returned.

Implemented in IldRequestModel.

virtual short IldRequest::getParamIndex ( const char * varName )

pure virtual

Get the index of a parameter from its name.

Parameters

varName The parameter name.

Returns: The parameter index in the current parameter set.

If no parameter with the name varName exists, this function returns -1.

This function can raise the following error:

ILD_BAD_COLUMN_NAME

Implemented in IldRequestModel.

virtual IlInt IldRequest::getParamIntegerValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the integer value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The parameter value as an IlInt.

This integer represents the value located at the position indicated by index and row in the current parameter set.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getParamLongTextValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the text value of a parameter.

index The parameter index in the current set. Optionally, the row index.

Returns: The text value of the parameter.

Warning: The amount of memory that DB Link allocates internally for a large text value is limited to 64 kilobytes.

This function can raise the following errors:

ILD_MEMORY_EXHAUSTED
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

Implemented in IldRequestModel.

virtual double IldRequest::getParamMoneyValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the floating point value of a parameter.

Parameters

index	The parameter index in the curent set.
row	Optionally, the row index for the parameter value.

Returns: A double precision number that represents the value located at the position indicated by index and row in the current parameter set.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getParamName ( IlUShort index )

pure virtual

Find the name of a parameter.

Parameters

index The parameter index

Returns: The parameter name or null.

Your application should copy this character string because the current object modifies the string during execution of other SQL commands and deallocates the string when the current object itself is destroyed.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, this function returns a null pointer.

Implemented in IldRequestModel.

virtual IlNumeric IldRequest::getParamNumericValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the numeric value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: An instance of the class IlNumeric representing the value of the parameter.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the RDBMS itself.

In case of error, the values in the data members of the object returned by this function are not meaningful.

Implemented in IldRequestModel.

virtual double IldRequest::getParamRealValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the floating point value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The value of the parameter as a double precision number.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IldBytes IldRequest::getParamRefValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the reference value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The parameter value as an IldBytes structure,

Warning: This function is supported only for database management systems that have object capabilities.

This function can raise the following errors:

ILD_NOT_IMPLEMENTED
ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE
Any error detected by the ORDBMS itself.

In case of error, the value returned by this function is an empty structure.

Implemented in IldRequestModel.

virtual IlUInt IldRequest::getParamSize ( IlUShort index ) const

pure virtual

Find the size (in number of bytes) of a parameter.

Parameters

index The parameter index in the current input set.

Returns: The parameter value size.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual short IldRequest::getParamSQLType ( IlUShort index ) const

pure virtual

Find the type code of a parameter.

Parameters

index The parameterindex in the current set.

Returns: The parameter type code.

This type code is one of the SQL CLI-compliant values listed in the section Enumeration values of the file ildconst.h.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getParamSQLTypeName ( IlUShort index ) const

pure virtual

Find the SQL type name of a parameter.

Parameters

index The index of the parameter in the current set.

Returns: The SQL type name of the parameter.

This name depends on the target RDBMS.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual const char* IldRequest::getParamStringValue	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Find the string value of a parameter.

Parameters

index	The index of the parameter in the current set.
row	Optionally, the row index.

Returns: The parameter value as a character string.

Unless the parameter data buffer was bound to application-allocated memory space, the application should copy this character string because the current object will modify the string during a further execution of the prepared command. It deallocates the string when the current object itself is destroyed.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
ILD_NULL_VALUE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IldColumnType IldRequest::getParamType ( IlUShort index ) const

pure virtual

Find the type of a parameter.

Parameters

index The parameter index in the current input set.

Returns: One of the values from the enumeration IldColumnType.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlUInt IldRequest::getRowPos ( ) const

pure virtual

Find the index in the fetch array.

Returns: The position of the row currently accessed in the array fetch.

Implemented in IldRequestModel.

virtual IlUInt IldRequest::getRowProcessedCount ( ) const

pure virtual

Tell how many rows where actually fetched at once.

Returns: The number of rows that were actually fetched by the last call to the fetch function.

When the array fetch mode is off, the function returns 1.

Implemented in IldRequestModel.

virtual IlInt IldRequest::getStatus ( ) const

pure virtual

Find the status of the last executed statement.

Returns: The number of rows affected by the most recent SQL statement executed by the current object.

The returned value is the same number as returned in the parameter rowCount by the function IldRequest::execute. The returned value is not meaningful if the most recent SQL command was a DDL (Data Definition Language) command or if an error occurred.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::hasTuple ( ) const

pure virtual

Find if results were retrieved by the last fetch.

Returns: IlTrue if the most recent call to the member function IldRequest::fetch retrieved at least one row. Otherwise, it returns IlFalse.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::insertBinary	(	IldBytes &	binaryData,
		const char *	tableName,
		const char *	columnName,
		const char *	where = `0`
	)

pure virtual

Update an existing record of a table, to store a long binary value.

Parameters

binaryData	A structure holding the binary data and its length.
tableName	The table to update.
columnName	The column to update.
where	The restriction clause reduced to its predicates (that is, without the keyword `where`).

Returns: The current object by reference.

The argument binaryData is a structure holding both the data and its length. The existing contents of the column are replaced by binaryData.

This function can raise the following errors:

ILD_NOT_IMPLEMENTED
Any error detected by the RDBMS itself.

Warning: The actual data type of the column is not checked by DB Link. It is the application's responsibility to make sure that the column has the proper type depending on the target RDBMS.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::insertLongText	(	const char *	text,
		IlUInt	textSize,
		const char *	tableName,
		const char *	columnName,
		const char *	where = `0`
	)

pure virtual

Update an existing record of a table, to store a long text value.

Parameters

text	The value to push to update the row located.
textSize	The length of the text value in bytes.
tableName	The name of the relation.
columnName	The column to place the value into.
where	The restriction clause without the keyword `where`).

Returns: The current object by reference.

The existing value in the column is replaced by the contents of the text argument.

This function can raise the following errors:

ILD_NOT_IMPLEMENTED
Any error detected by the RDBMS itself.

Warning: The actual data type of the column is not checked by DB Link. It is the application's responsibility to make sure that the column has the proper type depending on the target RDBMS.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isColNull	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Check if a column conatins a null value.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: IlTrue if the value located at the position indicated by col and row in the current tuple is null. Otherwise, it returns IlFalse.

This function can raise the errors:

ILD_NO_MORE_TUPLES
ILD_OUT_OF_RANGE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isCompleted ( ) const

pure virtual

Find if a statement related command has completed.

Returns: The completion status of the last query executed asynchronously.

For RDBMSs that do not support asynchronous calls, or when the asynchronous processing mode is turned off, this function returns IlTrue. Otherwise, this function returns IlFalse if the query has not been completed.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isCursorModeOn ( ) const

pure virtual

Find if the request is using cursor mode.

Returns: IlTrue if cursor mode is activated.

For RDBMSs that do not support switching OFF cursors usage, the return value is always IlTrue.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isFree ( )

pure virtual

Tell if the object is free to process statements.

Returns: IlTrue if the invoking object is free to be used to process another statement or IlFalse if it is not the case.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isNullIndicatorOn	(	short *	buffer,
		IlUInt	row = `0`
	)		const

pure virtual

Tell if a parameter null indicator is set.

Parameters

buffer	The parameter null indicator buffer.
row	Optionally, the row index.

Returns: IlTrue if the null indicator represented by buffer at position row is set. It returns IlFalse otherwise.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isParamNull	(	IlUShort	index,
		IlUInt	row = `0`
	)

pure virtual

Tell if a parameter null indicator is set.

Parameters

index	The parameter index in the current set.
row	Optionally, the row index for the parameter.

Returns: IlTrue if the value located at the position indicated by index and row in the current set of parameters is null. Otherwise, it returns IlFalse.

This function can raise the following error:

ILD_OUT_OF_RANGE

In case of error, the value returned by this function is not meaningful.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isReadOnly ( ) const

pure virtual

Find the read-only status of the request.

Returns: The value of the read-only flag.

For RDBMSs that do not support this capability, the return value is always IlFalse.

Implemented in IldRequestModel.

virtual IlBoolean IldRequest::isScrollable ( ) const

pure virtual

Find the current scroll cursor mode status.

Returns: The current state of the scrollable cursor mode.

IlTrue means that scrollable cursor mode is activated. For RDBMSs that do not support this capability, the return value is always IlFalse.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::parse ( const char * query )

pure virtual

Prepare a statement for execution.

Parameters

query The statement to parse.

Returns: The current object by reference.

After calling this function, the query is "described" (in the SQL sense of that term) in the internal tuple structure. This function must be called before the function IldRequest::execute(IlInt*, IlUInt) if the query contains placeholders, that is, input or output parameters. The actions of this function are roughly equivalent to the successive execution of the SQL commands prepare and describe.

It can raise the following errors:

ILD_CANNOT_RESIZE_TUPLE
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_TYPE
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::release ( )

pure virtual

Free the invoking object.

Returns: The current object by reference.

It processes the internal cleanup and calls the RDBMS API functions that are necessary to close any existing result set.

As a user, you should, in most situations, call this member function rather than the destructor of the class. However, because the current IldDbms object still references the newly released object (that is, the IldDbms object still holds a pointer to the IldRequest object), you must explicitly ask to reuse it.

This member function can raise the following errors:

Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::removeColArraySize ( )

pure virtual

Turn off the array fetch mode.

Returns: The current object by reference.

After it has been called, only one row at a time is fetched upon each call to fetch.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::removeParamArraySize ( )

pure virtual

Turn off the array bind mode.

Returns: The current object by reference.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setColArraySize ( IlUInt size )

pure virtual

Turn on the array fetch mode.

Parameters

size	The size of the fetch array.

Returns: The current objet by reference.

The argument size tells DB Link how many rows at most will be fetched at a time when a call to fetch reaches the end of the results previously stored.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setCursorModeOn ( IlBoolean flag = IlTrue )

pure virtual

Activate (or deactivate) cursor use to run select commands.

Parameters

flag	The value to use.

Returns: The current object by reference.

Various RDBMSs can run select commands either as other commands, or by using cursors. Cursors usually provide additional capabilities that are not available otherwise, but they also might be less efficient. Therefore, this function can be used to activate (or deactivate) cursor use. By default, cursor mode is activated.

Warning: With Sybase, when a select command is not executed with a cursor, this select command must be completed (all rows fetched or cancelled) before any other command may be run with the same connection.

This function can raise the error:

ILD_NOT_IMPLEMENTED

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setCursorName ( const char * cursName )

pure virtual

Set the cursor name.

Parameters

cursName The name to use.

Returns: The current object by reference.

If this name is too long for the current RDBMS, a warning is raised, and the registered name is truncated.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setErrorReporter ( IldErrorReporter * rep )

pure virtual

Set the user error reporter.

Returns: The current object by reference.

This reporter will be triggered only if an error or warning is related to the current request object. If there are no other references to the previous error reporter, this function destroys the object when it registers a new one.

This function lets you replace the default reporter created by DB Link by an instance of a subclass of IldErrorReporter defined by your application. When you do so, you must also redefine the virtual functions of the user-defined subclass:

IldErrorReporter::dbmsError,
IldErrorReporter::dblinkError,
and IldErrorReporter::warn.

This function can raise the following error:

ILD_NO_REPORTER

Warning: The IldErrorReporter class includes a reference counter and a reference list that are updated each time an instance is set using this function. If the reference counter drops to 0, the replaced object is deleted. When an error reporter is explicitly deleted, all its references are notified. Deleting a reporter automatically resets its references to the default reporter.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamArraySize ( IlUInt size )

pure virtual

Turn on the array bind mode.

Parameters

size	The size of the bind array.

Returns: The current object by reference.

The argument size indicates to DB Link how many different sets of variable values will be used, at most, when a parsed query is executed (possibly multiple times).

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamNullInd	(	IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Set the null indicator of the parameter.

Parameters

col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

This function can raise the following error:

ILD_OUT_OF_RANGE

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	char	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets the char value of a parameter.

Parameters

value	The value to set.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	IlInt	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets the integer value of a parameter.

Parameters

value	The integer to set the parameter value.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	double	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets the floating point value of a parameter.

Parameters

value	The floating point value to set.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	const char *	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets the string value of a parameter.

Parameters

value	The string value to set.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

DB Link copies value, so you can delete it afterwards.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	IldBytes &	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets the binary value of a parameter.

Parameters

value	The binary structure of the value to set.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

DB Link copies value, so you can delete it afterwards.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	const IldDateTime *	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets the date time value of a parameter.

Parameters

value	The datetime structure of the value to set.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

DB Link copies value, so you can delete it afterwards.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	const IlNumeric *	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets the numeric value of a parameter.

Parameters

value	The numeric structure of the value to set.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

DB Link copies value, so you can delete it afterwards.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setParamValue	(	const IldADTValue *	value,
		IlUShort	col,
		IlUInt	row = `0`
	)

pure virtual

Sets a user defined value to a parameter.

Parameters

value	The user defined type object containing the value to set.
col	The column index.
row	Optionally, the row index.

Returns: The current object by reference.

DB Link copies value, so you can delete it afterwards. This function is supported only for database management systems with object capabilities.

This function can raise the following errors:

ILD_OUT_OF_RANGE
ILD_TYPE_MISMATCH
Any error detected by the object-relational database management system itself.

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setReadOnly ( IlBoolean flag = IlTrue )

pure virtual

Set the read-only mode.

Parameters

flag	The value for the request flag if the target RDBMS supports that feature.

Returns: The current object by reference.

This function can raise the error:

ILD_NOT_IMPLEMENTED

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setRowPos ( IlUInt pos )

pure virtual

Set the fetch index.

Returns: The current object by reference.

This function moves the currently accessed row in the fetch array to the pos ^th position.

This function can raise the error:

ILD_OUT_OF_RANGE

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::setScrollable ( IlBoolean flag = IlTrue )

pure virtual

Set the scrollable cursor mode.

Parameters

flag	Activates or deactivates the scrollable cursor mode.

Returns: The current object by reference.

By default, scrollable cursor mode is not activated for the following reasons:

It requires additional resources.
It may imply some restrictions on the request that may be run: for example, with Informix, a scrollable cursor cannot fetch a TEXT or BYTE column.

This function can raise the error:

ILD_NOT_IMPLEMENTED

Implemented in IldRequestModel.

virtual IldRequest& IldRequest::startGetLargeObject	(	const char *	tableName,
		const char *	columnName,
		const char *	whereCond
	)

pure virtual

Initiate the retrieval of a large object from the database in several pieces.

Parameters

tableName	The table to retrieve from.
columnName	The column to retrieve from.
whereCond	The restriction clause.

Returns: The current object by reference.

This member function executes an SQL select query based on the parameters whereCond, tableName, and columnName to initiate the retrieval of the large object by chunks from memory. After initiating the retrieval with this function, you must use the member function getLargeObjectChunk iteratively to complete the retrieval.

This function can be used for values of type IldLongTextType , IldBinaryType, or IldBLOBType.

It can raise the following errors:

ILD_NO_MORE_TUPLES
ILD_NOT_IMPLEMENTED
ILD_TYPE_MISMATCH
Any error detected by the RDBMS itself.

Implemented in IldRequestModel.

Rogue Wave DBLink API Reference Guide

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation