*** DRAFT ***
About Documentation Download License Support Purchase

SQLite Requirement Matrix Details
bind_blob.html

Index Summary Markup Original

R-63285-37134-15488-58217-13163-52553-20689-06808 tcl slt th3 src

In the SQL statement text input to sqlite3_prepare_v2() and its variants, literals may be replaced by a parameter that matches one of following templates:

In the templates above, NNN represents an integer literal, and VVV represents an alphanumeric identifier.

th3/req1/bind01.test:40 

/* IMP: R-63285-37134 */
# EVIDENCE-OF: R-63285-37134 In the SQL statement text input to
# sqlite3_prepare_v2() and its variants, literals may be replaced by a
# parameter that matches one of following templates: ? ?NNN :VVV @VVV
# $VVV In the templates above, NNN represents an integer literal, and
# VVV represents an alphanumeric identifier.

R-25857-01867-51039-59358-11204-13788-02264-02528 tcl slt th3 src

The values of these parameters (also called "host parameter names" or "SQL parameters") can be set using the sqlite3_bind_*() routines defined here.

th3/req1/bind01.test:54 

/* IMP: R-25857-01867 */
# EVIDENCE-OF: R-25857-01867 The values of these parameters (also called
# "host parameter names" or "SQL parameters") can be set using the
# sqlite3_bind_*() routines defined here.

R-05367-01575-38544-05441-45705-50827-33382-05876 tcl slt th3 src

The first argument to the sqlite3_bind_*() routines is always a pointer to the sqlite3_stmt object returned from sqlite3_prepare_v2() or its variants.

th3/req1/bind01.test:58 

/* IMP: R-05367-01575 */
# EVIDENCE-OF: R-05367-01575 The first argument to the sqlite3_bind_*()
# routines is always a pointer to the sqlite3_stmt object returned from
# sqlite3_prepare_v2() or its variants.

R-49438-33626-11664-14261-26905-24626-16262-08666 tcl slt th3 src

The second argument is the index of the SQL parameter to be set.

th3/req1/bind01.test:62 

/* IMP: R-49438-33626 */
# EVIDENCE-OF: R-49438-33626 The second argument is the index of the SQL
# parameter to be set.

R-42798-04097-62077-21747-11472-32542-49000-45202 tcl slt th3 src

The leftmost SQL parameter has an index of 1.

th3/req1/bind01.test:65 

/* IMP: R-42798-04097 */
# EVIDENCE-OF: R-42798-04097 The leftmost SQL parameter has an index of
# 1.

R-52009-56800-02876-38410-52331-04439-27959-64251 tcl slt th3 src

When the same named SQL parameter is used more than once, second and subsequent occurrences have the same index as the first occurrence.

th3/req1/bind01.test:96 

/* IMP: R-52009-56800 */
# EVIDENCE-OF: R-52009-56800 When the same named SQL parameter is used
# more than once, second and subsequent occurrences have the same index
# as the first occurrence.

R-05272-22592-13374-24756-51597-06491-53677-55023 tcl slt th3 src

The index for named parameters can be looked up using the sqlite3_bind_parameter_index() API if desired.

th3/req1/bind01.test:109 

/* IMP: R-05272-22592 */
# EVIDENCE-OF: R-05272-22592 The index for named parameters can be
# looked up using the sqlite3_bind_parameter_index() API if desired.

R-10933-37470-14937-54231-03343-64899-21190-46936 tcl slt th3 src

The index for "?NNN" parameters is the value of NNN.

th3/req1/bind01.test:114 

/* IMP: R-10933-37470 */
# EVIDENCE-OF: R-10933-37470 The index for "?NNN" parameters is the
# value of NNN.

R-54218-24562-17509-58575-21096-25882-18026-33588 tcl slt th3 src

The NNN value must be between 1 and the sqlite3_limit() parameter SQLITE_LIMIT_VARIABLE_NUMBER (default value: 32766).

/* IMP: R-54218-24562 */
# EVIDENCE-OF: R-54218-24562 The NNN value must be between 1 and the
# sqlite3_limit() parameter SQLITE_LIMIT_VARIABLE_NUMBER (default value:
# 32766).

R-01766-15387-49282-35089-26578-35550-62519-17422 tcl slt th3 src

The third argument is the value to bind to the parameter.

th3/req1/bind01.test:67 

/* IMP: R-01766-15387 */
# EVIDENCE-OF: R-01766-15387 The third argument is the value to bind to
# the parameter.

R-55392-56277-35725-48242-28273-14685-15840-32650 tcl slt th3 src

If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16() or sqlite3_bind_blob() is a NULL pointer then the fourth parameter is ignored and the end result is the same as sqlite3_bind_null().

th3/req1/bind01.test:635 

/* IMP: R-55392-56277 */
# EVIDENCE-OF: R-55392-56277 If the third parameter to
# sqlite3_bind_text() or sqlite3_bind_text16() or sqlite3_bind_blob() is
# a NULL pointer then the fourth parameter is ignored and the end result
# is the same as sqlite3_bind_null().

R-45427-27134-18298-64328-24893-59331-19022-41786 tcl slt th3 src

If the third parameter to sqlite3_bind_text() is not NULL, then it should be a pointer to well-formed UTF8 text.

/* IMP: R-45427-27134 */
# EVIDENCE-OF: R-45427-27134 If the third parameter to
# sqlite3_bind_text() is not NULL, then it should be a pointer to
# well-formed UTF8 text.

R-61158-57305-03105-25357-56020-55639-01161-13829 tcl slt th3 src

If the third parameter to sqlite3_bind_text16() is not NULL, then it should be a pointer to well-formed UTF16 text.

/* IMP: R-61158-57305 */
# EVIDENCE-OF: R-61158-57305 If the third parameter to
# sqlite3_bind_text16() is not NULL, then it should be a pointer to
# well-formed UTF16 text.

R-21156-19645-52425-35799-35184-17104-33723-09061 tcl slt th3 src

If the third parameter to sqlite3_bind_text64() is not NULL, then it should be a pointer to a well-formed unicode string that is either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16 otherwise.

/* IMP: R-21156-19645 */
# EVIDENCE-OF: R-21156-19645 If the third parameter to
# sqlite3_bind_text64() is not NULL, then it should be a pointer to a
# well-formed unicode string that is either UTF8 if the sixth parameter
# is SQLITE_UTF8, or UTF16 otherwise.

R-20022-00570-36475-01777-57661-23786-03560-20337 tcl slt th3 src

The byte-order of UTF16 input text is determined by the byte-order mark (BOM, U+FEFF) found in first character, which is removed, or in the absence of a BOM the byte order is the native byte order of the host machine for sqlite3_bind_text16() or the byte order specified in the 6th parameter for sqlite3_bind_text64().

/* IMP: R-20022-00570 */
# EVIDENCE-OF: R-20022-00570 The byte-order of UTF16 input text is
# determined by the byte-order mark (BOM, U+FEFF) found in first
# character, which is removed, or in the absence of a BOM the byte order
# is the native byte order of the host machine for sqlite3_bind_text16()
# or the byte order specified in the 6th parameter for
# sqlite3_bind_text64().

R-37936-22853-22443-15784-22618-50674-60606-55303 tcl slt th3 src

^If UTF16 input text contains invalid unicode characters, then SQLite might change those invalid characters into the unicode replacement character: U+FFFD.

/* IMP: R-37936-22853 */
# EVIDENCE-OF: R-37936-22853 ^If UTF16 input text contains invalid
# unicode characters, then SQLite might change those invalid characters
# into the unicode replacement character: U+FFFD.

R-40874-07817-64808-61349-14164-22324-19538-25900 tcl slt th3 src

In those routines that have a fourth argument, its value is the number of bytes in the parameter. To be clear: the value is the number of bytes in the value, not the number of characters.

th3/req1/bind01.test:158 

/* IMP: R-40874-07817 */
# EVIDENCE-OF: R-40874-07817 In those routines that have a fourth
# argument, its value is the number of bytes in the parameter. To be
# clear: the value is the number of bytes in the value, not the number
# of characters.

R-16566-16123-02807-20883-30772-24192-15588-47043 tcl slt th3 src

If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() is negative, then the length of the string is the number of bytes up to the first zero terminator.

th3/req1/bind01.test:171 

/* IMP: R-16566-16123 */
# EVIDENCE-OF: R-16566-16123 If the fourth parameter to
# sqlite3_bind_text() or sqlite3_bind_text16() is negative, then the
# length of the string is the number of bytes up to the first zero
# terminator.

R-03149-27046-20268-15208-62882-01338-52068-22067 tcl slt th3 src

The fifth argument to the BLOB and string binding interfaces controls or indicates the lifetime of the object referenced by the third parameter.

th3/req1/bind01.test:185 

/* IMP: R-03149-27046 */
# EVIDENCE-OF: R-03149-27046 The fifth argument to the BLOB and string
# binding interfaces controls or indicates the lifetime of the object
# referenced by the third parameter.

R-43234-44223-26949-41610-57422-00993-50699-20891 tcl slt th3 src

(1) A destructor to dispose of the BLOB or string after SQLite has finished with it may be passed.

/* IMP: R-43234-44223 */
# EVIDENCE-OF: R-43234-44223 (1) A destructor to dispose of the BLOB or
# string after SQLite has finished with it may be passed.

R-61480-49358-44699-35274-34938-16016-20585-63326 tcl slt th3 src

It is called to dispose of the BLOB or string even if the call to the bind API fails, except the destructor is not called if the third parameter is a NULL pointer or the fourth parameter is negative.

th3/req1/bind01.test:236 

/* IMP: R-61480-49358 */
# EVIDENCE-OF: R-61480-49358 It is called to dispose of the BLOB or
# string even if the call to the bind API fails, except the destructor
# is not called if the third parameter is a NULL pointer or the fourth
# parameter is negative.

R-05395-35212-59104-06059-25040-21226-51023-56208 tcl slt th3 src

(2) The special constant, SQLITE_STATIC, may be passsed to indicate that the application remains responsible for disposing of the object.

th3/req1/bind01.test:290 

/* IMP: R-05395-35212 */
# EVIDENCE-OF: R-05395-35212 (2) The special constant, SQLITE_STATIC,
# may be passsed to indicate that the application remains responsible
# for disposing of the object.

R-16727-30552-59838-52112-19419-11299-04704-42837 tcl slt th3 src

In this case, the object and the provided pointer to it must remain valid until either the prepared statement is finalized or the same SQL parameter is bound to something else, whichever occurs sooner.

/* IMP: R-16727-30552 */
# EVIDENCE-OF: R-16727-30552 In this case, the object and the provided
# pointer to it must remain valid until either the prepared statement is
# finalized or the same SQL parameter is bound to something else,
# whichever occurs sooner.

R-03400-28805-09700-08348-35021-23178-61085-56797 tcl slt th3 src

(3) The constant, SQLITE_TRANSIENT, may be passed to indicate that the object is to be copied prior to the return from sqlite3_bind_*().

th3/req1/bind01.test:309 

/* IMP: R-03400-28805 */
# EVIDENCE-OF: R-03400-28805 (3) The constant, SQLITE_TRANSIENT, may be
# passed to indicate that the object is to be copied prior to the return
# from sqlite3_bind_*().

R-63007-00158-07444-30400-48022-49637-62807-30158 tcl slt th3 src

The object and pointer to it must remain valid until then.

/* IMP: R-63007-00158 */
# EVIDENCE-OF: R-63007-00158 The object and pointer to it must remain
# valid until then.

R-43366-61198-05845-57681-29417-64282-40524-45626 tcl slt th3 src

SQLite will then manage the lifetime of its private copy.

/* IMP: R-43366-61198 */
# EVIDENCE-OF: R-43366-61198 SQLite will then manage the lifetime of its
# private copy.

R-63107-29542-42038-49029-17221-49854-37760-53513 tcl slt th3 src

The sixth argument to sqlite3_bind_text64() must be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE to specify the encoding of the text in the third parameter.

th3/req1/bind01.test:669 

/* IMP: R-63107-29542 */
# EVIDENCE-OF: R-63107-29542 The sixth argument to sqlite3_bind_text64()
# must be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, or
# SQLITE_UTF16LE to specify the encoding of the text in the third
# parameter.

R-19162-55388-28844-29887-54254-48882-22034-22486 tcl slt th3 src

The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is filled with zeroes.

th3/req1/bind01.test:335 

/* IMP: R-19162-55388 */
# EVIDENCE-OF: R-19162-55388 The sqlite3_bind_zeroblob() routine binds a
# BLOB of length N that is filled with zeroes.

R-61241-11973-05308-06384-59636-46330-32526-49143 tcl slt th3 src

A zeroblob uses a fixed amount of memory (just an integer to hold its size) while it is being processed.

th3/req1/bind02.test:11 

/* IMP: R-61241-11973 */
# EVIDENCE-OF: R-61241-11973 A zeroblob uses a fixed amount of memory
# (just an integer to hold its size) while it is being processed.

R-09849-00220-60139-37223-30218-05088-34235-14106 tcl slt th3 src

A negative value for the zeroblob results in a zero-length BLOB.

th3/req1/bind01.test:351 

/* IMP: R-09849-00220 */
# EVIDENCE-OF: R-09849-00220 A negative value for the zeroblob results
# in a zero-length BLOB.

R-03849-24470-04387-57438-43164-31085-17053-62847 tcl slt th3 src

The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in prepared statement S to have an SQL value of NULL, but to also be associated with the pointer P of type T.

th3/cov1/carray01.test:144 

/* IMP: R-03849-24470 */
# EVIDENCE-OF: R-03849-24470 The sqlite3_bind_pointer(S,I,P,T,D) routine
# causes the I-th parameter in prepared statement S to have an SQL value
# of NULL, but to also be associated with the pointer P of type T.

R-52975-24025-19782-48078-21253-08318-64480-41617 tcl slt th3 src

D is either a NULL pointer or a pointer to a destructor function for P.

th3/cov1/carray01.test:78 

/* IMP: R-52975-24025 */
# EVIDENCE-OF: R-52975-24025 D is either a NULL pointer or a pointer to
# a destructor function for P.

R-09933-20910-17434-57069-20423-40847-01443-50853 tcl slt th3 src

SQLite will invoke the destructor D with a single argument of P when it is finished using P.

th3/cov1/bindptr01.test:119 

/* IMP: R-09933-20910 */
# EVIDENCE-OF: R-09933-20910 SQLite will invoke the destructor D with a
# single argument of P when it is finished using P.

R-12385-29357-06321-01436-47924-30729-53833-26197 tcl slt th3 src

If any of the sqlite3_bind_*() routines are called with a NULL pointer for the prepared statement or with a prepared statement for which sqlite3_step() has been called more recently than sqlite3_reset(), then the call will return SQLITE_MISUSE.

th3/req1/bind01.test:371 

/* IMP: R-12385-29357 */
# EVIDENCE-OF: R-12385-29357 If any of the sqlite3_bind_*() routines are
# called with a NULL pointer for the prepared statement or with a
# prepared statement for which sqlite3_step() has been called more
# recently than sqlite3_reset(), then the call will return
# SQLITE_MISUSE.

R-14744-61161-64598-20723-40374-11950-32585-46634 tcl slt th3 src

Bindings are not cleared by the sqlite3_reset() routine.

th3/req1/bind01.test:446 

/* IMP: R-14744-61161 */
# EVIDENCE-OF: R-14744-61161 Bindings are not cleared by the
# sqlite3_reset() routine.

R-06094-55152-33533-26668-27298-05995-61599-07184 tcl slt th3 src

Unbound parameters are interpreted as NULL.

th3/req1/bind01.test:46 

/* IMP: R-06094-55152 */
# EVIDENCE-OF: R-06094-55152 Unbound parameters are interpreted as NULL.

R-26972-25540-17987-13345-11118-49972-58252-62199 tcl slt th3 src

The sqlite3_bind_* routines return SQLITE_OK on success or an error code if anything goes wrong.

th3/req1/bind01.test:467 

/* IMP: R-26972-25540 */
# EVIDENCE-OF: R-26972-25540 The sqlite3_bind_* routines return
# SQLITE_OK on success or an error code if anything goes wrong.

R-00110-20874-52504-15299-56251-38354-26784-53834 tcl slt th3 src

SQLITE_TOOBIG might be returned if the size of a string or BLOB exceeds limits imposed by sqlite3_limit(SQLITE_LIMIT_LENGTH) or SQLITE_MAX_LENGTH.

th3/cov1/vdbeapi03.test:566   th3/cov1/vdbeapi03.test:804 

/* IMP: R-00110-20874 */
# EVIDENCE-OF: R-00110-20874 SQLITE_TOOBIG might be returned if the size
# of a string or BLOB exceeds limits imposed by
# sqlite3_limit(SQLITE_LIMIT_LENGTH) or SQLITE_MAX_LENGTH.

R-18773-06579-40569-18123-18199-49078-54792-42080 tcl slt th3 src

SQLITE_RANGE is returned if the parameter index is out of range.

th3/req1/bind01.test:542 

/* IMP: R-18773-06579 */
# EVIDENCE-OF: R-18773-06579 SQLITE_RANGE is returned if the parameter
# index is out of range.

R-50561-21716-49344-62594-61737-43195-59179-37313 tcl slt th3 src

SQLITE_NOMEM is returned if malloc() fails.

th3/req1/bind01.test:566 

/* IMP: R-50561-21716 */
# EVIDENCE-OF: R-50561-21716 SQLITE_NOMEM is returned if malloc() fails.