DatabaseStep
Script function

world.DatabaseStep

DOC_scripting Read about scripting

Type

Method

Summary

Executes a previously-prepared SQL statement

Prototype

long DatabaseStep(BSTR Name);

DOC_data_types View list of data type meanings

Description

Executes an SQL statement over one row over the database. In the case of a SELECT statement, one row is returned for each call to DatabaseStep.

After successfully doing DatabasePrepare, you then need to call DatabaseStep for each row in the query. This is the execution phase. For SQL statements that return multiple rows of data, you need to do DatabaseStep once for each row. For SQL statements that just do one thing (like INSERT INTO) then you only need to call DatabaseStep once.

DatabaseStep will return SQLITE_ROW (100) if it has returned a row of data, otherwise it will return SQLITE_DONE (101) if it has reached the end of the query. You could make a loop that continues to call DatabaseStep until it no longer returns 100, in order to process every row in the query.

If you want to reprocess the SQL query from the start for some reason, you can call DatabaseReset and the query restarts at the beginning (you would then need to call DatabaseStep again to re-obtain the first row).

Lua example

require "tprint"

DatabaseOpen ("db", GetInfo (66) .. "mytestdb.sqlite", 6)

rc = DatabaseExec ("db", [[
DROP TABLE IF EXISTS weapons;
CREATE TABLE weapons(
        weapon_id INTEGER NOT NULL PRIMARY KEY autoincrement,
        name  TEXT NOT NULL,
        damage INT default 10,
        weight REAL
      );
      ]])
      

-- put some data into the database
DatabaseExec ("db", 
  [[
  INSERT INTO weapons (name, damage) VALUES ('sword', 42);
  INSERT INTO weapons (name, damage) VALUES ('mace', 55);
  INSERT INTO weapons (name, damage) VALUES ('staff', 35);
  ]])

-- prepare a query
DatabasePrepare ("db", "SELECT * from weapons ORDER BY name")

-- find the column names
names = DatabaseColumnNames ("db")
tprint (names)

-- execute to get the first row
rc = DatabaseStep ("db")  -- read first row

-- now loop, displaying each row, and getting the next one
while rc == 100 do
  
  print ("")
  values = DatabaseColumnValues ("db")
  tprint (values)

  rc = DatabaseStep ("db")  -- read next row

end -- while loop

-- finished with the statement
DatabaseFinalize ("db")

DatabaseClose ("db")  -- close it


Return value

100: Another row is ready.
101: Completed OK, no further rows.

-1 : Database id not found
-2 : Database not open
-4 : Do not have prepared statement


Otherwise an SQLite return code. For example:

1: SQL error or missing database
5 : The database file is locked
21 : Library used incorrectly



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_DatabaseTotalChanges DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseStep)

DOC_contents Documentation contents page