dbPoll

Recolhe o resultado de uma consulta.

Sintaxe

table, number, number dbPoll ( query aConsulta [, number timeout = 0, bool multiplosResultados = false ] )

Parâmetros

Nome	Tipo	Padrão	Descrição
aConsulta	query	—	Handle devolvido por dbQuery.
timeout	number	0	Quanto tempo esperar pelo resultado, em milissegundos. 0 verifica uma vez e volta na hora. Um número positivo espera até aquela quantidade de milissegundos. Um número negativo, -1 por convenção, espera o tempo que a consulta precisar.
multiplosResultados	bool	false	true devolve uma entrada por comando da consulta, em vez de apenas o primeiro.

Enquanto a consulta ainda está rodando — e quando um timeout positivo estoura antes de ela terminar — o dbPoll devolve nil. Isso não é erro: o handle continua válido e você consulta de novo mais tarde. Qualquer valor acima de 0 trava o servidor inteiro durante a espera, então use valores pequenos, ou trabalhe com callback e consulte com 0.

Retorno

Em caso de sucesso, três valores:

Posição	Descrição
1	As linhas, em uma tabela numerada a partir de 1. Cada linha é uma tabela com as colunas da consulta como chave.
2	Quantidade de linhas afetadas pelo comando — o valor útil depois de um INSERT, UPDATE ou DELETE.
3	Id gerado pela última inserção.

Os valores dentro de uma linha chegam como número, string ou booleano. Uma coluna NULL vem como false, e dados binários vêm como string.

Quando a consulta falha, o primeiro valor é false, seguido do código de erro do banco e da mensagem de erro. Você também recebe um false sozinho, com um aviso no console de debug, quando o handle não serve mais: já foi lido, foi descartado com dbFree, a conexão dele foi fechada ou ele nunca existiu.

local linhas = dbPoll(consulta, -1)

if linhas then
    outputDebugString(#linhas .. " conta(s) encontrada(s)")
    for _, linha in ipairs(linhas) do
        outputDebugString(linha.nome .. " -> " .. tostring(linha.dinheiro))
    end
end

O segundo e o terceiro valores são o que você quer depois de uma inserção:

local consulta = dbQuery(conexao, "INSERT INTO contas (nome, dinheiro) VALUES (?, ?)", nome, 0)
local linhas, afetadas, ultimoId = dbPoll(consulta, -1)

if linhas then
    outputDebugString("inseriu " .. afetadas .. " linha(s), novo id " .. ultimoId)
end

E, no caminho da falha, essas mesmas duas posições carregam o erro:

local linhas, codigoErro, mensagemErro = dbPoll(consulta, -1)

if linhas == false then
    outputDebugString("consulta falhou (" .. tostring(codigoErro) .. "): " .. tostring(mensagemErro))
end

Com multiplosResultados em true você recebe uma tabela única, com uma entrada por comando, e cada entrada traz as linhas, a contagem de afetadas e o último id inserido, nessa ordem:

local resultados = dbPoll(consulta, -1, true)

if resultados then
    for _, resultado in ipairs(resultados) do
        outputDebugString(#resultado[1] .. " linha(s), " .. resultado[2] .. " afetada(s)")
    end
end

Nota

Ler o resultado o libera. Chamar dbPoll duas vezes no mesmo handle devolve false na segunda, com um aviso no console de debug — guarde a tabela em uma variável se precisar dela mais de uma vez.

Veja também

• dbConnect — Abre uma conexão com um banco de dados.
• dbExec — Executa um comando SQL do qual você não precisa das linhas de volta.
• dbQuery — Dispara uma consulta e devolve um handle para você ler o resultado com dbPoll.
• dbFree — Descarta um resultado que você não vai ler.
• dbPrepareString — Monta uma string SQL com os valores já escapados no lugar dos ?.