Keywords: ODBC Binding for Ruby

# Ruby ODBC Reference

Last update: Thu, 11 October 2001

## ODBC

The module to encapsulate the Ruby ODBC binding.

### module functions:

`datasources`
  Returns an array of ODBC::DSNs, ie all known data source names.
`drivers`
  Returns an array of ODBC::Drivers, ie all known ODBC drivers.
`error`
  Returns the last error messages (String array) or nil. The layout of the warning/error messages is described here.
`info`
  Returns the last driver/driver manager warning messages (String array) or nil. The layout of the warning/error messages is described here.
`raise(value)`
  Raises an ODBC::Error exception with String error message value.
`newenv`
  Returns a new ODBC::Environment.
`connection_pooling[=value]`
  Gets or sets the process-wide connection pooling attribute.
`to_time(timestamp)`
`to_time(date, [time])`
`to_time(time, [date])`
  Creates a `Time` object from the specified arguments, which must be ODBC::Date, ODBC::Time, or ODBC::TimeStamp objects.
`to_date(timestamp)`
`to_date(date)`
  Creates a `Date` object from the specified arguments, which must be ODBC::Date, or ODBC::TimeStamp objects.
`connect(dsn, [user, passwd]) [{|dbc| block}]`
  If no block is specified, a connection to the given data source is established and a ODBC::Database object is returned, identifying that connection. Otherwise, the block is executed with the database object. When the block is finished, the connection is automatically released. Options are:
    dsn: Data source name (String or ODBC::DSN)
    user: Login user name (String)
    passwd: Login password (String)

### constants:

Some constants of the ODBC API are defined in order to set connection options and to deal with SQL data types:

Cursor behaviour:
  SQL_CURSOR_FORWARD_ONLY, SQL_CURSOR_KEYSET_DRIVEN, SQL_CURSOR_DYNAMIC, SQL_CURSOR_STATIC
Concurrency (transactions):
  SQL_CONCUR_READ_ONLY, SQL_CONCUR_LOCK, SQL_CONCUR_ROWVER, SQL_CONCUR_VALUES
Fetch direction:
  SQL_FETCH_NEXT, SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_PRIOR, SQL_FETCH_ABSOLUTE, SQL_FETCH_RELATIVE
Data types:
  SQL_UNKNOWN_TYPE, SQL_CHAR, SQL_NUMERIC, SQL_DECIMAL, SQL_INTEGER, SQL_SMALLINT, SQL_FLOAT, SQL_REAL, SQL_DOUBLE, SQL_VARCHAR, SQL_DATETIME, SQL_DATE, SQL_TYPE_DATE, SQL_TIME, SQL_TYPE_TIME, SQL_TIMESTAMP, SQL_TYPE_TIMESTAMP, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY, SQL_BIGINT, SQL_TINYINT, SQL_BIT, SQL_GUID
Environment attributes:
  SQL_CP_OFF, SQL_CP_ONE_PER_DRIVER, SQL_CP_ONE_PER_HENV, SQL_CP_DEFAULT, SQL_CP_STRICT_MATCH, SQL_CP_RELAXED_MATCH, SQL_CP_MATCH_DEFAULT, SQL_OV_ODBC2, SQL_OV_ODBC3

## ODBC::Object

The class to represent the root of all other ODBC related objects.

### super class:

`Object`

### methods:

`error`
  Returns the last error message (String) or nil.
`info`
  Returns the last driver/driver manager warning messages (String array) or nil.
`raise(value)`
  Raises an ODBC::Error exception with String error message value.

### singleton methods:

`error`
  Returns the last error message (String array) or nil.
`info`
  Returns the last driver/driver manager warning messages (String array) or nil.
`raise(value)`
  Raises an ODBC::Error exception with String error message value.

## ODBC::Environment

The class to represent the environment for ODBC::Databases.

### super class:

`ODBC::Object`

### methods:

`connect`
  Connects to an ODBC data source and returns a ODBC::Database object. Options are:
    dsn: Data source name (String or ODBC::DSN)
    user: Login user name (String)
    passwd: Login password (String)
`environment`
  Returns the ODBC::Environment of the object.
`commit`
  Commits the current transaction.
`rollback`
  Rollbacks the current transaction.
`transaction {|env| block}`
  First commits the current transaction, then executes the given block where the paramater is the object itself (an environment or a database connection). If the block raises an exception, the transaction is rolled back, otherwise committed.
`connection_pooling[=value]`
  Gets or sets the connection pooling attribute of the environment.
`cp_match[=value]`
  Gets or sets the connection pooling match attribute of the environment.
`odbc_version[=value]`
  Gets or sets the ODBC version attribute of the environment.

### singleton methods:

`new`
  Returns a new ODBC::Environment object.

## ODBC::Database

The class to represent a connection to an ODBC data source.

When underlying ODBC SQL functions report an error, an ODBC::Error exception with a corresponding error message from the ODBC driver manager and/or driver is raised.

### super class:

`ODBC::Environment`

### methods:

`connected?`
  Returns `true` when the object is in connected state, false otherwise.
`drvconnect(drv)`
  Connect to a data source specified by drv (ODBC::Driver).
`disconnect(no_drop=false)`
  Disconnects from the data source, all active statements for the connection are dropped except when the no_drop argument is true. The method returns true when the connection was released, false otherwise.
`tables([pattern])`
  Returns an ODBC::Statement with information of all or some (pattern String given) tables of the data source.
`columns([table])`
  Returns an ODBC::Statement with column information of the given table (String).
`indexes([table[,unique]])`
  Returns an ODBC::Statement with index information of the given table (String). If unique is given and true, information for unique indexes only is returned.
`types([tcode])`
  Returns an ODBC::Statement with type information of the numeric SQL type tcode or all types if tcode is omitted.
`primary_keys([table])`
  Returns an ODBC::Statement with primary key information of the given table (String).
`foreign_keys([table])`
  Returns an ODBC::Statement with foreign key information of the given table (String).
`table_privileges([table])`
  Returns an ODBC::Statement with owner/right information of the given table (String).
`procedures([p])`
  Returns an ODBC::Statement with information about stored procedures.
`procedure_columns([p])`
  Returns an ODBC::Statement with information about stored procedures.
`special_columns([table[,id, scope]])`
  Returns an ODBC::Statement with column information of the given table (String) indicating the optimal unique or identifying columns. id may be specified as `ODBC::SQL_BEST_ROWID` or `ODBC::SQL_ROW_VER`. scope may be specified as `ODBC::SQL_SCOPE_CURROW`, `ODBC::SQL_SCOPE_TRANSACTION`, or `ODBC::SQL_SCOPE_SESSION`. If omitted the defaults are `ODBC::SQL_BEST_ROWID` and `ODBC::SQL_SCOPE_CURROW`.
`run(sql, [args ...])`
  Prepares and executes the query specified by sql with parameters bound from args and returns an ODBC::Statement.
`do(sql, [args ...])`
  Prepares and executes the query as in run, but returns the number of result rows and automatically drops the statement. Useful for SQL insert, delete, or update statements.
`prepare(sql)`
  Prepares the query specified by sql and returns an ODBC::Statement.
`proc(sql) {|stmt| block}`
  Prepares the query specified by sql within a ODBCProc and returns that procedure. When the procedure is called, the statement is executed with the procedure's arguments bound to the statement's parameters and the statement is bound as parameter in the block, eg

      # add customer given name and id
      # and return number of affected rows

      addcust = dbc.proc("insert into customer values(?, ?)") { |stmt|
          stmt.nrows
      }

      addcust.call("J.R. User", 9999)

      # alternative to call: addcust["J.R. User", 9999]

`autocommit[=bool]`
  Sets or queries the autocommit option of the connection.
`concurrency[=intval]`
  Sets or queries the concurrency mode of the connection.
`maxrows[=intval]`
  Sets or queries the maximum rows for the connection.
`timeout[=intval]`
  Sets or queries the timeout value of the connection.
`maxlength[=intval]`
  Sets or queries the maximum length for the connection.
`rowsetsize[=intval]`
  Sets or queries the row set size option of the connection.
`cursortype[=intval]`
  Sets or queries the cursor behaviour of the connection.
`noscan[=bool]`
  Sets or queries the noscan option of the connection.
`ignorecase[=bool]`
  Sets or queries the uppercase conversion for column names. If turned on (bool is true), ODBC::Statements created by database methods will report column names in ODBC::Column or in the statement fetch methods as uppercase strings. Otherwise (the default) column names are passed unmodified.
`drop_all`
  Releases the resources of all open ODBC::Statements in this database connection.

### singleton methods:

`new`
  Creates an unconnected ODBC object, eg for a later `drvconnect` method call.
`new(dsn, [user, passwd])`
  Connect to an ODBC data source. Options are:
    dsn: Data source name (String or ODBC::DSN)
    user: Login user name (String)
    passwd: Login password (String)

### Remarks:

The run, prepare, do, and info methods (eg tables) can be invoked with a block. In this case the block is executed with the ODBC::Statement as parameter. The run and do methods use the ODBC API function `SQLExecDirect()` when the SQL statement has no parameters.

## ODBC::Statement

The class to represent the query result. The object of this class is created as the result of every query. You may need to invoke the close or drop methods for the finished object for better memory performance.

When underlying ODBC SQL functions report an error, an ODBC::Error exception with a corresponding error message from the ODBC driver manager and/or driver is raised.

ODBC to Ruby type mapping:

ODBC | Ruby
--- | ---
SQL_SMALLINT, SQL_INTEGER, SQL_TINYINT, SQL_BIT | T_FIXNUM, T_BIGNUM
SQL_FLOAT, SQL_DOUBLE, SQL_REAL | T_FLOAT
SQL_DATE, SQL_TYPE_DATE | ODBC::Date
SQL_TIME, SQL_TYPE_TIME | ODBC::Time
SQL_TIMESTAMP, SQL_TYPE_TIMESTAMP | ODBC::TimeStamp
all others | T_STRING

### super class:

`ODBC::Database`

### mixins:

`Enumerable`

### methods:

`cancel`
  Cancel and close the ODBC::Statement.
`close`
  Close the ODBC::Statement.
`drop`
  Close and free the ODBC::Statement.
`column(n)`
  Returns information of the n-th column of the query result as ODBC::Column.
`columns(as_ary=false)`
  Returns a hash of column information keyed by column names (Strings) of the query result. If as_ary is true, an array is returned. In both cases the elements are ODBC::Columns. If the hash keys happen to be not unique later columns get their column number appended, e.g. `FOOBAR`, `FOOBAR#1`.
`columns {|col| block}`
  Iterates over the columns of the query result with col bound to each ODBC::Column.
`ncols`
  Returns the number of columns of the query result.
`nrows`
  Returns the number of rows of the query result.
`cursorname[=name]`
  Returns or sets the cursor name of the statement.
`ignorecase[=bool]`
  Same as `ODBC::Database.ignorecase` but affecting this statement only. Inherited by the current state of the ODBC::Database at the time the statement is created.
`fetch`
  Returns the next row of the query result as an array.
`fetch_first`
  Returns the first row of the query result as an array.
`fetch_scroll(direction, offset=1)`
  Returns the row addressed by direction, eg `SQL_FETCH_LAST` as an array. offset is used for `SQL_FETCH_RELATIVE` and `SQL_FETCH_ABSOLUTE`.
`fetch_many(count)`
  Returns an array of the next count rows of the query result, where each row is an array.
`fetch_all`
  Same as `fetch_many` except that all remaining rows are returned.
`fetch_hash(with_table_names=false)`
  Returns the next row of the query result as a hash keyed by column names. If with_table_names is true, the keys are combined table/column names. For uniqueness of keys the same rules as in the `columns` method are applied.
`each {|row| block}`
  Iterates over the query result, performing a `fetch` for each row.
`each_hash(with_table_names=false) {|row| block}`
  Iterates over the query result, performing a `fetch_hash` for each row.
`execute([args ...])`
  Binds args to current query and executes it.

### Remarks:

The `fetch`, `fetch_hash`, and `execute` methods can be invoked with a block. In this case the block is executed with one row of the result set (`fetch` and `fetch_hash`) or with the ODBC::Statement (`execute`) as parameter.

If the `ignorecase` option is turned on, all column names used in the `column`, `columns`, and `*_hash` methods are converted to upper case.

## ODBC::Column

The class to represent information of a column of a query. Objects of this class are created as result of the `column` and `columns` methods of ODBC::Statement.

### super class:

`ODBC::Object`

### methods:

`name`
  Returns the column name (String).
`table`
  Returns the table name (String).
`length`
  Returns the length of the column (Integer).
`nullable`
  Returns the nullable state of the column (Boolean).
`searchable`
  Returns the searchable state of the column (Boolean).
`unsigned`
  Returns the unsigned flag of the column (Boolean).
`precision`
  Returns the precision of the column (Integer).
`scale`
  Returns the scale of the column (Integer).
`type`
  Returns the SQL type of the column (Integer).

## ODBC::Date

The class to represent a `SQL_DATE` column in a table.

### super class:

`ODBC::Object`

### mixins:

`Comparable`

### methods:

`<=>(adate)`
  Comparison, compares date with adate and returns 0, 1, or -1.
`day[=num]`
  Returns or sets the day component of the date object.
`month[=num]`
  Returns or sets the month component of the date object.
`year[=num]`
  Returns or sets the year component of the date object.
`to_s`
  Returns a string representation of the object with format `YYYY-MM-DD`.
`clone`
  Returns a fresh copy of the date object.

### singleton methods:

`new([year, month, day])`
`new(date)`
`new(time)`
`new(string)`
  Creates a new date object from numeric values or from a `Date`, `Time`, or `String` object. Recognized string formats are eg

      2001-01-01
      2001-01-01 12:00:01
      {ts '2001-01-01 12:00:01.1'}
      {d '2001-01-01'}

## ODBC::Time

The class to represent a `SQL_TIME` column in a table.

### super class:

`ODBC::Object`

### mixins:

`Comparable`

### methods:

`<=>(atime)`
  Comparison, compares time with atime and returns 0, 1, or -1.
`second[=num]`
  Returns or sets the second component of the time object.
`minute[=num]`
  Returns or sets the minute component of the time object.
`hour[=num]`
  Returns or sets the hour component of the time object.
`to_s`
  Returns a string representation of the object with format `hh:mm:ss`.
`clone`
  Returns a fresh copy of the time object.

### singleton methods:

`new([hour, minute, second])`
`new(time)`
`new(string)`
  Creates a new time object from numeric values or from a `Time` or `String` object. Recognized string formats are eg

      12:00:01
      2001-01-01 12:00:01
      {ts '2001-01-01 12:00:01.1'}
      {t '12:00:01'}

## ODBC::TimeStamp

The class to represent a `SQL_TIMESTAMP` column in a table.

### super class:

`ODBC::Object`

### mixins:

`Comparable`

### methods:

`<=>(atimestamp)`
  Comparison, compares time stamp with atimestamp and returns 0, 1, or -1.
`fraction[=num]`
  Returns or sets the fraction component of the time stamp object. Note that this is expressed in nanoseconds.
`second[=num]`
  Returns or sets the second component of the time stamp object.
`minute[=num]`
  Returns or sets the minute component of the time stamp object.
`hour[=num]`
  Returns or sets the hour component of the time stamp object.
`day[=num]`
  Returns or sets the day component of the time stamp object.
`month[=num]`
  Returns or sets the month component of the time stamp object.
`year[=num]`
  Returns or sets the year component of the time stamp object.
`to_s`
  Returns a string representation of the object with format `YYYY-MM-DD hh:mm:ss fraction`.
`clone`
  Returns a fresh copy of the time stamp object.

### singleton methods:

`new([year, month, day, hour, minute, second, fraction])`
`new(time)`
`new(string)`
  Creates a new time stamp object from numeric values or from a `Time` or `String` object. Recognized string formats are eg

      12:00:01
      2001-01-01
      2001-01-01 12:00:01
      {ts '2001-01-01 12:00:01.1'}
      {d '2001-01-01'}
      {t '12:00:01'}

## ODBC::DSN

The class to represent a data source name. Objects of this class are created as result of a ODBC::datasources module function call.

### super class:

`ODBC::Object`

### methods:

`name[=name]`
  Queries or sets the name (String) of the data source.
`descr[=descr]`
  Queries or sets the descr (description, String) of the data source.

### singleton methods:

`new`
  Returns an empty ODBC::DSN object.

## ODBC::Driver

The class to represent an ODBC driver with name and attributes. Objects of this class are created as result of a ODBC::drivers module function call.

### super class:

`ODBC::Object`

### methods:

`name[=name]`
  Queries or sets the name (String) of the ODBC driver.
`attrs[[key][=value]]`
  Queries or sets attributes in the attrs Hash of the ODBC driver object. The keys and values should be Strings.

### singleton methods:

`new`
  Returns an empty ODBC::Driver object.

## ODBCProc

The class to represent a procedure with ODBC database/statement context. Objects of this class are created as result of a ODBC::Database.proc method call.

### super class:

`Proc`

### methods:

`call([args*])`
  Executes the SQL statement with parameters set from args and then invokes the procedure's block, setting the block's parameter to the ODBC::Statement.
`[[args*]]`
  Synonym for `call`.

## ODBC::Error

The class to represent ODBC related exceptions. The descriptive string is made up of the first ODBC driver or driver manager message as concatenation of SQL state, native error, driver manager name, database name/vendor, DSN, and error text, eg

    S1000 (1146) [unixODBC][TCX][MySQL]Table 'test.foo' doesn't exist

For internally generated errors, eg method invocation on a broken connection, the descriptive string starts with 'INTERN' and native error 0, eg

    INTERN (0) [RubyODBC]No connection

For errors programmatically generated by the `raise` method, the descriptive string starts with 'INTERN' and native error 1, eg

    INTERN (1) [RubyODBC]Programmer forgot to RTFM

### super class:

`StandardError`

## Undocumented

### Use The Source, Luke!

`ODBC::add_dsn(driver, issys=false)`
`ODBC::add_dsn(name, attrs, issys=false)`
`ODBC::config_dsn(driver, issys=false)`
`ODBC::config_dsn(name, attrs, issys=false)`
`ODBC::del_dsn(driver, issys=false)`
`ODBC::del_dsn(name, attrs, issys=false)`
`ODBC::trace([mask])`
`ODBC::Statement.parameter([n])`
`ODBC::Statement.parameters`
`ODBC::Statement.nparams`
`ODBC::Statement.fetch!`
`ODBC::Statement.fetch_first!`
`ODBC::Statement.fetch_first_hash(with_table_names=false)`
`ODBC::Statement.fetch_scroll!(direction, offset=1)`
`ODBC::Statement.fetch_hash!(with_table_names=false)`
`ODBC::Statement.make_proc(stmt)`
`ODBC::Parameter ...`