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

## pg_exec_prepared

pg_exec_prepared — 事前準備された SQL 命令を中央集中処理系上で実行する Execute a pre-prepared SQL command on the server

## 構文 Synopsis

    pg_exec_prepared conn statementName resultFormats argFormats ?param...?

## 説明 Description

pg_exec_prepared は名前が付き､事前準備された SQL 宣言文を中央集中処理系上で実行し､結果の把持子を返す｡この命令は､引数を､引用の問題なしに SQL 宣言文假引数に束縛することを許容し､且つ生の二進化データの送出しと受入を運営する｡ `pg_exec_prepared` executes a pre-prepared SQL named statement on the server and returns a result handle. This command allows binding arguments to SQL statement parameters without quoting issues, and supports sending and receiving raw binary data.

## 引数 Arguments

`conn`

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

`statementName`

  事前準備された宣言文の名前｡ The name of the pre-prepared statement.

`resultFormats`

  問合せ結果が期待される書式｡平文の結果には `T` か `TEXT` を､二進書式結果には `B` か `BINARY` を使われたい｡もしこの假引数が空文字列の場合､ `TEXT` が仮定される｡ The format that the query results are expected in. Use `T` or `TEXT` for text format results, and `B` or `BINARY` for binary format results. If this parameter is an empty string, `TEXT` is assumed.

`argFormats`

  問合せ假引数が送り込まれる書式｡この假引数は空文字列でも､一つの語でも､リストでも好い｡もし假引数が空文字列であると､全ての假引数は平文書式で送込まれる｡もしこの假引数が一つの語の場合､全ての問合せ假引数について書式をしていする｡平文書式にはT (又は TEXT) を､二進書式にはB (又は BINARY) を使われたい｡もしこの假引数がリストの場合､それぞれの問合せ假引数に関する書式を指定して一つの語(T か TEXT か B か BINARY)を含まねばならない｡ The formats that the query parameters are sent in. This parameter can be an empty string, a single word, or a list. If this parameter is an empty string, all query parameters are sent in text format. If this parameter is a single word, it specifies the format for all query parameters. Use `T` (or `TEXT`) for text format, and `B` (or `BINARY`) for binary format. If this parameter is a list, it must contain a single word (`T` or `TEXT` or `B` or `BINARY`) specifying the format for each query parameter.

`param...`

  命令文字列場所占有子に束縛すべき零或はそれ以上の假引数の値｡最初の假引数は準備された問合わせ内の $1 を置換え､第二番目の引数は $2 を置換え､更に続く｡假引数は argFormats 引数に従って平文か二進化のデータとして解釈されることになる｡ Zero or more parameter values to bind to command string place-holders. The first parameter will replace `$1` in the prepared query, the second parameter will replace `$2`, etc. The parameters will be interpreted as text or binary data according to the `argFormats` argument.

## 返り値 Return Value

命令の結果を得る為に pg_result と伴に使用できる結果把持子を返す｡ Returns a result handle which can be used with pg_result to obtain the results of the command.

データベースとの通信で不都合が生じると Tcl 不都合が発生される｡註意すべきは､､不適切な命令が成功裡に中央集中系に送られると不都合は発生されず､且つ､応答が成功裡に受理される｡通常の戻りの后､結果の宣言文が確認されねばならない｡ A Tcl error will be thrown if an error occurs communicating with the database. Note that no Tcl error will be thrown if an invalid query is successfully sent to the server and a response successfully received. The result status must be checked after a normal return.

## Notes

宣言文は SQL PREPARE 命令を使って準備せねばならない､譬えば: The statement must be prepared with an SQL PREPARE command, for example:

        PREPARE statementName (INTEGER) AS SELECT * FROM mytable WHERE ID > $1

これが `pg_exec` 又は `pg_execute` を使ってデータベースに送付されねばならぬ(但し､`$1` は `\$1` として Tcl に関して除外されねばならない)｡準備された宣言文は処置の終わりまで持続する｡ This can be sent to the database with `pg_exec` or `pg_execute` (but note that `$1` must be escaped for Tcl as `\$1`). Prepared statements persist until the end of a session.

pg_exec_params の命令構文は平文と二進数結果列の混合を運営するが､きそになっているPostgreSQL(libpq) 外部函数は現在未だこれに対応してない｡従って､全ての結果の列が平文書式でなければならない､或は全ての列は二進化書式でなければならない｡ The command syntax of `pg_exec_prepared` supports mixed text and binary result columns, but the underlying PostgreSQL library (libpq) does not currently support this. Therefore, all result columns must be text format, or all columns must be binary format.

宣言文を準備する為に NULL 値引数を渡すことは対応していない｡ There is no support for passing NULL value arguments to prepared statements.

これを行った后には､pg_result -clear によって結果の把持子を解放することを確認せねばならない｡ Be sure to free the returned result handle with `pg_result -clear` when you are done with it.

この命令は PostgreSQL libpq function PQexecParams を使うか模擬する｡ This command uses or emulates the PostgreSQL libpq function `PQexecPrepared`.

### 註意 Caution

元々の Pgtcl 実装は同名であるが､引数の互換性がない命令を有している｡ The original Pgtcl implementation has a command with the same name but incompatible arguments.

## 用例 Example

最初に､ 一個の整数引数を採りデータベース内の対応する記録から二つの値を返す sel1 と呼ばれる準備された宣言文を生成する: First, create a prepared a statement called sel1 which takes a single integer parameter and returns two values from the corresponding record in a database:

    pg_execute $conn "PREPARE sel1 (INTEGER) AS SELECT cost, itemname FROM mytable WHERE partnum = \$1"

次に､記録から値を取込む為の準備された宣言文を使うことができる: 　 Now we can use that prepared statement to fetch the values from a record:

    set res [pg_exec_prepared $conn sel1 TEXT TEXT $partnumber]

一つの TEXT 引数 $partnumber は準備された問合せに送られ $1 に置換わる｡一個の TEXT 結果が返ることが期待される｡結果の把持子 res は pg_exec 空の結果把持子の様に pg_result をつかって利用される｡ One TEXT argument, $partnumber, is sent to the prepared query and replaces $1. One TEXT result is expected back. The result handle res is accessed using pg_result just like a result handle from pg_exec.

その他の用例はSection5.7, “Example - Prepared Queries - Picture Viewer, Part 1 - Store Pictures” 及び Section5.8, “Example - Prepared Queries - Picture Viewer, Part 2 - View Pictures” にある Other examples can be found in Section5.7, “Example - Prepared Queries - Picture Viewer, Part 1 - Store Pictures” and Section5.8, “Example - Prepared Queries - Picture Viewer, Part 2 - View Pictures”.

Prev | Up | Next
pg_exec_params | Home | pg_describe_cursor