Developer Resources

DbResult

Overview

The DbResult class is used to retrieve tabular data from a result set. After a query has successfully been run, a DbResult object is returned from the DbConnection.execute() function. Using this object, the caller can iterate through all rows in the result set and retrieve the data contained in the rows. The DbResult object can be used much like an array, with field values becoming named elements in that array. When the next row is fetched using the next() function, these values are replaced with the next row's data.

Methods

DbResult.getColumnCount
Returns the number of columns available in the result set
DbResult.getColumnInfo
Returns information about a specified column
DbResult.getColumnName
Returns the name of the column for a given column index
DbResult.getValue
Returns the name of the column for a given column index
DbResult.hasNext
Determines if the end of the result set has been reached
DbResult.next
Moves the row pointer to the next row in the result set

Example

// connect to local project database
var db = HostApp.getDatabase();

// create a table
var result = db.execute("CREATE TABLE mytable (field1 VARCHAR(80));");

// add some rows
db.execute("
        INSERT INTO mytable (field1) VALUES ('111');
        INSERT INTO mytable (field1) VALUES ('222');
        INSERT INTO mytable (field1) VALUES ('333');
        ");

// update application's project tree (we do this
// so that the newly created table displays in the
// application project tree)
HostApp.refresh();

// select the rows and display the values
var result = db.execute("SELECT * FROM mytable");

while (result.next())
{
    alert(result.field1);
}

DbResult.getColumnCount

function DbResult.getColumnCount() : Integer

Returns

An Integer which indicates the number of columns available in the result set.

Description

Returns the number of columns available in the result set. The field values can be referenced by either their field name or the zero-based field index.

DbResult.getColumnInfo

function DbResult.getColumnInfo(name : String) : DbColumn
function DbResult.getColumnInfo(index : Integer) : DbColumn

Returns

A DbColumn object containing the column information for the specified column. If the specified column index is out of range, or the specified column name doesn't exist, null is returned.

Description

Returns a DbColumn object with information about the column specified in the parameter (either by zero-based column index or column name). If the specified column index is out of range, or the specified column name doesn't exist, null is returned.

DbResult.getColumnName

function DbResult.getColumnName(index : Integer) : String

Returns

The column name in the result set as specified by the field index. If the index is out of range, an empty string is returned

Description

Returns the name of the column specified by the column index passed in the index parameter. Column indexes are zero-based, meaning that the first column is 0, the second 1, and so on.

DbResult.getValue

function DbResult.getValue(column_name : String) : Object
function DbResult.getValue(column_index : Integer) : Object

Arguments

column_name
The name of the desired column
column_index
The zero-based index of the desired column

Returns

An object containing the field value, or null if an error occurred.

Description

This function yields the same results that using the array operator does. A call to the method returns the value of the field specified by either the column_name or column_index parameter. The type of the return value is automatically determined by the column's type. Fields with a date or date/time type are returned as a string, which can be easily cast into a Date object.

DbResult.hasNext

function DbResult.hasNext() : Boolean

Returns

True if the row pointer does not currently point to the last record in the result set, otherwise false.

Description

Returns true if a call to next() will move the row to a valid record. If the row pointer is currently positioned on the last row of the result set, the call will return false.

DbResult.next

function DbResult.next() : Boolean

Returns

True if the row pointer was successfully moved to the next row, or false if the end of the result set was reached.

Description

Calling next() moves the row pointer to the next row in the result set. Also, after running a query, it is used to place the row pointer to the first row in the result set. If the end of the result set is reached, the function will return false. If the call succeeded and a new row is available for reading, the call will return true.