system.db.runScalarQuery

Description

Runs a query against a database connection just like the runQuery function, but only returns the value from the first row and column.  If no results are returned from the query, the special value None is returned.

Syntax

system.db.runScalarQuery(query, database, tx)

Parameters

String query - A SQL query that should be designed to return one row and one column.

String database - The name of the database connection to execute against. If omitted or "", the project's default database connection will be used.

String tx - A transaction identifier. If omitted, the query will be executed in its own transaction.

Returns

Object - The value from the first row and first column of the results. Returns None if no rows were returned.

Scope

All

Examples

Example 1:

# This code would count the number of active alarms, and acknowledge them all if there is at least one.

numAlarms = system.db.runScalarQuery("SELECT COUNT(*) FROM alarmstatus "

 + "WHERE unacknowledged = 1") 
if numAlarms > 0: 
   # There are alarms - acknowledge all of them 
   system.db.runUpdateQuery("UPDATE alarmstatus SET unacknowledged = 0")

Example 2:

This code would read a single value from a table and show it to the user an a popup box.

level = system.db.runScalarQuery("SELECT Level FROM LakeInfo WHERE LakeId='Tahoe'") 
system.gui.messageBox("The lake level is: %d feet" % level) 

lakeLevel = system.db.runScalarQuery(query) 
system.gui.messageBox("The lake level is: %d feet" % lakeLevel)