1Accessing SQLite's symbols:
2===========================
3Since the addition of Oracle Berkeley DB 5's SQL provider, all the sqlite3_* symbols
4can be loaded twice during the execution of a program linked with Libgda. Therefore
5how the sqlite3_* functions are called is important, and is the reason of the SQLITE3_CALL()
6macro which _MUST_ be used everytime an sqlite3_* function is called.
7
8The shared libraries layout to avoid symbols resolution clashed is outlined in the following
9diagram (when SQLite is used from a shared library, if not, then there is no symbol clash):
10
11libgda-4.0.so --(dlopen)--> libsqlite3.so (which exports all the sqlite3_* symbols)
12	      --(dlopen)--> providers/libgda-sqlite.so (which does not export any sqlite3_* symbol)
13	      --(dlopen)--> providers/libgda-bdbsql.so
14	                        --(dlopen)--> libdb-5.0.so (which exports all the sqlite3_* symbols)
15As the libsqlite3.so and the libdb-5.0.so shared libraries are loaded using the G_MODULE_BIND_LOCAL
16flag, their exported symbols don't clash.
17
18
19Which version of SQLite is used:
20================================
21
22When embedded SQLITE is used:
23* HAVE_SQLITE is *not* defined
24* patch it to add the PRAGMA command
25* linked as static
26
27When system SQLITE is used:
28* HAVE_SQLITE is defined
29* obviously not patched for PRAGMA
30* linked as dynamic => override the sqlite3CreateFunc function
31* For WIN32 (or MacOSX) we would need to use another mechanism (see lattice.umiacs.umd.edu/files/functions_tr.pdf) => impose embedded static lib
32
33Possible solutions in the future:
341 - make SQLite implement the required PRAGMA (patch proposed)
352 - don't use the required PRAGMA at all, and manage to intercept the sqlite3CreateFunc call
36    when statically linked (=> modify the source code of SQLite)
37
38
39
40
41BLOB handling in SQLite:
42========================
43
44SQLite now supports incremental I/O for BLOBS. Any data in any column can be accessed
45with this API.
46
47When writing a blob to the database:
48------------------------------------
49Opening a blob requires the following information:
50* the database name
51* the table name
52* the column name
53* the ROWID
54
55The first 3 pieces of information can be obtained from the INSERT or UPDATE statement
56itself.
57
58The ROWID can be obtained using sqlite3_last_insert_rowid() for an INSERT or must be queried
59for an UPDATE.
60
61When reading a blob from the database:
62--------------------------------------
63Opening a blob requires the following information:
64* the database name: use sqlite3_column_database_name()
65* the table name: use sqlite3_column_table_name()
66* the column name: use sqlite3_column_origin_name()
67* the ROWID: get it from the SELECT as the last row.
68