pg_sendquery_params
Prev | 4.4.Asynchronous Query Processing Commands | Next

## pg_sendquery_params

pg_sendquery_params — 非同期実行の為に媒介変数化された SQL 命令を中央集中処理系に送る Send a parameterized SQL command to the server for asynchronous execution

## 構文 Synopsis

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

## 説明 Description

`pg_sendquery_params` は媒介変数化された命令を PostgreSQL 中央集中処理系に送り､命令の完了を待たず､直ぐに戻る｡媒介変数値は中央集中処理系に送られた命令内の場所占有子に束縛されている｡sql命令文字列から假引数を分離することにより､この命令は引用の問題なしにsql宣言文假引数への引数の束縛を許容し､生のデータの送出しと受取りを運営する｡ `pg_sendquery_params` の構文は､pg_exec_params とおなじであり､それは同期問合せ実行である｡ `pg_sendquery_params` sends a parameterized command to the PostgreSQL server and returns immediately, without waiting for the command to complete. Parameter values are bound to place-holders in the command sent to the server. 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. The syntax of `pg_sendquery_params` is the same as pg_exec_params which is for synchronous query execution.

## 引数 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

なし None.

もし不都合が生じるとTcl不都合が発せられる｡ A Tcl error will be thrown if an error occurs.

## 註意 Notes

もし命令が猶実行されていかを確認する為に pg_isbusy を使われたい｡結果を得る為には､必要なら命令の完了を待ち､ pg_getresult を使われたい｡代りに､結果が準備できた時､呼戻し命令を登録する為に pg_result_callback を使われたい(即ち､pg_getresult が抑止されない時)｡ Use pg_isbusy to see if the command is still being executed. Use pg_getresult to get the result, waiting for the command to complete if necessary. Alternatively, use pg_result_callback to register a callback command to be executed when a result is ready (that is, when pg_getresult will not block).

確認すべきは､ 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_sendquery_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.

この命令は pgtclng-1.6.0 に追加された｡ This command was added in pgtclng-1.6.0.

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

pg_sendquery も媒介変数としての問合せを扱うが､媒介変数と結果の型はTEXT のみである｡全ての媒介変数が TEXT 型で､且つ結果も TEXT 型の場合､代りに pg_execを使う方が簡略である｡ pg_sendquery also supports parameterized asynchronous 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_sendquery instead.

Prev | Up | Next
pg_sendquery | Home | pg_sendquery_prepared