DatabaseOpen
Script function

world.DatabaseOpen

DOC_scripting Read about scripting

Type

Method

Summary

Opens an SQLite database

Prototype

long DatabaseOpen(BSTR Name, BSTR Filename, long Flags);

DOC_data_types View list of data type meanings

Description

Opens or creates a database. Databases can be held in memory or on disk. You need read or write permissions to access the database, as it is stored on disk as a normal disk file.

Name - a unique ID you choose to identify this database for all other operations on it (Eg. "db").

Filename - the file name on disk. The special filename ":memory:" opens an in-memory database. This can be used to manipulate data (or play with SQL) without actually writing to disk.

Flags -

Open_ReadOnly = 0x00000001
Open_ReadWrite = 0x00000002
Open_Create = 0x00000004
Open_DeleteOnClose = 0x00000008
Open_Exclusive = 0x00000010
Open_Main_db = 0x00000100
Open_Temp_db = 0x00000200
Open_Transient_db = 0x00000400
Open_Main_Journal = 0x00000800
Open_Temp_Journal = 0x00001000
Open_SubJournal = 0x00002000
Open_Master_Journal = 0x00004000
Open_NoMutex = 0x00008000
Open_FullMutex = 0x00010000

Warning - the SQLite documentation suggests that you choose one of:

Open_ReadOnly (1)
Open_ReadWrite (2) or
Open_ReadWrite + Open_Create (6)

If not, the behaviour of the open may be undefined.

Use DatabaseClose to close the database when you are finished with it.

If the database is still open when the world file is closed, the database is automatically closed.

It is not an error to re-open the same database ID of an existing, open, database, provided the disk file name is the same. This will be treated as a no-operation, so that triggers and aliases can open the database without having to check first if it was already open.

Lua example

DatabaseOpen ("db",   -- database ID
              GetInfo (66) .. "mytestdb.sqlite",   -- file name
              6)      -- flags

-- do stuff with the database here

DatabaseClose ("db")  -- close it


Lua notes

The Flags parameter can be omitted, and defaults to 6 (Open_ReadWrite + Open_Create).


Return value

0 : success

-6 : Database already exists under a different disk name

Otherwise, an SQLite error code, and the database ID cannot be used



See Also ...

Topics

DOC_database Database (SQLite)
DOC_lua_sqlite3 Lua SQLite (database) interface
DOC_scripting Scripting

Functions

FNC_DatabaseChanges DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)
FNC_DatabaseClose DatabaseClose (Closes an SQLite database)
FNC_DatabaseColumnName DatabaseColumnName (Find the name of a specified column returned by an SQL statement)
FNC_DatabaseColumnNames DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)
FNC_DatabaseColumns DatabaseColumns (Find how many columns will be returned by an SQL statement)
FNC_DatabaseColumnText DatabaseColumnText (Returns the contents of an SQL column, as text)
FNC_DatabaseColumnType DatabaseColumnType (Returns the type of data in an SQL column)
FNC_DatabaseColumnValue DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)
FNC_DatabaseColumnValues DatabaseColumnValues (Returns the contents of all the SQL columns after a step)
FNC_DatabaseError DatabaseError (Returns an English string describing the most recent SQL error)
FNC_DatabaseExec DatabaseExec (Executes SQL code against an SQLite database)
FNC_DatabaseFinalize DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)
FNC_DatabaseInfo DatabaseInfo (Returns information about a database)
FNC_DatabaseLastInsertRowid DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)
FNC_DatabaseList DatabaseList (Lists all databases)
FNC_DatabaseOpen DatabaseOpen (Opens an SQLite database)
FNC_DatabasePrepare DatabasePrepare (Prepares an SQL statement for execution)
FNC_DatabaseReset DatabaseReset (Resets a previously-prepared SQL statement to the start)
FNC_DatabaseStep DatabaseStep (Executes a previously-prepared SQL statement)
FNC_DatabaseTotalChanges DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseOpen)

DOC_contents Documentation contents page