SQLStatement  - AS3

Gibt an, ob die Anweisung aktuell ausgeführt wird.

Diese Eigenschaft hat den Wert „true“, wenn execute() aufgerufen wurde und von der Datenbank nicht alle Ergebnisse zurückgegeben wurden.

Verwandte API-Elemente

Gibt eine Klasse (Datentyp) an, die für jede als Ergebnis der Anweisungsausführung zurückgebenene Zeile verwendet wird.

Standardmäßig wird jede von einer SELECT-Anweisung zurückgegebene Zeile als „Object“-Instanz erstellt. Dabei treten die Spaltennamen des Ergebnissatzes als Eigenschaftsnamen des Objekts auf und die Werte der Spalten als die Werte der jeweiligen Eigenschaften.

Durch die Angabe einer Klasse für die Eigenschaft itemClass wird jede Zeile, die bei der Ausführung dieser „SQLStatement“-Instanz von einer SELECT-Anweisung zurückgegeben wird, als Instanz der angegebenen Klasse erstellt. Jeder Eigenschaft der Instanz itemClass wird der Wert aus der gleichnamigen Spalte zugewiesen.

Eine dieser Eigenschaft zugewiesene Klasse muss über einen Konstruktor verfügen, der keine Parameter erfordert. Außerdem muss die Klasse je eine Eigenschaft für jede von der Anweisung SELECT zurückgegebene Spalte aufweisen. Es gilt als Fehler, wenn es für eine Spalte der Liste SELECT keinen entsprechenden Eigenschaftsnamen in der Klasse itemClass gibt.

Verwandte API-Elemente

// 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());
        }
    }
}

Dient als assoziatives Array, dem Sie Werte für die in der Eigenschaft text der SQL-Anweisung angegebenen Parameter hinzufügen. Bei den Array-Schlüsseln handelt es sich um die Namen der Parameter. Wenn im Anweisungstext ein unbenannter Parameter angegeben wird, handelt es sich bei seinem Schlüssel um den Index des Parameters.

Im Text einer SQL-Anweisung wird ein Parameter mit einem der folgenden Zeichen gekennzeichnet: „?“, „:“ oder „@“.

Mit den Token „:“ und „@“ wird ein benannter Parameter gekennzeichnet; die darauf folgenden Zeichen geben den Namen des Parameters an.

Beispiel: In der folgenden SQL-Anweisung wird ein Parameter namens firstName mit dem Token „:“ gekennzeichnet:

SELECT FROM employees WHERE firstName = :firstName

Das Token „?“ kennzeichnet einen indizierten (nummerierten) Parameter; gemäß der Reihenfolge der Parameter im Anweisungstext erhält jeder Parameter automatisch eine Indexposition. Die Indexpositionswerte der Parameter basieren auf null. d. h. die Indexposition des ersten Parameters lautet 0.

Parameter dienen zur typisierten Ersetzung von Werten, die bei der Konstruktion der SQL-Anweisung unbekannt sind. Nur mithilfe von Parameter kann die Speicherklasse eines an die Datenbank übergebenen Wertes sichergestellt werden. Ohne Parameter werden alle Werte auf der Basis der Typenaffinität der zugewiesenen Spalte von ihrer Textrepräsentation in eine Speicherklasse konvertiert. Weitere Informationen zu Speicherklassen und Spaltenaffinität finden Sie im Abschnitt „Datentypunterstützung“ im Anhang „SQL-Unterstützung in lokalen Datenbanken“.

Parameter werden auch als Sicherheitsmaßnahmen zur Verhinderung eines böswilligen Verfahrens, das als SQL-Injektionsangriff bekannt ist, eingesetzt. Bei einem SQL-Injektionsangriff gibt ein Benutzer einen SQL-Code an einer für Benutzer zugänglichen Stelle ein (z. B. ein Dateneingabefeld). Wenn der Anwendungscode eine SQL-Anweisung durch die direkte Verkettung einer Benutzereingabe mit dem SQL-Text erstellt, wird der vom Benutzer eingegebene SQL-Code an der Datenbank ausgeführt. Das folgende Beispiel zeigt die Verkettung der Benutzereingabe mit dem SQL-Text. Verwenden Sie dieses Verfahren nicht:

     // assume the variables "username" and "password"
     // contain user-entered data
     var sql:String =
         "SELECT userId " +
         "FROM users " +
         "WHERE username = '" + username + "' " +
         "    AND password = '" + password + "'";
     var statement:SQLStatement = new SQLStatement();
     statement.text = sql;
     

Ein SQL-Injektionsangriff lässt sich verhindern, indem Anweisungsparameter verwendet werden, anstatt durch Benutzer eingegebene Werte mit dem Anweisungstext zu verketten. Die Parameterwerte werden ausdrücklich als ersetzte Werte behandelt und werden nicht Teil des eigentlichen Anweisungstexts. Folgendes ist die empfohlene Alternative zur vorherigen Notierung:

     // assume the variables "username" and "password"
     // contain user-entered data
     var sql:String =
         "SELECT userId " +
         "FROM users " +
         "WHERE username = :username " +
         "    AND password = :password";
     var statement:SQLStatement = new SQLStatement();
     statement.text = sql;
     // set parameter values
     statement.parameters[":username"] = username;
     statement.parameters[":password"] = password;
     

Alle Parameterwerte müssen vor der Ausführung der Anweisung eingestellt sein. Im Array parameters angegebene Parameter werden gebunden (d. h. mit dem Anweisungstext kombiniert), wenn die Methode execute() aufgerufen wird. Nachdem execute() aufgerufen wurde, werden alle späteren Werteänderungen nicht auf die ausführende Anweisung angewendet. Bei einem anschließenden Aufrufen von execute() werden die geänderten Werte jedoch angewendet. Enthält der Anweisungstext einen Parameter, für den in der parameters-Eigenschaft kein Wert angegeben ist, tritt ein Fehler auf.

Sie können alle Parameterwerte aus der Eigenschaft parameters mithilfe der Methode clearParameters() löschen.

Verwandte API-Elemente

// employees is a SQLStatement instance
employees.text = "SELECT FROM employees WHERE first = :firstName";
employees.parameters[":firstName"] = "Sam";
employees.execute();

// employees is a SQLStatement instance
employees.text = "SELECT FROM employees WHERE first = ?";
employees.parameters[0] = "Sam";
employees.execute();

Das SQLConnection-Objekt, das die Verbindung zu den Datenbanken verwaltet, auf denen die Anweisung ausgeführt wird.

Der tatsächliche SQL-Text der Anweisung.

Beim Text kann es sich um jede unterstützte SQL handeln. Eine umfassende Beschreibung des von der lokalen SQL-Datenbank unterstützten SQL-Dialekts finden Sie im Anhang „SQL-Unterstützung in lokalen Datenbanken“.

Erstellt eine „SQLStatement“-Instanz.

Bricht die Ausführung dieser Anweisung ab. Mithilfe dieser Methode können Sie, wie mit der SQLConnection.cancel()-Methode, eine noch nicht abgeschlossene Abfrage abbrechen. Im Gegensatz zu SQLConnection.cancel() wird mithilfe dieser Methode jedoch nur eine Anweisung abgebrochen. Wird diese Anweisung gerade nicht ausgeführt, hat das Aufrufen dieser Methode keine Auswirkung.

Als direkte Reaktion auf den Abschluss des Vorgangs cancel() werden keine Ereignisse ausgelöst. Sobald der Vorgang cancel() abgeschlossen und die Ausführung der Anweisung abgebrochen ist, wird von der „SQLStatement“-Instanz ein error-Ereignis ausgelöst, mit dem angegeben wird, dass die Ausführung der Anweisung (der Aufruf execute() oder next()) nicht abgeschlossen wurde. Wenn für den Parameter responder des Aufrufs execute() oder next() ein Wert angegeben wurde, wird die angegebene Fehlerprozedurmethode aufgerufen. In beiden Fällen weist die an die Listener übergebene SQLError-Instanz eine errorID-Eigenschaft mit dem Wert „3118“ (Vorgang abgebrochen) auf.

Löscht alle aktuellen Parametereinstellungen.

Verwandte API-Elemente

Führt die in der Eigenschaft text enthaltene SQL an der Datenbank aus, die mit dem „SQLConnection“-Objekt in der Eigenschaft sqlConnection verbunden ist.

Falls das responder-Argument nicht gleich null ist, gibt das festgelegte Responder-Objekt die Methoden an, die aufgerufen werden, um die Ergebnisse des Vorgangs zu verarbeiten. Wenn das Argument responder den Wert null hat, wird im asynchronen Ausführungsmodus bei einem erfolgreichen Abschluss des Vorgangs ein result-Ereignis ausgelöst. Schlägt der Vorgang fehl, wird ein error-Ereignis ausgelöst.

Um auf die Ergebnisse einer Anweisung zuzugreifen, zum Beispiel auf die Ergebniszeilen einer SELECT-Anweisung oder auf den von der Datenbank generierten primären Schlüssel einer INSERT-Anweisung, rufen Sie die getResult()-Methode auf. Die Ergebnisse sind im synchronen Modus sofort nach der Ausführung der Anweisung verfügbar; im asynchronen Modus nach dem Absetzen des result-Ereignisses.

Eine Anweisung kann erst ausgeführt werden, nachdem sie vorbereitet (kompiliert) wurde. Beim ersten Aufrufen der Methode execute() einer „SQLStatement“-Instanz wird die Anweisung zur Laufzeit vorbereitet. Eine einmal vorbereitete Anweisung braucht nur aufgrund einer Änderung der Eigenschaft text erneut vorbereitet zu werden. Durch die Einstellung von Parameterwerten wird keine erneute Vorbereitung der Anweisung erforderlich.

Parameter

Verwandte API-Elemente

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";
    
    var dbFile:File = new File(File.separator + "employee.db");
    conn.open(dbFile);
}

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

function resultHandler(event:SQLEvent):void
{
    var result:SQLResult = dbStatement.getResult();
    if (result != null)
    {
        var numRows:int = result.data.length;
        for (var i:int = 0; i < numRows; i++)
        {
            var row:Object = result.data[i];
            trace("id:", row.id, ", name:", row.name, ", ssn:", row.ssn);
        }
    }
}

function errorHandler(event:SQLErrorEvent):void
{
    trace("An error occured while executing the statement.");
}

var conn:SQLConnection;
var dbStatement:SQLStatement;
var employeeResponder:Responder;

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";
    
    var dbFile:File = new File(File.separator + "employee.db");
    conn.open(dbFile);
}

function connOpenHandler(event:SQLEvent):void
{
    employeeResponder = new Responder(resultHandler, errorHandler);
    dbStatement.execute(-1, employeeResponder);
}

function resultHandler(result:SQLResult):void
{
    if (result != null)
    {
        var numRows:int = result.data.length;
        for (var i:int = 0; i < numRows; i++)
        {
            var row:Object = result.data[i];
            trace("id:", row.id, ", name:", row.name, ", ssn:", row.ssn);
        }
    }
}

function errorHandler(error:SQLError):void
{
    trace("An error occured while executing the statement.");
}

Bietet Zugriff auf ein „SQLResult“-Objekt, das die Ergebnisse der Anweisungsausführung enthält, und zwar einschließlich der Ergebniszeilen einer SELECT-Anweisung sowie weiterer Informationen über die Anweisungsausführung für alle ausgeführten Anweisungen. Im asynchronen Modus stehen die Ergebnisinformationen erst nach Auslösung des result-Ergebnisses zur Verfügung.

Wenn bei der Ausführung einer SELECT-Anweisung die Methode execute() aufgerufen wird, wobei das Standardargument prefetch den Wert „-1“ hat, enthält das zurückgegebene „SQLResult“-Objekt den vollständigen Ergebnissatz der Abfrage.

Wurde das Argument prefetch für den Aufruf der Methode execute() oder next() angegeben, werden von der Methode getResult() die ältesten Ergebnisse in der Warteschlange zuerst verarbeitet. Jedesmal, wenn das Ereignis result ausgelöst wird, wird der Warteschlange ein neues „SQLResult“-Objekt hinzugefügt. Bei jedem Aufrufen der Methode getResult() wird das „SQLResult“-Objekt, das sich am längsten in der Warteschlange befindet, zurückgegeben und aus der Warteschlange entfernt. Enthält die Warteschlange keine „SQLResult“-Objekte mehr, gibt getResult() den Wert null zurück.

Beachten Sie, dass „SQLResult“-Objekte in der Warteschlange verbleiben, bis sie durch einen Aufruf von getResult() daraus entfernt werden. Beispiel: Wenn die execute()-Methode mehrfach aufgerufen wird, getResult() jedoch nicht, verbleiben die mit jedem Aufruf von execute() verknüpften SQLResult-Objekte in der Warteschlange.

Verwandte API-Elemente

Ruft den nächsten Teil des Ergebnissatzes einer SELECT-Anweisung ab. Wenn der Ergebnissatz keine weiteren Zeilen mehr enthält, wird ein result-Ereignis ausgelöst, aber kein weiteres „SQLResult“-Objekt zur Warteschlange getResult() hinzugefügt.

Falls im asynchronen Ausführungsmodus das responder-Argument nicht gleich null ist, gibt das festgelegte Responder-Objekt die Methoden an, die aufgerufen werden, um die Ergebnisse des Vorgangs zu verarbeiten. Wenn das Argument responder den Wert null hat, wird bei einem erfolgreichen Abschluss des Vorgangs ein result-Ereignis ausgelöst. Schlägt der Vorgang fehl, wird ein error-Ereignis ausgelöst.

Diese Methode kann nur aufgerufen werden, solange die Anweisung ausgeführt wird. Wenn es sich bei der Anweisung um eine SELECT-Abfrage handelt und ein prefetch-Argument größer Null angegeben wurde, wird die Anweisung ausgeführt, bis der gesamte Ergebnissatz zurückgegeben ist oder entweder die Methode SQLStatement.cancel() oder SQLConnection.cancel() aufgerufen wird.

Parameter

Verwandte API-Elemente

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";
    
    var dbFile:File = new File(File.separator + "employee.db");
    conn.open(dbFile);
}

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

function resultHandler(event:SQLEvent):void
{
    var result:SQLResult = dbStatement.getResult();
    if (result != null)
    {
        var numRows:int = result.data.length;
        for (var i:int = 0; i < numRows; i++)
        {
            var row:Object = result.data[i];
            trace("id:", row.id, ", name:", row.name, ", ssn:", row.ssn);
        }
        if (!result.complete)
        {
            dbStatement.next(10);
        }
    }
}

function errorHandler(event:SQLErrorEvent):void
{
    trace("An error occured while executing the statement.");
}

Wird ausgelöst, wenn während des Vorgangs ein Fehler auftritt.

Verwandte API-Elemente

Wird ausgelöst, wenn die Methode execute() oder next() erfolgreich ausgeführt wurde. Nachdem das Ereignis result ausgelöst wurde, können Sie die Methode getResult() aufrufen, um Anweisungsergebnisse abzurufen.

Verwandte API-Elemente