Tcl Database Connectivity

Whenever a TDBC driver reports an error in interacting with an underlying database, it SHOULD set the interpreter error code to a list of at least four elements. The first element should be the constant string TDBC. The second should be an 'error class' chosen from the list below. The third should be the (usually five-character) SQL state that the database reported, or the constant string HY000 if the SQL state cannot be determined. (In the latter case, the error class should be GENERAL_ERROR.) The fourth element should be the name of the TDBC driver that reported the error. Any elements beyond the fourth SHOULD give further details (for example an error code returned by a native API), and are driver dependent. The permissible values for the error class are as follows. Note that each one corresponds to the first two characters of a five-character 'SQL state' that is common to most SQL database API's; the SQL state corresponding to the class is also given. IFNRTCBTdGF0ZQ==IFByZWZpeCAgICAgRXJyb3IgQ2xhc3M=IC0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tICAgIDAwICAgICAgVU5RVUFMSUZJRURfU1VDQ0VTU0ZVTF9DT01QTEVUSU9OICAgIDAxICAgICAgV0FSTklORw==ICAgIDAyICAgICAgTk9fREFUQQ==ICAgIDA3ICAgICAgRFlOQU1JQ19TUUxfRVJST1I=ICAgIDA4ICAgICAgQ09OTkVDVElPTl9FWENFUFRJT04=ICAgIDA5ICAgICAgVFJJR0dFUkVEX0FDVElPTl9FWENFUFRJT04=ICAgIDBBICAgICAgRkVBVFVSRV9OT1RfU1VQUE9SVEVEICAgIDBCICAgICAgSU5WQUxJRF9UUkFOU0FDVElPTl9JTklUSUFUSU9OICAgIDBEICAgICAgSU5WQUxJRF9UQVJHRVRfVFlQRV9TUEVDSUZJQ0FUSU9OICAgIDBGICAgICAgTE9DQVRPUl9FWENFUFRJT04=ICAgIDBLICAgICAgSU5WQUxJRF9SRVNJR05BTF9TVEFURU1FTlQ=ICAgIDBMICAgICAgSU5WQUxJRF9HUkFOVE9SICAgIDBQICAgICAgSU5WQUxJRF9ST0xFX1NQRUNJRklDQVRJT04=ICAgIDBXICAgICAgSU5WQUxJRF9TVEFURU1FTlRfVU5fVFJJR0dFUg==ICAgIDIwICAgICAgQ0FTRV9OT1RfRk9VTkRfRk9SX0NBU0VfU1RBVEVNRU5UICAgIDIxICAgICAgQ0FSRElOQUxJVFlfVklPTEFUSU9OICAgIDIyICAgICAgREFUQV9FWENFUFRJT04=ICAgIDIzICAgICAgQ09OU1RSQUlOVF9WSU9MQVRJT04=ICAgIDI0ICAgICAgSU5WQUxJRF9DVVJTT1JfU1RBVEU=ICAgIDI1ICAgICAgSU5WQUxJRF9UUkFOU0FDVElPTl9TVEFURQ==ICAgIDI2ICAgICAgSU5WQUxJRF9TUUxfU1RBVEVNRU5UX0lERU5USUZJRVI=ICAgIDI3ICAgICAgVFJJR0dFUkVEX0RBVEFfQ0hBTkdFX1ZJT0xBVElPTg==ICAgIDI4ICAgICAgSU5WQUxJRF9BVVRIT1JJWkFUSU9OX1NQRUNJRklDQVRJT04=ICAgIDJCICAgICAgREVQRU5ERU5UX1BSSVZJTEVHRV9ERVNDUklQVE9SU19TVElMTF9FWElTVA==ICAgIDJDICAgICAgSU5WQUxJRF9DSEFSQUNURVJfU0VUX05BTUU=ICAgIDJEICAgICAgSU5WQUxJRF9UUkFOU0FDVElPTl9URVJNSU5BVElPTg==ICAgIDJFICAgICAgSU5WQUxJRF9DT05ORUNUSU9OX05BTUU=ICAgIDJGICAgICAgU1FMX1JPVVRJTkVfRVhDRVBUSU9OICAgIDMzICAgICAgSU5WQUxJRF9TUUxfREVTQ1JJUFRPUl9OQU1FICAgIDM0ICAgICAgSU5WQUxJRF9DVVJTT1JfTkFNRQ==ICAgIDM1ICAgICAgSU5WQUxJRF9DT05ESVRJT05fTlVNQkVSICAgIDM2ICAgICAgQ1VSU09SX1NFTlNJVElWSVRZX0VYQ0VQVElPTg==ICAgIDM3ICAgICAgU1lOVEFYX0VSUk9SX09SX0FDQ0VTU19WSU9MQVRJT04=ICAgIDM4ICAgICAgRVhURVJOQUxfUk9VVElORV9FWENFUFRJT04=ICAgIDM5ICAgICAgRVhURVJOQUxfUk9VVElORV9JTlZPQ0FUSU9OX0VYQ0VQVElPTg==ICAgIDNCICAgICAgU0FWRVBPSU5UX0VYQ0VQVElPTg==ICAgIDNDICAgICAgQU1CSUdVT1VTX0NVUlNPUl9OQU1FICAgIDNEICAgICAgSU5WQUxJRF9DQVRBTE9HX05BTUU=ICAgIDNGICAgICAgSU5WQUxJRF9TQ0hFTUFfTkFNRQ==ICAgIDQwICAgICAgVFJBTlNBQ1RJT05fUk9MTEJBQ0s=ICAgIDQyICAgICAgU1lOVEFYX0VSUk9SX09SX0FDQ0VTU19SVUxFX1ZJT0xBVElPTg==ICAgIDQ0ICAgICAgV0lUSF9DSEVDS19PUFRJT05fVklPTEFUSU9OICAgIDQ1ICAgICAgVU5IQU5ETEVEX1VTRVJfREVGSU5FRF9FWENFUFRJT04=ICAgIDQ2ICAgICAgSkFWQV9EREw=ICAgIDUxICAgICAgSU5WQUxJRF9BUFBMSUNBVElPTl9TVEFURQ==ICAgIDUzICAgICAgSU5TVUZGSUNJRU5UX1JFU09VUkNFUw==ICAgIDU0ICAgICAgUFJPR1JBTV9MSU1JVF9FWENFRURFRA==ICAgIDU1ICAgICAgT0JKRUNUX05PVF9JTl9QUkVSRVFVSVNJVEVfU1RBVEU=ICAgIDU2ICAgICAgTUlTQ0VMTEFORU9VU19TUUxfT1JfUFJPRFVDVF9FUlJPUg==ICAgIDU3ICAgICAgUkVTT1VSQ0VfTk9UX0FWQUlMQUJMRV9PUl9PUEVSQVRPUl9JTlRFUlZFTlRJT04=ICAgIDU4ICAgICAgU1lTVEVNX0VSUk9SICAgIDcwICAgICAgSU5URVJSVVBURUQ=ICAgIEYwICAgICAgQ09ORklHVVJBVElPTl9GSUxFX0VSUk9SICAgIEhZICAgICAgR0VORVJBTF9FUlJPUg==ICAgIEhaICAgICAgUkVNT1RFX0RBVEFCQVNFX0FDQ0VTU19FUlJPUg==ICAgIElNICAgICAgRFJJVkVSX0VSUk9SICAgIFAwICAgICAgUEdTUUxfUExTUUxfRVJST1I=ICAgIFMwICAgICAgT0RCQ18yXzBfRE1MX0VSUk9SICAgIFMxICAgICAgT0RCQ18yXzBfR0VORVJBTF9FUlJPUg==ICAgIFhBICAgICAgVFJBTlNBQ1RJT05fRVJST1I=ICAgIFhYICAgICAgSU5URVJOQUxfRVJST1I=ICBhbnl0aGluZw==ICAgZWxzZSAgICAgVU5LTk9XTl9TUUxTVEFURQ== The reason for structuring the error codes in this way is to make errors more accessible to the try command . For instance, a Tcl script that wishes to detect and handle division by zero in a SQL statement might look like: ICB0cnkgew==ICAgICAgJHN0YXRlbWVudCBmb3JlYWNoIHJvdyB7ICAgICAgICAgICMgLi4uIHByb2Nlc3MgdGhlIHJvdw==ICAgICAgfQ==IH0gdHJhcCB7VERCQyBEQVRBX0VYQ0VQVElPTiAyMjAxMn0gew==ICAgICAgcHV0cyAiRGl2aXNpb24gYnkgemVybyEiIH0= Since the previous specification left the error code unspecified, this change is not expected to impact any client code. The begintransaction method was inadvertently called, starttransaction in the TDBC specification. Therefore, the word starttransaction should be replaced with begintransaction wherever it appears. This change will break no existing code; no starttransaction method has been defined for any TDBC driver. The rule that an array variable provided as a bound value to a substituent in a SQL statement MUST result in an error has proven to be awkward to implement in practice. Moreover, the original specification fails to indicate what happens if a read trace on one of a statement's bound variables throws an error. The sentence, An array variable provided to a substituent MUST result in an error. is therefore to be replaced with: An array variable provided to a substituent, or a variable in which substitution results in an error being reported by a read trace, MUST result in a NULL value being provided. This change is expected to have minimal impact on existing code; the behaviour being described is simply providing a NULL value for a case that was an error before (an array where a scalar is expected) and a case that was unspecified before (an error within a variable trace). The syntax of the foreach method of connections, statements, and result sets in the original specification contains editorial errors. The correct syntax is: dbHandle foreach ?-as lists|dicts? ?-columnsvariable varName? ?--? varName sql ?dictionary? script statement foreach ?-as lists|dicts? ?-columnsvariable varName? ?--? varName ?dictionary? script resultset foreach ?-as lists|dicts? ?-columnsvariable varName? ?--? varName script This change represents an editorial correction; the reference implementation functioned in this way even prior to the acceptance of the original specification . The statementClass variable, and the init method, are no longer recommended for use in the constructors of connection classes. Instead, the recommended pattern is that a connection class SHOULD implement a statementCreate method that accepts the fully qualified name of the command that is to represent the statement, the connection handle and the SQL statement, and returns a handle to the statement object. The usual way to do so is with a forwarded method: ICBmb3J3YXJkIHN0YXRlbWVudENyZWF0ZSA6OmRyaXZlcjo6c3RhdGVtZW50IGNyZWF0ZQ== If the statementCreate method is not present, the default one looks for a variable named statementClass in the connection object, and invokes its create command. In this way, drivers that are written to the original specification continue to operate. Similarly, the resultSetClass variable, and the init method, are no longer recommended for use in the constructors of statement classes. Instead, the statement class SHOULD implement a resultSetCreate method that accepts the fully qualified name of the command that will represent the result set, the statement handle, and the parameters to the prepare method. Once again, this method will usually simply be forwarded to the appropriate constructor: ICBmb3J3YXJkIHJlc3VsdFNldENyZWF0ZSA6OmRyaXZlcjo6cmVzdWx0U2V0IGNyZWF0ZQ== Once again, backward compatibility is provided by a resultSetCreate method in the base class. This method looks for a resultSetClass variable in the statement instance, and interprets it as a class name, invoking the create method in that class. Rationale: These changes eliminate several jumps among methods with uplevel calls, and yield both simpler code and improved performance. For the convenience of drivers that deal with database APIs that provide a standard SQL dtate in the event of errors, a Tcl command, tdbc::mapSqlState is provided. This command accepts a (usually five character) SQL state, and returns the error class that should go in the second element of the error code. The mapping is described in the table in the Error Codes section above. Similarly, A C function is provided: const char * Tdbc_MapSqlState(const char *sqlstate); This call looks up the given sqlstate and returns its error class according to the table.