SQLStatement  - AS3

ステートメントが現在実行中かどうかを示します。

execute() が呼び出され、データベースから返されていない結果がある場合、このプロパティは true になります。

関連する API エレメント

ステートメントの実行結果として返された各行で使用されているクラス（データ型）を示します。

デフォルトでは、SELECT ステートメントから返される各行は Object インスタンスとして作成されます。このインスタンスでは、結果セットの列名がオブジェクトのプロパティの名前として使用され、各列の値が、それぞれに関連付けられているプロパティの値として使用されます。

itemClass プロパティでクラスを指定すると、この SQLStatement インスタンスで実行されている SELECT ステートメントから返される各行は、指定されたクラスのインスタンスとして作成されます。itemClass インスタンスの各プロパティには、そのプロパティと同じ名前を持つ列の値が割り当てられます。

このプロパティに割り当てるクラスは、パラメーターを必要としないコンストラクターを持っていなければなりません。また、このクラスは、SELECT ステートメントから返される各列に対応する、個別のプロパティを持っていなければなりません。SELECT リストの列と一致するプロパティ名が itemClass クラスにない場合は、エラーと見なされます。

関連する API エレメント

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

SQL ステートメントの text プロパティで指定されたパラメーターの値を追加する結合配列として機能します。 配列のキーは、パラメーターの名前です。 名前が付いていないパラメーターがステートメントのテキストで指定されている場合は、パラメーターのインデックスがキーになります。

SQL ステートメントのテキストでは、パラメーターは「?」、「:」または「@」のいずれかの文字で示されます。

「:」および「@」トークンは、名前の付いているパラメーターを示し、トークンに続く文字がパラメーターの名前として解釈されます。

例えば、次の SQL ステートメントでは、firstName という名前のパラメーターを「:」文字で指定しています。

SELECT FROM employees WHERE firstName = :firstName

「?」トークンは、インデックス付けされた（番号が付けられた）パラメーターを示します。各パラメーターには、ステートメントのテキストの順序に従って、自動的にインデックスが与えられます。パラメーターのインデックス値は 0 から始まります。つまり、最初のパラメーターのインデックスは 0 になります。

パラメーターは、SQL ステートメントの構築時に不明な値を、型指定して置き換える手段として使用されます。 データベースに渡される値の記憶クラスを保証するには、パラメーターを使用する以外に方法はありません。 パラメーターが使用されていない場合、関連付けられている列の型の類似性に基づいて、すべての値がテキスト表現から記憶クラスに変換されます。記憶クラスと列の類似性について詳しくは、「データタイプサポート」のセクション（付録「ローカルデータベースでの SQL サポート」にあります）を参照してください。

パラメーターは、SQL インジェクションアタックと呼ばれる悪質な手法を防ぐセキュリティ手段としても使用されます。SQL インジェクションアタックでは、ユーザーがアクセス可能な場所（データ入力フィールドなど）に SQL コードを入力します。アプリケーションコードが、ユーザーの入力を SQL テキストと直接連結して SQL ステートメントを構築すると、ユーザーが入力した SQL コードがデータベースに対して実行されてしまいます。次のコードは、ユーザーの入力を SQL テキストに連結する例を示したものです。この手法は使用しないでください。

     // 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;
     

ユーザーが入力した値をステートメントのテキストに連結するのではなく、ステートメントのパラメーターを使用することで、SQL インジェクションアタックを防ぐことができます。これは、パラメーター値が明示的に置き換え値として扱われ、そのままステートメントのテキストの一部とはならないからです。上記のコードは、次のように書き換えることが推奨されます。

     // 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;
     

すべてのパラメーター値は、ステートメントを実行する前に設定する必要があります。 parameters 配列で指定されたパラメーター値は、execute() メソッドが呼び出されるとバインドされます（ステートメントのテキストと結合されます）。 execute() が呼び出されると、その後で値に加えられた変更は、実行中のステートメントには適用されません。ただし、その後で execute() を呼び出した場合は、変更された値が使用されます。ステートメントのテキストに、parameters プロパティで指定された値が設定されていないパラメーターが含まれている場合は、エラーが発生します。

parameters プロパティからすべてのパラメーター値をクリアするには、clearParameters() メソッドを使用します。

関連する API エレメント

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

ステートメントの実行対象となっているデータベースへの接続を管理する SQLConnection オブジェクトです。

ステートメントの実際の SQL テキストです。

テキストは、サポートされている任意の SQL にすることができます。ローカル SQL データベースでサポートされている SQL ダイアレクトの詳細な説明については、付録「ローカルデータベースでの SQL サポート」を参照してください。

SQLStatement インスタンスを作成します。

このステートメントの実行をキャンセルします。SQLConnection.cancel() と同様、このメソッドは、長時間実行されているクエリを停止する場合や、完了していないクエリをキャンセルする場合に使用します。ただし、SQLConnection.cancel() とは異なり、このメソッドは単一のステートメントだけをキャンセルします。ステートメントが現在実行中でない場合は、このメソッドを呼び出しても何も実行されません。

cancel() 操作の完了に直接応答する形でイベントが送出されることはありません。ただし、cancel() 操作が完了してステートメントの実行がキャンセルされると、SQLStatement インスタンスは error イベントを送出し、ステートメントの実行（execute() または next() の呼び出し）が完了しなかったことを示します。または、responder パラメーター（execute() または next() 呼び出しのパラメーター）に値が指定されている場合は、指定されたフォルトハンドラーメソッドが呼び出されます。 いずれの場合も、リスナーに渡される SQLError インスタンスの errorID プロパティには、3118（処理の中止）という値が設定されます。

現在のパラメーター設定をすべてクリアします。

関連する API エレメント

text プロパティの SQL を、sqlConnection プロパティの SQLConnection オブジェクトに接続されているデータベースに対して実行します。

responder 引数が null 以外の場合は、指定された Responder オブジェクトによって、操作の結果を処理するために呼び出されるメソッドが指定されます。responder 引数が null の場合は、非同期実行モードで操作が正常に完了すると result イベントが送出され、操作が失敗すると error イベントが送出されます。

ステートメントの結果（SELECT ステートメントの結果行や INSERT ステートメントでデータベースが生成したプライマリキーなど）にアクセスするには、getResult() メソッドを呼び出します。同期モードでは、ステートメントの実行直後に、非同期モードでは、result イベントの送出時に、結果を確認できます。

すべてのステートメントは、準備（コンパイル）しなければ実行できません。ステートメントは、SQLStatement インスタンスの execute() メソッドの初回呼び出し時に、ランタイムによって準備されます。ステートメントが準備されたら、text プロパティが変更されない限り、再度準備する必要はありません。パラメーター値を設定する場合は、ステートメントを再度準備する必要はありません。

パラメーター

関連する API エレメント

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.");
}

ステートメントの実行結果を含む SQLResult オブジェクトへのアクセスを提供します。この結果には、SELECT ステートメントの結果行と、実行されたすべてのステートメントのステートメント実行に関するその他の情報が含まれます。非同期モードでは、result イベントが送出されるまで、結果情報を取得できません。

SELECT ステートメントを、execute() メソッドがデフォルトの prefetch 引数（-1）を指定して呼び出されている場合に実行すると、返される SQLResult オブジェクトにはクエリの結果セット全体が含まれます。

prefetch 引数が、execute() メソッドまたは next() メソッドの呼び出しで指定されている場合、getResult() メソッドは結果の先入れ先出しキューとして動作します。result イベントが送出されるたびに、新しい SQLResult オブジェクトがキューに追加されます。getResult() メソッドが呼び出されるたびに、最も古い SQLResult オブジェクト（最初にキューに追加されたもの）が返され、キューから削除されます。キューに存在する SQLResult オブジェクトがなくなると、getResult() は null を返します。

getResult() を呼び出して削除されない限り、SQLResult オブジェクトはキューに残ることに注意してください。例えば、execute() メソッドを、getResult() を呼び出さずに繰り返し呼び出すと、各 execute() 呼び出しに関連付けられている SQLResult オブジェクトは、そのままキューに残ります。

関連する API エレメント

SELECT ステートメントの結果セットの次の部分を取得します。結果セットにこれ以上行がない場合、result イベントは送出されますが、SQLResult オブジェクトが新たに getResult() キューに追加されることはありません。

非同期実行モードでは、responder 引数が null でない場合、操作の結果を処理するために呼び出されるメソッドは指定された Responder によって示されます。responder 引数が null の場合は、操作が正しく完了すると result イベントが送出され、操作が失敗すると error イベントが送出されます。

このメソッドは、ステートメントが実行中の場合にのみ呼び出せます。ステートメントが SELECT クエリで、prefetch 引数に 0 より大きい値が指定されている場合、結果セット全体が返されるまで、または SQLStatement.cancel() メソッドまたは SQLConnection.cancel() メソッドが呼び出されるまで、ステートメントが実行されるものと見なされます。

パラメーター

関連する API エレメント

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.");
}

処理中にエラーが発生した場合に送出されます。

関連する API エレメント

execute() メソッドまたは next() メソッド呼び出しの処理が正常に完了したときに送出されます。result イベントが送出されたら、getResult() メソッドを呼び出してステートメントの結果を取得できます。

関連する API エレメント