|
ns_db — Access a database
package require nstcl-database ?1.0?
package require nstcl ?1.0?
::nstcl::ns_db option ?arg ? ?... ?
This command allows access to one or more database(s).
- ns_db bindrow dbhandle
- Returns an ns_set whose keys correspond to the column names returned from the database after an SQL statement was executed from ns_db exec. If the result from ns_db exec was not NS_ROWS (i.e. the SQL was a DDL or DML statement, and not a query), then an error will be thrown.
- ns_db bouncepool dbhandle
- Marks all of the handle(s) from the pool that dbhandle is a member of as stale, causing the database connection(s) to be reset upon subsequent use.
- ns_db cancel dbhandle
- Cancels the current operation (essentially the same thing as ns_db flush dbhandle).
- ns_db close dbhandle
- Close dbhandle's connection to the database. This should only be used with handles obtained from ns_db open.
- ns_db connected dbhandle
- As currently implemented, a boolean value of 1 is always returned.
- ns_db datasource dbhandle
- Returns the data source for the database pool that dbhandle is a member of.
- ns_db dbtype dbhandle
- Returns the type of database that dbhandle is connected to (i.e. "Oracle", "Postgres", etc.)
- ns_db dml dbhandle sql
- Execute a DML (or DDL) sql statement (such as an "insert", "update", "create table", etc.)
- ns_db driver dbhandle
- Returns the name of the database driver of the handle.
- ns_db exception dbhandle
- Returns the most recent error message (if any) for dbhandle.
- ns_db exec dbhandle sql
- Executes a sql statement, and returns NS_ROWS (if the sql statement was a query), or NS_DML (if the sql statement was a DML or DDL command).
If the sql statement raises an exception in the database, then an error is thrown.
- ns_db flush dbhandle
- Flushes the pending results from the previous SQL select statement (freeing you from having to call ns_db getrow repeatedly to cycle through the entire result set).
- ns_db gethandle ?-timeout timeout? ?poolname? ?nhandles?
- ns_db gethandle returns the specified number of handles (in the form of a Tcl list) for the given pool.
The -timeout timeout switch is included for source compatability with AOLserver. However, since nstcl is designed to be used in a single threaded enviroment, there is nothing to wait on, and this switch is ignored.
If poolname is not specified, handle(s) from the default pool will be returned. In nstcl the "default pool" is either the pool explicity set as the default with a call to ::nstcl::set_default_pool, or the only pool (if only a single pool has been defined). There is no default pool if multiple pools have been created and none of them have been set as the default. In this case calling ns_db gethandle without a poolname results in an error.
The nhandles defaults to one. An error will be thrown if you attempt to allocate more handles than have been defined for a pool.
Each handle returned by ns_db gethandle needs (eventually) to be released with an explicit call to ns_db releasehandle. Until you have released all the handles you have from a particular pool you will not be able to get any more handles from the same pool.
- ns_db getrow dbhandle setId
- Fetches the next row from the database after an initial call to ns_db select and places it in the setId ns_set (which should normally be the same set returned by ns_db select).
As long as there is at least one row remaining in the databases result set ns_db getrow will return 1. When the last row is fetched, ns_db getrow will return 0, and any subsequent call (barring another query first) will raise an error.
- ns_db open driver datasource user password
- This opens a single connection to a database outside of the handle(s) in the defined database pool(s). A database handle returned if the connection is opened successfully, or any error in opening the connection is propogated.
- ns_db poolname dbhandle
- Returns the name of the database pool that dbhandle came from.
- ns_db pools
- Returns a list of all of the defined database pools.
- ns_db releasehandle dbhandle
- Places dbhandle back into the list of available database handles of the pool it belongs to. Unlike AOLserver, which has a concept of the lifetime of a connection, and will automatically release allocated handles at the end of the connection, with nstcl you must explicitly release every handle you use when you are done with it.
- ns_db 1row dbhandle SQL
- Assuming that SQL is a query that will return exactly one row (an error is thrown if this assumption turns out to be false), the row is returned as an ns_set.
- ns_db 0or1row dbhandle SQL
- Assuming that SQL is a query that will return at most one row (an error is thrown if this assumption turns out to be false), either an empty string (when the database returns no rows), or an ns_set is returned (when the database returns one row).
- ns_db password dbhandle
- Returns the database password specified when the pool (of which dbhandle is a member of) was configured.
- ns_db select dbhandle SQL
- Executes the SQL query on the database and returns an ns_set whose keys correspond to the column names selected. Use ns_db getrow to retrieve the actual result rows. You cannot call ns_db select a second time (with the same dbhandle) until you have retrieved all the rows or called ns_db flush.
- ns_db setexception dbhandle code message
- Returns the specified status code and message.
- ns_db user dbhandle
- Returns the database username specified when the pool (of which dbhandle is a member of) was configured.
- ns_db verbose dbhandle ?on | off?
- Queries (or changes) the verbosity setting of dbhandle's database pool.
database, nstcl