SQLite C Interface-Opening A New Database Connection

Int sqlite3_open (
Const char * filename,/* Database filename (UTF-8 )*/
Sqlite3 ** ppDb/* OUT: SQLite db handle */
);
Int sqlite3_open16 (
Const void * filename,/* Database filename (UTF-16 )*/
Sqlite3 ** ppDb/* OUT: SQLite db handle */
);
Int sqlite3_open_v2 (
Const char * filename,/* Database filename (UTF-8 )*/
Sqlite3 ** ppDb,/* OUT: SQLite db handle */
Int flags,/* Flags */
Const char * zVfs/* Name of VFS module to use */
);

 

These routines open an SQLite database file whose name is given by the filename argument. the filename argument is interpreted as UTF-8 for sqlite3_open () and sqlite3_open_v2 () and as UTF-16 in the native byte order for sqlite3_open16 (). A database connection handle is usually returned in * ppDb, even if an error occurs. the only exception is that if SQLite is unable to allocate memory to hold the sqlite3 object, a NULL will be written into * ppDb instead of a pointer to the sqlite3 object. if the database is opened (and/or created) successfully, thenSQLITE_ OKIs returned. Otherwise an error code is returned.Sqlite3_errmsg ()OrSqlite3_errmsg16 ()Routines can be used to obtain an English language description of the error.

These routines open the SQLite database file provided by the filename parameter. For sqlite3_open () and sqlite3_open_v2 (), the filename parameter is interpreted in UTF-8; For sqlite3_open16 (), the UTF-16 is interpreted in the native byte order. The database connection handle is returned in * ppDb, even if an error occurs. The only exception is that if SQLite cannot allocate memory to the sqlite3 object, * ppDb will be written to NULL instead of the pointer to the sqlite3 object. If the database is successfully opened (and/or created), SQLITE_ OK is returned. Otherwise, an error code is returned. The sqlite3_errmsg () or sqlite3_errmsg16 () routine can be used to obtain the English description of the error.

 

The default encoding for the database will be UTF-8 if sqlite3_open () or sqlite3_open_v2 () is called and UTF-16 in the native byte order if sqlite3_open16 () is used.

If sqlite3_open () or sqlite3_open_v2 () is called, the default encoding for the database is a UTF-8; If sqlite3_open16 () is used, it is the UTF-16 of the local byte order.

 

Whether or not an error occurs when it is opened, resources associated with the database connection handle shoshould be released by passing it to sqlite3_close () when it is no longer required.

No matter whether an error occurs when you open the database, when you no longer need it, you should pass the database connection handle to sqlite3_close () to release resources related to it.

 

The sqlite3_open_v2 () interface works like sqlite3_open () blocks t that it accepts two additional parameters for additional control over the new database connection. the flags parameter can take one of the following three values, optionally combined with the SQLITE_OPEN_NOMUTEX or SQLITE_OPEN_FULLMUTEX flags:

• SQLITE_OPEN_READONLY
  The database is opened in read-only mode. If the database does not already exist, an error is returned.
• SQLITE_OPEN_READWRITE
  The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned.
• SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
  The database is opened for reading and writing, and is creates it if it does not already exist. This is the behavior that is always used for sqlite3_open () and sqlite3_open16 ().

The sqlite3_open_v2 () interface and sqlite3_open () interface work in a similar way, But it accepts two additional parameters to control the new database connection. The flags parameter can be one of the following three values and can selectively combine the SQLITE_OPEN_NOMUTEX or SQLITE_OPEN_FULLMUTEX Tag:

• SQLITE_OPEN_READONLY
  The database is read-only. If the database does not exist, an error is returned.
• SQLITE_OPEN_READWRITE
  If possible, the database is opened in read/write mode, or if the file is protected by the operating system, it is opened in read-only mode. In both cases, the database must already exist; otherwise, an error is returned.
• SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
  The database is opened in read/write mode. If it does not exist, it is created. This is what sqlite3_open () and sqlite3_open16 () always use.

 

If the 3rd parameter to sqlite3_open_v2 () is not one of the combinations shown above or one of the combinations shown above with the SQLITE_OPEN_NOMUTEX or character flags, then the behavior is undefined.

If the 3rd parameters of sqlite3_open_v2 () are not one of the preceding combinations or the combination of the preceding and SQLITE_OPEN_NOMUTEX or SQLITE_OPEN_FULLMUTEX, the behavior is not defined.

 

If the SQLITE_OPEN_NOMUTEX flag is set, then the database connection opens in the multi-thread threading mode as long as the single-thread mode has not been set at compile-time or start-time. if the SQLITE_OPEN_FULLMUTEX flag is set then the database connection opens in the serialized threading mode unless single-thread was previusly selected at compile-time or start-time.

If SQLITE_OPEN_NOMUTEX is set, as long as the single-thread mode is not set at the compilation or start time, the database connection is enabled in multi-thread mode. If SQLITE_OPEN_FULLMUTEX is set, the database connection is enabled in serial thread mode unless a single thread is selected during or before the compilation.

 

If the filename is ": memory:", then a private, temporary in-memory database is created for the connection. this in-memory database will vanish when the database connection is closed. future versions of SQLite might make use of additional special filenames that begin with the ":" character. it is recommended that when a database filename actually does begin with a ":" character you shoshould prefix the filename with a pathname such ". /"to avoid ambiguity.

If the file name is ": memory:", a private, in-memory database is created for the connection. When the database connection is closed, the memory database will no longer exist. Later versions of SQLite may use other special file names starting. When the database file name does start with the ":" character, we recommend that you add the path name prefix (for example, "./") in the file name to avoid ambiguity.

 

If the filename is an empty string, then a private, temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.

If the file name is a Null String, a private, temporary disk database will be created. The private database will be automatically deleted as long as the database connection is closed.

 

The fourth parameter to sqlite3_open_v2 () is the name ofSqlite3_vfsObject that defines the operating system interface that the new database connection shocould use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.

The first parameter of sqlite3_open_v2 () is the name of the sqlite3_vfs object. It defines the operating system interface that should be used for new data connections. If 4th parameters are NULL pointers, the default sqlite3_vfs object is used.

 

Note to Windows users:The encoding used for the filename argument of sqlite3_open () and sqlite3_open_v2 () must be UTF-8, not whatever codepage is currently defined. filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open () or sqlite3_open_v2 ().

Note for Windows users:The encoded file name parameters for sqlite3_open () and sqlite_open_v2 () must be UTF-8. A file name that contains international characters must be converted to a UTF-8 before being passed to sqlite_open () or sqlite_open_v2.