| PostgreSQL Tcl Interface Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Fast Forward | Next | |
pg_result returns information about a command result created by a prior pg_exec.
You can keep a command result around for as long as you need it, but when you are 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.
resultHandleThe handle of the command result.
resultOptionOne of the following options, specifying which piece of result information to return:
-statusThe status of the result.
-error ?diagCode?The error message, if the status indicates an error, otherwise an empty string.
diagCode, if specified, requests data for a specific diagnostic code:
severityThe 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.
sqlstateThe SQLSTATE code for the error. (See PostgreSQL manual Appendix A).
primaryThe primary human-readable error message (typically one line).
detailAn optional secondary error message carrying more detail abhout the problem, which may run to multiple lines.
hintAn 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.
positionA 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_positionThis 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_queryThis is the text of a failed internally generated command. This could be, for example, a SQL query issued by a PL/pgSQL function.
contextAn 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.
fileThe filename of the source code location where the error was reported.
lineThe line number of the source code location where the error was reported.
functionThe name of the source code function reporting the error.
-foreach arrayName tclCodeIterates 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.
-connThe connection that produced the result.
-oidIf the command was an INSERT, the OID of the inserted row, otherwise 0.
-numTuplesThe number of rows (tuples) returned by the query.
-cmdTuplesThe number of rows (tuples) affected by the command. (This is similar to -numTuples but relevant to INSERT and UPDATE commands.)
-numAttrsThe number of columns (attributes) in each row.
-assign arrayNameAssign the results to an array, using subscripts of the form (rowNumber, columnName).
-foreach arrayName codeFor each resulting row assigns the results to the named array, using subscripts matching the column names, then executes the code body.
-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 rowNumberReturns the columns of the indicated row in a list. Row numbers start at zero.
-tupleArray rowNumber arrayNameStores 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 arrayNameStores 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.
-attributesReturns a list of the names of the columns in the result.
-lAttributesReturns a list of sublists, {name typeOid typeSize} for each column.
-listReturns one list containing all the data returned by the query.
-llistReturns a list of lists, where each embedded list represents a tuple in the result.
-dictReturns 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.
-clearClear the command result object.