Every database driver for TDBC (Tcl DataBase Connectivity) implements a connection object that represents
a connection to a database. By convention, this object is created by the command,
tdbc::driver::connectioncreate. This command accepts the name of a Tcl command that will represent the
connection and a possible set of options (see CONFIGURATIONOPTIONS). It establishes a connection to the
database and returns the name of the newly-created Tcl command.
The configure object command on a database connection, if presented with no arguments, returns a list of
alternating keywords and values representing the connection's current configuration. If presented with a
single argument -option, it returns the configured value of the given option. Otherwise, it must be given
an even number of arguments which are alternating options and values. The specified options receive the
specified values, and nothing is returned.
The close object command on a database connection closes the connection. All active statements and result
sets on the connection are closed. Any uncommitted transaction is rolled back. The object command is
deleted.
The prepare object command on a database connection prepares a SQL statement for execution. The sql-code
argument must contain a single SQL statement to be executed. Bound variables may be included. The return
value is a newly-created Tcl command that represents the statement. See tdbc::statement for more detailed
discussion of the SQL accepted by the prepare object command and the interface accepted by a statement.
On a database connection where the underlying database and driver support stored procedures, the
preparecall object command prepares a call to a stored procedure for execution. The syntax of the stored
procedure call is:
?resultvar =? procname(?arg ?, arg...?)
The return value is a newly-created Tcl command that represents the statement. See tdbc::statement for
the interface accepted by a statement.
The statements object command returns a list of statements that have been created by prepare and
preparecall statements against the given connection and have not yet been closed.
The resultsets object command returns a list of result sets that have been obtained by executing
statements prepared using the given connection and not yet closed.
The tables object command allows the program to query the connection for the names of tables that exist
in the database. The optional pattern parameter is a pattern to match the name of a table. It may
contain the SQL wild-card characters '%' and and whose values are subdictionaries. See the documentation
for the individual database driver for the interpretation of the values.
The columns object command allows the program to query the connection for the names of columns that exist
in a given table. The optional pattern parameter is a pattern to match the name of a column. It may
contain the SQL wild-card characters '%' and and whose values are dictionaries. Each of the
subdictionaries will contain at least the following keys and values (and may contain others whose usage
is determined by a specific database driver).
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 $connectionallrows-asdicts). 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 table's 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 table's 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 (-foreigntableName), the keys that refer to a particular table (-primarytableName), 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 $connectionallrows-asdicts). 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,
SETDEFAULT, SETNULL, RESTRICT, or NOACTION.
deleteAction
Action to take when a DELETE statement invalidates the constraint. The value will be CASCADE, SETDEFAULT, SETNULL, RESTRICT, or NOACTION.
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 begintransaction object command on a database connection begins a transaction on the database. If the
underlying database does not support atomic, consistent, isolated, durable transactions, the
begintransaction object command returns an error reporting the fact. Similarly, if multiple
begintransaction commands are executed withough an intervening commit or rollback command, an error is
returned unless the underlying database supports nested transactions.
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
caller's 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.
Install Now
PNG Icons
