class SQLRCursor - RDoc Documentation

# class SQLRCursor

### Public Class Methods

new(connection) click to toggle source

Creates a cursor to run queries and fetch result sets using connection “connection”

    static VALUE sqlrcur_new(VALUE self, VALUE connection) {
            sqlrconnection *sqlrcon;
            Data_Get_Struct(connection,sqlrconnection,sqlrcon);
            sqlrcursor     *sqlrcur=new sqlrcursor(sqlrcon,true);
            return Data_Wrap_Struct(self,0,sqlrcur_free,(void *)sqlrcur);
    }

### Public Instance Methods

affectedRows() click to toggle source

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. -1 is returned by databases which don't support this option.

    static VALUE sqlrcur_affectedRows(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->affectedRows());
    }

cacheOff() click to toggle source

Sets query caching off.

    static VALUE sqlrcur_cacheOff(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->cacheOff();
            return Qnil;
    }

cacheToFile(filename) click to toggle source

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.

    static VALUE sqlrcur_cacheToFile(VALUE self, VALUE filename) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->cacheToFile(STR2CSTR(filename));
            return Qnil;
    }

clearBinds() click to toggle source

Clears all bind variables.

    static VALUE sqlrcur_clearBinds(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->clearBinds();
            return Qnil;
    }

closeResultSet() click to toggle source

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.

    static VALUE sqlrcur_closeResultSet(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->closeResultSet();
            return Qnil;
    }

colCount() click to toggle source

Returns the number of columns in the current result set.

    static VALUE sqlrcur_colCount(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->colCount());
    }

countBindVariables() click to toggle source

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

    static VALUE sqlrcur_countBindVariables(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->countBindVariables());
    }

defineOuptutBindBlob(variable) click to toggle source

Defines a binary lob output bind variable

    static VALUE sqlrcur_defineOutputBindBlob(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->defineOutputBindBlob(STR2CSTR(variable));
            return Qnil;
    }

defineOutputBindClob(variable) click to toggle source

Defines a character lob output bind variable

    static VALUE sqlrcur_defineOutputBindClob(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->defineOutputBindClob(STR2CSTR(variable));
            return Qnil;
    }

defineOutputBindCursor(variable) click to toggle source

Defines a cursor output bind variable

    static VALUE sqlrcur_defineOutputBindCursor(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->defineOutputBindCursor(STR2CSTR(variable));
            return Qnil;
    }

defineOutputBindDouble(variable) click to toggle source

Defines an decimal output bind variable.

    static VALUE sqlrcur_defineOutputBindDouble(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->defineOutputBindDouble(STR2CSTR(variable));
            return Qnil;
    }

defineOutputBindInteger(variable) click to toggle source

Defines an integer output bind variable.

    static VALUE sqlrcur_defineOutputBindInteger(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->defineOutputBindInteger(STR2CSTR(variable));
            return Qnil;
    }

defineOutputBindString(variable,length) click to toggle source

Defines a string output bind variable. “length” bytes will be reserved to store the value.

    static VALUE sqlrcur_defineOutputBindString(VALUE self, VALUE variable,
                                                            VALUE bufferlength) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->defineOutputBindString(STR2CSTR(variable),NUM2INT(bufferlength));
            return Qnil;
    }

dontGetColumnInfo() click to toggle source

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

    static VALUE sqlrcur_dontGetColumnInfo(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->dontGetColumnInfo();
            return Qnil;
    }

endOfResultSet() click to toggle source

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

    static VALUE sqlrcur_endOfResultSet(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->endOfResultSet());
    }

errorMessage() click to toggle source

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

    static VALUE sqlrcur_errorMessage(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *result=sqlrcur->errorMessage();
            if (result) {
                    return rb_str_new2(result);
            } else {
                    return Qnil;
            }
    }

errorNumber() click to toggle source

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

    static VALUE sqlrcur_errorNumber(VALUE self) {
            sqlrcursor *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->errorNumber());
    }

executeQuery() click to toggle source

Execute the query that was previously prepared and bound.

    static VALUE sqlrcur_executeQuery(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->executeQuery());
    }

fetchFromBindCursor() click to toggle source

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

    static VALUE sqlrcur_fetchFromBindCursor(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->fetchFromBindCursor());
    }

firstRowIndex() click to toggle source

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

    static VALUE sqlrcur_firstRowIndex(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->firstRowIndex());
    }

getCacheFileName() click to toggle source

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

    static VALUE sqlrcur_getCacheFileName(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *result=sqlrcur->getCacheFileName();
            if (result) {
                    return rb_str_new2(result);
            } else {
                    return Qnil;
            }
    }

getColumnInfo() click to toggle source

Tells the server to send column info.

    static VALUE sqlrcur_getColumnInfo(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->getColumnInfo();
            return Qnil;
    }

getColumnIsAutoIncrement(col) click to toggle source

Returns 1 if the specified column auto-increments and 0 otherwise. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnIsAutoIncrement(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(
                            sqlrcur->getColumnIsAutoIncrement(STR2CSTR(col)));
            } else {
                    return INT2NUM(
                            sqlrcur->getColumnIsAutoIncrement(NUM2INT(col)));
            }
    }

getColumnIsBinary(col) click to toggle source

Returns 1 if the specified column contains binary data and 0 otherwise. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnIsBinary(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnIsBinary(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnIsBinary(NUM2INT(col)));
            }
    }

getColumnIsNullable(col) click to toggle source

Returns 1 if the specified column can contain nulls and 0 otherwise. “col” may be specified as the colum name or number.

    static VALUE sqlrcur_getColumnIsNullable(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnIsNullable(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnIsNullable(NUM2INT(col)));
            }
    }

getColumnIsPartOfKey(col) click to toggle source

Returns 1 if the specified column is part of a composite key and 0 otherwise. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnIsPartOfKey(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnIsPartOfKey(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnIsPartOfKey(NUM2INT(col)));
            }
    }

getColumnIsPrimaryKey(col) click to toggle source

Returns 1 if the specified column is a primary key and 0 otherwise. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnIsPrimaryKey(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnIsPrimaryKey(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnIsPrimaryKey(NUM2INT(col)));
            }
    }

getColumnIsUnique(col) click to toggle source

Returns 1 if the specified column is unique and 0 otherwise. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnIsUnique(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnIsUnique(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnIsUnique(NUM2INT(col)));
            }
    }

getColumnIsUnsigned(col) click to toggle source

Returns 1 if the specified column is an unsigned number and 0 otherwise. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnIsUnsigned(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnIsUnsigned(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnIsUnsigned(NUM2INT(col)));
            }
    }

getColumnIsZeroFilled(col) click to toggle source

Returns 1 if the specified column was created with the zero-fill flag and 0 otherwise. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnIsZeroFilled(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnIsZeroFilled(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnIsZeroFilled(NUM2INT(col)));
            }
    }

getColumnLength(col) click to toggle source

Returns the length of the specified column. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnLength(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnLength(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnLength(NUM2INT(col)));
            }
    }

getColumnList(table,wild) click to toggle source

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

    static VALUE sqlrcur_getColumnList(VALUE self, VALUE table, VALUE wild) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->getColumnList(STR2CSTR(table),STR2CSTR(wild)));
    }

getColumnName(col) click to toggle source

Returns the name of the specified column.

    static VALUE sqlrcur_getColumnName(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *result=sqlrcur->getColumnName(NUM2INT(col));
            if (result) {
                    return rb_str_new2(result);
            } else {
                    return Qnil;
            }
    }

getColumnNames() click to toggle source

Returns an array of the column names of the current result set.

    static VALUE sqlrcur_getColumnNames(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char * const *names=sqlrcur->getColumnNames();
            if (!names) {
                    return Qnil;
            }
            VALUE  nameary=rb_ary_new2(sqlrcur->colCount());
            for (uint32_t i=0; i<sqlrcur->colCount(); i++) {
                    if (names[i]) {
                            rb_ary_store(nameary,i,rb_str_new2(names[i]));
                    } else {
                            rb_ary_store(nameary,i,Qnil);
                    }
            }
            return nameary;
    }

getColumnPrecision(col) click to toggle source

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. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnPrecision(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnPrecision(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnPrecision(NUM2INT(col)));
            }
    }

getColumnScale(col) click to toggle source

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. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnScale(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getColumnScale(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getColumnScale(NUM2INT(col)));
            }
    }

getColumnType(col) click to toggle source

Returns the type of the specified column. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getColumnType(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *result;
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    result=sqlrcur->getColumnType(STR2CSTR(col));
            } else {
                    result=sqlrcur->getColumnType(NUM2INT(col));
            }
            if (result) {
                    return rb_str_new2(result);
            } else {
                    return Qnil;
            }
    }

getDatabaseList(wild) click to toggle source

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

    static VALUE sqlrcur_getDatabaseList(VALUE self, VALUE wild) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->getDatabaseList(STR2CSTR(wild)));
    }

getField(row,col) click to toggle source

Returns the specified field as a string. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getField(VALUE self, VALUE row, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *result;
            long           length;
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    result=sqlrcur->getField(NUM2INT(row),STR2CSTR(col));
                    length=sqlrcur->getFieldLength(NUM2INT(row),STR2CSTR(col));
            } else {
                    result=sqlrcur->getField(NUM2INT(row),NUM2INT(col));
                    length=sqlrcur->getFieldLength(NUM2INT(row),NUM2INT(col));
            }
            if (result) {
                    return rb_str_new(result,length);
            } else {
                    return Qnil;
            }
    }

getFieldAsDouble(row,col) click to toggle source

Returns the specified field as an decimal. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getFieldAsDouble(VALUE self, VALUE row, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            double result;
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    result=sqlrcur->getFieldAsDouble(NUM2INT(row),STR2CSTR(col));
            } else {
                    result=sqlrcur->getFieldAsDouble(NUM2INT(row),NUM2INT(col));
            }
            return rb_float_new(result);
    }

getFieldAsInteger(row,col) click to toggle source

Returns the specified field as an integer. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getFieldAsInteger(VALUE self, VALUE row, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            long   result;
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    result=sqlrcur->getFieldAsInteger(NUM2INT(row),STR2CSTR(col));
            } else {
                    result=sqlrcur->getFieldAsInteger(NUM2INT(row),NUM2INT(col));
            }
            return INT2NUM(result);
    }

getFieldLength(row,col) click to toggle source

Returns the length of the specified row and column. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getFieldLength(VALUE self, VALUE row, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM((int)sqlrcur->getFieldLength(NUM2INT(row),
                                                                    STR2CSTR(col)));
            } else {
                    return INT2NUM((int)sqlrcur->getFieldLength(NUM2INT(row),
                                                                    NUM2INT(col)));
            }
    }

getLongest(col) click to toggle source

Returns the length of the longest field in the specified column. “col” may be specified as the column name or number.

    static VALUE sqlrcur_getLongest(VALUE self, VALUE col) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(col,rb_cString)==Qtrue) {
                    return INT2NUM(sqlrcur->getLongest(STR2CSTR(col)));
            } else {
                    return INT2NUM(sqlrcur->getLongest(NUM2INT(col)));
            }
    }

getNullsAsEmptyStrings() click to toggle source

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

    static VALUE sqlrcur_getNullsAsEmptyStrings(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->getNullsAsEmptyStrings();
            return Qnil;
    }

getNullsAsNils() click to toggle source

Tells the connection to return NULL fields and output bind variables as nil's.

    static VALUE sqlrcur_getNullsAsNils(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->getNullsAsNulls();
            return Qnil;
    }

getOutputBindBlob(variable) click to toggle source

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

    static VALUE sqlrcur_getOutputBindBlob(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *varname=STR2CSTR(variable);
            const char     *result=sqlrcur->getOutputBindBlob(varname);
            long           length=sqlrcur->getOutputBindLength(varname);
            if (result) {
                    return rb_str_new(result,length);
            } else {
                    return Qnil;
            }
    }

getOutputBindClob(variable) click to toggle source

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

    static VALUE sqlrcur_getOutputBindClob(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *varname=STR2CSTR(variable);
            const char     *result=sqlrcur->getOutputBindClob(varname);
            long           length=sqlrcur->getOutputBindLength(varname);
            if (result) {
                    return rb_str_new(result,length);
            } else {
                    return Qnil;
            }
    }

getOutputBindCursor(variable) click to toggle source

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

    static VALUE sqlrcur_getOutputBindCursor(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcursor     *returnsqlrcur=sqlrcur->getOutputBindCursor(
                                                            STR2CSTR(variable),
                                                            true);
            return Data_Wrap_Struct(csqlrcursor,0,sqlrcur_free,
                                            (void *)returnsqlrcur);
    }

getOutputBindDouble(variable) click to toggle source

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

    static VALUE sqlrcur_getOutputBindDouble(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *varname=STR2CSTR(variable);
            double         result=sqlrcur->getOutputBindDouble(varname);
            return rb_float_new(result);
    }

getOutputBindInteger(variable) click to toggle source

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

    static VALUE sqlrcur_getOutputBindInteger(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *varname=STR2CSTR(variable);
            long           result=sqlrcur->getOutputBindInteger(varname);
            return INT2NUM(result);
    }

getOutputBindLength(variable) click to toggle source

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

    static VALUE sqlrcur_getOutputBindLength(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->getOutputBindLength(STR2CSTR(variable)));
    }

getOutputBindString(variable) click to toggle source

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

    static VALUE sqlrcur_getOutputBindString(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char     *varname=STR2CSTR(variable);
            const char     *result=sqlrcur->getOutputBindString(varname);
            long           length=sqlrcur->getOutputBindLength(varname);
            if (result) {
                    return rb_str_new(result,length);
            } else {
                    return Qnil;
            }
    }

getResultSetBufferSize() click to toggle source

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

    static VALUE sqlrcur_getResultSetBufferSize(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->getResultSetBufferSize());
    }

getResultSetId() click to toggle source

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

    static VALUE sqlrcur_getResultSetId(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->getResultSetId());
    }

getRow(row) click to toggle source

Returns an array of the values of the fields in the specified row.

    static VALUE sqlrcur_getRow(VALUE self, VALUE row) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char * const *fields=sqlrcur->getRow(NUM2INT(row));
            uint32_t       *lengths=sqlrcur->getRowLengths(NUM2INT(row));
            VALUE  fieldary=rb_ary_new2(sqlrcur->colCount());
            for (uint32_t i=0; i<sqlrcur->colCount(); i++) {
                    if (fields[i]) {
                            rb_ary_store(fieldary,i,rb_str_new(fields[i],
                                                                    lengths[i]));
                    } else {
                            rb_ary_store(fieldary,i,Qnil);
                    }
            }
            return fieldary;
    }

getRowHash(row) click to toggle source

Returns a hash of the values of the fields in the specified row.

    static VALUE sqlrcur_getRowHash(VALUE self, VALUE row) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            const char * const *fields=sqlrcur->getRow(NUM2INT(row));
            uint32_t       *lengths=sqlrcur->getRowLengths(NUM2INT(row));
            VALUE  fieldhash=rb_hash_new();
            for (uint32_t i=0; i<sqlrcur->colCount(); i++) {
                    if (fields[i]) {
                            rb_hash_aset(fieldhash,
                                            rb_str_new2(sqlrcur->getColumnName(i)),
                                            rb_str_new(fields[i],lengths[i]));
                    } else {
                            rb_hash_aset(fieldhash,
                                            rb_str_new2(sqlrcur->getColumnName(i)),
                                            Qnil);
                    }
            }
            return fieldhash;
    }

getRowLengths(row) click to toggle source

Returns an array of the lengths of the fields in the specified row.

    static VALUE sqlrcur_getRowLengths(VALUE self, VALUE row) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            uint32_t       *lengths=sqlrcur->getRowLengths(NUM2INT(row));
            if (!lengths) {
                    return Qnil;
            }
            VALUE  lengthary=rb_ary_new2(sqlrcur->colCount());
            for (uint32_t i=0; i<sqlrcur->colCount(); i++) {
                    rb_ary_store(lengthary,i,INT2NUM(lengths[i]));
            }
            return lengthary;
    }

getRowLengthsHash(row) click to toggle source

Returns a hash of the lengths of the fields in the specified row.

    static VALUE sqlrcur_getRowLengthsHash(VALUE self, VALUE row) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            uint32_t       *lengths=sqlrcur->getRowLengths(NUM2INT(row));
            VALUE  lengthhash=rb_hash_new();
            for (uint32_t i=0; i<sqlrcur->colCount(); i++) {
                    rb_hash_aset(lengthhash,
                                    rb_str_new2(sqlrcur->getColumnName(i)),
                                    INT2NUM(lengths[i]));
            }
            return lengthhash;
    }

getTableList(wild) click to toggle source

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

    static VALUE sqlrcur_getTableList(VALUE self, VALUE wild) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->getTableList(STR2CSTR(wild)));
    }

inputBind(variable,value,(precision),(scale)) click to toggle source

Defines am input bind variable. The value may be a string, integer or decimal. If it is a decimal then the precision and scale may be specified. If you don't have the precision and scale then set them both to 0. However in that case you may get unexpected rounding behavior if the server is faking binds.

    static VALUE sqlrcur_inputBind(int argc, VALUE *argv, VALUE self) {
            sqlrcursor     *sqlrcur;
            VALUE  variable;
            VALUE  value;
            VALUE  precision;
            VALUE  scale;
            bool   success=true;
            rb_scan_args(argc,argv,"22",&variable,&value,&precision,&scale);
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(value,rb_cString)==Qtrue) {
                    if ((rb_obj_is_instance_of(precision,rb_cBignum)==Qtrue ||
                            rb_obj_is_instance_of(precision,rb_cFixnum)==Qtrue ||
                            rb_obj_is_instance_of(precision,rb_cInteger)==Qtrue ||
                            rb_obj_is_instance_of(precision,rb_cNumeric)==Qtrue) &&
                            NUM2INT(precision)>0) {
                            // in this case, the precision parameter is actually
                            // the string length
                            sqlrcur->inputBind(STR2CSTR(variable),
                                            STR2CSTR(value),NUM2INT(precision));
                    } else {
                            sqlrcur->inputBind(STR2CSTR(variable),STR2CSTR(value));
                    }
            } else if (rb_obj_is_instance_of(value,rb_cBignum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cFixnum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cInteger)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cNumeric)==Qtrue) {
                    sqlrcur->inputBind(STR2CSTR(variable),NUM2INT(value));
            } else if (rb_obj_is_instance_of(value,rb_cFloat)==Qtrue) {
                    sqlrcur->inputBind(STR2CSTR(variable),NUM2DBL(value),
                                            (unsigned short)NUM2INT(precision),
                                            (unsigned short)NUM2INT(scale));
            } else if (rb_obj_is_instance_of(value,rb_cNilClass)==Qtrue) {
                    sqlrcur->inputBind(STR2CSTR(variable),(const char *)NULL);
            } else {
                    success=false;
            }
            return INT2NUM(success);
    }

inputBindBlob(variable,value,size) click to toggle source

Defines a binary lob input bind variable.

    static VALUE sqlrcur_inputBindBlob(VALUE self, VALUE variable,
                                            VALUE value, VALUE size) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            bool   success=true;
            if (value==Qnil) {
                    sqlrcur->inputBindBlob(STR2CSTR(variable),NULL,NUM2INT(size));
            } else if (rb_obj_is_instance_of(value,rb_cString)==Qtrue) {
                    sqlrcur->inputBindBlob(STR2CSTR(variable),
                                    STR2CSTR(value),NUM2INT(size));
            } else {
                    success=false;
            }
            return INT2NUM(success);
    }

inputBindClob(variable,value,size) click to toggle source

Defines a character lob input bind variable.

    static VALUE sqlrcur_inputBindClob(VALUE self, VALUE variable,
                                            VALUE value, VALUE size) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            bool   success=true;
            if (value==Qnil) {
                    sqlrcur->inputBindClob(STR2CSTR(variable),NULL,NUM2INT(size));
            } else if (rb_obj_is_instance_of(value,rb_cString)==Qtrue) {
                    sqlrcur->inputBindClob(STR2CSTR(variable),
                                    STR2CSTR(value),NUM2INT(size));
            } else {
                    success=false;
            }
            return INT2NUM(success);
    }

inputBinds(variables,values,(precisions),(scales)) click to toggle source

Defines an array of input bind variables. The values may be strings, integers or decimals. If they are decimals then the precisions and scales may also be specified.

    static VALUE sqlrcur_inputBinds(int argc, VALUE *argv, VALUE self) {
            sqlrcursor     *sqlrcur;
            VALUE  variables;
            VALUE  values;
            VALUE  precisions;
            VALUE  scales;
            int    argcount=rb_scan_args(argc,argv,"22",
                                    &variables,&values,&precisions,&scales);
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (variables==Qnil || values==Qnil) {
                    return Qnil;
            }
            VALUE  variable;
            VALUE  value;
            VALUE  precision=0;
            VALUE  scale=0;
            bool   success=true;
            for (;;) {
                    variable=rb_ary_shift(variables);
                    if (variable==Qnil) {
                            break;
                    }
                    value=rb_ary_shift(values);
                    if (argcount==4) {
                            precision=rb_ary_shift(precisions);
                            scale=rb_ary_shift(scales);
                    }
                    if (rb_obj_is_instance_of(value,rb_cString)==Qtrue) {
                            sqlrcur->inputBind(STR2CSTR(variable),STR2CSTR(value));
                    } else if (rb_obj_is_instance_of(value,rb_cBignum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cFixnum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cInteger)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cNumeric)==Qtrue) {
                            sqlrcur->inputBind(STR2CSTR(variable),NUM2INT(value));
                    } else if (rb_obj_is_instance_of(value,rb_cFloat)==Qtrue) {
                            sqlrcur->inputBind(STR2CSTR(variable),NUM2DBL(value),
                                            (unsigned short)NUM2INT(precision),
                                            (unsigned short)NUM2INT(scale));
                    } else if (rb_obj_is_instance_of(value,rb_cNilClass)==Qtrue) {
                            sqlrcur->inputBind(STR2CSTR(variable),
                                                    (const char *)NULL);
                    } else {
                            success=false;
                    }
            }
            return INT2NUM(success);
    }

lowerCaseColumnNames() click to toggle source

Columns names are converted to lower case.

    static VALUE sqlrcur_lowerCaseColumnNames(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->lowerCaseColumnNames();
            return Qnil;
    }

mixedCaseColumnNames() click to toggle source

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

    static VALUE sqlrcur_mixedCaseColumnNames(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->mixedCaseColumnNames();
            return Qnil;
    }

openCachedResultSet(filename) click to toggle source

Opens a cached result set. Returns 1 on success and 0 on failure.

    static VALUE sqlrcur_openCachedResultSet(VALUE self, VALUE filename) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->openCachedResultSet(STR2CSTR(filename)));
    }

prepareFileQuery(path,filename) click to toggle source

Prepare to execute the contents of “path”/“filename”.

    static VALUE sqlrcur_prepareFileQuery(VALUE self, VALUE path, VALUE filename) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->prepareFileQuery(STR2CSTR(path),
                                                    STR2CSTR(filename)));
    }

prepareQuery(query) click to toggle source

Prepare to execute “query”.

    static VALUE sqlrcur_prepareQuery(VALUE self, VALUE query) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->prepareQuery(STR2CSTR(query));
            return Qnil;
    }

prepareQuery(query,length) click to toggle source

Prepare to execute “query” with length “length”. This function must be used if the query contains binary data.

    static VALUE sqlrcur_prepareQueryWithLength(VALUE self,
                                            VALUE query, VALUE length) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->prepareQuery(STR2CSTR(query),NUM2INT(length));
            return Qnil;
    }

resumeCachedResultSet(id,filename) click to toggle source

Resumes a result set previously left open using suspendSession() and continues caching the result set to “filename”. Returns 1 on success and 0 on failure.

    static VALUE sqlrcur_resumeCachedResultSet(VALUE self,
                                                    VALUE id, VALUE filename) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->resumeCachedResultSet(NUM2INT(id),
                                                            STR2CSTR(filename)));
    }

resumeResultSet(id) click to toggle source

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

    static VALUE sqlrcur_resumeResultSet(VALUE self, VALUE id) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->resumeResultSet(NUM2INT(id)));
    }

rowCount() click to toggle source

Returns the number of rows in the current result set.

    static VALUE sqlrcur_rowCount(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->rowCount());
    }

sendFileQuery(path,filename) click to toggle source

Sends the query in file “path”/“filename” and gets a result set.

    static VALUE sqlrcur_sendFileQuery(VALUE self, VALUE path, VALUE filename) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->sendFileQuery(STR2CSTR(path),
                                                    STR2CSTR(filename)));
    }

sendQuery(query) click to toggle source

Sends “query” directly and gets a result set.

    static VALUE sqlrcur_sendQuery(VALUE self, VALUE query) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->sendQuery(STR2CSTR(query)));
    }

sendQueryWithLength(query,length) click to toggle source

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

    static VALUE sqlrcur_sendQueryWithLength(VALUE self,
                                            VALUE query, VALUE length) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->sendQuery(STR2CSTR(query),NUM2INT(length)));
    }

setCacheTtl(ttl) click to toggle source

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.

    static VALUE sqlrcur_setCacheTtl(VALUE self, VALUE ttl) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->setCacheTtl(NUM2INT(ttl));
            return Qnil;
    }

setResultSetBufferSize(rows) click to toggle source

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

    static VALUE sqlrcur_setResultSetBufferSize(VALUE self, VALUE rows) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->setResultSetBufferSize(NUM2INT(rows));
            return Qnil;
    }

substitution(variable,value,(precision),(scale)) click to toggle source

Defines a substitution variable. The value may be a string, integer or decimal. If it is a decimal then the precision and scale may be specified.

    static VALUE sqlrcur_substitution(int argc, VALUE *argv, VALUE self) {
            sqlrcursor     *sqlrcur;
            VALUE  variable;
            VALUE  value;
            VALUE  precision;
            VALUE  scale;
            bool   result=true;
            rb_scan_args(argc,argv,"22",&variable,&value,&precision,&scale);
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (rb_obj_is_instance_of(value,rb_cString)==Qtrue) {
                    sqlrcur->substitution(STR2CSTR(variable),STR2CSTR(value));
            } else if (rb_obj_is_instance_of(value,rb_cBignum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cFixnum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cInteger)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cNumeric)==Qtrue) {
                    sqlrcur->substitution(STR2CSTR(variable),NUM2INT(value));
            } else if (rb_obj_is_instance_of(value,rb_cFloat)==Qtrue) {
                    sqlrcur->substitution(STR2CSTR(variable),NUM2DBL(value),
                                            (unsigned short)NUM2INT(precision),
                                            (unsigned short)NUM2INT(scale));
            } else if (rb_obj_is_instance_of(value,rb_cNilClass)==Qtrue) {
                    sqlrcur->substitution(STR2CSTR(variable),(const char *)NULL);
            } else {
                    result=false;
            }
            return INT2NUM(result);
    }

substitutions(variables,values,(precisions),(scales)) click to toggle source

Defines an array of substitution variables. The values may be strings, integers or decimals. If they are decimals then the precisions and scales may also be specified.

    static VALUE sqlrcur_substitutions(int argc, VALUE *argv, VALUE self) {
            sqlrcursor     *sqlrcur;
            VALUE  variables;
            VALUE  values;
            VALUE  precisions;
            VALUE  scales;
            int    argcount=rb_scan_args(argc,argv,"22",
                                            &variables,&values,&precisions,&scales);
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            if (variables==Qnil || values==Qnil) {
                    return Qnil;
            }
            VALUE  variable;
            VALUE  value;
            VALUE  precision=0;
            VALUE  scale=0;
            bool   success=true;
            for (;;) {
                    variable=rb_ary_shift(variables);
                    if (variable==Qnil) {
                            break;
                    }
                    value=rb_ary_shift(values);
                    if (argcount==4) {
                            precision=rb_ary_shift(precisions);
                            scale=rb_ary_shift(scales);
                    }
                    if (rb_obj_is_instance_of(value,rb_cString)==Qtrue) {
                            sqlrcur->substitution(STR2CSTR(variable),
                                                    STR2CSTR(value));
                    } else if (rb_obj_is_instance_of(value,rb_cBignum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cFixnum)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cInteger)==Qtrue ||
                            rb_obj_is_instance_of(value,rb_cNumeric)==Qtrue) {
                            sqlrcur->substitution(STR2CSTR(variable),
                                                    NUM2INT(value));
                    } else if (rb_obj_is_instance_of(value,rb_cFloat)==Qtrue) {
                            sqlrcur->substitution(STR2CSTR(variable),
                                            NUM2DBL(value),
                                            (unsigned short)NUM2INT(precision),
                                            (unsigned short)NUM2INT(scale));
                    } else if (rb_obj_is_instance_of(value,rb_cNilClass)==Qtrue) {
                            sqlrcur->substitution(STR2CSTR(variable),
                                                    (const char *)NULL);
                    } else {
                            success=false;
                    }
            }
            return INT2NUM(success);
    }

suspendResultSet() click to toggle source

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().

    static VALUE sqlrcur_suspendResultSet(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->suspendResultSet();
            return Qnil;
    }

totalRows() click to toggle source

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. -1 is returned by databases which don't support this option.

    static VALUE sqlrcur_totalRows(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->totalRows());
    }

upperCaseColumnNames() click to toggle source

Columns names are converted to upper case.

    static VALUE sqlrcur_upperCaseColumnNames(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->upperCaseColumnNames();
            return Qnil;
    }

validBind(variable) click to toggle source

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

    static VALUE sqlrcur_validBind(VALUE self, VALUE variable) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            return INT2NUM(sqlrcur->validBind(STR2CSTR(variable)));
    }

validateBinds() click to toggle source

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 function

    static VALUE sqlrcur_validateBinds(VALUE self) {
            sqlrcursor     *sqlrcur;
            Data_Get_Struct(self,sqlrcursor,sqlrcur);
            sqlrcur->validateBinds();
            return Qnil;
    }