View source for DbPoll

__NOTOC__
{{Server function}}
This function checks the progress of a database query.

==Syntax== 
<syntaxhighlight lang="lua">
table dbPoll ( handle queryHandle, int timeout[, bool multipleResults = false ] )
</syntaxhighlight>
{{OOP||queryHandle:poll}}
===Required Arguments===
*'''queryHandle:''' A query handle previously returned from [[dbQuery]]
*'''timeout:''' How many milliseconds to wait for a result. Use 0 for an instant response (which may return nil). Use -1 to wait until a result is ready. Note: A wait here will freeze the entire server just like the executeSQL* functions

===Optional Arguments===
{{New items|3.0160|1.5.2|
*'''multipleResults:''' Set to true to enable the return values from multiple statements
|7972}}

===Returns===
*''nil:'' Returns nil if the query results are not yet ready. You should try again in a little while. (If you give up waiting for a result, be sure to call [[dbFree]])
*''false:'' Returns false if the query string contained an error, the connection has been lost or the query handle is incorrect. This automatically frees the query handle, so you do not have to call [[dbFree]].
** This also returns two extra values: (See the example on how the retrieve them)
***''int:'' error code
***''string'' error message
*''table:'' Returns a table when the query has successfully completed. This automatically frees the query handle, so you do not have to call [[dbFree]].
** This also returns extra values:
***''int:'' number of affected rows
***''int:'' last insert id
{{Note|If a column contained a number it is returned as a number, this includes things which were stored as string but are numbers such as "1" would be returned as 1.}}

==Example==
This example waits until a result is ready:
<syntaxhighlight lang="lua">
local result = dbPoll ( qh, -1 )
</syntaxhighlight>

This example shows the possible return values:
<syntaxhighlight lang="lua">
local result, num_affected_rows, last_insert_id = dbPoll ( qh, -1 )

if result == nil then
    outputConsole( "dbPoll result not ready yet" )
elseif result == false then
    local error_code,error_msg = num_affected_rows,last_insert_id
    outputConsole( "dbPoll failed. Error code: " .. tostring(error_code) .. "  Error message: " .. tostring(error_msg) )
else
    outputConsole( "dbPoll succeeded. Number of affected rows: " .. tostring(num_affected_rows) .. "  Last insert id: " .. tostring(last_insert_id) )
end
</syntaxhighlight>

This example shows how to handle the result if the query selected data:
<syntaxhighlight lang="lua">
local result = dbPoll ( qh, -1 )

if result then
    for _, row in ipairs ( result ) do

        -- by using a second loop (use it if you want to get the values of all columns the query selected):
        for column, value in pairs ( row ) do
            -- column = the mysql column of the table in the query
            -- value = the value of that column in this certain row
        end
		
        -- or without a second loop (use it if you want to handle every value in a special way):
        outputChatBox ( row["column"] ) -- it will output the value of the column "column" in this certain row
    end
end
</syntaxhighlight>


{{New items|3.0153|1.5.2|
This example shows how to handle the result of a multiple statement query: (See [[dbConnect]] option '''multi_statements''')
<syntaxhighlight lang="lua">
local multiResults = dbPoll ( qh, -1, true )

if multiResults then
    for sidx, statementResult in ipairs ( multiResults ) do
        local resultRows, numAffectedRows, lastInsertId = unpack(statementResult)
        for ridx, row in ipairs ( resultRows ) do
            for column, value in pairs ( row ) do
                outputDebugString( ""
                        .. " statement#" .. sidx
                        .. " row#" .. ridx
                        .. " column:" .. tostring(column)
                        .. " value:" .. tostring(value)
                        )
            end
        end
    end
end
</syntaxhighlight>
|7972}}

==Requirements==
{{Requirements|1.1.1-9.03328|n/a}}

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.4-9.05862|Added 'last insert id' return value}}
{{ChangelogItem|1.5.2-9.07972|Added 'multipleResults' argument}}

==See Also==
{{Registry_functions}}