diff --git a/docs/scripting/functions/DB_SelectNextRow.md b/docs/scripting/functions/DB_SelectNextRow.md new file mode 100644 index 000000000..4b7ecb88f --- /dev/null +++ b/docs/scripting/functions/DB_SelectNextRow.md @@ -0,0 +1,133 @@ +--- +title: DB_SelectNextRow +description: Moves to the next row of the result set allocated with `DB_ExecuteQuery`. +keywords: + - sqlite +tags: ["sqlite"] +--- + +## Description + +The function moves to the next row of the result set allocated with [DB_ExecuteQuery](DB_ExecuteQuery). + +| Name | Description | +|-------------------|---------------------------------------------------| +| DBResult:dbresult | The result of [DB_ExecuteQuery](DB_ExecuteQuery). | + +## Returns + +Returns 1 if result set handle is valid and the last row is not reached yet, otherwise 0. + +## Examples + +```c +// examples.inc + +// ... + +Examples_ListNames(DB:dbConnectionHandle) +{ + // Database result set + new DBResult:db_result_set = DB_ExecuteQuery("SELECT `name` FROM `examples`"); + + // If database result set is valid + if (db_result_set) + { + // Allocate some memory to store results + new result[256]; + + // Do operations + do + { + // Add value from "example" field to the return value variable + DB_GetFieldStringByName(db_result_set, "name", result, sizeof result); + } + + // While next row could be fetched + while (DB_SelectNextRow(db_result_set)); + + // Free result set + DB_FreeResultSet(db_result_set); + } +} +``` + +```c +// mode.pwn + +// ... + +#include + +static DB:gDBConnectionHandle; + +// ... + +public OnGameModeInit() +{ + // ... + + // Create a connection to a database + gDBConnectionHandle = DB_Open("example.db"); + + // If connection to the database exists + if (gDBConnectionHandle) + { + // Successfully created a connection to the database + print("Successfully created a connection to database \"example.db\"."); + Examples_ListNames(gDBConnectionHandle); + } + else + { + // Failed to create a connection to the database + print("Failed to open a connection to database \"example.db\"."); + } + + // ... + + return 1; +} + +public OnGameModeExit() +{ + // Close the connection to the database if connection is open + if (DB_Close(gDBConnectionHandle)) + { + // Extra cleanup + gDBConnectionHandle = DB:0; + } + + // ... + + return 1; +} +``` + +## Notes + +:::warning + +Using an invalid handle other than zero will crash your server! Get a valid database connection handle by using [DB_ExecuteQuery](DB_ExecuteQuery). + +::: + +## Related Functions + +- [DB_Open](DB_Open): Open a connection to an SQLite database +- [DB_Close](DB_Close): Close the connection to an SQLite database +- [DB_ExecuteQuery](DB_ExecuteQuery): Query an SQLite database +- [DB_FreeResultSet](DB_FreeResultSet): Free result memory from a DB_ExecuteQuery +- [DB_GetRowCount](DB_GetRowCount): Get the number of rows in a result +- [DB_SelectNextRow](DB_SelectNextRow): Move to the next row +- [DB_GetFieldCount](DB_GetFieldCount): Get the number of fields in a result +- [DB_GetFieldName](DB_GetFieldName): Returns the name of a field at a particular index +- [DB_GetFieldString](DB_GetFieldString): Get content of field with specified ID from current result row +- [DB_GetFieldStringByName](DB_GetFieldStringByName): Get content of field with specified name from current result row +- [DB_GetFieldInt](DB_GetFieldInt): Get content of field as an integer with specified ID from current result row +- [DB_GetFieldIntByName](DB_GetFieldIntByName): Get content of field as an integer with specified name from current result row +- [DB_GetFieldFloat](DB_GetFieldFloat): Get content of field as a float with specified ID from current result row +- [DB_GetFieldFloatByName](DB_GetFieldFloatByName): Get content of field as a float with specified name from current result row +- [DB_GetMemHandle](DB_GetMemHandle): Get memory handle for an SQLite database that was opened with db_open. +- [DB_GetLegacyDBResult](DB_GetLegacyDBResult): Get memory handle for an SQLite query that was executed with DB_ExecuteQuery. +- [DB_GetDatabaseConnectionCount](DB_GetDatabaseConnectionCount): The function gets the number of open database connections for debugging purposes. +- [DB_GetDatabaseResultSetCount](DB_GetDatabaseResultSetCount): The function gets the number of open database results.