world.DatabaseGetField

MUSHclient script function (Method) — introduced in version 4.65

Returns a single field from an SQL database

Prototype

VARIANT DatabaseGetField(BSTR Name, BSTR Sql);

Data type meanings

Description

This executes SQL on a database previously opened with DatabaseOpen.

It lets you obtain a single value more easily than doing a DatabasePrepare / DatabaseStep / DatabaseColumnValue / DatabaseFinalize in the cases where you just want to establish a single thing (eg. the count of spells in a table).

You need to supply the database id of an existing opened database, and the SQL statement to be executed.

You cannot call DatabaseGetField if you have called DatabasePrepare but not DatabaseFinalize, as a statement is currently being processed.

The function effectively does this:

DatabasePrepare (Name, Sql)

If unsuccessful, exit with null variant.

Otherwise:
DatabaseStep (Name)

If successful, and a row was returned, then:
result = DatabaseColumnValue (Name, 1)

DatabaseFinalize (Name)

If successful, then the value for the first column of the first row is the return value, otherwise the null variant (nil in Lua).

Lua example

DatabaseOpen ("db", GetInfo (82), 1)

value = DatabaseGetField ("db", 
                          "SELECT value FROM control WHERE name = 'Version' ")

DatabaseClose ("db")

Lua notes

Returns nil on error.

Return value

The contents of the column, as a string, long, double or empty variant.

Returns the null variant if there is an error, such as invalid database id, no current row, etc.

Related topic

Database (SQLite)

See also