BeasleyTclDBI

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.

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

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

Category Package

Category Database

Description edit

See Also edit

Proposed API edit