tdbc::resultset(3tcl)

💖 tdbc::resultset — the manual page bestie 💖

okay so this is tdbc::resultset(3tcl), part of Tcl Database Connectivity (TDBC) — and if you're here, you're about to make a database give you rows. buckle up, it's giving very much "data, but make it cute". 🦋

---

✨ NAME ✨

tdbc::resultset — the TDBC result set object, aka the thing holding your query results. 👑

---

🌸 SYNOPSIS 🌸

package require tdbc 1.0
package require tdbc::driver version

tdbc::driver::connection create db ?-option value...?

set stmt [db prepare sql-code]
set resultset [$stmt execute ?args...?]

$resultset columns
$resultset rowcount
$resultset nextrow ?-as lists|dicts? ?--? varname
$resultset nextlist varname
$resultset nextdict varname
$resultset nextresults
$resultset allrows ?-as lists|dicts? ?-columnsvariable name? ?--?
$resultset foreach ?-as lists|dicts? ?-columnsvariable name? ?--?
       varname script
$resultset close

---

💅 DESCRIPTION 💅

so every single database driver for TDBC (Tcl DataBase Connectivity, iconic name, no notes) implements a result set object, and that object represents the results you get back from executing an SQL statement in a database. you don't make these yourself — instances get created for you when you run the execute object command on a statement object. 💫

the columns object command returns a list of the names of the columns in the result set. the columns show up in the same order they appeared in the SQL statement that ran the database query. and if your SQL statement doesn't return a set of columns — like, say, if it's an INSERT, UPDATE, or DELETE — then columns just hands you an empty list. she said "no columns today bestie". 🙈

the rowcount object command returns the number of rows in the database that were affected by executing an INSERT, UPDATE or DELETE statement. for a SELECT statement? the row count is unspecified. so don't come for her, she never promised. 💀

the nextlist object command sets the variable named by varname — in the caller's scope, important — to the next row of the results, expressed as a list of column values. NULL values get replaced by empty strings. the columns of the result row appear in the same order they appeared in the SELECT statement. nextlist returns 1 if the operation succeeded, and 0 if you've hit the end of the result set. 🎀

the nextdict object command sets the variable named by varname in the caller's scope to the next row of the results, expressed as a dictionary. the dictionary's keys are column names, and the values are the values of those columns in that row. if a column's value in the row is NULL, its key is simply omitted from the dictionary — she's not showing up if she's not coming. the keys appear in the dictionary in the same order the columns appeared in the SELECT statement. nextdict returns 1 if the operation succeeded, and 0 if the end of the result set was reached. ✨

the nextrow object command is precisely equivalent to the nextdict or nextlist object command, depending on whether -as dicts (that's the default, just so you know) or -as lists is specified. same energy, different outfit. 🫶

some databases support the idea of a single statement that returns multiple sets of results. yes, really, main character behaviour.

the nextresults object command gets executed — typically after the nextlist or nextdict object command has returned 0 — to advance to the next result set. it returns 1 if there's another result set to process, and 0 if the result set you just processed was the last one. once you call nextresults and get back 1, you can call columns again to get the column descriptions of the next result set, then go right back to calling nextdict or nextlist to process the rows of that next result set. 💖

⚠️ it is an error to call columns, nextdict, nextlist or nextrow after nextresults has returned 0. like, do not. she's done. periodt.

the allrows object command sets the variable designated by the -columnsvariable option (if it's present) to the result of the columns object command. then it executes the nextrow object command repeatedly until the end of the result set is reached. if nextresults returns a nonzero value, it runs those same two steps again — columns followed by iterated nextrow calls — for as long as further results are available. the rows returned by nextrow get assembled into a Tcl list, and that list becomes the return value of the allrows command. and the last value returned from columns is what your application will see in -columnsvariable. 🧚

the foreach object command sets the variable designated by the -columnsvariable option (if present) to the result of the columns object command. then it executes the nextrow object command repeatedly until the end of the result set is reached, storing the successive rows in the variable designated by varName. for each row, it executes the given script. here's the whole vibe check on what the script can do: 🔥

• if the script terminates with an error, the error is reported by the foreach command, and iteration stops.
• if the script performs a break operation, the iteration terminates prematurely.
• if the script performs a continue operation, the iteration recommences with the next row.
• if the script performs a return, results are the same as if a script outside the control of foreach had returned.
• any other unusual return code terminates the iteration and is reported from the foreach.

once nextrow returns 0, the foreach object command tries to advance to the next result set using nextresults. if nextresults returns 1, the above steps (columns and nextrow, with script invocation) are repeated as long as more result sets remain. the script will always see the correct description of the columns of the current result set in the variable designated by -columnsvariable. at the end of the call, the variable designated by -columnsvariable will hold the description of the columns of the last result set. 🌈

the close object command deletes the result set and frees any associated system resources. clean up after yourself, bestie, it's the polite thing to do. 💜

---

👀 SEE ALSO 👀

encoding(3tcl), tdbc(3tcl), tdbc::connection(3tcl), tdbc::statement(3tcl), tdbc::tokenize(3tcl)

---

⭐ KEYWORDS ⭐

TDBC, SQL, database, connectivity, connection, resultset, statement, bound variable, stored procedure, call

---

🎀 COPYRIGHT 🎀

Copyright (c) 2008 by Kevin B. Kenny.

---

and that's the whole page!! you ate that, fr fr. this was Tcl 8.6, tdbc::resultset(3tcl), and honestly? iconic. go forth and iterate, my love. 💖✨🦋