/ Check-in [63ca02a5]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Clarify documentation on the return value from sqlite3_column_blob() for a zero-length BLOB. Clarify the documentation on what happens when you have a zeroblob() with a negative length. Additional test cases but no changes to code. Ticket #2623. (CVS 4395)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 63ca02a5b2700858f0eceadc9b58b942d473b191
User & Date: drh 2007-09-04 12:18:42
Context
2007-09-04
14:31
Add internal locking to the test_async.c backend. So that more than one connection may be used from within a single process. (CVS 4396) check-in: 17ca684c user: danielk1977 tags: trunk
12:18
Clarify documentation on the return value from sqlite3_column_blob() for a zero-length BLOB. Clarify the documentation on what happens when you have a zeroblob() with a negative length. Additional test cases but no changes to code. Ticket #2623. (CVS 4395) check-in: 63ca02a5 user: drh tags: trunk
12:00
Documentation fixes. No changes to code. Tickets #2622 and #2624. (CVS 4394) check-in: 2eadef90 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
....
1699
1700
1701
1702
1703
1704
1705
1706

1707
1708
1709
1710
1711
1712
1713
....
2054
2055
2056
2057
2058
2059
2060





2061
2062
2063
2064
2065
2066
2067
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.257 2007/09/04 12:00:00 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
** routine returns.
**
** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
** is filled with zeros.  A zeroblob uses a fixed amount of memory
** (just an integer to hold it size) while it is being processed.
** Zeroblobs are intended to serve as place-holders for BLOBs whose
** content is later written using 
** [sqlite3_blob_open | increment BLOB I/O] routines.

**
** The sqlite3_bind_*() routines must be called after
** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
** before [sqlite3_step()].
** Bindings are not cleared by the [sqlite3_reset()] routine.
** Unbound parameters are interpreted as NULL.
**
................................................................................
** the string to UTF-8 and then returns the number of bytes.
** If the result is a numeric value then sqlite3_column_bytes() uses
** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
** the number of bytes in that string.
** The value returned does not include the zero terminator at the end
** of the string.  For clarity: the value returned is the number of
** bytes in the string, not the number of characters.





**
** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
** but leaves the result in UTF-16 instead of UTF-8.  
** The zero terminator is not included in this count.
**
** These routines attempt to convert the value where appropriate.  For
** example, if the internal representation is FLOAT and a text result







|







 







|
>







 







>
>
>
>
>







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
....
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
....
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.258 2007/09/04 12:18:42 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
** routine returns.
**
** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
** is filled with zeros.  A zeroblob uses a fixed amount of memory
** (just an integer to hold it size) while it is being processed.
** Zeroblobs are intended to serve as place-holders for BLOBs whose
** content is later written using 
** [sqlite3_blob_open | increment BLOB I/O] routines.  A negative
** value for the zeroblob results in a zero-length BLOB.
**
** The sqlite3_bind_*() routines must be called after
** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
** before [sqlite3_step()].
** Bindings are not cleared by the [sqlite3_reset()] routine.
** Unbound parameters are interpreted as NULL.
**
................................................................................
** the string to UTF-8 and then returns the number of bytes.
** If the result is a numeric value then sqlite3_column_bytes() uses
** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
** the number of bytes in that string.
** The value returned does not include the zero terminator at the end
** of the string.  For clarity: the value returned is the number of
** bytes in the string, not the number of characters.
**
** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
** even zero-length strings, are always zero terminated.  The return
** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
** pointer, possibly even a NULL pointer.
**
** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
** but leaves the result in UTF-16 instead of UTF-8.  
** The zero terminator is not included in this count.
**
** These routines attempt to convert the value where appropriate.  For
** example, if the internal representation is FLOAT and a text result

Changes to test/zeroblob.test.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
...
170
171
172
173
174
175
176
177






178
179
180
181
182
183
184
#
#***********************************************************************
# This file implements regression tests for SQLite library.  The
# focus of this file is testing of the zero-filled blob functionality
# including the sqlite3_bind_zeroblob(), sqlite3_result_zeroblob(),
# and the built-in zeroblob() SQL function.
#
# $Id: zeroblob.test,v 1.8 2007/09/01 16:16:16 danielk1977 Exp $

set testdir [file dirname $argv0]
source $testdir/tester.tcl

ifcapable !incrblob {
  finish_test
  return
................................................................................
  execsql {select zeroblob(-1)|1} 
} {1} 
do_test zeroblob-6.4 { 
  catchsql {select length(zeroblob(2147483648))} 
} {1 {string or blob too big}} 
do_test zeroblob-6.5 { 
  catchsql {select zeroblob(2147483648)} 
} {1 {string or blob too big}} 







# Test bind_zeroblob()
#
do_test zeroblob-7.1 {
  set ::STMT [sqlite3_prepare $::DB "SELECT length(?)" -1 DUMMY]
  sqlite3_bind_zeroblob $::STMT 1 450
  sqlite3_step $::STMT







|







 







|
>
>
>
>
>
>







9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
...
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
#
#***********************************************************************
# This file implements regression tests for SQLite library.  The
# focus of this file is testing of the zero-filled blob functionality
# including the sqlite3_bind_zeroblob(), sqlite3_result_zeroblob(),
# and the built-in zeroblob() SQL function.
#
# $Id: zeroblob.test,v 1.9 2007/09/04 12:18:42 drh Exp $

set testdir [file dirname $argv0]
source $testdir/tester.tcl

ifcapable !incrblob {
  finish_test
  return
................................................................................
  execsql {select zeroblob(-1)|1} 
} {1} 
do_test zeroblob-6.4 { 
  catchsql {select length(zeroblob(2147483648))} 
} {1 {string or blob too big}} 
do_test zeroblob-6.5 { 
  catchsql {select zeroblob(2147483648)} 
} {1 {string or blob too big}}
do_test zeroblob-6.6 {
  execsql {select hex(zeroblob(-1))}
} {{}}
do_test zeroblob-6.7 {
  execsql {select typeof(zeroblob(-1))}
} {blob}

# Test bind_zeroblob()
#
do_test zeroblob-7.1 {
  set ::STMT [sqlite3_prepare $::DB "SELECT length(?)" -1 DUMMY]
  sqlite3_bind_zeroblob $::STMT 1 450
  sqlite3_step $::STMT