GDAL

Public Types | Public Member Functions | Static Public Member Functions | List of all members
CPLODBCStatement Class Reference

Abstraction for statement, and resultset. More...

`#include <cpl_odbc.h>`

## Public Types
enum | Flag { RetrieveNumericColumnsAsDouble = 1 << 0 }
| Flags which control ODBC statement behavior. More...

## Public Member Functions
| CPLODBCStatement (CPLODBCSession *, int flags=0)
| Constructor.
| ~CPLODBCStatement ()
| Destructor.
HSTMT | GetStatement ()
| Return statement handle.
int | Flags () const
| Returns statement flags.
void | Clear ()
| Clear internal command text and result set definitions.
void | AppendEscaped (const char *)
| Append text to internal command.
void | Append (const char *)
| Append text to internal command.
void | Append (const std::string &)
| Append text to internal command.
void | Append (int)
| Append to internal command.
void | Append (double)
| Append to internal command.
int | Appendf (const char *,...)
| Append to internal command.
const char * | GetCommand ()
| Return statement string.
int | ExecuteSQL (const char *=nullptr)
| Execute an SQL statement.
int | Fetch (int nOrientation=SQL_FETCH_NEXT, int nOffset=0)
| Fetch a new record.
void | ClearColumnData ()
| ClearColumnData.
int | GetColCount ()
| Fetch the resultset column count.
const char * | GetColName (int)
| Fetch a column name.
short | GetColType (int)
| Fetch a column data type.
const char * | GetColTypeName (int)
| Fetch a column data type name.
short | GetColSize (int)
| Fetch the column width.
short | GetColPrecision (int)
| Fetch the column precision.
short | GetColNullable (int)
| Fetch the column nullability.
const char * | GetColColumnDef (int)
| Fetch a column default value.
int | GetColId (const char *) const
| Fetch column index.
const char * | GetColData (int, const char *=nullptr)
| Fetch column data.
const char * | GetColData (const char *, const char *=nullptr)
| Fetch column data.
int | GetColDataLength (int)
| GetColDataLength.
double | GetColDataAsDouble (int) const
| Fetch column data as a double value.
double | GetColDataAsDouble (const char *) const
| Fetch column data as a double value.
int | GetRowCountAffected ()
| GetRowCountAffected.
int | GetColumns (const char *pszTable, const char *pszCatalog=nullptr, const char *pszSchema=nullptr)
| Fetch column definitions for a table.
int | GetPrimaryKeys (const char *pszTable, const char *pszCatalog=nullptr, const char *pszSchema=nullptr)
| Fetch primary keys for a table.
int | GetTables (const char *pszCatalog=nullptr, const char *pszSchema=nullptr)
| Fetch tables in database.
void | DumpResult (FILE *fp, int bShowSchema=FALSE)
| Dump resultset to file.
int | CollectResultsInfo ()
| CollectResultsInfo.

## Static Public Member Functions
static CPLString | GetTypeName (int)
| Get name for SQL column type.
static SQLSMALLINT | GetTypeMapping (SQLSMALLINT)
| Get appropriate C data type for SQL column type.

## Detailed Description

Abstraction for statement, and resultset.

Includes methods for executing an SQL statement, and for accessing the resultset from that statement. Also provides for executing other ODBC requests that produce results sets such as SQLColumns() and SQLTables() requests.

## Member Enumeration Documentation

## ◆ Flag

enum CPLODBCStatement::Flag

Flags which control ODBC statement behavior.

Enumerator
RetrieveNumericColumnsAsDouble | Numeric column values should be retrieved as doubles, using either the SQL_C_DOUBLE or SQL_C_FLOAT types. By default numeric column values are retrieved as characters. Retrieving as character is the safest behavior, but can risk loss of precision. If set, GetColDataAsDouble should be used for numeric columns instead of GetColData. Warning: this flag can expose issues in particular ODBC drivers on different platforms. Use with caution.

## Constructor & Destructor Documentation

## ◆ CPLODBCStatement()

CPLODBCStatement::CPLODBCStatement | ( | CPLODBCSession * | poSession,
|  | int | flags = `0`
| ) |  |
| explicit

Constructor.

The optional flags argument can be used to specify flags which control the behavior of the statement.

## Member Function Documentation

## ◆ Append() [1/4]

void CPLODBCStatement::Append | ( | const char * | pszText | ) |

Append text to internal command.

The passed text is appended to the internal SQL command text.

Parameters

  pszText | text to append.

## ◆ Append() [2/4]

void CPLODBCStatement::Append | ( | const std::string & | s | ) |

Append text to internal command.

The passed text is appended to the internal SQL command text.

Parameters

  s | text to append.

## ◆ Append() [3/4]

void CPLODBCStatement::Append | ( | double | dfValue | ) |

Append to internal command.

The passed value is formatted and appended to the internal SQL command text.

Parameters

  dfValue | value to append to the command.

## ◆ Append() [4/4]

void CPLODBCStatement::Append | ( | int | nValue | ) |

Append to internal command.

The passed value is formatted and appended to the internal SQL command text.

Parameters

  nValue | value to append to the command.

## ◆ AppendEscaped()

void CPLODBCStatement::AppendEscaped | ( | const char * | pszText | ) |

Append text to internal command.

The passed text is appended to the internal SQL command text after escaping any special characters so it can be used as a character string in an SQL statement.

Parameters

  pszText | text to append.

## ◆ Appendf()

int CPLODBCStatement::Appendf | ( | const char * | pszFormat,
|  |  | ...
| ) |  |

Append to internal command.

The passed format is used to format other arguments and the result is appended to the internal command text. Long results may not be formatted properly, and should be appended with the direct Append() methods.

Parameters

  pszFormat | printf() style format string.

Returns
  FALSE if formatting fails due to result being too large.

## ◆ DumpResult()

void CPLODBCStatement::DumpResult | ( | FILE * | fp,
|  | int | bShowSchema = `FALSE`
| ) |  |

Dump resultset to file.

The contents of the current resultset are dumped in a simply formatted form to the provided file. If requested, the schema definition will be written first.

Parameters

  fp | the file to write to. stdout or stderr are acceptable.
  bShowSchema | TRUE to force writing schema information for the rowset before the rowset data itself. Default is FALSE.

## ◆ ExecuteSQL()

int CPLODBCStatement::ExecuteSQL | ( | const char * | pszStatement = `nullptr` | ) |

Execute an SQL statement.

This method will execute the passed (or stored) SQL statement, and initialize information about the resultset if there is one. If a NULL statement is passed, the internal stored statement that has been previously set via Append() or Appendf() calls will be used.

Parameters

  pszStatement | the SQL statement to execute, or NULL if the internally saved one should be used.

Returns
  TRUE on success or FALSE if there is an error. Error details can be fetched with OGRODBCSession::GetLastError().

## ◆ Fetch()

int CPLODBCStatement::Fetch | ( | int | nOrientation = `SQL_FETCH_NEXT`,
|  | int | nOffset = `0`
| ) |  |

Fetch a new record.

Requests the next row in the current resultset using the SQLFetchScroll() call. Note that many ODBC drivers only support the default forward fetching one record at a time. Only SQL_FETCH_NEXT (the default) should be considered reliable on all drivers.

Currently it isn't clear how to determine whether an error or a normal out of data condition has occurred if Fetch() fails.

Parameters

  nOrientation | One of SQL_FETCH_NEXT, SQL_FETCH_LAST, SQL_FETCH_PRIOR, SQL_FETCH_ABSOLUTE, or SQL_FETCH_RELATIVE (default is SQL_FETCH_NEXT).
  nOffset | the offset (number of records), ignored for some orientations.

Returns
  TRUE if a new row is successfully fetched, or FALSE if not.

## ◆ GetColColumnDef()

const char * CPLODBCStatement::GetColColumnDef | ( | int | iCol | ) |

Fetch a column default value.

Returns the default value of a column.

Parameters

  iCol | the zero based column index.

Returns
  NULL if the default value is not specified or the internal copy of the default value.

## ◆ GetColCount()

int CPLODBCStatement::GetColCount | ( |  | ) |

Fetch the resultset column count.

Returns
  the column count, or zero if there is no resultset.

## ◆ GetColData() [1/2]

const char * CPLODBCStatement::GetColData | ( | const char * | pszColName,
|  | const char * | pszDefault = `nullptr`
| ) |  |

Fetch column data.

Fetches the data contents of the requested column for the currently loaded row. The result is returned as a string regardless of the column type. NULL is returned if an illegal column is given, or if the actual column is "NULL".

Parameters

  pszColName | the name of the column requested.
  pszDefault | the value to return if the column does not exist, or is NULL. Defaults to NULL.

Returns
  pointer to internal column data or NULL on failure.

## ◆ GetColData() [2/2]

const char * CPLODBCStatement::GetColData | ( | int | iCol,
|  | const char * | pszDefault = `nullptr`
| ) |  |

Fetch column data.

Fetches the data contents of the requested column for the currently loaded row. The result is returned as a string regardless of the column type. NULL is returned if an illegal column is given, or if the actual column is "NULL".

Parameters

  iCol | the zero based column to fetch.
  pszDefault | the value to return if the column does not exist, or is NULL. Defaults to NULL.

Returns
  pointer to internal column data or NULL on failure.

## ◆ GetColDataAsDouble() [1/2]

double CPLODBCStatement::GetColDataAsDouble | ( | const char * | pszColName | ) | const

Fetch column data as a double value.

Fetches the data contents of the requested column for the currently loaded row as a double value.

Returns NaN if a non-numeric column is requested or the actual column value is "NULL".

Warning
  this method can only be used if the Flag::RetrieveNumericColumnsAsDouble flag was set for the CPLODBCStatement.

Parameters

  pszColName | the name of the column requested.

Returns
  numeric column value or NaN on failure.

## ◆ GetColDataAsDouble() [2/2]

double CPLODBCStatement::GetColDataAsDouble | ( | int | iCol | ) | const

Fetch column data as a double value.

Fetches the data contents of the requested column for the currently loaded row as a double value.

Returns NaN if a non-numeric column is requested or the actual column value is "NULL".

Warning
  this method can only be used if the Flag::RetrieveNumericColumnsAsDouble flag was set for the CPLODBCStatement.

Parameters

  iCol | the zero based column to fetch.

Returns
  numeric column value or NaN on failure.

## ◆ GetColId()

int CPLODBCStatement::GetColId | ( | const char * | pszColName | ) | const

Fetch column index.

Gets the column index corresponding with the passed name. The name comparisons are case insensitive.

Parameters

  pszColName | the name to search for.

Returns
  the column index, or -1 if not found.

## ◆ GetColName()

const char * CPLODBCStatement::GetColName | ( | int | iCol | ) |

Fetch a column name.

Parameters

  iCol | the zero based column index.

Returns
  NULL on failure (out of bounds column), or a pointer to an internal copy of the column name.

## ◆ GetColNullable()

short CPLODBCStatement::GetColNullable | ( | int | iCol | ) |

Fetch the column nullability.

Parameters

  iCol | the zero based column index.

Returns
  TRUE if the column may contains or FALSE otherwise.

## ◆ GetColPrecision()

short CPLODBCStatement::GetColPrecision | ( | int | iCol | ) |

Fetch the column precision.

Parameters

  iCol | the zero based column index.

Returns
  column precision, may be zero or the same as column size for columns to which it does not apply.

## ◆ GetColSize()

short CPLODBCStatement::GetColSize | ( | int | iCol | ) |

Fetch the column width.

Parameters

  iCol | the zero based column index.

Returns
  column width, zero for unknown width columns.

## ◆ GetColType()

short CPLODBCStatement::GetColType | ( | int | iCol | ) |

Fetch a column data type.

The return type code is a an ODBC SQL_ code, one of SQL_UNKNOWN_TYPE, SQL_CHAR, SQL_NUMERIC, SQL_DECIMAL, SQL_INTEGER, SQL_SMALLINT, SQL_FLOAT, SQL_REAL, SQL_DOUBLE, SQL_DATETIME, SQL_VARCHAR, SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMPT.

Parameters

  iCol | the zero based column index.

Returns
  type code or -1 if the column is illegal.

## ◆ GetColTypeName()

const char * CPLODBCStatement::GetColTypeName | ( | int | iCol | ) |

Fetch a column data type name.

Returns data source-dependent data type name; for example, "CHAR", "VARCHAR", "MONEY", "LONG VARBINAR", or "CHAR ( ) FOR BIT DATA".

Parameters

  iCol | the zero based column index.

Returns
  NULL on failure (out of bounds column), or a pointer to an internal copy of the column dat type name.

## ◆ GetColumns()

int CPLODBCStatement::GetColumns | ( | const char * | pszTable,
|  | const char * | pszCatalog = `nullptr`,
|  | const char * | pszSchema = `nullptr`
| ) |  |

Fetch column definitions for a table.

The SQLColumn() method is used to fetch the definitions for the columns of a table (or other queryable object such as a view). The column definitions are digested and used to populate the CPLODBCStatement column definitions essentially as if a "SELECT * FROM tablename" had been done; however, no resultset will be available.

Parameters

  pszTable | the name of the table to query information on. This should not be empty.
  pszCatalog | the catalog to find the table in, use NULL (the default) if no catalog is available.
  pszSchema | the schema to find the table in, use NULL (the default) if no schema is available.

Returns
  TRUE on success or FALSE on failure.

## ◆ GetPrimaryKeys()

int CPLODBCStatement::GetPrimaryKeys | ( | const char * | pszTable,
|  | const char * | pszCatalog = `nullptr`,
|  | const char * | pszSchema = `nullptr`
| ) |  |

Fetch primary keys for a table.

The SQLPrimaryKeys() function is used to fetch a list of fields forming the primary key. The result is returned as a result set matching the SQLPrimaryKeys() function result set. The 4th column in the result set is the column name of the key, and if the result set contains only one record then that single field will be the complete primary key.

Parameters

  pszTable | the name of the table to query information on. This should not be empty.
  pszCatalog | the catalog to find the table in, use NULL (the default) if no catalog is available.
  pszSchema | the schema to find the table in, use NULL (the default) if no schema is available.

Returns
  TRUE on success or FALSE on failure.

## ◆ GetTables()

int CPLODBCStatement::GetTables | ( | const char * | pszCatalog = `nullptr`,
|  | const char * | pszSchema = `nullptr`
| ) |  |

Fetch tables in database.

The SQLTables() function is used to fetch a list tables in the database. The result is returned as a result set matching the SQLTables() function result set. The 3rd column in the result set is the table name. Only tables of type "TABLE" are returned.

Parameters

  pszCatalog | the catalog to find the table in, use NULL (the default) if no catalog is available.
  pszSchema | the schema to find the table in, use NULL (the default) if no schema is available.

Returns
  TRUE on success or FALSE on failure.

## ◆ GetTypeMapping()

SQLSMALLINT CPLODBCStatement::GetTypeMapping | ( | SQLSMALLINT | nTypeCode | ) |
| static

Get appropriate C data type for SQL column type.

Returns a C data type code, corresponding to the indicated SQL data type code (as returned from CPLODBCStatement::GetColType()).

Parameters

  nTypeCode | the SQL_ code, such as SQL_CHAR.

Returns
  data type code. The valid code is always returned. If SQL code is not recognised, SQL_C_BINARY will be returned.

## ◆ GetTypeName()

CPLString CPLODBCStatement::GetTypeName | ( | int | nTypeCode | ) |
| static

Get name for SQL column type.

Returns a string name for the indicated type code (as returned from CPLODBCStatement::GetColType()).

Parameters

  nTypeCode | the SQL_ code, such as SQL_CHAR.

Returns
  internal string, "UNKNOWN" if code not recognised.

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

- cpl_odbc.h
- cpl_odbc.cpp