|
const char *sqlite3_column_database_name(sqlite3_stmt*,int); const void *sqlite3_column_database_name16(sqlite3_stmt*,int); const char *sqlite3_column_table_name(sqlite3_stmt*,int); const void *sqlite3_column_table_name16(sqlite3_stmt*,int); const char *sqlite3_column_origin_name(sqlite3_stmt*,int); const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
These routines provide a means to determine what column of what table in which database a result of a SELECT statement comes from. The name of the database or table or column can be returned as either a UTF-8 or UTF-16 string. The _database_ routines return the database name, the _table_ routines return the table name, and the origin_ routines return the column name. The returned string is valid until the prepared statement is destroyed using sqlite3_finalize() or until the same information is requested again in a different encoding.
The names returned are the original un-aliased names of the database, table, and column.
The first argument to the following calls is a prepared statement. These functions return information about the Nth column returned by the statement, where N is the second function argument.
If the Nth column returned by the statement is an expression or subquery and is not a column value, then all of these functions return NULL. These routine might also return NULL if a memory allocation error occurs. Otherwise, they return the name of the attached database, table and column that query result column was extracted from.
As with all other SQLite APIs, those postfixed with "16" return UTF-16 encoded strings, the other functions return UTF-8.
These APIs are only available if the library was compiled with the SQLITE_ENABLE_COLUMN_METADATA C-preprocessor symbol defined.
If two or more threads call one or more of these routines against the same prepared statement and column at the same time then the results are undefined.
H13741 | The sqlite3_column_database_name(S,N) interface returns either the UTF-8 zero-terminated name of the database from which the Nth result column of the prepared statement S is extracted, or NULL if the Nth column of S is a general expression or if unable to allocate memory to store the name. |
H13742 | The sqlite3_column_database_name16(S,N) interface returns either the UTF-16 native byte order zero-terminated name of the database from which the Nth result column of the prepared statement S is extracted, or NULL if the Nth column of S is a general expression or if unable to allocate memory to store the name. |
H13743 | The sqlite3_column_table_name(S,N) interface returns either the UTF-8 zero-terminated name of the table from which the Nth result column of the prepared statement S is extracted, or NULL if the Nth column of S is a general expression or if unable to allocate memory to store the name. |
H13744 | The sqlite3_column_table_name16(S,N) interface returns either the UTF-16 native byte order zero-terminated name of the table from which the Nth result column of the prepared statement S is extracted, or NULL if the Nth column of S is a general expression or if unable to allocate memory to store the name. |
H13745 | The sqlite3_column_origin_name(S,N) interface returns either the UTF-8 zero-terminated name of the table column from which the Nth result column of the prepared statement S is extracted, or NULL if the Nth column of S is a general expression or if unable to allocate memory to store the name. |
H13746 | The sqlite3_column_origin_name16(S,N) interface returns either the UTF-16 native byte order zero-terminated name of the table column from which the Nth result column of the prepared statement S is extracted, or NULL if the Nth column of S is a general expression or if unable to allocate memory to store the name. |
H13748 | The return values from column metadata interfaces are valid for the lifetime of the prepared statement or until the encoding is changed by another metadata interface call for the same prepared statement and column. |
A13751 | If two or more threads call one or more column metadata interfaces for the same prepared statement and result column at the same time then the results are undefined. |
See also lists of Objects, Constants, and Functions.