SQLStatement  - AS3

Indica se a instrução está sendo executada no momento.

Essa propriedade será true se execute() tiver sido chamado e se nem todos os resultados tiverem sido retornados do banco de dados.

Elementos da API relacionados

Indica uma classe (tipo de dado) que é usada para cada linha retornada como um resultado da execução da instrução.

Por padrão, cada linha retornada por uma instrução SELECT é criada como uma ocorrência Object, com os nomes das colunas do conjunto de resultados conforme os nomes das propriedades do objeto, e o valor de cada coluna conforme o valor de sua propriedade associada.

Ao especificar uma classe para a propriedade itemClass, cada linha retornada por uma instrução SELECT executada por essa ocorrência SQLStatement é criada como uma ocorrência da classe designada. Cada propriedade da ocorrência itemClass recebe o valor da coluna com o mesmo nome da propriedade.

Qualquer classe atribuída a essa propriedade deve ter um construtor que não requeira qualquer parâmetro. Além disso, a classe deve ter uma única propriedade para cada coluna retornada pela instrução SELECT. Será considerado um erro se uma coluna na lista SELECT não tiver um nome de propriedade correspondente na classe itemClass.

Elementos da API relacionados

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

Serve como uma matriz associativa à qual você adiciona valores para os parâmetros especificados na propriedade text da instrução SQL. As chaves da matriz são os nomes dos parâmetros. Se um parâmetro sem nome é especificado no texto da instrução, sua chave é o índice do parâmetro.

Dentro do texto de uma instrução SQL, um parâmetro é indicado com um dos seguintes caracteres: "?", ":" ou "@".

As fichas ":" e "@" indicam um parâmetro nomeado; os caracteres seguintes à ficha designam o nome do parâmetro.

Por exemplo, na seguinte instrução SQL, um parâmetro nomeado firstName é especificado usando o caractere ":":

SELECT FROM employees WHERE firstName = :firstName

A ficha "?" indica um parâmetro indexado (numerado); cada parâmetro recebe automaticamente um índice de acordo com a sequência dos parâmetros no texto da instrução. Os valores de índices de parâmetros são baseados em zero. Em outras palavras, o índice do primeiro parâmetro é 0.

Os parâmetros são usados para permitir a substituição digitada de valores que são desconhecidos no momento em que a instrução SQL é construída. O uso de parâmetros é o único modo de garantir a classe de armazenamento para um valor passado ao banco de dados. Quando os parâmetros não são usados, todos os valores são convertidos de sua representação de texto para uma classe de armazenamento baseada na afinidade do tipo da coluna associada. Para obter mais informações sobre classes de armazenamento e afinidade de colunas, consulte a seção "Suporte ao tipo de dados" no apêndice "Suporte SQL em bancos de dados locais".

Os parâmetros também são usados como medida de segurança para evitar um técnica mal-intencionada conhecida como ataque de injeção SQL. Em um ataque de injeção SQL, um usuário informa o código SQL em um local acessível ao usuário (por exemplo, um campo de entrada de dados). Se o código do aplicativo construir uma instrução SQL concatenando diretamente a entrada do usuário no texto SQL, o código SQL informado pelo usuário será executado em relação ao banco de dados. A lista a seguir mostra um exemplo de concatenação da entrada do usuário no texto SQL. Não use essa técnica:

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

O uso de parâmetros de instruções em vez da concatenação de valores informados pelo usuário no texto de uma instrução evita um ataque de injeção SQL, pois os valores de parâmetros são tratados explicitamente como valores substituídos, em vez de se tornarem parte do texto literal da instrução. A seguir, é dada a alternativa recomendada para a listagem anterior:

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

Todos os valores de parâmetros devem ser definidos antes da execução da instrução. Os valores de parâmetros especificados na matriz parameters são vinculados (ou seja, combinados com o texto da instrução) quando o método execute() é chamado. Uma vez que execute() tenha sido chamado, quaisquer alterações subsequentes nos valores não serão aplicadas à instrução em execução. No entanto, em uma chamada execute() subsequente, os valores alterados são usados. Se o texto da instrução incluir um parâmetro que não tenha um valor especificado na propriedade parameters, ocorrerá um erro.

Para limpar todos os valores de parâmetros da propriedade tempo de execução do Flash, use o método clearParameters().

Elementos da API relacionados

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

O objeto SQLConnection que gerencia a conexão com o(s) banco(s) de dados no(s) qual(is) a instrução é executada.

O texto SQL real da instrução.

O texto pode ser qualquer SQL suportada. Para uma descrição completa do dialeto SQL suportado em bancos de dados SQL locais, consulte o apêndice "Suporte SQL em bancos de dados locais".

Cria uma ocorrência SQLStatement.

Cancela a execução dessa instrução. Assim como SQLConnection.cancel(), esse método é usado para interromper uma longa consulta em execução ou para cancelar uma consulta que ainda não esteja concluída. No entanto, ao contrário de SQLConnection.cancel(), esse método só cancela a instrução única. Se a instrução não estiver em execução no momento, chamar esse método não terá efeito.

Nenhum evento é despachado em resposta direta à conclusão da operação cancel(). No entanto, uma vez que a operação cancel() esteja concluída e a execução da instrução seja cancelada, a ocorrência SQLStatement despacha um evento error indicando que a execução da instrução (a chamada execute() ou next()) não foi concluída. Como alternativa, se um valor foi especificado para o parâmetro responder da chamada execute() ou next(), o método do manipulador de faltas especificado é chamado. Em ambos os casos, a instância SQLError que é passada aos ouvintes terá uma propriedade errorID com um valor de 3118 (Operação abortada).

Limpa todas as definições de parâmetros atuais.

Elementos da API relacionados

Executa a SQL na propriedade text contra o banco de dados que está conectado ao objeto SQLConnection na propriedade sqlConnection.

No modo de execução assíncrono, se o argumento responder não for null, o objeto Responder especificado indicará os métodos que serão chamados para manipular os resultados da operação. Se o argumento responder for null, no modo de execução assíncrono, um evento result será despachado se a operação for bem-sucedida, ou um evento error será despachado se a operação falhar.

Acessar os resultados de uma instrução, tais como as linhas de resultado da instrução SELECT ou o banco de dados que gerou a chave primária de uma instrução INSERT, chame o método getResult(). Os resultados estão disponíveis imediatamente depois que a instrução realiza no modo síncrono e quando o evento result é despachado no modo assíncrono.

Cada instrução deve ser preparada (compilada) antes que possa ser executada. A primeira vez que um método execute() da instrução SQLStatement é chamado, a instrução é preparada pelo tempo de execução. Uma vez que a instrução esteja preparada, ela não precisará ser preparada novamente, a não ser que a propriedade text seja alterada. Definir um ou mais valores de parâmetros não requer que a instrução seja preparada novamente.

Parâmetros

Elementos da API relacionados

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

Provê acesso a um objeto SQLResult contendo os resultados da execução da instrução, incluindo qualquer linha de resultado de uma instrução SELECT e outras informações sobre a execução da instrução de todas as instruções executadas. No modo de execução assíncrono, as informações sobre resultados não ficam disponíveis até que o evento result seja despachado.

Quando uma instrução SELECT é executada, se o método execute() for chamado com o argumento padrão prefetch de -1, o objeto SQLResult retornado conterá o conjunto de resultados inteiro da consulta.

Quando um argumento prefetch é especificado para uma chamada do método execute() ou next(), o método getResult() comporta-se como uma fila de resultados do tipo primeiro a entrar, primeiro a sair. Toda vez que o evento result é despachado, um novo objeto SQLResult é adicionado à fila. Toda vez que o método getResult() é chamado, o objeto SQLResult mais antigo (aquele que foi adicionado à fila primeiro) é retornado e removido da fila. Quando não há mais objetos restantes SQLResult na fila, getResult() retorna null.

Observe que, a não ser que sejam removidos chamando getResult(), os objetos SQLResult permanecem na fila. Por exemplo, se o método execute() for chamado várias vezes sem chamar getResult(), os objetos SQLResult associados a cada chamada execute() permanecerão na fila.

Elementos da API relacionados

Recupera a próxima porção de um conjunto de resultados da instrução SELECT. Se não há mais linhas no conjunto de resultados, um evento result é despachado, mas nenhum outro objeto SQLResult é adicionado à fila getResult().

No modo de execução assíncrono, se o argumento responder não for null, o objeto Responder especificado indicará os métodos que serão chamados para manipular os resultados da operação. Se o argumento responder for null, um evento result será despachado se a operação for bem-sucedida, ou um evento error será despachado se a operação falhar.

Esse método só pode ser chamado quando a instrução ainda está em execução. Quando a instrução é uma consulta SELECT e é especificado um argumento prefetch maior do que zero, a instrução é considerada em execução até que o conjunto inteiro de resultados seja retornado, até que o método SQLStatement.cancel() ou SQLConnection.cancel() seja chamado.

Parâmetros

Elementos da API relacionados

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

Despachado quando ocorre um erro durante uma operação.

Elementos da API relacionados

Despachado quando uma operação de chamada dos métodos execute() ou next() é concluída com êxito. Uma vez que o evento result é despachado, o método getResult() pode ser chamado para recuperar resultados de instruções.

Elementos da API relacionados