SQL Relay C++ API: sqlrcursor Class Reference

SQL Relay C++ API

- Main Page
- Classes

- Class List
- Class Members

Public Member Functions | List of all members
sqlrcursor Class Reference

## Public Member Functions
| sqlrcursor (sqlrconnection *sqlrc)
| ~sqlrcursor ()
void | setResultSetBufferSize (uint64_t rows)
uint64_t | getResultSetBufferSize ()
void | dontGetColumnInfo ()
void | getColumnInfo ()
void | mixedCaseColumnNames ()
void | upperCaseColumnNames ()
void | lowerCaseColumnNames ()
void | cacheToFile (const char *filename)
void | setCacheTtl (uint32_t ttl)
const char * | getCacheFileName ()
void | cacheOff ()
bool | getDatabaseList (const char *wild)
bool | getTableList (const char *wild)
bool | getColumnList (const char *table, const char *wild)
bool | sendQuery (const char *query)
bool | sendQuery (const char *query, uint32_t length)
bool | sendFileQuery (const char *path, const char *filename)
void | prepareQuery (const char *query)
void | prepareQuery (const char *query, uint32_t length)
bool | prepareFileQuery (const char *path, const char *filename)
void | substitution (const char *variable, const char *value)
void | substitution (const char *variable, int64_t value)
void | substitution (const char *variable, double value, uint32_t precision, uint32_t scale)
void | substitutions (const char **variables, const char **values)
void | substitutions (const char **variables, const int64_t *values)
void | substitutions (const char **variables, const double *values, const uint32_t *precisions, const uint32_t *scales)
void | inputBind (const char *variable, const char *value)
void | inputBind (const char *variable, const char *value, uint32_t valuelength)
void | inputBind (const char *variable, int64_t value)
void | inputBind (const char *variable, double value, uint32_t precision, uint32_t scale)
void | inputBind (const char *variable, int16_t year, int16_t month, int16_t day, int16_t hour, int16_t minute, int16_t second, int32_t microsecond, const char *tz)
void | inputBindBlob (const char *variable, const char *value, uint32_t size)
void | inputBindClob (const char *variable, const char *value, uint32_t size)
void | inputBinds (const char **variables, const char **values)
void | inputBinds (const char **variables, const int64_t *values)
void | inputBinds (const char **variables, const double *values, const uint32_t *precisions, const uint32_t *scales)
void | defineOutputBindString (const char *variable, uint32_t bufferlength)
void | defineOutputBindInteger (const char *variable)
void | defineOutputBindDouble (const char *variable)
void | defineOutputBindDate (const char *variable)
void | defineOutputBindBlob (const char *variable)
void | defineOutputBindClob (const char *variable)
void | defineOutputBindCursor (const char *variable)
void | clearBinds ()
uint16_t | countBindVariables () const
void | validateBinds ()
bool | validBind (const char *variable)
bool | executeQuery ()
bool | fetchFromBindCursor ()
const char * | getOutputBindString (const char *variable)
int64_t | getOutputBindInteger (const char *variable)
double | getOutputBindDouble (const char *variable)
bool | getOutputBindDate (const char *variable, int16_t *year, int16_t *month, int16_t *day, int16_t *hour, int16_t *minute, int16_t *second, int32_t *microsecond, const char **tz)
const char * | getOutputBindBlob (const char *variable)
const char * | getOutputBindClob (const char *variable)
uint32_t | getOutputBindLength (const char *variable)
sqlrcursor * | getOutputBindCursor (const char *variable)
bool | openCachedResultSet (const char *filename)
uint32_t | colCount ()
uint64_t | rowCount ()
uint64_t | totalRows ()
uint64_t | affectedRows ()
uint64_t | firstRowIndex ()
bool | endOfResultSet ()
const char * | errorMessage ()
int64_t | errorNumber ()
void | getNullsAsEmptyStrings ()
void | getNullsAsNulls ()
const char * | getField (uint64_t row, uint32_t col)
const char * | getField (uint64_t row, const char *col)
int64_t | getFieldAsInteger (uint64_t row, uint32_t col)
int64_t | getFieldAsInteger (uint64_t row, const char *col)
double | getFieldAsDouble (uint64_t row, uint32_t col)
double | getFieldAsDouble (uint64_t row, const char *col)
uint32_t | getFieldLength (uint64_t row, uint32_t col)
uint32_t | getFieldLength (uint64_t row, const char *col)
const char *const * | getRow (uint64_t row)
uint32_t * | getRowLengths (uint64_t row)
const char *const * | getColumnNames ()
const char * | getColumnName (uint32_t col)
const char * | getColumnType (uint32_t col)
const char * | getColumnType (const char *col)
uint32_t | getColumnLength (uint32_t col)
uint32_t | getColumnLength (const char *col)
uint32_t | getColumnPrecision (uint32_t col)
uint32_t | getColumnPrecision (const char *col)
uint32_t | getColumnScale (uint32_t col)
uint32_t | getColumnScale (const char *col)
bool | getColumnIsNullable (uint32_t col)
bool | getColumnIsNullable (const char *col)
bool | getColumnIsPrimaryKey (uint32_t col)
bool | getColumnIsPrimaryKey (const char *col)
bool | getColumnIsUnique (uint32_t col)
bool | getColumnIsUnique (const char *col)
bool | getColumnIsPartOfKey (uint32_t col)
bool | getColumnIsPartOfKey (const char *col)
bool | getColumnIsUnsigned (uint32_t col)
bool | getColumnIsUnsigned (const char *col)
bool | getColumnIsZeroFilled (uint32_t col)
bool | getColumnIsZeroFilled (const char *col)
bool | getColumnIsBinary (uint32_t col)
bool | getColumnIsBinary (const char *col)
bool | getColumnIsAutoIncrement (uint32_t col)
bool | getColumnIsAutoIncrement (const char *col)
uint32_t | getLongest (uint32_t col)
uint32_t | getLongest (const char *col)
void | suspendResultSet ()
uint16_t | getResultSetId ()
bool | resumeResultSet (uint16_t id)
bool | resumeCachedResultSet (uint16_t id, const char *filename)
void | closeResultSet ()

## Constructor & Destructor Documentation

sqlrcursor::sqlrcursor | ( | sqlrconnection * | sqlrc | ) |

Creates a cursor to run queries and fetch result sets using connecton "sqlrc".

sqlrcursor::~sqlrcursor | ( |  | ) |

Destroys the cursor and cleans up all associated result set data.

## Member Function Documentation

uint64_t sqlrcursor::affectedRows | ( |  | ) |

Returns the number of rows that were updated, inserted or deleted by the query. Not all databases support this call. Don't use it for applications which are designed to be portable across databases. 0 is returned by databases which don't support this option.

void sqlrcursor::cacheOff | ( |  | ) |

Sets query caching off.

void sqlrcursor::cacheToFile | ( | const char * | filename | ) |

Sets query caching on. Future queries will be cached to the file "filename".

A default time-to-live of 10 minutes is also set.

Note that once cacheToFile() is called, the result sets of all future queries will be cached to that file until another call to cacheToFile() changes which file to cache to or a call to cacheOff() turns off caching.

void sqlrcursor::clearBinds | ( |  | ) |

Clears all bind variables.

void sqlrcursor::closeResultSet | ( |  | ) |

Closes the current result set, if one is open. Data that has been fetched already is still available but no more data may be fetched. Server side resources for the result set are freed as well.

uint32_t sqlrcursor::colCount | ( |  | ) |

Returns the number of columns in the current result set.

uint16_t sqlrcursor::countBindVariables | ( |  | ) | const

Parses the previously prepared query, counts the number of bind variables defined in it and returns that number.

void sqlrcursor::defineOutputBindBlob | ( | const char * | variable | ) |

Defines a binary lob output bind variable.

void sqlrcursor::defineOutputBindClob | ( | const char * | variable | ) |

Defines a character lob output bind variable.

void sqlrcursor::defineOutputBindCursor | ( | const char * | variable | ) |

Defines a cursor output bind variable.

void sqlrcursor::defineOutputBindDate | ( | const char * | variable | ) |

Defines a date output bind variable.

void sqlrcursor::defineOutputBindDouble | ( | const char * | variable | ) |

Defines a decimal output bind variable.

void sqlrcursor::defineOutputBindInteger | ( | const char * | variable | ) |

Defines an integer output bind variable.

void sqlrcursor::defineOutputBindString | ( | const char * | variable,
|  | uint32_t | bufferlength
| ) |  |

Defines an output bind variable. "bufferlength" bytes will be reserved to store the value.

void sqlrcursor::dontGetColumnInfo | ( |  | ) |

Tells the server not to send any column info (names, types, sizes). If you don't need that info, you should call this method to improve performance.

bool sqlrcursor::endOfResultSet | ( |  | ) |

Returns false if part of the result set is still pending on the server and true if not. This method can only return false if setResultSetBufferSize() has been called with a parameter other than 0.

const char* sqlrcursor::errorMessage | ( |  | ) |

If a query failed and generated an error, the error message is available here. If the query succeeded then this method returns NULL.

int64_t sqlrcursor::errorNumber | ( |  | ) |

If a query failed and generated an error, the error number is available here. If there is no error then this method returns 0.

bool sqlrcursor::executeQuery | ( |  | ) |

Execute the query that was previously prepared and bound.

bool sqlrcursor::fetchFromBindCursor | ( |  | ) |

Fetch from a cursor that was returned as an output bind variable.

uint64_t sqlrcursor::firstRowIndex | ( |  | ) |

Returns the index of the first buffered row. This is useful when buffering only part of the result set at a time.

const char* sqlrcursor::getCacheFileName | ( |  | ) |

Returns the name of the file containing the cached result set.

void sqlrcursor::getColumnInfo | ( |  | ) |

Tells the server to send column info.

bool sqlrcursor::getColumnIsAutoIncrement | ( | uint32_t | col | ) |

Returns true if the specified column auto-increments and false otherwise.

bool sqlrcursor::getColumnIsAutoIncrement | ( | const char * | col | ) |

Returns true if the specified column auto-increments and false otherwise.

bool sqlrcursor::getColumnIsBinary | ( | uint32_t | col | ) |

Returns true if the specified column contains binary data and false otherwise.

bool sqlrcursor::getColumnIsBinary | ( | const char * | col | ) |

Returns true if the specified column contains binary data and false otherwise.

bool sqlrcursor::getColumnIsNullable | ( | uint32_t | col | ) |

Returns true if the specified column can contain nulls and false otherwise.

bool sqlrcursor::getColumnIsNullable | ( | const char * | col | ) |

Returns true if the specified column can contain nulls and false otherwise.

bool sqlrcursor::getColumnIsPartOfKey | ( | uint32_t | col | ) |

Returns true if the specified column is part of a composite key and false otherwise.

bool sqlrcursor::getColumnIsPartOfKey | ( | const char * | col | ) |

Returns true if the specified column is part of a composite key and false otherwise.

bool sqlrcursor::getColumnIsPrimaryKey | ( | uint32_t | col | ) |

Returns true if the specified column is a primary key and false otherwise.

bool sqlrcursor::getColumnIsPrimaryKey | ( | const char * | col | ) |

Returns true if the specified column is a primary key and false otherwise.

bool sqlrcursor::getColumnIsUnique | ( | uint32_t | col | ) |

Returns true if the specified column is unique and false otherwise.

bool sqlrcursor::getColumnIsUnique | ( | const char * | col | ) |

Returns true if the specified column is unique and false otherwise.

bool sqlrcursor::getColumnIsUnsigned | ( | uint32_t | col | ) |

Returns true if the specified column is an unsigned number and false otherwise.

bool sqlrcursor::getColumnIsUnsigned | ( | const char * | col | ) |

Returns true if the specified column is an unsigned number and false otherwise.

bool sqlrcursor::getColumnIsZeroFilled | ( | uint32_t | col | ) |

Returns true if the specified column was created with the zero-fill flag and false otherwise.

bool sqlrcursor::getColumnIsZeroFilled | ( | const char * | col | ) |

Returns true if the specified column was created with the zero-fill flag and false otherwise.

uint32_t sqlrcursor::getColumnLength | ( | uint32_t | col | ) |

Returns the number of bytes required on the server to store the data for the specified column

uint32_t sqlrcursor::getColumnLength | ( | const char * | col | ) |

Returns the number of bytes required on the server to store the data for the specified column

bool sqlrcursor::getColumnList | ( | const char * | table,
|  | const char * | wild
| ) |  |

Sends a query that returns a list of columns in the table specified by the "table" parameter matching "wild". If wild is empty or NULL then a list of all columns will be returned.

const char* sqlrcursor::getColumnName | ( | uint32_t | col | ) |

Returns the name of the specified column.

const char* const* sqlrcursor::getColumnNames | ( |  | ) |

Returns a null terminated array of the column names of the current result set.

uint32_t sqlrcursor::getColumnPrecision | ( | uint32_t | col | ) |

Returns the precision of the specified column. Precision is the total number of digits in a number. eg: 123.45 has a precision of 5. For non-numeric types, it's the number of characters in the string.

uint32_t sqlrcursor::getColumnPrecision | ( | const char * | col | ) |

Returns the precision of the specified column. Precision is the total number of digits in a number. eg: 123.45 has a precision of 5. For non-numeric types, it's the number of characters in the string.

uint32_t sqlrcursor::getColumnScale | ( | uint32_t | col | ) |

Returns the scale of the specified column. Scale is the total number of digits to the right of the decimal point in a number. eg: 123.45 has a scale of 2.

uint32_t sqlrcursor::getColumnScale | ( | const char * | col | ) |

Returns the scale of the specified column. Scale is the total number of digits to the right of the decimal point in a number. eg: 123.45 has a scale of 2.

const char* sqlrcursor::getColumnType | ( | uint32_t | col | ) |

Returns the type of the specified column.

const char* sqlrcursor::getColumnType | ( | const char * | col | ) |

Returns the type of the specified column.

bool sqlrcursor::getDatabaseList | ( | const char * | wild | ) |

Sends a query that returns a list of databases/schemas matching "wild". If wild is empty or NULL then a list of all databases/schemas will be returned.

const char* sqlrcursor::getField | ( | uint64_t | row,
|  | uint32_t | col
| ) |  |

Returns the specified field as a string.

const char* sqlrcursor::getField | ( | uint64_t | row,
|  | const char * | col
| ) |  |

Returns the specified field as a string

double sqlrcursor::getFieldAsDouble | ( | uint64_t | row,
|  | uint32_t | col
| ) |  |

Returns the specified field as a decimal.

double sqlrcursor::getFieldAsDouble | ( | uint64_t | row,
|  | const char * | col
| ) |  |

Returns the specified field as a decimal.

int64_t sqlrcursor::getFieldAsInteger | ( | uint64_t | row,
|  | uint32_t | col
| ) |  |

Returns the specified field as an integer.

int64_t sqlrcursor::getFieldAsInteger | ( | uint64_t | row,
|  | const char * | col
| ) |  |

Returns the specified field as an integer.

uint32_t sqlrcursor::getFieldLength | ( | uint64_t | row,
|  | uint32_t | col
| ) |  |

Returns the length of the specified field.

uint32_t sqlrcursor::getFieldLength | ( | uint64_t | row,
|  | const char * | col
| ) |  |

Returns the length of the specified field.

uint32_t sqlrcursor::getLongest | ( | uint32_t | col | ) |

Returns the length of the longest field in the specified column.

uint32_t sqlrcursor::getLongest | ( | const char * | col | ) |

Returns the length of the longest field in the specified column.

void sqlrcursor::getNullsAsEmptyStrings | ( |  | ) |

Tells the connection to return NULL fields and output bind variables as empty strings. This is the default.

void sqlrcursor::getNullsAsNulls | ( |  | ) |

Tells the connection to return NULL fields and output bind variables as NULL's rather than as empty strings.

const char* sqlrcursor::getOutputBindBlob | ( | const char * | variable | ) |

Get the value stored in a previously defined binary lob output bind variable.

const char* sqlrcursor::getOutputBindClob | ( | const char * | variable | ) |

Get the value stored in a previously defined character lob output bind variable.

sqlrcursor* sqlrcursor::getOutputBindCursor | ( | const char * | variable | ) |

Get the cursor associated with a previously defined output bind variable.

bool sqlrcursor::getOutputBindDate | ( | const char * | variable,
|  | int16_t * | year,
|  | int16_t * | month,
|  | int16_t * | day,
|  | int16_t * | hour,
|  | int16_t * | minute,
|  | int16_t * | second,
|  | int32_t * | microsecond,
|  | const char ** | tz
| ) |  |

Get the value stored in a previously defined date output bind variable.

double sqlrcursor::getOutputBindDouble | ( | const char * | variable | ) |

Get the value stored in a previously defined decimal output bind variable.

int64_t sqlrcursor::getOutputBindInteger | ( | const char * | variable | ) |

Get the value stored in a previously defined integer output bind variable.

uint32_t sqlrcursor::getOutputBindLength | ( | const char * | variable | ) |

Get the length of the value stored in a previously defined output bind variable.

const char* sqlrcursor::getOutputBindString | ( | const char * | variable | ) |

Get the value stored in a previously defined string output bind variable.

uint64_t sqlrcursor::getResultSetBufferSize | ( |  | ) |

Returns the number of result set rows that will be buffered at a time or 0 for the entire result set.

uint16_t sqlrcursor::getResultSetId | ( |  | ) |

Returns the internal ID of this result set. This parameter may be passed to another cursor for use in the resumeResultSet() method. Note: The value this method returns is only valid after a call to suspendResultSet().

const char* const* sqlrcursor::getRow | ( | uint64_t | row | ) |

Returns a null terminated array of the values of the fields in the specified row.

uint32_t* sqlrcursor::getRowLengths | ( | uint64_t | row | ) |

Returns a null terminated array of the lengths of the fields in the specified row.

bool sqlrcursor::getTableList | ( | const char * | wild | ) |

Sends a query that returns a list of tables matching "wild". If wild is empty or NULL then a list of all tables will be returned.

void sqlrcursor::inputBind | ( | const char * | variable,
|  | const char * | value
| ) |  |

Defines a string input bind variable.

void sqlrcursor::inputBind | ( | const char * | variable,
|  | const char * | value,
|  | uint32_t | valuelength
| ) |  |

Defines a string input bind variable.

void sqlrcursor::inputBind | ( | const char * | variable,
|  | int64_t | value
| ) |  |

Defines a integer input bind variable.

void sqlrcursor::inputBind | ( | const char * | variable,
|  | double | value,
|  | uint32_t | precision,
|  | uint32_t | scale
| ) |  |

Defines a decimal input bind variable. (If you don't have the precision and scale then set them both 0. However in that case you may get unexpected rounding behavior if the server is faking binds.)

void sqlrcursor::inputBind | ( | const char * | variable,
|  | int16_t | year,
|  | int16_t | month,
|  | int16_t | day,
|  | int16_t | hour,
|  | int16_t | minute,
|  | int16_t | second,
|  | int32_t | microsecond,
|  | const char * | tz
| ) |  |

Defines a date input bind variable. "day" should be 1-31 and "month" should be 1-12. "tz" may be left NULL. Most databases ignore "tz".

void sqlrcursor::inputBindBlob | ( | const char * | variable,
|  | const char * | value,
|  | uint32_t | size
| ) |  |

Defines a binary lob input bind variable.

void sqlrcursor::inputBindClob | ( | const char * | variable,
|  | const char * | value,
|  | uint32_t | size
| ) |  |

Defines a character lob input bind variable.

void sqlrcursor::inputBinds | ( | const char ** | variables,
|  | const char ** | values
| ) |  |

Defines an array of string input bind variables.

void sqlrcursor::inputBinds | ( | const char ** | variables,
|  | const int64_t * | values
| ) |  |

Defines an array of integer input bind variables.

void sqlrcursor::inputBinds | ( | const char ** | variables,
|  | const double * | values,
|  | const uint32_t * | precisions,
|  | const uint32_t * | scales
| ) |  |

Defines an array of decimal input bind variables.

void sqlrcursor::lowerCaseColumnNames | ( |  | ) |

Columns names are converted to lower case.

void sqlrcursor::mixedCaseColumnNames | ( |  | ) |

Columns names are returned in the same case as they are defined in the database. This is the default.

bool sqlrcursor::openCachedResultSet | ( | const char * | filename | ) |

Opens a cached result set. Returns true on success and false on failure.

bool sqlrcursor::prepareFileQuery | ( | const char * | path,
|  | const char * | filename
| ) |  |

Prepare to execute the contents of "path"/"filename". Returns false if the // file couldn't be opened.

void sqlrcursor::prepareQuery | ( | const char * | query | ) |

Prepare to execute "query".

void sqlrcursor::prepareQuery | ( | const char * | query,
|  | uint32_t | length
| ) |  |

Prepare to execute "query" with length "length". This method must be used if the query contains binary data.

bool sqlrcursor::resumeCachedResultSet | ( | uint16_t | id,
|  | const char * | filename
| ) |  |

Resumes a result set previously left open using suspendSession() and continues caching the result set to "filename". Returns true on success and false on failure.

bool sqlrcursor::resumeResultSet | ( | uint16_t | id | ) |

Resumes a result set previously left open using suspendSession(). Returns true on success and false on failure.

uint64_t sqlrcursor::rowCount | ( |  | ) |

Returns the number of rows in the current result set (if the result set is being stepped through, this returns the number of rows processed so far).

bool sqlrcursor::sendFileQuery | ( | const char * | path,
|  | const char * | filename
| ) |  |

Sends the query in file "path"/"filename" directly and gets a result set.

bool sqlrcursor::sendQuery | ( | const char * | query | ) |

Sends "query" directly and gets a result set.

bool sqlrcursor::sendQuery | ( | const char * | query,
|  | uint32_t | length
| ) |  |

Sends "query" with length "length" directly and gets a result set. This method must be used if the query contains binary data.

void sqlrcursor::setCacheTtl | ( | uint32_t | ttl | ) |

Sets the time-to-live for cached result sets. The sqlr-cachemanger will remove each cached result set "ttl" seconds after it's created, provided it's scanning the directory containing the cache files.

void sqlrcursor::setResultSetBufferSize | ( | uint64_t | rows | ) |

Sets the number of rows of the result set to buffer at a time. 0 (the default) means buffer the entire result set.

void sqlrcursor::substitution | ( | const char * | variable,
|  | const char * | value
| ) |  |

Defines a string substitution variable.

void sqlrcursor::substitution | ( | const char * | variable,
|  | int64_t | value
| ) |  |

Defines an integer substitution variable.

void sqlrcursor::substitution | ( | const char * | variable,
|  | double | value,
|  | uint32_t | precision,
|  | uint32_t | scale
| ) |  |

Defines a decimal substitution variable.

void sqlrcursor::substitutions | ( | const char ** | variables,
|  | const char ** | values
| ) |  |

Defines an array of string substitution variables.

void sqlrcursor::substitutions | ( | const char ** | variables,
|  | const int64_t * | values
| ) |  |

Defines an array of integer substitution variables.

void sqlrcursor::substitutions | ( | const char ** | variables,
|  | const double * | values,
|  | const uint32_t * | precisions,
|  | const uint32_t * | scales
| ) |  |

Defines an array of decimal substitution variables.

void sqlrcursor::suspendResultSet | ( |  | ) |

Tells the server to leave this result set open when the connection calls suspendSession() so that another connection can connect to it using resumeResultSet() after it calls resumeSession().

uint64_t sqlrcursor::totalRows | ( |  | ) |

Returns the total number of rows that will be returned in the result set. Not all databases support this call. Don't use it for applications which are designed to be portable across databases. 0 is returned by databases which don't support this option.

void sqlrcursor::upperCaseColumnNames | ( |  | ) |

Columns names are converted to upper case.

void sqlrcursor::validateBinds | ( |  | ) |

If you are binding to any variables that might not actually be in your query, call this to ensure that the database won't try to bind them unless they really are in the query. There is a performance penalty for calling this method.

bool sqlrcursor::validBind | ( | const char * | variable | ) |

Returns true if "variable" was a valid bind variable of the query.