NAME

       Tdbc_Init, Tdbc_MapSqlState, Tdbc_TokenizeSql - C procedures to facilitate writing TDBC drivers

SYNOPSIS

       #include <tdbc.h>

       int
       Tdbc_Init(interp)

       Tcl_Obj *
       Tdbc_TokenizeSql(interp, sqlcode)

       const char *
       Tdbc_MapSqlState(state)

ARGUMENTS

       Tcl_Interp *interp (in/out)        Pointer to a Tcl interpreter.

       const char *state (in)             Pointer to a character string containing a 'SQL state' from a database
                                          error.

       const char *sqlcode (in)           Pointer to a character string containing a SQL statement.
________________________________________________________________________________________________________________

DESCRIPTION

       The  TDBC  library  provides  several  C  procedures  that simplify writing a TDBC driver. They include a
       procedure that tokenizes a SQL statement, locating variables to be  substituted,  and  a  procedure  that
       accepts a SQL state and returns an error class for the interpreter error information.

       Tdbc_Init  must  be invoked prior to any other TDBC call.  It accepts a pointer to a Tcl interpreter, and
       arranges to load the TDBC library. It returns TCL_OK if the Tcl  library  was  loaded  successfully,  and
       TCL_ERROR otherwise. If TCL_ERROR is returned, the interpreter's result contains the error message.

       Tdbc_TokenizeSql  accepts  a pointer to a Tcl interpreter, and a pointer to a character string containing
       one or more SQL statements. It tokenizes the SQL statements, and returns a  pointer  to  a  Tcl_Obj  that
       contains  a  list  of the tokens that make up the statement. Concatenating the tokens together will yield
       the original SQL code. The returned Tcl_Obj has a reference count of zero. The caller is responsible  for
       managing  the  reference  count  as  needed.   See  TOKENS  below for a description of what may be in the
       returned list of tokens.

       Tdbc_MapSqlState accepts a pointer to a string, usually five characters long, that  is  the  'SQL  state'
       that  resulted from a database error. It returns a character string that is suitable for inclusion as the
       error class when constructing the error code for an error in a TDBC driver.  (By  convention,  the  error
       code is a list having at least four elements: "TDBC errorClass sqlstate driverName details...".)

TOKENS

       Each token returned from Tdbc_TokenizeSql may be one of the following:

       [1]    A  bound  variable, which begins with one of the characters ':', '@', or '$'. The remainder of the
              string is the variable name and will consist of  alphanumeric  characters  and  underscores.  (The
              leading character will be be non-numeric.)

       [2]    A semicolon that separates two SQL statements.

       [3]    Something  else  in  a  SQL  statement.  The  tokenizer  does  not attempt to parse SQL; it merely
              identifies bound variables (distinguishing them from similar strings appearing  inside  quotes  or
              comments) and statement delimiters.

SEE ALSO

       tdbc(3tcl), tdbc::mapSqlState(3tcl), tdbc::tokenize(3tcl)

KEYWORDS

       TDBC, SQL, database, tokenize

COPYRIGHT

       Copyright (c) 2009 by Kevin B. Kenny.

Tcl                                                    8.6                                          Tdbc_Init(3)