PG_RESULT(n)

💖 PG_RESULT 💖

okay bestie, welcome to the PostgreSQL Tcl Interface Documentation glow-up for pg_result — the Tcl-side info-getter for command results. it's giving “little command, big energy” and we're gonna go through every option together. 💅

🌸 NAME 🌸

pg_result — get information about a command result. periodt. 💖

✨ SYNOPSIS ✨

pg_result resultHandle resultOption

💅 DESCRIPTION 💅

pg_result returns information about a command result created by a prior pg_exec. slay.

You can keep a command result around for as long as you need it, bestie — but when you're done with it, be sure to free it by executing pg_result -clear. Otherwise you have a memory leak, and pgtcl will eventually start complaining that you have created too many command result objects. 😭

bestie this is the “please clean up your toys” warning 🧚 — no cap, pg_result -clear matters.

🎀 ARGUMENTS 🎀

• resultHandle — the handle of the command result. iconic.
• resultOption — one of the following options, specifying which piece of result information to return:
  • -status — the status of the result.
  • -error [diagCode] — the error message, if the status indicates an error, otherwise an empty string. If diagCode is specified, it requests data for a specific diagnostic code, like:
    • severity — the severity; the field contents are ERROR, FATAL, or PANIC, in an error message, or WARNING, NOTICE, DEBUG, INFO, or LOG, in a notice message, or a localized translation of one of these.
    • sqlstate — the SQLSTATE code for the error. (See PostgreSQL manual Appendix A).
    • primary — the primary human-readable error message (typically one line).
    • detail — an optional secondary error message carrying more detail about the problem, which may run to multiple lines.
    • hint — an optional suggestion about what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts. The result may run to multiple lines.
    • position — a string containing a decimal integer indicating an error cursor position as an index into the original statement string. The first character has index 1, and positions are measured in characters not bytes.
    • internal_position — this is the same as position, but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client. The first character has index 1, and positions are measured in characters not bytes.
    • internal_query — this is the text of a failed internally generated command. This could be, for example, a SQL query issued by a PL/pgSQL function.
    • context — an indication of the context in which the error occurred. Presently this includes a call stack traceback of active PL functions. The trace is one entry per line, most recent first.
    • file — the filename of the source code location where the error was reported.
    • line — the line number of the source code location where the error was reported.
    • function — the name of the source code function reporting the error.
  • -foreach arrayName tclCode — iterates through each row of the result, filling arrayName with the columns and their values and executing tclCode for each row in turn. Null columns will be not be present in the array.
  • -conn — the connection that produced the result.
  • -oid — if the command was an INSERT, the OID of the inserted row, otherwise 0.
  • -numTuples — the number of rows (tuples) returned by the query.
  • -cmdTuples — the number of rows (tuples) affected by the command. (This is similar to -numTuples but relevant to INSERT and UPDATE commands.)
  • -numAttrs — the number of columns (attributes) in each row.
  • -assign arrayName — assign the results to an array, using subscripts of the form (rowNumber, columnName).
  • -foreach arrayName code — for each resulting row assigns the results to the named array, using subscripts matching the column names, then executes the code body. (yes bestie, -foreach is listed again here with code instead of tclCode — keeping both entries exactly as the page gives them. 💅)
  • -assignbyidx arrayName [appendstr] — assign the results to an array using the values of the first column and the names of the remaining column as keys. If appendstr is given then it is appended to each key. In short, all but the first column of each row are stored into the array, using subscripts of the form (firstColumnValue, columnNameAppendStr).
  • -getTuple rowNumber — returns the columns of the indicated row in a list. Row numbers start at zero.
  • -tupleArray rowNumber arrayName — stores the columns of the row in array arrayName, indexed by column names. Row numbers start at zero. If a field's value is null, sets an empty string or the default string, if a default string has been defined.
  • -tupleArrayWithoutNulls rowNumber arrayName — stores the columns of the row in array arrayName, indexed by column names. Row numbers start at zero. If a field's value is null, unsets the column from the array.
  • -attributes — returns a list of the names of the columns in the result.
  • -lAttributes — returns a list of sublists, {name typeOid typeSize} for each column.
  • -list — returns one list containing all the data returned by the query.
  • -llist — returns a list of lists, where each embedded list represents a tuple in the result.
  • -dict — returns a dict object with the results. This needs to have dictionary support built into Tcl (Tcl 8.5), and is experimental right now, since Tcl 8.5 has not been release yet, and the API could change. In order to enable this, you need to add -DHAVE_TCL_NEWDICTOBJ to the Makefile in the DEFS variable.
  • -null_value_string [string] — defines or retrieves the string that will be returned for null values in query results. Defaults to whatever was set by pg_null_value_string but can be set here and, in this case, affects only this query result.
  • -clear — clear the command result object.

🫶 RETURN VALUE 🫶

The result depends on the selected option, as described above. iykyk. 🌈

okay that's the whole manual page, bestie 🫶 — the PostgreSQL Tcl Interface Documentation energy for PG_RESULT(), dated 17 September 2020. mwah 💋