Updated 2013-09-06 17:39:53 by pooryorick

Tcldbi, by JSB, is not the same code base as tcl dbi.

Based on the MODDBC project, the author has put the code into a namespace, updated the drivers, added a driver for ODBC. It also supports PostgreSQL, Sybase, and msql.

Description  edit

Is this related to tcl dbi?

Scott Beasley No, BeasleyTclDBI is/will be a pure Tcl package that uses current binary dB extensions.

JSB 02-09-2009 - The code was written but never shored-up or released. It had issues about it that I didn't like.

See Also  edit

TDBC
Database Interface
PostgreSQL
Sybase
msql
tcl dbi
TclDBI or a common database interface re-hashed

Proposed API  edit

tcldbi::connect db_type db_name host port user [passwd] [connstr]
   inputs required:
      db_type: dB type that is being connected to, as of now it can
               be one of the following: postgres, odbc, sybase, msql, oracle

      db_name: name of dB to connect to.
host
host name dB server is located on. This can be blank for some DBMS.
port
port name dB server is listening on. This can be blank for some DBMS.
user
user name to connect with.
   inputs optional:
      passwd:  password to login with.  Some DBMS do not require a password.
      connstr: a long connection string to connect to things like odbc with, and
               possibly others in the future.

   output:
      a connection handle that can be used to open up cursors, perform SQL executes or
      fetch rows on some dbms's.

tcldbi::disconnect handle
   inputs required:
      a connection handle returned by a tcldbi::connect call.

tcldbi::opencursor handle
   inputs required:
      a connection handle returned by a tcldbi::connect call.
   output:
      a connection handle that can be used perform SQL executes and fetch rows.

   special:
      On dbms's that do not support cursors, this will have to be done in code for the dB
      driver

tcldbi::closecursor handle
   inputs required:
      handle: a connection handle returned by a tcldbi::opencursor call.

   special:
      On dbms's that do not support cursors, this will have to be done in code for the dB
      driver

tcldbi::sql handle sqlstr
   inputs required:
      handle: a connection handle returned by a tcldbi::opencursor call or on some dbms's a
              handle from a tcldbi::connect call can be used.
      sqlstr: the SQL string to execute.
   output:
      a result handle that will be used to fetch rows with.

   special:
      On dbms's that do not support this, it will have to be done in code for the dB driver
      usually by just returning the connection handle.

tcldbi::fetch handle [arrayname] command
   inputs required:
      handle: a result handle returned by a tcldbi::sql call.
   inputs optional:
      arrayname: an array name to copy the fetched row back to.  The array then can be
                 indexed by column names.
      command: a command or set of commands to execute on each row fetched
   output:
      a Tcl list of the fetched row if arrayname was not specified.  A {} (NULL) will be
      returned if there are no more rows left to read, and tcldbi::eors will be set to 1.

tcldbi::columns cmd handle
   inputs required:
      cmd: type of column information to return,  Can be: names, types or sizes.
      handle: a result handle returned by a tcldbi::sql call.
   output:
      a Tcl list of the specified type.

tcldbi::trans cmd handle
   inputs required:
      cmd: transaction type,  Can be: begin, commit, rollback or cancel.
      handle: a connection handle returned by a tcldbi::opencursor call or on some dbms's a
              handle from a tcldbi::connect call can be used.

   special:
      On dbms's that do not support this, it will have to be done in code for the dB driver.

tcldbi::autocommit cmd handle
   inputs required:
      cmd: switch, ether on or off
      handle: a connection handle returned by a tcldbi::opencursor call or on some dbms's a
              handle from a tcldbi::connect call can be used.

   special:
      On dbms's that do not support this, it will have to be done in code for the dB driver.

Optional API's (Do we want or need any of these?):

tcldbi::prepare handle sqlstr
   inputs required:
      handle: a connection handle returned from a tcldbi::connect call.
      sqlstr: the SQL string to execute.
   output:
      a result handle that will be used to call tcldbi::execute with.

   special:
      On dbms's that do not support this, it will have to be done in code for the dB driver.

tcldbi::execute
   inputs required:
      handle: a connection handle returned by a tcldbi::prepare call.
   output:
      a result handle that will be used to call tcldbi::fetch* with.

   special:
      On dbms's that do not support this, it will have to be done in code for the dB driver.

tcldbi::sqlexecimediate handle sqlstr
   inputs required:
      handle: a connection handle returned from a tcldbi::opencursor or a tcldbi::connect
              call on some dbms's.
      sqlstr: the SQL string to execute.
   output:
      a Tcl list of lists containing the fetched rows.

   special:
      On dbms's that do not support this, it will have to be done in code for the dB driver.

tcldbi::fetchall handle command
   inputs required:
      handle: a result handle returned by a tcldbi::sql call.
   inputs optional:
      command: a command or set of commands to execute on each row fetched
   output:
      a Tcl list of lists containing the fetched rows.

tcldbi::apisavailable db_type

or

tcldbi::dbmscapabilities db_type
   db_type: dB type that is being connected to, as of now it can
               be one of the following: postgres, odbc, sybase, msql, oracle
   output:
      a Tcl list containing the supported tcldbi:: API's and/or the capabilities
      supported by the given driver.

tcldbi:: variables
   tcldbi::eors
      signifies where the end of a result set has been reached.

   tcldbi::errno
      tcldbi generated error number.

   tcldbi::errstr
      tcldbi generated error string.

   tcldbi::native_errno
      dbms generated error number.

   tcldbi::native_errstr
      dbms generated error string.

   tcldbi::rowcount
      rows affected or returned from call to tcldbi::sql