flash.data

# SQLResult - AS3

Package | flash.data
Class | public class SQLResult
Inheritance | SQLResult Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The SQLResult class provides access to data returned in response to the execution of a SQL statement (a SQLStatement instance).

The SQLResult instance for a SQL statement is accessed by calling the `SQLStatement.getResult()` method or as an argument passed to the result handler of a Responder instance specified in a call to `SQLStatement.execute()` or `SQLStatement.next()`. Generally, developer code does not construct SQLResult instances directly.

You use a SQLResult object to access the rows of data returned from a `SELECT` statement (using the `data` property), to get row identifier information for an `INSERT` statement (using the `lastInsertRowID` property), to determine the number of rows affected by an `INSERT`, `UPDATE`, or `DELETE` statement (using the `rowsAffected` property), or to determine whether there are additional `SELECT` result rows that haven't been retrieved (using the `complete` property).

More examples

Accessing SELECT statement result data

Related API Elements

flash.data.SQLStatement.getResult()
flash.data.SQLStatement.execute()
flash.data.SQLStatement.next()

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | complete : Boolean [read-only] Indicates whether all the resulting data from a statement execution has been returned. | SQLResult
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | data : Array [read-only] The data returned as a result of the statement execution, specifically when a SQL SELECT statement is executed. | SQLResult
|  | lastInsertRowID : Number [read-only] The last generated row identifier generated by a SQL INSERT statement. | SQLResult
|  | rowsAffected : Number [read-only] Indicates how many rows were affected by the operation. | SQLResult

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | SQLResult(data:Array = null, rowsAffected:Number = 0, complete:Boolean = true, rowID:Number = 0) Creates a SQLResult instance. | SQLResult
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### complete

property

`complete:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Indicates whether all the resulting data from a statement execution has been returned.

When a statement returns one or more rows this property indicates whether all of the rows have been returned. When a SQLStatement object's `execute()` method is called with a `prefetch` argument value, only the specified number of rows of the resulting data are returned in the SQLResult object's `data` property. Subsequent calls to `SQLStatement.next()` cause additional data to become available. This property is used to determine when the final results have been returned.

Note that because the number of rows is unknown at execution time, the database cursor must move beyond the last row before a statement's execution is considered complete. When the `SQLStatement.execute()` method is called with a `prefetch` argument, at least one row more than the total number of rows in the result set must be requested before the resulting SQLResult instance's `complete` property is `true`.

Implementation
`public function get complete():Boolean`

Related API Elements

flash.data.SQLStatement.execute()
flash.data.SQLStatement.next()

### data

property

`data:Array` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The data returned as a result of the statement execution, specifically when a SQL `SELECT` statement is executed.

When a statement returns one or more rows this property is an array containing objects that represent the rows of result data. Each object in the array has property names that correspond to the result data set's column names.

For example, suppose you execute the following SQL `SELECT` statement:

Copy

         SELECT lastName, firstName
         FROM employees

Assuming the `employees` table contains 10 rows, the `SQLResult.data` property is an Array with 10 elements. Each element is an object with two properties, `lastName` and `firstName`.

The situation is more complex when you are using a `SELECT` statement with a complex result column, such as an aggregate function. For example, suppose you execute the following SQL:

Copy

         SELECT departmentId, SUM(salary)
         FROM employees
         GROUP BY departmentId

In the results from this statement, each object in the `data` Array has two properties named `departmentId` and `SUM(salary)`. However, "SUM(salary)" is not a valid identifier. If you are using a computed column such as an aggregate or other function, specify an alias for the computed column in your SQL statement. The alias is used as the property name in the result data objects. For example, consider this alternative to the previous statement:

Copy

         SELECT departmentId, SUM(salary) AS salarySubtotal
         FROM employees
         GROUP BY departmentId

In this statement's `data` array, the result objects have two properties named `departmentId` and `salarySubtotal`.

The `data` property is always an Array regardless of how many rows and columns are in the result set. For example, the following `SELECT` statement results in one row and one column, which is essentially a single value:

         SELECT COUNT(*) AS numEmployees
         FROM employees

Copy

After executing the query the `data` property contains an Array object with one element. That element is an object with a single property, `numEmployees`.

If there are duplicate column names in the result data, for example if the `SELECT` statement includes an two different `id` columns from two different tables, the duplicate names are given property names according to the value of the `SQLConnection.columnNameStyle` property. By default, each column's name is used as the property name, but if there is are multiple columns in the result set with the same name, the long name format `[table-name]_[column-name]` is used for the identically named columns. This behavior can be changed by setting the `SQLConnection.columnNameStyle` property.

By default the objects in the `data` Array are Object instances. However, by setting the value of the `SQLStatement.itemClass` property to a class, the `data` Array elements are created as instances of that class instead. For every column in the result data set, the `itemClass` class must have a property whose name exactly matches the column name.

If a statement does not return any data this property is `null`. This is the case if the statement is not a `SELECT` statement, or if it is a `SELECT` statement that returns 0 rows.

Implementation
`public function get data():Array`

Related API Elements

SQLConnection.columnNameStyle
SQLStatement.itemClass
Example ( How to use this example )
The following code demonstrates using the `itemClass` property to have the runtime create instances of a custom class from SQL `SELECT` statement results.
Copy

    // Employee class definition
    package
    {
        public class Employee
        {
            public var name:String;
            public var ssn:String;
            public var id:uint;
            public override function toString():String
            {
                return "id: "+ id.toString() + " name: " + name + " ssn: " + ssn;
            }
        }
    }

    // using the Employee class as SQLStatement.itemClass
    var conn:SQLConnection;
    var dbStatement:SQLStatement;

    function init():void
    {
        conn = new SQLConnection();
        conn.addEventListener(SQLEvent.OPEN, connOpenHandler);

        dbStatement = new SQLStatement();
        dbStatement.sqlConnection = conn;
        dbStatement.text = "SELECT id, name, ssn FROM employees";
        dbStatement.itemClass = Employee;

        var dbFile:File = new File(File.separator + "employee.db");
        conn.open(dbFile);
    }

    function connOpenHandler(event:SQLEvent):void
    {
        dbStatement.addEventListener(SQLEvent.RESULT, resultHandler);
        dbStatement.execute();
    }

    function resultHandler(event:SQLEvent):void
    {
        var result:SQLResult = dbStatement.getResult();
        if (result != null)
        {
            var emp:Employee;
            var numRows:int = result.data.length;
            for (var i:int = 0; i < numRows; i++)
            {
                emp = result.data[i];
                trace(emp.toString());
            }
        }
    }

### lastInsertRowID

property

`lastInsertRowID:Number` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The last generated row identifier generated by a SQL `INSERT` statement.

The value is 0 if the executed statement was not an `INSERT` statement.

A row identifier is used to uniquely identify a row in a table within the database. The value is frequently generated by the database.

For more information about primary keys and generated row identifiers, see the "CREATE TABLE" and "Expressions" sections in the appendix "SQL support in local databases."

Implementation
`public function get lastInsertRowID():Number`

More examples

Retrieving a database-generated primary key of an inserted row

Related API Elements

flash.data.SQLConnection.lastInsertRowID
flash.events.SQLUpdateEvent.rowID

### rowsAffected

property

`rowsAffected:Number` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Indicates how many rows were affected by the operation. Only changes that are directly specified by an `INSERT`, `UPDATE`, or `DELETE` statement are counted.

Auxiliary changes caused by triggers are not counted. Use the `SQLConnection.totalChanges` property to find the total number of changes including changes caused by triggers.

Note that when the related SQL operation is a `DELETE` statement with no `WHERE` clause (that is, the statement deletes all the rows in the table), the `rowsAffected` property is always 0, regardless of the number of rows that were deleted. If you need to know the number of rows that are deleted, you can include the `WHERE` clause `WHERE 1 = 1`, in which case all the rows are deleted, and the `rowsAffected` property accurately reflects the number of rows that were deleted. However, depending on the number of rows being deleted, doing so may have a negative impact on the statement's performance.

Implementation
`public function get rowsAffected():Number`

Related API Elements

flash.data.SQLConnection.totalChanges
Constructor Detail

### SQLResult

()
Constructor

`public function SQLResult(data:Array = null, rowsAffected:Number = 0, complete:Boolean = true, rowID:Number = 0)`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Creates a SQLResult instance. Generally, developer code does not call the SQLResult constructor directly. To retrieve a SQLResult instance associated with a particular SQLStatement instance, call the instance's `getResult()` method. A SQLResult instance is also passed as an argument to the result handler function when a Responder instance is specified for an `execute()` or `next()` method call.

Parameters

| `data:Array` (default = `null`)`` — The array of rows returned from the execution of a statement. If the statement doesn't return any rows this value should be null.
| `rowsAffected:Number` (default = `0`)`` — Indicates how many rows the executed statement affected.
| `complete:Boolean` (default = `true`)`` — Indicates whether there are additional rows that can be fetched or whether all data has been returned.
| `rowID:Number` (default = `0`)`` — If the statement was a SQL `INSERT` operation this is the new unique identifier for the row.

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00