util/X86LINUX64/share/man/man3/Tdbc_Init.3

   1 '\"
   2 '\" Copyright (c) 2009 by Kevin B. Kenny.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 .TH Tdbc_Init 3 8.6 Tcl "Tcl Database Connectivity"
   7 '\" .so man.macros
   8 '\" IGNORE
   9 .if t .wh -1.3i ^B
  10 .nr ^l \n(.l
  11 .ad b
  12 .de AP
  13 .ie !"\\$4"" .TP \\$4
  14 .el \{\
  15 .   ie !"\\$2"" .TP \\n()Cu
  16 .   el          .TP 15
  17 .\}
  18 .ta \\n()Au \\n()Bu
  19 .ie !"\\$3"" \{\
  20 \&\\$1 \\fI\\$2\\fP (\\$3)
  21 .\".b
  22 .\}
  23 .el \{\
  24 .br
  25 .ie !"\\$2"" \{\
  26 \&\\$1  \\fI\\$2\\fP
  27 .\}
  28 .el \{\
  29 \&\\fI\\$1\\fP
  30 .\}
  31 .\}
  32 ..
  33 .\"     # define tabbing values for .AP
  34 .de AS
  35 .nr )A 10n
  36 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  37 .nr )B \\n()Au+15n
  38 .\"
  39 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  40 .nr )C \\n()Bu+\\w'(in/out)'u+2n
  41 ..
  42 .AS Tcl_Interp Tcl_CreateInterp in/out
  43 .\"     # BS - start boxed text
  44 .\"     # ^y = starting y location
  45 .\"     # ^b = 1
  46 .de BS
  47 .br
  48 .mk ^y
  49 .nr ^b 1u
  50 .if n .nf
  51 .if n .ti 0
  52 .if n \l'\\n(.lu\(ul'
  53 .if n .fi
  54 ..
  55 .\"     # BE - end boxed text (draw box now)
  56 .de BE
  57 .nf
  58 .ti 0
  59 .mk ^t
  60 .ie n \l'\\n(^lu\(ul'
  61 .el \{\
  62 .\"     Draw four-sided box normally, but don't draw top of
  63 .\"     box if the box started on an earlier page.
  64 .ie !\\n(^b-1 \{\
  65 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  66 .\}
  67 .el \}\
  68 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  69 .\}
  70 .\}
  71 .fi
  72 .br
  73 .nr ^b 0
  74 ..
  75 .\"     # CS - begin code excerpt
  76 .de CS
  77 .RS
  78 .nf
  79 .ta .25i .5i .75i 1i
  80 ..
  81 .\"     # CE - end code excerpt
  82 .de CE
  83 .fi
  84 .RE
  85 ..
  86 '\" END IGNORE
  87 .BS
  88 .SH "NAME"
  89 Tdbc_Init, Tdbc_MapSqlState, Tdbc_TokenizeSql \- C procedures to facilitate writing TDBC drivers
  90 .SH SYNOPSIS
  91 .nf
  92 \fB#include <tdbc.h>\fR
  93
  94 int
  95 \fBTdbc_Init\fR(\fIinterp\fR)
  96
  97 Tcl_Obj *
  98 \fBTdbc_TokenizeSql\fR(\fIinterp, sqlcode\fR)
  99
 100 const char *
 101 \fBTdbc_MapSqlState\fR(\fIstate\fR)
 102 .fi
 103 .SH ARGUMENTS
 104 .AS "Tcl_Interp" statement in/out
 105 .AP Tcl_Interp *interp in/out
 106 Pointer to a Tcl interpreter.
 107 .AP "const char" *state in
 108 Pointer to a character string containing a 'SQL state' from a database error.
 109 .AP "const char" *sqlcode in
 110 Pointer to a character string containing a SQL statement.
 111 .BE
 112
 113 .SH DESCRIPTION
 114 .PP
 115 The TDBC library provides several C procedures that simplify writing a TDBC
 116 driver. They include a procedure that tokenizes a SQL statement, locating
 117 variables to be substituted, and a procedure that accepts a SQL state and
 118 returns an error class for the interpreter error information.
 119 .PP
 120 \fBTdbc_Init\fR must be invoked prior to any other TDBC call.  It accepts
 121 a pointer to a Tcl interpreter, and arranges to load the TDBC library. It
 122 returns \fBTCL_OK\fR if the Tcl library was loaded successfully, and
 123 \fBTCL_ERROR\fR otherwise. If \fBTCL_ERROR\fR is returned, the
 124 interpreter's result contains the error message.
 125 .PP
 126 \fBTdbc_TokenizeSql\fR accepts a pointer to a Tcl interpreter, and a
 127 pointer to a character string containing one or more SQL
 128 statements. It tokenizes the SQL statements, and returns a pointer to
 129 a Tcl_Obj that contains a list of the tokens that make up the
 130 statement. Concatenating the tokens together will yield the original
 131 SQL code. The returned Tcl_Obj has a reference count of zero. The
 132 caller is responsible for managing the reference count as needed.
 133 See \fBTOKENS\fR below for a description of what may be in the
 134 returned list of tokens.
 135 .PP
 136 \fBTdbc_MapSqlState\fR accepts a pointer to a string, usually five
 137 characters long, that is the 'SQL state' that resulted from a database
 138 error. It returns a character string that is suitable for inclusion as
 139 the error class when constructing the error code for an error in a
 140 TDBC driver. (By convention, the error code is a list having at least
 141 four elements: "\fBTDBC\fR \fIerrorClass\fR \fIsqlstate\fR
 142 \fIdriverName\fR \fIdetails...\fR".)
 143 .SH TOKENS
 144 Each token returned from \fBTdbc_TokenizeSql\fR may be one of the
 145 following:
 146 .IP [1]
 147 A bound variable, which begins with one of the
 148 characters '\fB:\fR', '\fB@\fR', or '\fB$\fR'. The
 149 remainder of the string is the variable
 150 name and will consist of alphanumeric characters and underscores. (The
 151 leading character will be be non-numeric.)
 152 .IP [2]
 153 A semicolon that separates two SQL statements.
 154 .IP [3]
 155 Something else in a SQL statement. The tokenizer does not attempt to
 156 parse SQL; it merely identifies bound variables (distinguishing them
 157 from similar strings appearing inside quotes or comments) and
 158 statement delimiters.
 159 .SH "SEE ALSO"
 160 tdbc(n), tdbc::mapSqlState(n), tdbc::tokenize(n)
 161 .SH "KEYWORDS"
 162 TDBC, SQL, database, tokenize
 163 .SH "COPYRIGHT"
 164 Copyright (c) 2009 by Kevin B. Kenny.
 165 .\" Local Variables:
 166 .\" mode: nroff
 167 .\" End:
 168 .\"