|type||Contains the data type of the column, and will generally be chosen from the set, bigint, binary, bit, char, date, decimal, double, float, integer, longvarbinary, longvarchar, numeric, real, time, timestamp, smallint, tinyint, varbinary, and varchar. (If the column has a type that cannot be represented as one of the above, type will contain a driver-dependent description of the type.)|
|precision||Contains the precision of the column in bits, decimal digits, or the width in characters, according to the type.|
|scale||Contains the scale of the column (the number of digits after the radix point), for types that support the concept.|
|nullable||Contains 1 if the column can contain NULL values, and 0 otherwise.|
|The primarykeys object command allows the program to query the connection for the primary keys belonging to a given table. The tableName parameter identifies the table being interrogated. The result is a list of dictionaries enumerating the keys (in a similar format to the list returned by $connection allrows -as dicts). The keys of the dictionary may include at least the following. Values that are NULL or meaningless in a given database are omitted.|
|tableCatalog||Name of the catalog in which the table appears.|
|tableSchema||Name of the schema in which the table appears.|
|tableName||Name of the table owning the primary key.|
|constraintCatalog||Name of the catalog in which the primary key constraint appears. In some database systems, this may not be the same as the tables catalog.|
|constraintSchema||Name of the schema in which the primary key constraint appears. In some database systems, this may not be the same as the tables schema.|
|constraintName||Name of the primary key constraint,|
|columnName||Name of a column that is a member of the primary key.|
|ordinalPosition||Ordinal position of the column within the primary key.|
|To these columns may be added additional ones that are specific to a particular database system.|
|The foreignkeys object command allows the program to query the connection for foreign key relationships that apply to a particular table. The relationships may be constrained to the keys that appear in a particular table (-foreign tableName), the keys that refer to a particular table (-primary tableName), or both. At least one of -primary and -foreign should be specified, although some drivers will enumerate all foreign keys in the current catalog if both options are omitted. The result of the foreignkeys object command is a list of dictionaries, with one list element per key (in a similar format to the list returned by $connection allrows -as dicts). The keys of the dictionary may include at least the following. Values that are NULL or meaningless in a given database are omitted.|
|foreignConstraintCatalog||Catalog in which the foreign key constraint appears.|
|foreignConstraintSchema||Schema in which the foreign key constraint appears.|
|foreignConstraintName||Name of the foreign key constraint.|
|primaryConstraintCatalog||Catalog holding the primary key constraint (or unique key constraint) on the column to which the foreign key refers.|
|primaryConstraintSchema||Schema holding the primary key constraint (or unique key constraint) on the column to which the foreign key refers.|
|primaryConstraintName||Name of the primary key constraint (or unique key constraint) on the column to which the foreign key refers.|
|updateAction||Action to take when an UPDATE statement invalidates the constraint. The value will be CASCADE, SET DEFAULT, SET NULL, RESTRICT, or NO ACTION.|
|deleteAction||Action to take when a DELETE statement invalidates the constraint. The value will be CASCADE, SET DEFAULT, SET NULL, RESTRICT, or NO ACTION.|
|primaryCatalog||Catalog name in which the primary table (the one to which the foreign key refers) appears.|
|primarySchema||Schema name in which the primary table (the one to which the foreign key refers) appears.|
|primaryTable||Table name of the primary table (the one to which the foreign key refers).|
|primaryColumn||Name of the column to which the foreign key refers.|
|foreignCatalog||Name of the catalog in which the table containing the foreign key appears.|
|foreignSchema||Name of the schema in which the table containing the foreign key appears.|
|foreignTable||Name of the table containing the foreign key.|
|foreignColumn||Name of the column appearing in the foreign key.|
|ordinalPosition||Position of the column in the foreign key, if the key is a compound key.|
The commit object command on a database connection ends the most recent transaction started by begintransaction and commits changes to the database.
The rollback object command on a database connection rolls back the most recent transaction started by begintransaction. The state of the database is as if nothing happened during the transaction.
The transaction object command on a database connection presents a simple way of bundling a database transaction. It begins a transaction, and evaluates the supplied script argument as a Tcl script in the callers scope. If script terminates normally, or by break, continue, or return, the transaction is committed (and any action requested by break, continue, or return takes place). If the commit fails for any reason, the error in the commit is treated as an error in the script. In the case of an error in script or in the commit, the transaction is rolled back and the error is rethrown. Any nonstandard return code from the script causes the transaction to be rolled back and then is rethrown.
The allrows object command prepares a SQL statement (given by the sql-code parameter) to execute against the database. It then executes it (see tdbc::statement for details) with the optional dictionary parameter giving bind variables. Finally, it uses the allrows object command on the result set (see tdbc::resultset) to construct a list of the results. Finally, both result set and statement are closed. The return value is the list of results.
The foreach object command prepares a SQL statement (given by the sql-code parameter) to execute against the database. It then executes it (see tdbc::statement for details) with the optional dictionary parameter giving bind variables. Finally, it uses the foreach object command on the result set (see tdbc::resultset) to evaluate the given script for each row of the results. Finally, both result set and statement are closed, even if the given script results in a return, an error, or an unusual return code.
The configuration options accepted when the connection is created and on the connections configure object command include the following, and may include others specific to a database driver.
-encoding name Specifies the encoding to be used in connecting to the database. The name should be one of the names accepted by the encoding command. This option is usually unnecessary; most database drivers can figure out the encoding in use by themselves. -isolation level Specifies the transaction isolation level needed for transactions on the database. The acceptable values for level are shown under TRANSACTION ISOLATION LEVELS. -timeout ms Specifies the maximum time to wait for a an operation database engine before reporting an error to the caller. The ms argument gives the maximum time in milliseconds. A value of zero (the default) specifies that the calling process is to wait indefinitely for database operations. -readonly flag Specifies that the connection will not modify the database (if the Boolean parameter flag is true), or that it may modify the database (if flag is false). If flag is true, this option may have the effect of raising the transaction isolation level to readonly.
The acceptable values for the -isolation configuration option are as follows:
A database that does not implement one of these isolation levels will instead use the next more restrictive isolation level. If the given level of isolation cannot be obtained, the database interface throws an error reporting the fact. The default isolation level is readcommitted.
readuncommitted Allows the transaction to read "dirty", that is, uncommitted data. This isolation level may compromise data integrity, does not guarantee that foreign keys or uniqueness constraints are satisfied, and in general does not guarantee data consistency. readcommitted Forbids the transaction from reading "dirty" data, but does not guarantee repeatable reads; if a transaction reads a row of a database at a given time, there is no guarantee that the same row will be available at a later time in the same transaction. repeatableread Guarantees that any row of the database, once read, will have the same values for the life of a transaction. Still permits "phantom reads" (that is, newly-added rows appearing if a table is queried a second time). serializable The most restrictive (and most expensive) level of transaction isolation. Any query to the database, if repeated, will return precisely the same results for the life of the transaction, exactly as if the transaction is the only user of the database. readonly Behaves like serializable in that the only results visible to the transaction are those that were committed prior to the start of the transaction, but forbids the transaction from modifying the database.
A script should not the isolation level when a transaction is in progress.
encoding(n), tdbc(n), tdbc::resultset(n), tdbc::statement(n), tdbc::tokenize(n)
TDBC, SQL, database, connectivity, connection, resultset, statement
Copyright (c) 2008 by Kevin B. Kenny.