Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

SQLDBC::SQLDBC_ResultSetMetaData Class Reference

#include <SQLDBC.h>

List of all members.


Detailed Description

A SQLDBC_ResultSetMetaData class can retrieve information used to find out types and properties of the columns in a ResultSet.

Definition at line 598 of file SQLDBC.h.

Public Types

Public Methods


Member Typedef Documentation

typedef enum SQLDBC::SQLDBC_ResultSetMetaData::ColumnNullBehavior SQLDBC::SQLDBC_ResultSetMetaData::ColumnNullBehavior
 


Member Enumeration Documentation

enum SQLDBC::SQLDBC_ResultSetMetaData::ColumnNullBehavior
 

Enumeration values:
columnNoNulls  The column must not be NULL values.
columnNullable  The column allows NULL values.
columnNullableUnknown  It is unknown whether the column allows NULL values.

Definition at line 602 of file SQLDBC.h.


Member Function Documentation

SQLDBC_Int2 SQLDBC::SQLDBC_ResultSetMetaData::getColumnCount  
 

Returns the number of columns in this ResultSet object.

Returns:
The number of columns in this result set.

SQLDBC_Int4 SQLDBC::SQLDBC_ResultSetMetaData::getColumnLength SQLDBC_Int2    column
 

Returns maximum width in characters of the specified column.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
Returns:
The maximum number of bytes allowed as the width for the column values.

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSetMetaData::getColumnName SQLDBC_Int2    column,
char *    buffer,
const SQLDBC_StringEncoding    encoding,
const SQLDBC_Length    bufferSize,
SQLDBC_Length   bufferLength
const
 

Requests the name of the specified column.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
buffer Buffer where the column name should be copied into
encoding Encoding of the column name that is requested.
bufferSize Size in bytes of the buffer.
bufferLength [out] The number of bytes stored in the buffer, not included the number of bytes necessary for the zero-terminator. If the source string exceeds the bufferSize value SQLDBC_DATA_TRUNC is returned and the bufferLength is set to the number of bytes required to store the name without truncation (not included the number of bytes necessary for the zero-terminator).
Returns:
SQLDBC_OK on success, SQLDBC_DATA_TRUNC if the buffer is too small.

SQLDBC_SQLType SQLDBC::SQLDBC_ResultSetMetaData::getColumnType SQLDBC_Int2    column
 

Returns the data type of the specified column.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
Returns:
The Data type of the specified column.

SQLDBC_Int4 SQLDBC::SQLDBC_ResultSetMetaData::getPhysicalLength SQLDBC_Int2    column
 

Returns column's maximum physical width in bytes of the specified columns.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
Returns:
Maximum number of bytes allowed as the physically width of the specified column.

SQLDBC_Int4 SQLDBC::SQLDBC_ResultSetMetaData::getPrecision SQLDBC_Int2    column
 

Returns the maximum number of decimal digits of the specified column.

For number types, getPrecision retrieves the number of decimal digits. For character types, it retrieves the maximum length in characters. For binary types, it retrieves the maximum length in bytes.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
Returns:
The maximum number of decimal digits for the column values.

SQLDBC_Int4 SQLDBC::SQLDBC_ResultSetMetaData::getScale SQLDBC_Int2    column
 

Returns the number of decimal places of the data type of the specified column.

For non-numeric types, the scale is set to zero.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
Returns:
Number of decimal places of the data type of the specified column.

ColumnNullBehavior SQLDBC::SQLDBC_ResultSetMetaData::isNullable SQLDBC_Int2    column
 

Returns whether NULL values are allowed for the specified column values.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
Returns:
Whether NULL values are allowed for the specified column; Possible values are columnNoNulls, columnNullable or columnNullableUnknown

SQLDBC_Bool SQLDBC::SQLDBC_ResultSetMetaData::isWritable SQLDBC_Int2    column
 

Returns whether a write operation is possible on the specified column.

Parameters:
column Index of the column. The first column is number 1, the second is number 2, ...
Returns:
SQLDBC_TRUE if a write operation is possible; SQLDBC_FALSE otherwise


Friends And Related Function Documentation

friend class SQLDBC_PreparedStatement [friend]
 

A class for preparing and executing SQL statements.

A prepared SQL command can be parsed and contain input and output parameters. Parameters are marked with a '?' or ':<name>' tag. All DML commands can be parsed. DDL commands can be parsed, too. However, it is not recommended to do so. Prepared SQL commands increase the performance since they are parsed only once and executed several times. Applications only need to change the content of the bound parameters and execute the command again.

All prepared SQL commands are stored in an internally managed ParseInfo Cache . The ParseInfo Cache shares this information with different prepared SQL statements within the same connection.

The SQL statement may contain ASCII or UCS2 characters and must not zero-terminated. The execute() member function converts it to the adequate code set considering the code of the database. Therefore it is possible to write portable code for UNICODE and non-UNICODE databases.

Note:
To increase the performance, applications must use UCS2 statements for UNICODE databases only.
Example:
Preparation and execution of an SQL statement.
   SQLDBC_PrepareStatement *stmt = conn->createPreparedStatement();
   SQLDBC_Retcode rc = stmt->prepare("SELECT * FROM DUAL");
   if (rc != SQLDBC_OK) {
     // Handle error ...
   }
   rc = stmt->execute();
   if (rc != SQLDBC_OK) {
     // Handle error ...
   }
   

Hints:
  • The application must call createPreparedStatement() to retrieve a prepared SQL statement
  • For parsing the SQL statement, call the prepare() member function,
  • For a single-row execution, use the execute() member function,
  • For mass execution, bind arrays of parameter values, use setBatchSize() to set the row array size to the number of array elements bound, and use the execute() method.
  • Use the isQuery() method to check whether the parsed statement creates a result set upon execution.
  • Use SQLDBC_Statement for a direct execution, since the prepared statement inherits all direct-execution functions from SQLDBC_Statement.
  • The current result set is deleted when
    • A new statement is parsed
    • The statement is re-executed
    • The statement is deleted
Todo:
binding parameter by name

Definition at line 750 of file SQLDBC.h.

friend struct SQLDBC_PreparedStatementStorage [friend]
 

Definition at line 753 of file SQLDBC.h.

friend class SQLDBC_ResultSet [friend]
 

A class for presenting a database result set.

A database result set is generated by executing an SQL statement that queries the database.

Select statements, catalog functions, and some procedures create result sets. For example, the following SQL statement creates a result set containing all the rows and columns of the table DUAL:

SELECT * FROM DUAL

A result set can be empty, which is different from there being no result set at all. For example, the following SQL statement creates an empty result set:

SELECT * FROM DUAL WHERE 1 = 2

An SQLDBC_ResultSet object maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The next() method moves the cursor to the next row, and as it returns SQLDBC_NO_DATA_FOUND when there are no more rows in the SQLDBC_ResultSet object, it can be used in a WHILE loop to iterate the result set.

Example for creating an SQLDBC_ResultSet object:

SQLDBC_Statement *stmt = conn->createStatement ();
stmt->execute ("SELECT * FROM DUAL");
SQLDBC_ResultSet *rs = stmt->getResultSet ();
rs->next();

To reduce the time needed for retrieving the data from the database, the SQLDBC_ResultSet class supports so called block cursors, which can return more than one row at a time. The rows returned by a block cursor are called a 'row set'. The result set is fixed, the rowset is not. It changes position and contents each time a new set of rows is retrieved from the database.

With block cursors, the method setRowSetSize() must be used with a parameter greater than 1.

Navigation within the data represented by the SQLDBC_ResultSet object is possible using of navigation methods like first(), next(), previous(), relative() etc.

When block cursors are used, after applying the navigation methods, the cursor points to the actual row set. For example assuming a result set size of 50 and a rowset size of 10, in the following sequence the block cursor points to the rows indicated:

  • first() : Rows 1 - 10 of the result set
  • next() : Rows 11 - 20 of the result set
  • next() : Rows 21 - 30 of the result set
  • previous() : Rows 11 - 20 of the result set
  • last() : Rows 41 - 50 of the result set

In order to perform operations that operate on a single row only when multiple rows have been fetched, the application must indicate which row is the current row. When a block cursor first returns a row set, the current row is the first row of that row set. To change the current row, the application must call the member function setPos().

The data of a certain column in the current row can be retrieved by calling the method getObject().

Data fetched from the database is passed on to the application in variables that the application has allocated for this purpose. Before fetching the data from the database, the application bind these variables to the columns of the result set. Applications can bind any number of columns of the result set, including binding no columns at all.

Binding of columns is done by calling to the member function bindColumn(). The column binding valid for all rows.

After positioning the cursor through navigation methods, the data from the database is written into the bound column variables by a call to the member function fetch() of the row set of this result set. When block cursors are used, the number of rows actually filled can be determined with the member function getResultCount().

For unbounded columns, data can be written into application variables with getObject(), or - in case of block cursors - by calling setPos() on the rowset and then calling getObject().

Definition at line 751 of file SQLDBC.h.

friend struct SQLDBC_ResultSetStorage [friend]
 

Definition at line 752 of file SQLDBC.h.


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