これは pgintcl/内部 であり pgintcl の内部実装に関する備忘録である｡
最後の pgintcl-3.4.0 の改良は 2011-09-19 
企画の我家頁は: http://sourceforge.net/projects/pgintcl/
This is pgintcl/INTERNALS, notes on internal implementation of pgintcl.
Last updated for pgintcl-3.4.0 on 2011-09-19
The project home page is: http://sourceforge.net/projects/pgintcl/
-----------------------------------------------------------------------------
内部実装備忘録: 	INTERNAL IMPLEMENTATION NOTES:
この情報は､維持､試験､修繕の為に提供される｡
This information is provided for maintenance, test, and debugging.

接続把持子は Tcl socket 通信路である｡pgin.tcl を使う応用譜はこの通信路から読み､書きしてはならない｡
A connection handle is just a Tcl socket channel. The application using
pgin.tcl must not read from or write to this channel.

内部手続き函数と､結果構造と､他のデータは "pgtcl" と呼ばれる名前空間内に保存される｡次の名前空間変数が全ての接続に適用される:
    pgtcl::debug      修繕旗徴､既定は0(修繕なし) A debug flag, default 0 (no debugging)
    pgtcl::version    pgin.tcl の版番号 pgin.tcl version string
    pgtcl::rn         結果番号計数 Result number counter
    pgtcl::fnoids     機能 OID 高速記憶;FAST-PATH FUNCTION CALLS参照 Function OID cache; see FAST-PATH FUNCTION CALLS
    pgtcl::errnames   不都合伝言文欄名の定数配列 Constant array of error message field names

次の配列は接続把持子によって索引付けされ､その接続に適用するデータのみを含む｡
    pgtcl::notice()   通告を受取った時に実行する命令 Command to execute when receiving a Notice
    pgtcl::xstate()   一括実行の状態 Transaction state
    pgtcl::notify()   通告; 通告参照  Notifications; see NOTIFICATIONS
    pgtcl::notifopt() 通告指示項目；通告参照 Notification optionss; see NOTIFICATION
    pgtcl::std_str()  pg_escape_stringへの文字列 For pg_escape_string etc; see ESCAPING
    pgtcl::bepid()    背景処理識別番号 Backend process ID (PID)
更なる名前空間変数は下の節で記述されている｡
構造変数は次の節で記述する


Internal procedures, result structures, and other data are stored in a
namespace called "pgtcl". The following namespace variables apply to
all connections:

    pgtcl::debug      A debug flag, default 0 (no debugging)
    pgtcl::version    pgin.tcl version string
    pgtcl::rn         Result number counter
    pgtcl::fnoids     Function OID cache; see FAST-PATH FUNCTION CALLS
    pgtcl::errnames   Constant array of error message field names

The following arrays are indexed by connection handle, and contain data
applying only to that connection:

    pgtcl::notice()   Command to execute when receiving a Notice
    pgtcl::xstate()   Transaction state
    pgtcl::notify()   Notifications; see NOTIFICATIONS
    pgtcl::notifopt() Notification optionss; see NOTIFICATION
    pgtcl::std_str()  For pg_escape_string etc; see ESCAPING
    pgtcl::bepid()    Backend process ID (PID)

Additional namespace variables are described in the sections below.
Result structure variables are described next.

-----------------------------------------------------------------------------
RESULT STRUCTURES:

結果構造は pgtcl 名前空間内の変数 結果$N として実装される､ここで N は整数である｡(変数Nはpgtcl::rn 内に貯蔵され､且つ､新しい結果構造が必要なそれぞれの時に増加される｡) 結果把持子は $N 丁度の整数として戻される｡結果構造は配列であって､結果に就いて結果値と同じ様に全ての汎情報を保存する｡
A result structure is implemented as a variable result$N in the pgtcl
namespace, where N is an integer. (The value of N is stored in pgtcl::rn
and is incremented each time a new result structure is needed.) The result
handle is passed back to the caller as $N, just the integer. The result
structure is an array which stores all the meta-information about the
result as well as the result values.

使用中の結果構造配列索引:
The result structure array indexes in use are:

  全体の結果を記述する変数 Variables describing the overall result:
    result(conn)      接続把持子(受け口通信路)The connection handle (the socket channel)
    result(nattr)     属性の数(列) Number of attributes (columns)
    result(ntuple)    リストの個数 Number of tuples (rows)
    result(status)    PostgreSQLの状態符号 PostgreSQL status code, e.g. PGRES_TUPLES_OK
    result(error)     宣言が PGRES_FATAL_ERROR の場合は不都合伝言文 Error message if status is PGRES_FATAL_ERROR
    result(complete)  命令完了宣言文､譬えば､. "SELECT 10" とか Command completion status, e.g. "SELECT 10"
    result(error,C)   もし宣言文が PGRES_FATAL_ERRORの場合は不都合伝言文欄 C ｡ C は拡張不都合伝言文欄の為の符号の内の一つ｡｡ Error message field C if status is PGRES_FATAL_ERROR.
                      C is one of the codes for extended error message fields.

  結果内の属性(列)を記述する変数 Variables describing the attributes (columns) in the result:
    result(attrs)     各属性の名前のリスト A list of the name of each attribute
    result(types)     各属性の型OIDのリスト A list of the type OID for each attribute
    result(sizes)     属性のバイト長さ､変動なら-1 A list of attribute byte lengths or -1 if variable
    result(modifs)    各属性の寸法修正リスト A list of the size modifier for each attributes
    result(formats)   各属性の書式データのリスト A list of the data format for each attributes
    result(tbloids)   それぞれの属性の為の表 OIDのリスト A list of the table OIDs for each attribute

  結果内に準備された問合せ假引数を記述する変数 Variables describing prepared query parameters in the result:
    result(nparams)      準備された状態假引数の個数 The number of prepared statement parameters
    result(paramtypes)   準備された 型 OID假引数状態のリスト？？ List of prepared statement parameter type OIDs

  問合せ結果の値を保存する変数 Variables storing the query result values:
    result($irow,$icol)       結果に関するデータ値 Data value for result
    result(null,$irow,$icol)  結果に関するnull旗徴 NULL flag for result

pg_exec と pg_exec_prepared 命令は新しい結果構造を生成して返す｡ pg_result 命令は結果構造から情報を取出し､又､ -clear 指示項目により結果構造を解放する｡(他の命令､特に､ pg_select と pg_execute は pg_exec を使う､それで､前者も結果構造を作るが､命令の内部に留め､呼出側はそれを見る事はできない｡) 内蔵の結果構造も又直接他の pg_select や pg_execute の様な担当譜から利用される｡結果構造配列は pg_result -clear によって消去(解放)され､どの様な残り物の接続把持子を伴う結果構造は､ pg_disconnect により接続機能が閉じられる時解放される｡
The pg_exec and pg_exec_prepared commands create and return a new result
structure. The pg_result command retrieves information from the result
structure and also frees the result structure with the -clear option.
(Other commands, notably pg_select and pg_execute, use pg_exec, so they
also make a result structure, but it stays internal to the command and the
caller never sees it.) The result structure innards are also directly
accessed by some other routines, such as pg_select and pg_execute.  Result
structure arrays are unset (freed) by pg_result -clear, and any left-over
result structures associated with a connection handle are freed when the
connection handle is closed by pg_disconnect.

問合せ結果値は result($irow,$icol) に保存され､そこでは､ $irow は組(行)番号であり､0 と$result(ntuples)-1 とその間の数､又､$icol は属性(列)番号で 0 と $result(nattr)-1 とその間の数である｡もしデータベースに返された値が NULL なら､$result($irow,$icol) は空文字列に設定され､この行と列に関する $result(null,$irow,$icol) も又空文字列に設定される｡非-NULL 値に関して､ $result(null,$irow,$icol) は全く設定されない｡ "null,*,*" 索引は応用譜の為に､ 空文字列から NULL を区別する必要がある場合､ pg_result -getNull のみから使われる - 空文字列と NULL の両者は result($irow,$icol) 内に空文字列として保存され､どの pg_result 利用手段によっても空文字列を返す｡ pg_select や pg_execute や pg_exec_prepared によって空文字列から NULL を区別する方法はない｡
The query result values are stored in result($irow,$icol) where $irow is
the tuple (row) number, between 0 and $result(ntuples)-1 inclusive, and
$icol is the attribute (column) number, between 0 and $result(nattr)-1
inclusive. If the value returned by the database is NULL, then
$result($irow,$icol) is set to an empty string, and
$result(null,$irow,$icol) is also set to an empty string for this row and
column. For non-NULL values, $result(null,$irow,$icol) is not set at all.
The "null,*,*" indexes are used only by pg_result -getNull if it is
necessary for the application to distinguish NULL from empty string - both
of which are stored as empty strings in result($irow,$icol) and return an
empty string with any of the pg_result access methods. There is no way to
distinguish NULL from empty string with pg_select, pg_execute, or
pg_exec_prepared.

完全な問合せの結果は何が起こる前に保存される(即ち､ pg_exec と pg_exec_prepared を返す前に､且つ､ pg_execute と pg_select が第一行を処理する前に)｡これは､ libpq と pgtcl-ng (その同期様式内で)では正しいが､ Tcl が遅れるかもしれない｡
The entire result of a query is stored before anything else happens (that
is, before pg_exec and pg_exec_prepared return, and before pg_execute and
pg_select process the first row).  This is also true of libpq and pgtcl-ng
(in their synchronous mode), but Tcl can be slower.

拡張不都合伝言文欄は PostgreSQL-7.4 で改められた｡受取った不都合伝言文の個別の部分は､(error,$c) によって索引される結果配列に保存される､茲で $c は通信規格に使われる一文字符号である｡更なる情報は"pg_result -errorField"に関する pgin.tcl 説明文を参照されたい｡( 2.2.0 により､pg_result -errorField は pg_result -error と同じである: 両者は､完全な伝言文よりも拡張不都合伝言文欄を返す任意追加欄名か符号引数を採る｡)
Extended error message fields are new with PostgreSQL-7.4. Individual parts
of a received error message are stored in the result array indexed by
(error,$c) where $c is the one-letter code used in the protocol. See the
pgin.tcl documentation for "pg_result -errorField" for more information.
(As of 2.2.0, pg_result -errorField is the same as pg_result -error: both
take an optional field name or code argument to return an extended error
message field, rather than the full message.)

-----------------------------------------------------------------------------
緩衝 BUFFERING

PostgreSQL 通信規約第3版(PostgreSQL-7.4)は伝言文基盤通信規約を使う｡背景処理から伝言文を読む為に､ pgin.tcl は pgtcl 名前空間内の幾つかの Tcl 変数を使う 接続-経由 緩衝を実装する｡接続機能の名前は変数の名前の部分であり､下の様に Tcl によって表現される｡

PostgreSQL protocol version 3 (PostgreSQL-7.4) uses a message-based
protocol.  To read messages from the backend, pgin.tcl implements a
per-connection buffer using several Tcl variables in the pgtcl namespace.
The name of the connection handle (the socket name) is part of the variable
name, represented by $c below.

       pgtcl::buf_$c    背景処理からの伝言文を保持している緩衝域.
       pgtcl::bufi_$c   buf_$c 空の処理さるべき次のバイトの索引
       pgtcl::bufn_$c   緩衝域 buf_$c 内のバイトの総個数｡
       pgtcl::buf_$c    The buffer holding a message from the backend.
       pgtcl::bufi_$c   Index of the next byte to be processed from buf_$c
       pgtcl::bufn_$c   Total number of bytes in the buffer buf_$c.

譬えば､もし接続機能が "sock3" であれば､変数はpgtcl::buf_sock3 と pgtcl::bufi_sock3 と  pgtcl::bufn_sock3 である｡
For example, if the connection handle is "sock3", the variables are
pgtcl::buf_sock3, pgtcl::bufi_sock3, and pgtcl::bufn_sock3.

幾つかの試験から､ Tcl 内では緩衝域から最も早くデータを取り出す方法は [string index] と [string range] を使用することであったが､これは直感的ではない様だ｡                 
A few tests determined that the fastest way to fetch data from the buffers
in Tcl was to use [string index] and [string range], although this might
not seem intuitive.

-----------------------------------------------------------------------------
假引数  PARAMETERS

PostgreSQL 背景処理は前面依頼者に幾らかの假引数について通知でき､且つ､ pgin.tcl はこれ等を pgtcl 名前空間内の次の変数に保存する:
The PostgreSQL backend can notify a front-end client about some parameters,
and pgin.tcl stores these in the following variable in the pgtcl namespace:

    pgtcl::param_$c    假引数の値の配列で､假引数名で索引される｡Array of parameter values, indexed by parameter name

茲で $c は､接続把持子である(ソケット名)｡
where $c is the connection handle (socket name).

これ等の假引数の利用は  pgin.tcl 拡張の pg_parameter_status 命令経由である｡
Access to these parameters is through the pg_parameter_status command,
a pgin.tcl extension.

-----------------------------------------------------------------------------
通信規約の問題  PROTOCOL ISSUES

 pgin.tcl の､この版は 通信規約第3版 PostgreSQL 背景処理 (7.4 版以降)のみに通話する｡第2版への接続作成が一つあり､且つそれは不都合伝言文を読む｡もし第2版の不都合伝言文が読まれると､pgin.tcl はそれを認識し､第3版伝言文から得た振りをする｡これは､接続段階の間の使用に関して､もし第2版のみの背景処理への接続の場合に適切な伝言文を伴う不都合を許容する為のものである｡
This version of pgin.tcl speaks only to a Protocol Version 3 PostgreSQL
backend (7.4 or later). There is one concession made to Version 2, and
that is reading an error message. If a Version 2 error message is read,
pgin.tcl will recognize it and pretend it got a Version 3 message. This
is for use during the connection stage, to allow it to fail with a
proper message if connecting to a Version 2-only backend.

-----------------------------------------------------------------------------
通知  NOTIFICATIONS

配列 pgtcl::notify は貴兄が望む通知の航跡を保持する｡配列は pgtcl::notify(connection,name) の様に索引され､茲で connection は接続把持子(ソケット名)であり､且つ､名前は pg_listen 内で使用された假引数である｡配列要素の値は通知で実行されるべき命令である｡これは､手続き函数の名前や､引数に続く手続き函数名でも好い｡適切な Tcl リストでなければならない｡
An array pgtcl::notify keeps track of notifications you want. The array is
indexed as pgtcl::notify(connection,name) where connection is the
connection handle (socket name) and name is the parameter used in
pg_listen. The value of an array element is the command to execute on
notification. This can be a procedure name, or a procedure name with
leading arguments. It must be a proper Tcl list.

 PostgreSQL-9.0.0 の開始と共に､ '有効部分 payload' が SQL NOTIFY 命令によって提供され得る｡ pgin.tcl-3.2.0 の開始と共に､この有効部分(空文字列でない場合)は命令への追加引数に渡される｡命令はリストとして採り､有効部分は lappend 内として追加される｡結果のリストは実行すべき命令である｡もし有効部分がないか､空文字列か､註集中処理装置が PostgreSQL-9.0.0 より古い場合､命令には追加引数は渡されない｡命令は､従って常に追加引数を受容れるべきである｡
Starting with PostgreSQL-9.0.0, a 'payload' string can be provided with the
SQL NOTIFY command.  Starting with pgin.tcl-3.2.0, this payload (if not empty)
will be passed as an additional argument to the command. The command is taken
as a list, and the payload is appended as in lappend.  The resulting list is
the command to execute. If there is no payload, or it is empty, or the server
is older than PostgreSQL-9.0.0, no additional argument will be passed to the
command. The command should therefore always accept an optional argument.

pgintcl-3.4.0 の開始と共に､通知に関する指示項目を保存する為の追加配列 pgtcl::notifopt() が存する｡この配列は pgtcl::notif() と同じ方法で索引され､且つ､整数値を保持する｡値 0 は､この通知がない場合である｡値 1 は､通知聴取者が引数として背景処理 ID 通知を､ pg_listen への -pid 指示項目によって索引されて､取得した場合である｡他の指示項目は定義されない｡ 
Starting with pgintcl-3.4.0, there is an additional array pgtcl::notifopt()
to store options for the notification. This array is indexed the same way
as pgtcl::notif(), and holds integer values. The value is 0 if there are no
options for this notification. The value is 1 if the notification listener
should get the notifying backend process ID as an argument, as indicated by
the -pid option to pg_listen. No other options are defined.

-----------------------------------------------------------------------------
註意事項  NOTICES

註意事項と警告伝言文機能は pg_notice_handler 命令を使って誂える事ができる｡無為設定では､註意事項機能は次の通りで
      puts -nonewline stderr
且つ､この文字列は初回の pg_notice_handler 呼出に返される｡註意事項機能は一つ或はそれ以上の引数を伴う手続き函数として定義されるべきである｡最初の引数は処理機能が pg_notice_handler により設定されるときに供給され､且つ最後の引数は註意または警告伝言文である｡
Notice and warning message handling can be customized using the
pg_notice_handler command. By default, the notice handler is 
      puts -nonewline stderr
and this string will be returned the first time pg_notice_handler is
called. A notice handler should be defined as a proc with one or more
arguments. Leading arguments are supplied when the handler is set with
pg_notice_handler, and the final argument is the notice or warning message.

-----------------------------------------------------------------------------
巨大対象  LARGE OBJECTS

巨大対象命令は PostgreSQL "fast-path" 函数呼出対話機能(libpq と同じ)を使って実装される｡ fast-path の更なる情報については次の節を参照されたい｡
The large object commands are implemented using the PostgreSQL "fast-path"
function call interface (same as libpq). See the next section for more
information on fast-path.

pg_lo_creat 命令は様式引数を採る｡PostgreSQL libpq 説明書の様に､lo_creat は "INV_READ" か  "INV_WRITE" か "INV_READ|INV_WRITE" を採る筈である｡(pgin.tcl はそれらと同等に "r" と "w" と "rw" も受容れるが､これは pgtcl-ng と両立しない｡) "INV_READ|INV_WRITE"以外と伴に巨大対象を生成する方法は明確ではない｡[譯註:様式引数 読み書き様式を指定する"r" と "w" と "rw"]
The pg_lo_creat command takes a mode argument. According to the PostgreSQL
libpq documentation, lo_creat should take "INV_READ", "INV_WRITE", or
"INV_READ|INV_WRITE".  (pgin.tcl accepts "r", "w", and "rw" as equivalent
to those respectively, but this is not compatible with pgtcl-ng.) It isn't
clear why you would ever create a large object with other than
"INV_READ|INV_WRITE".

pg_lo_open 命令も様式引数を採る｡PostgreSQL libpq 説明書に従い､lo_open はlo_creat と同じ様式引数を採る｡しかし libpgtcl 内では pg_lo_open は､様式として､何かの理由で､"r" と "w" と "rw" を受容れる｡ pgin.tcl は様式として､どちらも受容れるが､libpgtcl との両立の為には pg_lo_open と伴には "INV_READ" や  "INV_WRITE" や "INV_READ|INV_WRITE" ではなく､"r" か "w" か "rw" を使う方が好い｡
The pg_lo_open command also takes a mode argument. According to the
PostgreSQL libpq documentation, lo_open takes the same mode values as
lo_creat.  But in libpgtcl the pg_lo_open command takes "r", "w", or "rw"
for the mode, for some reason. pgin.tcl accepts either form for mode,
but to be compatible with libpgtcl you should use "r", "w", or "rw"
with pg_lo_open instead of INV_READ, INV_WRITE, or INV_READ|INV_WRITE.


-----------------------------------------------------------------------------
FAST-PATH FUNCTION CALLS

PostgreSQL の "Fast-path function call" 対話機能の利用は pgin.tcl 内で利用できる｡これは巨大対象を実装する為に記述され､一般使用は推奨されない｡この対話機能が如何なるもので､如何に使用するべきかの更なる詳細は libpq 説明書を参照されたい｡
Access to the PostgreSQL "Fast-path function call" interface is available
in pgin.tcl. This was written to implement the large object command, and
general use is discouraged. See the libpq documentation for more details on
what this interface is and how to use it.

準備 と 束縛 と 実行 の段階を区別する為の拡張通信路の使用に賛同して､PostgreSQL 内の Fast-path 函数呼出し対話機能の抑制が期待される｡PREPARE/BIND/EXECUTE. を参照されたい｡
It is expected that the Fast-path function call interface in PostgreSQL
will be deprecated in favor of using the Extended Protocol to do
separate Prepare, Bind, and Execute steps. See PREPARE/BIND/EXECUTE.

内部では､背景処理函数はその PostgreSQL OID によって呼出されるが､pgin.tcl は､貴兄の為に函数名のOIDへの対応を処理する｡ pgin.tcl 内の fast-path 函数対話機能は PostgreSQL 函数の対象 ID を高速保存する為の配列 pgtcl::fnoids を使う｡この配列の一つの即値は､これ等の OID は全てのデータベース間で共通であるとの仮定の基に､全ての接続の間で共有される｡(もし､ PostgreSQL の､実行されている異なる版の中央処理機能に同時に接続を有すると､これは破壊されることがあり得る｡)  pgtcl::fnoids への索引は函数の名前か､ pgin.tcl の fast-path 函数呼出命令に提供されている様な函数に加えて引数型リストである｡それぞれの配列索引の値は函数の OID である｡
Internally, backend functions are called by their PostgreSQL OID, but
pgin.tcl handles the mapping of function name to OID for you.  The
fast-path function interface in pgin.tcl uses an array pgtcl::fnoids to
cache object IDs of the PostgreSQL functions.  One instance of this array
is shared among all connections, under the assumption that these OIDs are
common to all databases. (It is possible that if you have simultaneous
connections to multiple database servers running different versions of
PostgreSQL this could break.) The index to pgtcl::fnoids is the name
of the function, or the function plus argument type list, as supplied
to the pgin.tcl fast-path function call commands. The value of each
array index is the OID of the function.

PostgreSQL は過積載された函数(同じ名前､異なる数 及び/又は 引数の型)を運営する｡ pgin.tcl に函数名の後に引数型リストを指定して過積載函数を呼出すことができる｡下の用例を参照されたい｡引数リストを正確に指定する必要がある､psql "\df" が行っている様に - 正しい方名のリストとして､一個のコンマと空白によって句切られて｡現在の処､戻りの型によって函数を区別する規定は存在しない｡戻りの型によってのみ異なる何かの PostgreSQL 函数は存在するようには見えない｡
PostgreSQL supports overloaded functions (same name, different number
and/or argument types). You can call overloaded functions with pgin.tcl by
specifying the argument type list after the function name. See examples
below. You must specify the argument list exactly like psql "\df" does - as
a list of correct type names, separated by a single comma and space. There
is currently no provision to distinguish functions by their return type. It
doesn't seem like there are any PostgreSQL functions which differ only by
return type.

PostgreSQL-7.4 より前は､ fast-path 呼出の特定の不都合が､背景処理と前面処理の同期を失わせ､通信路を閉じさせていた｡これは libpq も同様であった｡新しい PostgreSQL-7.4 内で修繕された｡
Before PostgreSQL-7.4, certain errors in fast-path calls (such as supplying
the wrong number of arguments to the backend function) would cause the
back-end and front-end to lose synchronization, and the channel would be
closed. This was true about libpq as well.  This has been fixed with the
new protocol in PostgreSQL-7.4.


命令  Commands:

   pg_callfn $db "fname" result "arginfo" arg...

     PostgreSQL の背景処理函数を呼出結果を保存する｡結果の寸法をバイト単位で返す｡
     Call a PostgreSQL backend function and store the result.
     Returns the size of the result in bytes.

     假引数  Parameters:

       $db は接続機能子｡
       $db is the connection handle.

       "fname" は PostgreSQL 函数名｡これは "encode"の様な単純名でも､ "like(text, text)"の様な括弧付きの引数が続く名前でも好い｡貴兄が呼出を望む幾つかの過積載函数を指定する為に後者の形式が必要である｡
       "fname" is the PostgreSQL function name. This is either a simple
       name, like "encode", or a name followed by a parenthesized
       argument type list, like "like(text, text)". The second form
       is needed to specify which of several overloaded functions you want
       to call.

       "result" は変数の名前であり､其処にPostgreSQL 背景処理函数が返す値が保存される｡ "result" 内に保存されるバイトの数は pg_callfn の値として返される｡
       "result" is the name of a variable where the PostgreSQL backend
       function returned value is to be stored. The number of bytes
       stored in "result" is returned as the value of pg_callfn.

       "arginfo" は引数記述のリストである｡それぞれのリスト要素は次の内の一つである:
           I    整数の integer32 引数が期待される｡
           S   Tcl もj列引数が期待される｡文字列の長さが使われる(Tcl 文字列にはnullも含まれる)｡
           n (整数 > 0)
                Tcl 文字列が期待され､且つ､これは正確に多バイトの文字列引数が渡される(必要ならnullバイトが詰め込まれる)｡
       arg...   PostgreSQL 函数に零個以上の引数が続く｡引数の個数は "arginfo" リスト内の要素の個数に合致せねばならない｡値は､"arginfo"内の対応する記述に従って背景処理の函数に渡される｡

       "arginfo" is a list of argument descriptors. Each list element is
       one of the following:
           I    An integer32 argument is expected.
           S    A Tcl string argument is expected. The length of the
                string is used (remember Tcl strings can contain null bytes).
           n (an integer > 0)
                A Tcl string argument is expected, and exactly this many
                bytes of the string argument are passed (padding with null
                bytes if needed).

       arg...   Zero or more arguments to the PostgreSQL function follow.
                The number of arguments must match the number of elements
                in the "arginfo" list. The values are passed to the backend
                function according to the corresponding descriptor in
                "arginfo".

  一個の32整数引数を返す PostgreSQL 背景函数の為には､次の簡易化対話機能が利用できる:
  For PostgreSQL backend functions which return a single integer32 argument,
  the following simplified interface is available:

   pg_callfn_int $db "fname" "arginfo" arg...
      
       dbと, fnameと, arginfo,と 他の引数は pg_callfn に関しては､同じである｡from pg_callfn_int からの戻り値は､PostgreSQL背景函数によって返される整数32 値である

       The db, fname, arginfo, and other arguments are the same as
       for pg_callfn. The return value from pg_callfn_int is the
       integer32 value returned by the PostgreSQL backend function.

用例  Examples:
    註意: これらの用例は本命令を実演するが､これらの場合の両方では､代わりに､SQL 問合せをした方が好い｡
    Note: These examples demonstrate the command, but in both of these
    cases you would be better off using an SQL query instead.

       set n [pg_callfn $db version result ""]
    これは､背景函数 version() を呼出し､戻り値を $result 内に､且つ､結果の長さを $n 内に保存する｡
    This calls the backend function version() and stores the return
    value in $result and the result length in $n. 

       pg_callfn $db encode result {S S} $str base64
    これは､２つの文字列引数を伴って､背景函数 encode($str, "base64") を呼出し､結果を $result に保存する｡
    This calls the backend function encode($str, "base64") with 2
    string arguments and stores the result in $result.

       pg_callfn_int $db length(text) S "This is a test"
    これは､背景函数 length("This is a test") を呼出す｡ length() の多重函数呼出しがあるため､引数型リスト "(text)" は､函数の名前の後に与えねばならない｡文字列の長さ (14) が函数によって返される｡ 
    This calls the backend function length("This is a test"). Because
    there are multiple functions called length(), the argument type
    list "(text)" must be given after the function name. The length
    of the string (14) is returned by the function.

-----------------------------------------------------------------------------
準備/束縛/実行
PREPARE/BIND/EXECUTE

PostgreSQL-7.4 の開始から､別々になった､解析と､束縛と､実行の段階が通信規約により提供された｡
解析段階はSQL PREPARE 命令に置換える事ができる｡
 pgin.tcl は pg_exec_prepared (pgin.tcl-2.0.0で導入された)とpg_exec_params (pgin.tcl-2.1.0で導入された) によって､この拡張した問合せの対応を提供する｡
更に､pg_exec_params への簡単化対話機能を提供する pg_exec の変異型も存在する｡

Starting with PostgreSQL-7.4, access to separate Parse, Bind, and Execute
steps are provided by the protocol. The Parse step can be replaced by an
SQL PREPARE command.  pgin.tcl provides support for this extended query
protocol with pg_exec_prepared (introduced in pgin.tcl-2.0.0), and
pg_exec_params (introduced in pgin.tcl-2.1.0). There is also a variation of
pg_exec which provides a simplified interface to pg_exec_params.

拡張問合せ通信規格の主な利点は､問合せ文書文字列からの假引数の分離である｡
これは､假引数の引用と除外の必要を避け､SQL 挿入攻撃を防ぎ得る｡
更に､問合せが一度に､準備され､解析され､保存され､そして､再-解析なしに多数回実行すると､
pg_exec_prepared は幾らかの出来栄えの優越性を提供できる｡   

The main advantage of the extended query protocol is separation of
parameters from the query text string. This avoids the need to quote and
escape parameters, and may prevent SQL injection attacks.  pg_exec_prepared
also offers some performance advantages if a query can be prepared, parsed,
and stored once and then execute multiple times without re-parsing.

更に､ pg_exec_prepared と pg_exec_params 命令は､文書假引数と結果と共に働き､
除外されてない二進データを中央集中処理系に送ることを支援する｡
(Fast-path函数呼出しもこれを支援する｡)
これらの命令も､依頼者への二進データ戻しを支援する｡
(これは､二進遊走子を伴ってなされる｡)
 しかしながら､通信規格定義とpgin.tcl 命令は文書と二進混合の結果を支援し､
libpq は 全ての結果の列が文書になるか､全て二進になるかを要求する｡
二進/文書 が混合した結果の列の使用は､
貴兄の応用譜を､この対話機能の libpq-基準の版とは非互換にする｡｡

In addition to working with text parameters and results, the
pg_exec_prepared and pg_exec_params commands support sending unescaped
binary data to the server. (Fast-path function calls also support this.)
These commands also support returning binary data to the client.  (This can
also be done with binary cursors.) Although the protocol definition and
pgin.tcl commands support mixed text and binary results, libpq requires all
result columns to be text, or all binary. Using mixed binary/text result
columns will make your application incompatible with libpq-based versions
of this interface.

 pg_exec_prepared は､実行の為の､束縛媒介変数の後の､予備-準備SQL記述である｡
名付けられたSQL記述は､pg_exec_prepared を使う前に､
SQL"PREPARE" 命令を使って準備されねばならない｡
pg_exec_prepared の利点は､
通信規約-水準の解析段階は､依頼者に假引数型からOIDに翻訳することを要求するが､
 PREPARE を使用すると､中央集中処理系に媒介変数の引数の型を決定をさせる､事である｡
pg_exec_prepared は､Libpq call: PQexecPrepared() を模擬する｡  

pg_exec_prepared is for execution of pre-prepared SQL statements after
binding parameters.  A named SQL statement must be prepared using the SQL
"PREPARE" command before using pg_exec_prepared.  An advantage of
pg_exec_prepared is that the protocol-level Parse step requires the client
to translate parameter types to OIDs, but using PREPARE lets the server
determine the parameter argument types.  pg_exec_prepared is modeled after
the Libpq call: PQexecPrepared().

pg_exec_params does all three steps of the extended query protocol: parse,
bind, and execute. Parameter types can be specified by type OID, or parameters
can be based as text to be interpreted by the server as it does for any
untyped literal string. To find the type OID of a PostgreSQL type '<T>',
you need to query the server like this:
     SELECT oid FROM pg_type where typname='<T>'
pg_exec_params is modeled after the Libpq call: PQexecParams().

pg_exec_params は､拡張問合せ通信規約の三つの全ての段階を実行する: 解析と､束縛と､実行｡
媒介変数の型はOID型から指定でき､又､
どの未型付与の逐語的文字列に関して行う様に
中央集中処理系によって解釈される文書に､媒介変数が基くこともできる｡
PostgreSQLのOID型を見付けるには '<T>'と打鍵されたい､
この様に､中央集中処理系に問合す必要がある:
     SELECT oid FROM pg_type where typname='<T>'
pg_exec_params は Libpq call: PQexecParams() が模範になっている｡

A limitation of both pg_exec_prepared and pg_exec_params is lack of support
for NULLs as parameter values.  There is no way to pass a NULL parameter to
the prepared statement.  This is not a protocol or database limitation, but
just lack of a good idea on how to implement the command interface to
support NULLs without needlessly complication the more common case without
NULLs.


-----------------------------------------------------------------------------
MD5 AUTHENTICATION

MD5 認証は PostgreSQL-7.2 の時に付加された｡これは､
挑戦/応答 通信規約であり､それは 電網上の明瞭な−文書の暗証番号通過を避ける｡
これを活性化する為に､PostgreSQL管理者は pg_hba.conf ファイル内に "暗証番号"の代わりに
 "md5"を入力する｡pgin.tcl はこれを透明に対応する; 即ち､もし背景が接続中に､
MD5 認証を要求すると､ pg_connect はこの通信規約を使う｡
MD5 実装は pgin.tcl の元祖の著者が記述した｡それは､tcllib 実装を使わない､
それは著しく速いが､大変複雑である｡(訳註:最後の関係代名詞whichの先行詞はどれ?)

MD5 authentication was added at PostgreSQL-7.2. This is a
challenge/response protocol which avoids having clear-text passwords passed
over the network. To activate this, the PostgreSQL administrator puts "md5"
in the pg_hba.conf file instead of "password". Pgin.tcl supports this
transparently; that is, if the backend requests MD5 authentication during
the connection, pg_connect will use this protocol. The MD5 implementation
was coded by the original author of pgin.tcl. It does not use the tcllib
implementation, which is significantly faster but much more complex.

-----------------------------------------------------------------------------
文字符号系 ENCODING

文字揃い符号は pgin.tcl-3.0.0 に追加された｡ README と REFERENCE ファイル内に更なる情報がある｡
Character set encoding was added to pgin.tcl-3.0.0. More information can be
found in the README and REFERENCE files.

次のものはPostgreSQLに送られる前にユニコードに変換される:
    + 問合せ文字列 (pg_exec と､之を使う全ての高水準命令)
    + pg_exec_prepared/pg_exec_params 内の TEXT-書式の問合せ假引数  
    + 問合せ假引数が使われる時の pg_exec 内の全ての媒介変数引数
    + pg_exec_prepared 内の準備された宣言文の名前
    + pg_copy_write を使って送られたCOPY 表 FROM STDIN データ
次のものはPostgreSQLから受取る時にユニコードから変換される:
    + TEXT書式される時の問合せ結果列データ(二進書式の時以外)
    + 全ての不都合と文字列対応通知
    + 假引数の名前と値
    + 通知伝言文
    + 命令完了伝言文
    + 問合せ結果欄の名前 (列の名前)
    + pg_copy_read を使って受取ったCOPY 表 TO STDOUT データ

The following are converted to Unicode before being sent to PostgreSQL:

    + Query strings (pg_exec, and all higher-level commands which use it)
    + TEXT-format query parameters in pg_exec_prepared/pg_exec_params 
    + All parameter arguments in pg_exec when query parameters are used
    + Prepared statement name in pg_exec_prepared
    + COPY table FROM STDIN data sent using pg_copy_write

The following are converted from Unicode when received from PostgreSQL:

    + Query result column data when TEXT-format (not when BINARY-format)
    + All Error and Notice response strings
    + Parameter names and values
    + Notification messages
    + Command completion message
    + Query result field names (column names)
    + COPY table TO STDOUT data received using pg_copy_read

PostgreSQL送付の為の､データのユニコードへの変換は､五か所で行われる: 
pg_exec と､ pg_exec_params による文字列問合せと､pg_exec_prepared による 記述名称と､
pg_exec_prepared による文書書式媒介変数と､pg_copy_write 内でのCOPY FROM データ記入である｡

Conversion of data to Unicode for sending to PostgreSQL occurs in 5 places
in the code: pg_exec and pg_exec_params query strings, pg_exec_prepared
statement name, pg_exec_prepared text format parameters, and when writing
COPY FROM data in pg_copy_write.

PostgreSQL からユニコードへの変換は､符号命令内の三か所で生じる: 
通信規約伝言文 "string" 型を受容れる時(それは種々の伝言文､媒介変数､欄名称に及ぶ)と､
TEXT様式の組データを読む時と､pg_copy_read 内でCOPY TO データを読む時｡

Conversion of Unicode data from PostgreSQL occurs in 3 places in the code:
when receiving a protocol message "string" type (which covers various
messages, parameters, and field names), when reading TEXT mode tuple data,
and when reading COPY TO data in pg_copy_read.

接続媒介変数の使用者名と､データベース名と､暗証番号についてのユニコード変換は存しない｡
PostgreSQLは､これらを保存する為に ､
データベースの､群/鋳型1 のータベース の方法を使っていると思われるが､
その方法は､依頼者が接続しているデータベースの符号化とは異なる｡
即ち､これらの文字が如何に記録されるか明確ではない｡
現在の処､データベース名と､使用者名と､暗証番号は非-ASCII文字を避けるのが賢い｡
将来は治るかもしれない｡
There is no Unicode conversion for the connection parameters username,
database-name, or password. PostgreSQL seems to store these using the
encoding of the database cluster/template1 database, which may differ from
the encoding of the database to which the client is connected.  It is
unclear how to recode these characters.  At this time, it is wise to avoid
non-ASCII characters in database names, usernames, and passwords. This may
be fixed in the future.

急速-経路 函数対話機能呼出しは､その全ての引数を二進数データとして扱い､
且つ､それらを符号化や復号化はしない｡急速-経路函数呼出しは､第一に､
巨大対象対応の為に実装され､そして､巨大対象対応はユニコード符号化によって影響されない､
理由は､それは全て二進数データであるから｡
思わしく無いのは､符号化対応は､急速-経路函数呼出しへの符号化の対応化である､
理由は､媒介変数化された問合せが置換えられる傾向があるから｡

The fast-path function call interface treats all its arguments as binary
data and does not encode or decode them. The fast-path function calls
were implemented primarily for large object support, and large object
support is not affected by Unicode encoding because it is all binary
data. It is unlikely that encoding support will be added to fast-path
function calls, since parameterized queries are the preferred replacement.

-----------------------------------------------------------------------------
除外 ESCAPING

配列 pgtcl::std_str() は標準適合文字列に設定している PostgreSQL に関する前接続設定の保存に使われる｡これは追加の $conn 引数を受取る pg_escape_string と pg_quote と
pg_escape_bytea の版を運営する為に Pgin.tcl-3.1.0 で追加された｡
An array pgtcl::std_str() is used to store the per-connection setting for
the PostgreSQL setting standard_conforming_strings.  This was added in
Pgin.tcl-3.1.0 to support the versions of pg_escape_string, pg_quote, and
pg_escape_bytea which accept an optional $conn argument.

もし $conn が 1 で配列値が参照されていると､標準適合文字列はデータベース接合に合っている､又､逆斜線 (\) は SQL 引用文字列定数内では特別のものとは看做されない｡この場合､ pg_escape_string と pg_quote は二重逆斜線ではない｡ pg_escape_bytea は逆斜線と八進数の除外の時には逆斜線が一水準除外される｡

If the array value indexed by $conn is 1, then standard conforming strings
is on for that database connection, and the backslash (\) is not considered
special in SQL quoted string constants. In this case, pg_escape_string and
pg_quote will not double backslashes. pg_escape_bytea will omit one level
of backslashes when escaping backslash and octal values.

もし $conn が 0 で配列値が参照されていると､標準適合文字列はあのデータベースと接続について断であり､且つ､逆斜線 (\) はSQL 引用文字列定数内では特別のものである｡この場合､pg_escape_string と pg_quote は二重逆斜線され､pg_escape_bytea は一つの逆斜線について4つの逆斜線を使い､八進数には２の逆斜線を使う｡
If the array value indexed by $conn is 0, then standard conforming strings
is off for that database and connection, and the backslash (\) is special
in SQL quoted string constants. In that case, pg_escape_string and pg_quote
will double backslashes. pg_escape_bytea will use 4 backslashes for a single
backslash, and 2 backslashes in an octal value.

他に "_default_" 配列索引が存在し 除外命令に提供される引数 $conn がない時に使われる｡libpq と丁度同じ様に_default_ 値は､何時であれ､どのデータベース接続開扉も受容れる標準適合文字列に関するParameter伝言文を設定する｡もし一つの接続を使用しているか､標準適合文字列に対して同じ値の多重接続を使っていると､文字列除外の時の $conn 引数を使わなくても正しい除外の振舞が得られる｡
There is also an array index "_default_" which is used when no $conn
argument is supplied to the escape commands. Just as in libpq, the
_default_ value is set any time a Set Parameter message for
standard_conforming_strings is received over any open database connection.
If you are using a single connection, or multiple connections with the same
value for standard_conforming_strings, you will get correct escaping
behavior even without using the $conn argument when escaping strings.


-----------------------------------------------------------------------------
