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

## pg_exec_params

pg_exec_params — 中央集中処理系上の媒介変数化されたSQL命令を実行する Execute a parameterized SQL command on the server

## 構文 Synopsis

    pg_exec_params conn commandString resultFormats argFormats argTypes ?param...?

## 説明 Description

pg_exec_params は命令内の場所占有子に束縛された媒介変数を伴って命令を PostgreSQL 中央集中処理系に送り､結果の把持子を得る｡これはpg_exec_prepared に似ているが､準備宣言文は使わない､又､二進化媒介変数を使用したい場合は OID型を提供せねばならない｡ 媒介変数をSQL 命令文字列から区別する為に､この命令は引用の問題なしに引数を SQL 宣言文媒介変数への束縛を許容し､且つ､生の二進データの送付と受け入れを運営する｡ `pg_exec_params` sends a command to the PostgreSQL server with parameters to be bound to place-holders in the command, and returns a result handle. This is similar to pg_exec_prepared, but doesn't use a pre-prepared statement, and if you want to use binary parameters you must also provide the type OIDs. By separating parameters from the SQL command string, 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.

`commandString`

  解析し､引数に束縛し､実行すべき SQL 命令｡引数占有子は $1, $2, 等として表示される｡ 　 The SQL command to parse, bind arguments to, and execute. Argument place-holders are indicated as `$1`, `$2`, etc.

`resultFormats`

  問合せ結果として期待される書式｡平文の書式には`T`か`TEXT` を使われたい､二進書式には`B` or `BINARY` を使われたい｡ 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.

`argTypes`

  媒介変数引数の引数に関する PostgreSQL の OID 型のリスト｡このリストは､空であるか､それぞれの問合せ媒介変数に関する一つの入力を含まねばならない｡もしリストが空であると､全ての引数は型のない文字の文字列として扱われる､且つ､全ての引数書式は平文でなければならない｡もしリストが､非-空であると､それぞれの零の入力は､対応する平文書式引数は型のない文字の文字列として扱われる｡それぞれの非-零の入力は対応する二進化書式非異数に対応する OID 型である｡ OID型を得る為には､ pg_type 表を問合わせられたい｡ A list of PostgreSQL Type OIDs for the query parameter arguments. This list must either be empty, or contain one entry for each query parameter. If the list is empty, all arguments are treated as untyped literal strings, and all argument formats must be text. If the list is non-empty, each zero entry results in the corresponding text format argument being treated as an untyped literal string. Each non-zero entry is the type OID for the corresponding binary format argument. To get type OIDs, query the `pg_type` table.

`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

確認すべきは､ Tcl 変数置換を回避する為に SQL 命令文字列内の $1 の様な媒介変数場所占有子を波括弧や除外することを確認せねばならない｡ Be sure to brace-quote or escape the parameter place-holders such as `$1` in the SQL command string to protect them from Tcl variable expansion.

`pg_exec_params` の命令構文は平文と二進数結果列の混合を運営するが､きそになっているPostgreSQL(libpq) 外部函数は現在未だこれに対応してない｡従って､全ての結果の列が平文書式でなければならない､或は全ての列は二進化書式でなければならない｡ The command syntax of `pg_exec_params` 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 as query parameters.

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

この命令はpgtclng-1.5.1とpgintcl-2.1.0に追加された｡ This command was added in pgtclng-1.5.1 and in pgintcl-2.1.0.

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

pg_exec も媒介変数としての問合せを扱うが､媒介変数と結果の型はTEXT のみである｡全ての媒介変数が TEXT 型で､且つ結果も TEXT 型の場合､代りに pg_execを使う方が簡略である｡ pg_exec also supports parameterized queries, but only TEXT parameter and result types. If all your parameters are TEXT type, and your result is TEXT type, it is simpler to use pg_exec instead.

Prev | Up | Next
pg_select | Home | pg_exec_prepared