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

## pg_execute

pg_execute — 中央集中処理系上で SQL 命令を実行し､任意追加で結果の上で巡回する Execute an SQL command on the server and optionally loop over the results

## 構文 Synopsis

    pg_execute ?-array arrayVar? ?-oid oidVar? conn commandString ?procedure?

## 説明 Description

`pg_execute` は PostgreSQL 中央集中処理系に命令を提出する｡ `pg_execute` submits a command to the PostgreSQL server.

もし命令が SELECT 宣言文でない場合､命令に影響された行の個数が返される｡もし命令が INSERT 宣言文で､且つ､一個の行が挿入される場合､もし任意追加の -oid 引数が提供されていれば､挿入された行の OID (がもし利用できれば)が変数 oidVar 内に保存される｡ If the command is not a SELECT statement, the number of rows affected by the command is returned. If the command is an INSERT statement and a single row is inserted, the OID of the inserted row (if available) is stored in the variable `oidVar` if the optional `-oid` argument is supplied.

もし命令が SELECT 宣言文の場合､結果のそれぞれの行に対し､ arrayVar 変数が提供されていれば､列の名前が配列索引として､行の値がarrayVar 変数に保存され､提供されない場合､列の名前が付いた変数内に保存される､そして､任意追加の手続き函数が提供されれば､実行する｡(手続き函数の省略は恐らく問合せが一つの行を返す場合のみ理に適う｡)選択された行の個数が返される｡ If the command is a SELECT statement, then, for each row in the result, the row values are stored in the `arrayVar` variable, if supplied, using the column names as the array indices, else in variables named by the column names, and then the optional `procedure` is executed if supplied. (Omitting the `procedure` probably makes sense only if the query will return a single row.) The number of rows selected is returned.

手続き函数は期待される振舞により Tcl 命令の､中断､継続､戻りに使うことができる｡註意すべきは､もし手続き函数が return を実行すると､ pg_execute は影響された行の数を返さない｡ The `procedure` can use the Tcl commands `break`, `continue`, and `return` with the expected behavior. Note that if the `procedure` executes `return`, then `pg_execute` does not return the number of affected rows.

pg_execute はより新しい命令であり､ pg_select の性質の上位の組を提供し､結果の把持子の利用が必要ない場合は､多くの場合に pg_exec に代替できる｡ `pg_execute` is a newer command which provides a superset of the features of pg_select and can replace pg_exec in many cases where access to the result handle is not needed.

## 引数 Arguments

`-array `arrayVar``

  配列変数の名前を指定し､結果の行が列の名前が索引になって保存される｡これは commandString が SELECT 宣言文でない場合無視される｡ Specifies the name of an array variable where result rows are stored, indexed by the column names. This is ignored if `commandString` is not a SELECT statement.

`-oid `oidVar``

  INSERT 宣言文からの行の OID が保存される変数の名前を指定する｡行の OID は､もし表が OIDsによって生成された場合のみ利用できる｡PostgreSQL-8.0 の開始と伴に表は既定では OIDs では生成されない｡もし表が OIDs を有さない場合､ oidVar に 0 が保存される｡ Specifies the name of a variable into which the row OID from an INSERT statement will be stored. The OID of a row is only available if the table was created with OIDs. Starting with PostgreSQL-8.0, tables are not created with OIDs by default. If the table has no OIDs, 0 is stored in oidVar.

`conn`

  その上で命令を実行すべき接続の把持子｡ The handle of the connection on which to execute the command.

`commandString`

  実行すべき SQL 命令｡ 　 The SQL command to execute.

`procedure`

  SELECT 宣言文のそれぞれの行の結果に関して実行すべき任意追加の手続き函数｡ Optional procedure to execute for each result row of a SELECT statement.

## Return Value

命令により影響されたか返された行の個数｡ The number of rows affected or returned by the command.

もしデータベースとの通信に不都合が生じるか問合せに不都合処理が存在すると Tcl 不都合が発せられる｡註意すべきは､データベース不都合を生成する問合せについて Tcl 不都合を発生しない pg_exec とは異る｡もし手続き本体が提供され且つその実行が Tcl 不都合になる場合も､ Tcl 不都合が発生される｡ A Tcl error will be thrown if an error occurs communicating with the database, or if there is an error processing the query. Note that this differs from pg_exec, which will not throw a Tcl error for a query which generates a database error. A Tcl error will also be thrown if a procedure body is supplied and its execution results in a Tcl error.

データベース中央集中処理系の不都合取扱いについて､ pg_execute は Tcl 不都合を発生し､且つ不都合伝言文が二要素リストになる｡第一要素は PGRES_FATAL_ERROR の様な不都合符号であり､第二要素はデータベース中央集中処理系の不都合文である｡不幸にして､他の不都合も同じく Tcl 不都合発生になるが､不都合伝言文はリストではなく､単に伝言文でる､従って､不都合伝言文のリスト書式は仮定されない｡ For database server handled errors, `pg_execute` will throw a Tcl error and the error message will be a two-element list. The first element is an error code, such as `PGRES_FATAL_ERROR`, and the second element is the database server error text. Unfortunately, other errors also result in a Tcl error being thrown but the error message is not a list - just the message text, so the list form of the error message cannot be assumed.

## Notes

pg_execute は COPY の開始に使うことはできない､理由はそれが結果の把持子を返さないから｡ COPY の開始には pg_exec を使わねばならない｡ `pg_execute` cannot be used to start a COPY because it doesn't return a result handle. You must use pg_exec to start a COPY.

この命令は PostgreSQL libpq 函数 PQexec を使い模擬する｡ This command uses or emulates the PostgreSQL libpq function `PQexec`.

## Examples

次の用例の中で､ catch による不都合確認は明瞭性の為に省略されている｡ In the following examples, error checking with `catch` has been omitted for clarity.

行を挿入し OID を result_oid 内に保全する､その際､ mytable が OIDS を使って生成されることを仮定する｡ Insert a row and save the OID in `result_oid`, assuming the mytable was created using WITH OIDS:

    pg_execute -oid result_oid $conn "INSERT INTO mytable VALUES (1);"

それぞれの行から列の品目と値を印刷する｡ Print the columns `item` and `value` from each row:

    pg_execute -array d $conn "SELECT item, value FROM mytable" {
        puts "Item=$d(item) Value=$d(value)"
    }

最大値と最小値を見付け $s(max) と $s(min) に保存する｡ Find the maximum and minimum values and store them in `$s(max)` and `$s(min)`:

    pg_execute -array s $conn "SELECT max(value) AS max, min(value) AS min FROM mytable"

最大値と最小値を見付け $max と $min に保存する｡ Find the maximum and minimum values and store them in `$max` and `$min`:

    pg_execute $conn "SELECT max(value) AS max, min(value) AS min FROM mytable"

Prev | Up | Next
pg_exec | Home | pg_select