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

## pg_escape_bytea

pg_escape_bytea — 可変長のバイナリ列(バイト配列)列を伴う SQL 文字列定数の使用の為に二進文字列を除外する Escape a binary string for use in an SQL string constant with bytea (byte array) columns

## 構文 Synopsis

    pg_escape_bytea ?conn? binary_string

## 説明 Description

pg_escape_bytea は 一個引用された SQL 文字列の使用を安全にする為に追加された文字を伴う引数を返す｡ 文字列上で動く pg_escape_string とは異なり､ `pg_escape_bytea` は､保存されるか PostgreSQL bytea (byte 配列) 列に使われる筈の任意の二進データに向いている｡この命令は､平文様式の問合せ内で､任意の二進データが､ PostgreSQL 問合せの仕組みを経て安全に送られることを許容する｡(除外した､及び除外しない二進データを二進様式の準備された問合せに使用する別法である｡pg_exec_preparedを参照されたい) `pg_escape_bytea` returns its argument with added characters which makes it safe for use in single-quoted SQL string constants. Unlike pg_escape_string, which works on text strings, `pg_escape_bytea` is meant for arbitrary binary data meant to be stored or used with PostgreSQL `bytea` (byte array) columns. This command allows arbitrary binary data to be safely sent through the PostgreSQL query mechanism in a text mode query. (An alternative to escaping and unescaping binary data is to use binary mode prepared queries. See pg_exec_prepared.)

## 引数 Arguments

`conn`

  送る為に除外されるべき二進列の接続の把持子｡ Optional handle of the connection that the binary string should be escaped for sending to.

`binary_string`

  除外すべき二進列データ｡これは正規のTcl文字列である､但し任意のバイト値を含み得る｡ The binary string data to escape. This is just a regular Tcl string, except that it can contain arbitrary byte values.

## 返り値 Return Value

除外されたデータ文字列｡単一引数の間に置かれていると､安全にSQL宣言文に使われる｡ The escaped data string. When placed in single quotes, it can safely be used in SQL statements.

## 註意 Notes

pg_unescape_byteaをも参照されたい､但し､註意すべきは､これらの命令は互いに逆の命令ではない｡ pg_escape_bytea は出力を生成する､それはデータベースによる二つの水準を通り抜けることになっている: 一つは､SQL解析の時､及び､一つはバイトデータ型の処理の時｡譬えば､入力文字列内の引用符号は pg_escape_bytea によって二つの引用符号に変換される､が､ pg_unescape_bytea によって元に変換されはしない｡ See also pg_unescape_bytea, but note that these commands are not inverses of each other. `pg_escape_bytea` creates output that is meant to go through two levels of parsing by the database: one when parsing SQL, and one when processing the bytea data type. For example, a quote mark in the input string is translated to two quote marks by `pg_escape_bytea`, but is not translated back by `pg_unescape_bytea`.

この命令の pgintcl 実装は遅い｡貴兄の二進データを除外と非除外させることを避ける為に､代りに二進の準備された問合せを考慮されたい｡ The pgintcl implementation of this command is slow. Consider using binary prepared queries instead, to avoid having to escape and unescape your binary data.

この命令は pgtclng-1.5.2 と pgintcl-2.2.0 から追加された｡ This command was added in pgtclng-1.5.2 and in pgintcl-2.2.0.

任意追加の `conn` 引数は pgtclng-1.7.0 and in pgintcl-3.1.0 からこの命令に追加された｡ The optional `conn` argument was added to this command in pgtclng-1.7.0 and in pgintcl-3.1.0.

`conn` 引数は PostgreSQL 中央集中処理系の構成設定媒介変数 `standard_conforming_strings` を得る為に使われる｡これは逆斜線を二重化する必要があるかの決定に使われる｡もし`conn` 媒介変数が供給されると､設定は､特定のデータベース接続に使われることを正確に決定できる｡(註意すべきは､この情報は依頼者側で維持され､如何なる追加のデータベース中央集中処理系への通信負荷も必要ない｡) The `conn` argument is used to get the state of the PostgreSQL server configuration parameter `standard_conforming_strings`. This is used to determine if backslashes need to be doubled. If the `conn` parameter is supplied, the setting can be accurately determined for the specific database connection being used. (Note that this information is maintained on the client side and does not necessitate any additional database server traffic.)

conn 假引数が供給されない場合､依頼者によるどのデータベース接続からの最も最近の情報に基づいて最良の推論がなされる｡従って､もし､依頼者が単一のデータベース接続をなすか､複数のデータベース接続で､同じ符号系且つ標準に適合する文字列の場合､conn を提供する必要はない｡ If the `conn` parameter is not supplied, a best guess will be made based on the most recent information from any database connection by the client. Therefore, if the client makes a single database connection, or multiple connections with the same setting for standard_conforming_strings, there is no need to provide the `conn` parameter.

この命令は､接続把持子が全く提供されない場合､ PostgreSQL libpq function PQescapeString を使用し､提供される場合はPQescapeStringConnを使用する｡ This command uses or emulates the PostgreSQL libpq function `PQescapeBytea`, if no connection handle is supplied, or `PQescapeByteaConn` if a connection handle is supplied.

用例はSection5.9, “Example - Bytea Escaping - Picture Viewer, Part 1 - Store Pictures”を参照されたい｡ See Section5.9, “Example - Bytea Escaping - Picture Viewer, Part 1 - Store Pictures” for an example.

PostgreSQL-9.0.0 は bytea 文字列の十六進様式符号系を除外様式符号系の代りに導入した｡libpq-に基づく pgtcl-ng の中では､接続把持子が提供され且つ､接続が PostgreSQL 9.0 かそれ以上の版であれば､pg_escape_bytea は十六進符号系で返す｡それ以外の全ての場合(接続把持子が提供されない､又は､古いデータベースに接続されている) pgtcl-ng は除外様式符号系を使う｡純-Tcl pgintcl 内では pg_escape_bytea は常に除外様式符号系を返す｡ PostgreSQL-9.0.0 introduced hex mode encoding of bytea strings as an alternative to the escape mode encoding. In libpq-based pgtcl-ng, `pg_escape_bytea` returns a string with hex encoding if a connection handle is supplied and the connection is to a PostgreSQL 9.0 or higher database. In all other cases (no connection handle supplied, or connected to an older database), pgtcl-ng uses escape mode encoding. In the pure-Tcl pgintcl, `pg_escape_bytea` always returns a string with escape mode encoding.

Prev | Up | Next
pg_escape_literal | Home | pg_unescape_bytea