pg_result
Prev | 4.3.Query Execution Commands | Next

## pg_result

pg_result — 命令の結果に関する情報を得る Get information about a command result

## 構文 Synopsis

    pg_result resultHandle resultOption

## 説明 Description

`pg_result` は､以前の命令 pg_exec, pg_exec_prepared, pg_exec_params, pg_getresult, pg_describe_cursor, or pg_describe_prepared によって生成された命令結果に関する情報を返す｡ `pg_result` returns information about a command result created by a prior pg_exec, pg_exec_prepared, pg_exec_params, pg_getresult, pg_describe_cursor, or pg_describe_prepared.

必要な限りの間､命令の結果を保持できるが､それについて完了した後は必ず pg_result -clear を実行してそれを解放することを確認されたい｡そうしないと､記憶域の漏洩や､記憶域や利用可能な結果の意外な暴走に遭う｡対話機能の pgtcl-ng 実装はデータベース接続当り 128個の制限がある､検出の手段として結果が解放されない結果として｡( pgintcl 実装は活性の命令結果対象が多すぎることを確認しない) 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 may eventually run out of memory or available command results. The pgtcl-ng implementation of the interface has a limit of 128 results per database connection, as a means of detecting if results are not being freed. (The pgintcl implementation does not check for too many active command result objects.)

## 引数 Arguments

`resultHandle`

  命令結果の把持子｡ 　 The handle of the command result.

`resultOption`

  結果のどの部分を持ち帰るべきかを次の指示項目の内の一つが指定する: One of the following options, specifying which piece of result information to return:

  `-assign `arrayName``

    記述形式の(rowNumber,columnName) を使って結果を配列に代入する｡ Assign the results to an array, using subscripts of the form `(rowNumber,columnName)`.

  `-assignbyidx` `arrayName` ?`appendstr`?

    第一列の値と残りの列の名前を鍵として使い結果を配列に代入する｡もし `appendstr` が与えられるとそれはそれぞれの鍵に追記される｡端的には､ (firstColumnValue,columnNameAppendStr)の形式を使用して､それぞれの列の第一列以外は全て配列に保存される｡ 　　 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)`.

  `-attributes`

    結果内の列の名前のリストを返す｡ 　 Returns a list of the names of the columns in the result.

  `-clear`

    命令の結果の対象を解消する｡ 　 Clear the command result object.

  `-cmdStatus`

    結果を作り出した SQL 命令からの命令状態貼札を返す｡これは UPDATE の様な SQL 命令であり､屡､影響された行の数の様な追加データが添付される｡註意： これは pgtclng-1.5.1 と in pgintcl-2.0.1 で追加された｡ 　 Returns the command status tag from the SQL command that generated the result. This is the name of the SQL command, such as UPDATE, often followed by additional data such as the number of rows affected. Note: This was added in pgtclng-1.5.1 and in pgintcl-2.0.1.

  `-cmdTuples`

    命令に影響された行(リスト)の数を返す｡これは､ `PGRES_COMMAND_OK` の完了状態を伴う命令に関して適切である｡ PostgreSQL-9.0 の開始に伴い､ pgintcl-3.2.0 か pgtclng-1.8.0 で使用される時は､これは SELECT 問合せからの行の数を返す｡但し､ SELECT 問合せと共に `-numTuples` を使用することがより好ましい｡ Returns the number of rows (tuples) affected by the command. This is appropriate to use for commands with completion status `PGRES_COMMAND_OK`. Starting with PostgreSQL-9.0, when used with either pgintcl-3.2.0 or pgtclng-1.8.0, this will also return the number of rows from a SELECT query. However, the use of `-numTuples` with SELECT queries is preferred.

  `-conn`

    結果を生成した接続の把持子(名前)を返す｡ Returns the handle (name) of the connection that produced the result.

  `-dict`

    問合せ結果を Tcl 辞書として返す｡その辞書はそれぞれの結果の行につき､ 0-基準行番号を鍵として使い一個の入力を含む｡(それぞれの行に関する)値は辞書であり､鍵として結果の欄の名前と､且つ､値として欄の値を､含む｡ 註意: これは pgtclng-1.9.0 と in pgintcl-3.3.0に追加された｡ Tcl-8.5 以上で有効に働く｡ Returns the query results as a Tcl dictionary. The dictionary contains one entry for each result row, using the 0-based row number as the key. The value (for each row) is a dictionary containing result field names as keys, and field values as values. Note: This was added in pgtclng-1.9.0 and in pgintcl-3.3.0. It only works with Tcl-8.5 and higher.

  `-error` ?`fieldCode`?

    状態が不都合を指し示す場合に不都合伝言文を返す､それ以外は空文字列を返す｡ 註意: 任意追加の `fieldCode` 媒介変数が提供されると､拡張不都合符号欄の値を返す｡ `-errorField` の詳細については､次の節を参照されたい｡ Returns the error message, if the status indicates an error, otherwise an empty string. Note: the optional `fieldCode` parameter was added in pgintcl-2.2.0 and pgtclng-1.5.2, making `-error` and `-errorField` synonymous. If a `fieldCode` is supplied, returns the value of an extended error code field. Refer to the next option, `-errorField` for details.

  `-errorField` ?`fieldCode`?

    `fieldCode` が何も与えられないと不都合伝言文を返し､`fieldCode` が与えられると拡張不都合符号欄を返す｡註意:`fieldCode` は pgintcl-2.2.0 と pgtclng-1.5.2 内で任意追加にされ､ `-error` と `-errorField` は同義語にされた｡これらの版以前は､ `-error` が全部の不都合伝言文を得る為に使われ､ -errorField は拡張不都合符号欄値を得る為に使われた｡ Returns the error message, if no `fieldCode` is supplied, or the value of an extended error code field, if `fieldCode` is supplied. Note: the `fieldCode` parameter was made optional in pgintcl-2.2.0 and pgtclng-1.5.2, making `-error` and `-errorField` synonymous. Prior to those versions, `-error` was used to get the whole error message, and `-errorField` was used to get an extended error code field value.

    `fieldCode` は､詰語の表に従って､名前(連結別名)による不都合符号欄､又は一個の略称文字により不都合符号欄を選択する｡注意: FieldCode と Alias は大文字小文字を区別しないが､一個の略称文字は大文字小文字を区別する｡ `fieldCode` selects the error code field by name (or alias), or single character abbreviation, according to the following table. Note: the FieldCode and Alias are case insensitive, but the single letter Abbreviations are case sensitive.

    欄符号 FieldCode | 略号Abbreviation | 連結 Alias | 説明 Description
    --- | --- | --- | ---
    SEVERITY | S |  | 不都合段階､不都合や致命的 等 Error severity, such as ERROR or FATAL
    SQLSTATE | C |  | 5文字のSQL 状態符号 5-character SQL State code
    MESSAGE_PRIMARY | M | primary | 主不都合伝言文 Primary error message
    MESSAGE_DETAIL | D | detail | 不都合伝言文詳細 副伝言文 Error message detail, secondary message
    MESSAGE_HINT | H | hint | 不都合伝言文 霊感や示唆 Error message hint or suggestion
    STATEMENT_POSITION | P | position | 遊走子位置の十進数 Decimal integer cursor position
    CONTEXT | W |  | 不都合文脈 亦は呼出棚追跡 Error context, or call stack trace
    SOURCE_FILE | F | file | PostgreSQL 源譜ファイル名 PostgreSQL source code filename
    SOURCE_LINE | L | line | PostgreSQL 源譜行番号 PostgreSQL source code line number
    SOURCE_FUNCTION | R | function | PostgreSQL 源譜函数名 PostgreSQL source code function name
    SCHEMA_NAME | s |  | 不都合に関連する対象の計画書の名前 Name of the schema of the object associated with the error
    TABLE_NAME | t |  | 不都合に関連する表の名前 Name of the table associated with the error
    COLUMN_NAME | c |  | 不都合に関連する列の名前 Name of table column associated with the error
    DATATYPE_NAME | d |  | 不都合に関連するデータの型の名前 Name of the data type associated with the error
    CONSTRAINT_NAME | t |  | 不都合に関連するデータベース制約名 Name of the database constraint associated with the error

    注意:与えられたどの不都合にも不都合欄符号が全て与えられる訳ではない｡データベース中央集中処理系が要求された不都合欄を提供しない場合は`pg_result -errorField` は空文字列を返す｡ Note: Not all error field codes apply to any given error condition. `pg_result -errorField` will return an empty string if the database server did not provide the requested error field.

    欄符号連結別名は pgintcl-2.2.0 と pgtclng-1.5.2 に追加された｡ Field code aliases were added to pgintcl-2.2.0 and pgtclng-1.5.2.

    計画書､表､列､データ型､束縛に関する欄符号の名前[譯註:上記の表の末尾5項目]はpgintcl-3.5.0 と pgtclng-2.1.0 で追加された｡ これらの欄符号は小文字の一文字略号が使われている(PostgreSQL-9.2 と 9.3 で始まった PostgreSQL 中央集中処理系によって定義された)ので､略号は大文字小文字を区別する必要がある｡それ以前の版では､略号欄符号は大文字小文字を区別しなかった｡ Field codes for Schema, Table, Column, Datatype, and Constraint names were added to pgintcl-3.5.0 and pgtclng-2.1.0. Since these field codes use lower-case letter abbreviations (which are defined by the PostgreSQL server, starting with PostgreSQL-9.2 and 9.3), it was necessary to make the abbreviations case sensitive. In earlier releases, the single-character abbreviated field codes were case insensitive.

  `-getNull `rowNumber``

    指定された行に関する 1 と 0 でなるリストを返す､茲で､ 1 はその列の値が NULLであり ､0はその列の値が NULL でない｡行番号は零から始まる｡ Returns a list of 1s and 0s for the indicated row, with 1 meaning the value of the column is NULL, and 0 meaning the value of the column is not NULL. Row numbers start at zero.

  `-getTuple `rowNumber``

    リスト内の指定された行の列の値を返す｡行番号は零から始まる｡ Returns the values of the columns of the indicated row in a list. Row numbers start at zero.

  `-lAttributes`

    問合せ結果列の属性のリストを返す｡それぞれの列に就いてリストは {ColumnName TypeOid TypeSize} の形式の副リストを含む｡これらの値の更なる情報は PostgreSQL Libpq 説明書内に見られる｡註意:pg_result -lxAttributes はこの情報の上位の組を返す｡ Returns a list of attributes of the query result columns. For each column, the list contains a sublist of the form `{ColumnName TypeOid TypeSize}`. More information on these values can be found in the PostgreSQL Libpq documentation. Note that pg_result -lxAttributes returns a superset of this information.

  `-list`

    全体の結果を､行が主､列が副の順のリストとして返す｡ Returns the entire result as a list of values in row-major, column-minor order.

  `-llist`

    全体の結果をリストのリストとして返す｡ Returns the entire result as a list of lists. The outer list contains one element for each result row, and the inner lists contain the values for each column of the row.

  `-lxAttributes`

    問合せ結果の列の属性の拡張リストを返す｡それぞれの列に関して､リストは {ColumnName TypeOid TypeSize TypeSizeModifier Format TableOID TableColumnIndex} の形式の副リストを含む｡この値に関する更なる情報は PostgreSQL Libpq 説明文に見られる｡ 注意すべきは､ pg_result -lAttributes によって返される情報の拡張である｡ Returns an extended list of attributes of the query result columns. For each column, the list contains a sublist of the form `{ColumnName TypeOid TypeSize TypeSizeModifier Format TableOID TableColumnIndex}`. More information on these values can be found in the PostgreSQL Libpq documentation. Note that this is an extension of the information returned by pg_result -lAttributes.

  `-numAttrs`

    それぞれの行の列(属性)の個数を返す｡ Returns the number of columns (attributes) in each row.

  `-numParams`

    もし結果が pg_describe_prepared によって返されると､準備された問合せの中の媒介変数の個数を返す｡どの､その他の結果の型に関しても 0 を返す｡これは pgtclng-1.7.0 と pgintcl-3.1.0 で追加された｡ Returns the number of parameters in a prepared query, if the result was returned by pg_describe_prepared. Returns 0 for any other type of result. Note: This was added in pgtclng-1.7.0 and in pgintcl-3.1.0.

  `-numTuples`

    問合せによって返される行(リスト)の個数を返す｡これは､ PGRES_TUPLES_OK の完了状態を伴う命令について使用することは適切である｡ Returns the number of rows (tuples) returned by the query. This is appropriate to use for commands with completion status `PGRES_TUPLES_OK`.

  `-oid`

    もし命令が一個の行の INSERT であった場合､表が OID を有する場合には､挿入された行の OID (Object 識別番号) を返す｡ PostgreSQL 8.0で始まった既定では OID 無しで表を作成する｡それ以外の場合0を返す｡ If the command was a single row INSERT, returns the OID (Object ID) of the inserted row, if the table has OIDs. The default starting with PostgreSQL 8.0 is to create tables without OIDs. Otherwise returns 0.

  `-paramTypes`

    もし結果がpg_describe_preparedによって返された場合､準備された問合せ内の PostgreSQL 型 OID のリストを返す｡それ以外のどの結果の型の場合も､空リストを返す｡註意: これは pgtclng-1.7.0 and in pgintcl-3.1.0 で追加された｡ Returns a list of the PostgreSQL type OIDs of the parameters in a prepared query, if the result was returned by pg_describe_prepared. Returns an empty list for any other type of result. Note: This was added in pgtclng-1.7.0 and in pgintcl-3.1.0.

  `-status`

    結果の状態を返す｡これは次の文字列の内の一つになる: Returns the status of the result. This will be one of the following strings:

    状態 Status | 意味 Meaning
    --- | ---
    PGRES_COMMAND_OK | INSERTの様なデータを返さない命令の成功裡の完了｡ Successful completion of a command returning no data, such as INSERT.
    PGRES_TUPLES_OK | データを返す命令(譬えば SELECT や SHOW)の成功裡の完了｡註意すべきは縦えSELECT が行を全く返さなくともこの状態である Successful completion of a command which returns data (such as SELECT or SHOW). Note this is the status even if the SELECT happens to return no rows.
    PGRES_COPY_OUT | 標準出力に複写開始 Begin COPY TO STDOUT.
    PGRES_COPY_IN | Begin 標準入力から複写開始 COPY FROM STDIN.
    PGRES_EMPTY_QUERY | 中央集中処理系に送られた問合せ文字列は空｡ The query string sent to the server was empty.
    PGRES_BAD_RESPONSE | 中央集中処理系の応答が理解不能｡ The server's response was not understood.
    PGRES_FATAL_ERROR | 不都合が生じた｡これはどの SQL構文不都合や､実在しない表からの SELECT の様な命令処理の不都合を含む｡ An error occurred. This includes any SQL syntax errors, or errors processing the command such as SELECT from a non-existing table.

  `-tupleArray `rowNumber` `arrayName``

    配列`arrayName`内の行の､列名で索引された列を保存する｡行番号は零から開始する｡ Stores the columns of the row in array `arrayName`, indexed by column names. Row numbers start at zero.

## 返り値 Return Value

結果は､上で述べた様に選択された指示項目に従う｡ 　 The result depends on the selected option, as described above.

もし､命令の処理に不都合があると Tcl 不都合が発生する､ありそうもないが､中央集中処理系との通信なしからも含まれる｡ A Tcl error will be thrown if there is an error processing the command, which is unlikely since no communication with the server is involved.

## 註意 Notes

Section5.4, “Example - The Different Ways to Get Query Results” は pg_result によって問合せ結果を得る別の方法の用例を含んでいる｡ Section5.4, “Example - The Different Ways to Get Query Results” contains examples of the different ways to get query results with `pg_result`.

この命令は libpq 取扱い説明書のCommand Execution Functions の章内で記述された PostgreSQL libpq 函数の様々な使い方がある｡ This command uses a variety of PostgreSQL libpq functions described in the Command Execution Functions chapter of the libpq reference manual.

Prev | Up | Next
pg_describe_prepared | Home | pg_encrypt_password