Updated 2013-09-10 19:26:46 by pooryorick

nstcl is is a Tcl package which reimplements many of the useful APIs and commands from AOLserver and OpenACS, making them available for use in Tcl/Tk applications & scripts.

Attributes  edit

current release
release time
Michael Cleverly

See Also  edit

database interface
another interpretation of a database API, from naviserver
Introduction to Database Access with nstcl

Components  edit

nstcl is grouped into a set of subpackages, including:

Most notable of these is the nstcl-database package, and the "ns_db" API, which provides a common interface to various different database extensions.

As of version 1.0 nstcl now supports the following databases:

Extending nstcl to support a new database extension involves writing a half dozen or so (mostly trivial) procs.

nstcl makes use of string subcommands, such as string map that first appeared in Tcl 8.2. As a result, use with a modern Tcl (8.3.4+) is preferred. However, for those stuck with an older version of Tcl, a set of so-called "forward compatability" procs are provided that enable nstcl to function on Tcl 8.0+.

Database access requires a supported database extension. Certain features of nstcl make use of packages from tcllib. See the README [1] for details.

nstcl is distributed under the terms of the MIT/X11 license (essentially the equivalent of the original BSD license without the advertising clause) [2].

AK: I took a cursory look at the documentation and did not see any obvious place explaining which six procedures to implement for a new database. On the Tcl Chatroom we already had the question how to connect nstcl and Metakit.

MC: See the "Implementing a New Driver" section of the man page for load_driver. [3] The functions are:

  • nstcl::database::${TYPE}::load_driver (does the package require or loads the .so)
  • nstcl::database::${TYPE}::dbtype (returns a single string indicating what type of database, i.e. "Metakit")

Then the six functions that actually interact with the database:

  • nstcl::database::${TYPE}::bindrow (create the ns_set that will contain the column names of the database columns returned by the query. The column values are populated with the call to getrow)
  • nstcl::database::${TYPE}::close (close a connection to the database)
  • nstcl::database::${TYPE}::exec (execute DDL/DML/query)
  • nstcl::database::${TYPE}::flush (throws away any unretrieved pending results)
  • nstcl::database::${TYPE}::gethandle (get a handle to the database)
  • nstcl::database::${TYPE}::getrow (gets the next result in the result set from a prior query)

My general advice would be for people to take a look at the nstcl-database-*.tcl file(s) for the database extension(s) that they're already familliar with. Of course, I'd be happy to write more specific docs too, if that would help.


[email protected] points out that this module is tremendously useful for anything to do with databases; for data migration (eg from Oracle to Postgres) and database importing (package require csv then foreach to import and enter data from CSV files). Once you get the hang of nstcl developing db-backed applications is quite easy. Would like to hear from anyone that is using it inside of tclhttpd - the templating part could serve as a sort of ASP like language for use with tclhttpd.

RLH 2005-11-16: Is nstcl still being maintained? I see from the site that 2002 was the last release. It seems with a little spit and polish this could be very nice indeed.

escargo: SourceForge shows some CVS commits from 2 years ago, plus 5 open bugs. Nothing has changed recently.

RLH: Yes but I wonder if it has been "abandoned"...

MC 2005-11-17: I'd classify it more as "mature" than "abandoned". Once Tcl 8.5 is out of alpha I plan on updating nstcl to use the various goodies that 8.5 provides (dicts, {*}, namespace ensembles, etc.).

RLH Very cool...

escargo 2006-10-23: With Tcl 8.5 still a ways out, has there been any activity? I'm thinking that I might want to use this with Metakit to allow something to be unit tested with Metakit before being deployed with Oracle. (escargo 25 Nov 2006 - Or maybe with SQLite.)

escargo 2012-10-19: According to Tcl/Tk 8.5 Roadmap, Tcl 8.5 was released in 2007. Were any updates made to nstcl?

Silas - if you get the following error:
Connection to database failed
could not connect to server: No such file or directory
      Is the server running locally and accepting
      connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"?

Try something like (in nstcl::configure_pool):
nstcl::configure_pool -immediately postgres $your_database 1 localhost:5432:$your_database