Fossil SCM

Reduced the set of th1-exported SQLITE_xxx constants to those which are actually used in script APIs. Minor doc updates.

stephan 2012-07-22 11:55 th1-query-api
Commit 8e0405513321df912a3abb64d92f6b3767746c0f
Parent 2b4b2a5091dc81a…
3 files changed +6 -3 +1 -1 +43 -17
~ src/th_main.c ~ test/th1-query-api-1.th1 ~ www/th1_query.wiki
M src/th_main.c
+6 -3
--- src/th_main.c
+++ src/th_main.c
@@ -2017,18 +2017,21 @@
20172017
 char buf[BufLen];
20182018
 int i, l;
20192019
 #define SET(K) l = snprintf(buf, BufLen, "%d", K); \
20202020
 Th_SetVar( interp, #K, strlen(#K), buf, l );
20212021
 SET(SQLITE_BLOB);
2022
- SET(SQLITE_DONE);
2023
- SET(SQLITE_ERROR);
20242022
 SET(SQLITE_FLOAT);
20252023
 SET(SQLITE_INTEGER);
20262024
 SET(SQLITE_NULL);
2025
+ SET(SQLITE_TEXT);
2026
+#if 0
2027
+ /* so far we don't need these in script code */
2028
+ SET(SQLITE_ERROR);
2029
+ SET(SQLITE_DONE);
20272030
 SET(SQLITE_OK);
20282031
 SET(SQLITE_ROW);
2029
- SET(SQLITE_TEXT);
2032
+#endif
20302033
 #undef SET
20312034
 int rc = TH_OK;
20322035
 static Th_Command_Reg aCommand[] = {
20332036
 {"query", queryTopLevelCmd, 0},
20342037
 {0, 0, 0}
20352038
--- src/th_main.c
+++ src/th_main.c
@@ -2017,18 +2017,21 @@
2017 char buf[BufLen];
2018 int i, l;
2019 #define SET(K) l = snprintf(buf, BufLen, "%d", K); \
2020 Th_SetVar( interp, #K, strlen(#K), buf, l );
2021 SET(SQLITE_BLOB);
2022 SET(SQLITE_DONE);
2023 SET(SQLITE_ERROR);
2024 SET(SQLITE_FLOAT);
2025 SET(SQLITE_INTEGER);
2026 SET(SQLITE_NULL);
 
 
 
 
 
2027 SET(SQLITE_OK);
2028 SET(SQLITE_ROW);
2029 SET(SQLITE_TEXT);
2030 #undef SET
2031 int rc = TH_OK;
2032 static Th_Command_Reg aCommand[] = {
2033 {"query", queryTopLevelCmd, 0},
2034 {0, 0, 0}
2035
--- src/th_main.c
+++ src/th_main.c
@@ -2017,18 +2017,21 @@
2017 char buf[BufLen];
2018 int i, l;
2019 #define SET(K) l = snprintf(buf, BufLen, "%d", K); \
2020 Th_SetVar( interp, #K, strlen(#K), buf, l );
2021 SET(SQLITE_BLOB);
 
 
2022 SET(SQLITE_FLOAT);
2023 SET(SQLITE_INTEGER);
2024 SET(SQLITE_NULL);
2025 SET(SQLITE_TEXT);
2026 #if 0
2027 /* so far we don't need these in script code */
2028 SET(SQLITE_ERROR);
2029 SET(SQLITE_DONE);
2030 SET(SQLITE_OK);
2031 SET(SQLITE_ROW);
2032 #endif
2033 #undef SET
2034 int rc = TH_OK;
2035 static Th_Command_Reg aCommand[] = {
2036 {"query", queryTopLevelCmd, 0},
2037 {0, 0, 0}
2038
M test/th1-query-api-1.th1
+1 -1
--- test/th1-query-api-1.th1
+++ test/th1-query-api-1.th1
@@ -90,11 +90,11 @@
9090
 query finalize $stmt
9191
 if { 0 != $rc } {
9292
 puts "ERROR: $rc\n"
9393
 }
9494
95
-set consts [list SQLITE_BLOB SQLITE_DONE SQLITE_ERROR SQLITE_FLOAT SQLITE_INTEGER SQLITE_NULL SQLITE_OK SQLITE_ROW SQLITE_TEXT]
95
+set consts [list SQLITE_BLOB SQLITE_FLOAT SQLITE_INTEGER SQLITE_NULL SQLITE_TEXT]
9696
 #set consts $SQLITE_CONSTANTS
9797
 puts consts = $consts "\n"
9898
 for {set i 0} {$i < [llength $consts]} {incr i} {
9999
 set x [lindex $consts $i]
100100
 puts \$$x = [expr \$$x] "\n"
101101
--- test/th1-query-api-1.th1
+++ test/th1-query-api-1.th1
@@ -90,11 +90,11 @@
90 query finalize $stmt
91 if { 0 != $rc } {
92 puts "ERROR: $rc\n"
93 }
94
95 set consts [list SQLITE_BLOB SQLITE_DONE SQLITE_ERROR SQLITE_FLOAT SQLITE_INTEGER SQLITE_NULL SQLITE_OK SQLITE_ROW SQLITE_TEXT]
96 #set consts $SQLITE_CONSTANTS
97 puts consts = $consts "\n"
98 for {set i 0} {$i < [llength $consts]} {incr i} {
99 set x [lindex $consts $i]
100 puts \$$x = [expr \$$x] "\n"
101
--- test/th1-query-api-1.th1
+++ test/th1-query-api-1.th1
@@ -90,11 +90,11 @@
90 query finalize $stmt
91 if { 0 != $rc } {
92 puts "ERROR: $rc\n"
93 }
94
95 set consts [list SQLITE_BLOB SQLITE_FLOAT SQLITE_INTEGER SQLITE_NULL SQLITE_TEXT]
96 #set consts $SQLITE_CONSTANTS
97 puts consts = $consts "\n"
98 for {set i 0} {$i < [llength $consts]} {incr i} {
99 set x [lindex $consts $i]
100 puts \$$x = [expr \$$x] "\n"
101
M www/th1_query.wiki
+43 -17
--- www/th1_query.wiki
+++ www/th1_query.wiki
@@ -31,11 +31,10 @@
3131
3232
 <nowiki><pre>
3333
 query $stmt step
3434
 query step $stmt
3535
36
-
3736
 query $stmt finalize
3837
 query finalize $stmt
3938
4039
 query col string $stmt 1
4140
 query $stmt col string 1
@@ -42,27 +41,44 @@
4241
4342
 query bind string $stmt 1 "foo"
4443
 query $stmt bind string 1 "foo"
4544
 </pre></nowiki>
4645
46
+The "prefered" form is:
47
+
48
+<nowiki><pre>
49
+query StmtId command ...
50
+</pre></nowiki>
51
+
52
+(Why, then, are both forms accepted? Because the "preferred" form only
53
+evolved only after using the first form in script code.)
54
+
4755
4856
 <h2>prepare</h2>
4957
5058
 This subcommand prepares a query for execution. It returns a statement handle
5159
 ID which must be passed to any other functions using the API.
5260
5361
 All prepared statements must be <tt>finalize</tt>d when they have outlived
5462
 their usefulness.
63
+
64
+<nowiki><pre>
65
+set stmt [query prepare {SELECT ...}]
66
+...
67
+query $stmt finalize
68
+</pre></nowiki>
69
+
5570
5671
 <h2>finalize</h2>
5772
5873
 Releases all resources associated with the statement. Note that future
5974
 calls to <tt>prepare</tt> might re-use the same statement statement
6075
 ID.
6176
6277
 <nowiki><pre>
6378
 set stmt [query prepare "SELECT ..."]
79
+...
6480
 query $stmt finalize
6581
 </pre></nowiki>
6682
6783
6884
 <h2>step</h2>
@@ -70,11 +86,11 @@
7086
 This subcommand steps the result set by one row. It returns 0
7187
 at the end of the set, a positive value if a new row is available,
7288
 and throws for any other condition.
7389
7490
 <nowiki><pre>
75
-for {} {0 &lt; [query $stmt step]} {} {
91
+for {} {[query $stmt step]} {} {
7692
 puts [query $stmt col string 0] "\n"
7793
 }
7894
 </pre></nowiki>
7995
8096
@@ -92,14 +108,14 @@
92108
 <h2>bind xxx</h2>
93109
94110
 The <tt>bind xxx</tt> family of subcommands attach values to queries
95111
 before stepping through them. The subcommands include:
96112
97
- * <tt>bind int StmtId Index Value</tt>
98
- * <tt>bind double StmtId Index Value</tt>
99
- * <tt>bind null StmtId Index</tt>
100
- * <tt>bind string StmtId Index Value</tt>
113
+ * <tt>bind StmtId int Index Value</tt>
114
+ * <tt>bind StmtId double Index Value</tt>
115
+ * <tt>bind StmtId null Index</tt>
116
+ * <tt>bind StmtId string Index Value</tt>
101117
102118
 Note that all of those optionally accept the statement handle directly after
103119
 the "query" command (before the "col" subcommand). e.g.
104120
 <tt>query bind null $stmt 1</tt> and
105121
 <tt>query $stmt bind null 1</tt> are equivalent. They also accept the column index
@@ -110,29 +126,26 @@
110126
 Achtung: the bind API uses 1-based indexes, just like SQL does.
111127
112128
 <nowiki><pre>
113129
 set stmt [query prepare "SELECT ... WHERE user=?"]
114130
 query $stmt bind int 1 drh
115
-if {0 &lt; [query $stmt step]} {
131
+if {[query $stmt step]} {
116132
 puts [query $stmt col string 0] "\n"
117133
 }
118134
 query $stmt finalize
119135
 </pre></nowiki>
120136
121137
122138
 <h2>col xxx</h2>
123139
124
-The <tt>col xxx</tt> familys of subcommands are for fetching
125
-values and metadata from result rows.
126
-
127
- * <tt>col count StmtId</tt> Returns the number of result columns in the statement.
128
- * <tt>col isnull StmtId Index</tt> Returns non-0 if the given column contains an SQL NULL value.
129
- * <tt>col double StmtId Index</tt>
130
- * <tt>col int StmtId Index</tt>
131
- * <tt>col string StmtId Index</tt>
132
- * <tt>col string StmtId Index Format Modifiers</tt> See below.
133
- * <tt>col type StmtId Index</tt> Return value corresponds to one of the <tt>SQLITE_TYPENAME</tt> family of constants.
140
+The <tt>col xxx</tt> familys of subcommands are for fetching values and metadata from result rows.
141
+
142
+ * <tt>col StmtId count</tt> Returns the number of result columns in the statement.
143
+ * <tt>col StmtId isnull Index</tt> Returns non-0 if the given column contains an SQL NULL value.
144
+ * <tt>col StmtId (double|int|string) Index</tt> Fetches a column's value as either a number or string.
145
+ * <tt>col StmtId time Index Format Modifiers</tt> Formats a time value. See below.
146
+ * <tt>col StmtId type Index</tt> Returns the given column's type as a value from the <tt>SQLITE_TYPENAME</tt> family of constants.
134147
135148
 Note that all of those optionally accept the statement handle directly after
136149
 the "query" command (before the "col" subcommand). e.g.
137150
 <tt>query $stmt col count</tt> and
138151
 <tt>query col count $stmt</tt> are equivalent. They also accept the column index
@@ -169,5 +182,18 @@
169182
 <nowiki><pre>
170183
 query strftime %s 1319211587 unixepoch
171184
 query strftime {%Y%m%d @ %H:%M:%S} [query $stmt col string 2] {+10 years}]
172185
 </pre></nowiki>
173186
187
+<h2>Global Variables</h2>
188
+
189
+This API installs the following global variables, all of which correspond to
190
+<tt>SQLITE_xxx</tt> constant values:
191
+
192
+ * <tt>SQLITE_BLOB</tt>
193
+ * <tt>SQLITE_FLOAT</tt>
194
+ * <tt>SQLITE_INTEGER</tt>
195
+ * <tt>SQLITE_NULL</tt>
196
+ * <tt>SQLITE_TEXT</tt>
197
+
198
+These values are used only by the <tt>col type</tt> function. They can be
199
+accessed from script code via <tt>$::SQLITE_xxx</tt>.
174200
--- www/th1_query.wiki
+++ www/th1_query.wiki
@@ -31,11 +31,10 @@
31
32 <nowiki><pre>
33 query $stmt step
34 query step $stmt
35
36
37 query $stmt finalize
38 query finalize $stmt
39
40 query col string $stmt 1
41 query $stmt col string 1
@@ -42,27 +41,44 @@
42
43 query bind string $stmt 1 "foo"
44 query $stmt bind string 1 "foo"
45 </pre></nowiki>
46
 
 
 
 
 
 
 
 
 
47
48 <h2>prepare</h2>
49
50 This subcommand prepares a query for execution. It returns a statement handle
51 ID which must be passed to any other functions using the API.
52
53 All prepared statements must be <tt>finalize</tt>d when they have outlived
54 their usefulness.
 
 
 
 
 
 
 
55
56 <h2>finalize</h2>
57
58 Releases all resources associated with the statement. Note that future
59 calls to <tt>prepare</tt> might re-use the same statement statement
60 ID.
61
62 <nowiki><pre>
63 set stmt [query prepare "SELECT ..."]
 
64 query $stmt finalize
65 </pre></nowiki>
66
67
68 <h2>step</h2>
@@ -70,11 +86,11 @@
70 This subcommand steps the result set by one row. It returns 0
71 at the end of the set, a positive value if a new row is available,
72 and throws for any other condition.
73
74 <nowiki><pre>
75 for {} {0 &lt; [query $stmt step]} {} {
76 puts [query $stmt col string 0] "\n"
77 }
78 </pre></nowiki>
79
80
@@ -92,14 +108,14 @@
92 <h2>bind xxx</h2>
93
94 The <tt>bind xxx</tt> family of subcommands attach values to queries
95 before stepping through them. The subcommands include:
96
97 * <tt>bind int StmtId Index Value</tt>
98 * <tt>bind double StmtId Index Value</tt>
99 * <tt>bind null StmtId Index</tt>
100 * <tt>bind string StmtId Index Value</tt>
101
102 Note that all of those optionally accept the statement handle directly after
103 the "query" command (before the "col" subcommand). e.g.
104 <tt>query bind null $stmt 1</tt> and
105 <tt>query $stmt bind null 1</tt> are equivalent. They also accept the column index
@@ -110,29 +126,26 @@
110 Achtung: the bind API uses 1-based indexes, just like SQL does.
111
112 <nowiki><pre>
113 set stmt [query prepare "SELECT ... WHERE user=?"]
114 query $stmt bind int 1 drh
115 if {0 &lt; [query $stmt step]} {
116 puts [query $stmt col string 0] "\n"
117 }
118 query $stmt finalize
119 </pre></nowiki>
120
121
122 <h2>col xxx</h2>
123
124 The <tt>col xxx</tt> familys of subcommands are for fetching
125 values and metadata from result rows.
126
127 * <tt>col count StmtId</tt> Returns the number of result columns in the statement.
128 * <tt>col isnull StmtId Index</tt> Returns non-0 if the given column contains an SQL NULL value.
129 * <tt>col double StmtId Index</tt>
130 * <tt>col int StmtId Index</tt>
131 * <tt>col string StmtId Index</tt>
132 * <tt>col string StmtId Index Format Modifiers</tt> See below.
133 * <tt>col type StmtId Index</tt> Return value corresponds to one of the <tt>SQLITE_TYPENAME</tt> family of constants.
134
135 Note that all of those optionally accept the statement handle directly after
136 the "query" command (before the "col" subcommand). e.g.
137 <tt>query $stmt col count</tt> and
138 <tt>query col count $stmt</tt> are equivalent. They also accept the column index
@@ -169,5 +182,18 @@
169 <nowiki><pre>
170 query strftime %s 1319211587 unixepoch
171 query strftime {%Y%m%d @ %H:%M:%S} [query $stmt col string 2] {+10 years}]
172 </pre></nowiki>
173
 
 
 
 
 
 
 
 
 
 
 
 
 
174
--- www/th1_query.wiki
+++ www/th1_query.wiki
@@ -31,11 +31,10 @@
31
32 <nowiki><pre>
33 query $stmt step
34 query step $stmt
35
 
36 query $stmt finalize
37 query finalize $stmt
38
39 query col string $stmt 1
40 query $stmt col string 1
@@ -42,27 +41,44 @@
41
42 query bind string $stmt 1 "foo"
43 query $stmt bind string 1 "foo"
44 </pre></nowiki>
45
46 The "prefered" form is:
47
48 <nowiki><pre>
49 query StmtId command ...
50 </pre></nowiki>
51
52 (Why, then, are both forms accepted? Because the "preferred" form only
53 evolved only after using the first form in script code.)
54
55
56 <h2>prepare</h2>
57
58 This subcommand prepares a query for execution. It returns a statement handle
59 ID which must be passed to any other functions using the API.
60
61 All prepared statements must be <tt>finalize</tt>d when they have outlived
62 their usefulness.
63
64 <nowiki><pre>
65 set stmt [query prepare {SELECT ...}]
66 ...
67 query $stmt finalize
68 </pre></nowiki>
69
70
71 <h2>finalize</h2>
72
73 Releases all resources associated with the statement. Note that future
74 calls to <tt>prepare</tt> might re-use the same statement statement
75 ID.
76
77 <nowiki><pre>
78 set stmt [query prepare "SELECT ..."]
79 ...
80 query $stmt finalize
81 </pre></nowiki>
82
83
84 <h2>step</h2>
@@ -70,11 +86,11 @@
86 This subcommand steps the result set by one row. It returns 0
87 at the end of the set, a positive value if a new row is available,
88 and throws for any other condition.
89
90 <nowiki><pre>
91 for {} {[query $stmt step]} {} {
92 puts [query $stmt col string 0] "\n"
93 }
94 </pre></nowiki>
95
96
@@ -92,14 +108,14 @@
108 <h2>bind xxx</h2>
109
110 The <tt>bind xxx</tt> family of subcommands attach values to queries
111 before stepping through them. The subcommands include:
112
113 * <tt>bind StmtId int Index Value</tt>
114 * <tt>bind StmtId double Index Value</tt>
115 * <tt>bind StmtId null Index</tt>
116 * <tt>bind StmtId string Index Value</tt>
117
118 Note that all of those optionally accept the statement handle directly after
119 the "query" command (before the "col" subcommand). e.g.
120 <tt>query bind null $stmt 1</tt> and
121 <tt>query $stmt bind null 1</tt> are equivalent. They also accept the column index
@@ -110,29 +126,26 @@
126 Achtung: the bind API uses 1-based indexes, just like SQL does.
127
128 <nowiki><pre>
129 set stmt [query prepare "SELECT ... WHERE user=?"]
130 query $stmt bind int 1 drh
131 if {[query $stmt step]} {
132 puts [query $stmt col string 0] "\n"
133 }
134 query $stmt finalize
135 </pre></nowiki>
136
137
138 <h2>col xxx</h2>
139
140 The <tt>col xxx</tt> familys of subcommands are for fetching values and metadata from result rows.
141
142 * <tt>col StmtId count</tt> Returns the number of result columns in the statement.
143 * <tt>col StmtId isnull Index</tt> Returns non-0 if the given column contains an SQL NULL value.
144 * <tt>col StmtId (double|int|string) Index</tt> Fetches a column's value as either a number or string.
145 * <tt>col StmtId time Index Format Modifiers</tt> Formats a time value. See below.
146 * <tt>col StmtId type Index</tt> Returns the given column's type as a value from the <tt>SQLITE_TYPENAME</tt> family of constants.
 
 
 
147
148 Note that all of those optionally accept the statement handle directly after
149 the "query" command (before the "col" subcommand). e.g.
150 <tt>query $stmt col count</tt> and
151 <tt>query col count $stmt</tt> are equivalent. They also accept the column index
@@ -169,5 +182,18 @@
182 <nowiki><pre>
183 query strftime %s 1319211587 unixepoch
184 query strftime {%Y%m%d @ %H:%M:%S} [query $stmt col string 2] {+10 years}]
185 </pre></nowiki>
186
187 <h2>Global Variables</h2>
188
189 This API installs the following global variables, all of which correspond to
190 <tt>SQLITE_xxx</tt> constant values:
191
192 * <tt>SQLITE_BLOB</tt>
193 * <tt>SQLITE_FLOAT</tt>
194 * <tt>SQLITE_INTEGER</tt>
195 * <tt>SQLITE_NULL</tt>
196 * <tt>SQLITE_TEXT</tt>
197
198 These values are used only by the <tt>col type</tt> function. They can be
199 accessed from script code via <tt>$::SQLITE_xxx</tt>.
200

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button