これは Tcl言語による PostgreSQL対話譜の pgintcl 配布の pgintcl/案内書 である｡
最終改版は pgintcl-3.5.1 於 2017-11-12 
企画の我家頁は: http://sourceforge.net/projects/pgintcl/

This is pgintcl/README, describing pgintcl: A PostgreSQL interface in Tcl
Last updated for pgintcl-3.5.1 on 2017-11-12
The project home page is: http://sourceforge.net/projects/pgintcl/
-----------------------------------------------------------------------------

俯瞰 OVERVIEW:

これは純-tclのPostgreSQL データベース管理大系への対話譜である｡ 8.0 版の PostgreSQL 迄に付随されていた 元祖 libpgtcl の殆ど全ての命令を実装している､更に多くの拡張を有している｡ただ､完全にｔｃｌで書かれ､その為､機械語翻訳も､特別のOSや追加の付属品も必要ない｡
This is a pure-Tcl interface to the PostgreSQL Database Management System.
It implements almost all the commands in the original libpgtcl, the Tcl
interface which was bundled with PostgreSQL until release 8.0, plus it
has many extensions.  But it is written entirely in Tcl, so does not
require compilation for a specific platform or any additional components.

小生は､もともと､対話譜(libpgtcl)が利用できないか､機械語化に問題が窮めて多い状況のOS上で Tcl/Tk データベース依頼者を使えるようにこれを書いた｡
I originally wrote this to be able to use Tcl/Tk database clients on
platforms where the PostgreSQL client library (libpq) and the Tcl interface
(libpgtcl) were not available, or were too much trouble to build.

pgin.tcl は Tcl 二進データを使い､内部の PostgreSQL 前面/背面 通信規則を使って､直接に PostgreSQL 中央集中処理系に通話する TCP 受け口機能を使う｡従って､ pgin.tcl は libpq-基礎の応用譜故にその詳細から保護されていると謂うより､通信規則に依存する｡pgin.tcl のこの版は､ PostgreSQL 通信規則の第3版を使う､且つ PostgreSQL-7.4 以上の中央集中処理系とのみ通信する｡
pgin.tcl uses the Tcl binary data and TCP socket features to communicate
directly with a PostgreSQL database server, using the internal PostgreSQL
frontend/backend protocol. Therefore, pgin.tcl is dependent on the
protocol, rather than being protected from its details as are libpq-based
applications. This version of pgin.tcl uses version 3 of the PostgreSQL
protocol, and only communicates with PostgreSQL-7.4 and higher servers.

pgin.tcl は又､ pgtcl-ng と高度の互換性がある､それは pgtcl 対話譜の"次世代"libpq-基礎の実装である｡pgtcl-ng は次の番地にある
  http://sourceforge.net/projects/pgtclng/
両方の対話譜は同じ試験揃いが使われる｡
pgin.tcl is also highly compatible with pgtcl-ng, the "Next Generation"
libpq-based implementation of the pgtcl interface. pgtcl-ng can be found at
  http://sourceforge.net/projects/pgtclng/
The same test suite is used to verify both interfaces.

pgin.tcl の第三版はユニコード文字揃い符号化と復号化を追加した｡それはSQL_ASCIIと同じく LATIN1 と UTF8 データベース符号化が試験された｡(註意､ SQL_ASCII 符号化データベースは7-ビットascii文字のみを意味する｡データが非ascii文字を含む場合､ SQL_ASCII データベースを使用してはならない｡) それは､どのPostgreSQL データベース符号化でも動くが､使用者の試験は奨励されている｡(以前のpgin.tcl 第2版は文字揃い符号か処理は含まれてない｡適切な SQL_ASCII 符号化データベースとのみ稼働できる｡)
Version 3 of pgin.tcl added Unicode character set encoding and decoding.
It was tested with LATIN1 and UTF8 database encodings, as well as
SQL_ASCII. (Note SQL_ASCII encoded databases are meant for 7-bit ASCII
characters only. Do not use SQL_ASCII databases if your data includes
non-ASCII characters.) It should work with any PostgreSQL database
encoding, but user testing is encouraged. (The previous version 2 of
pgin.tcl does not include character set encoding handling. It may only work
properly with SQL_ASCII encoded databases.)


要求事項: REQUIREMENTS:

   Tcl-8.4.4 かそれ以上のこと､最新の 8.6.x が推奨される｡
   PostgreSQL-9.1.x 又はそれ以上のこと､最新の 10.x か 9.6.x が推奨される｡

   最新の試験には次のものが使われた:
      データベース中央集中処理系: PostgreSQL-9.6.6 と 10.1｡
      Windows XP 依頼者: ActiveState Tcl-8.6.0 と Tcl-8.5.14
      Linux 依頼者: Tcl-8.6.5.
   (古い PostgreSQL と Tcl の古い版も動くかもしれないが最早や試験はしてない)
   Pgin.tcl は Tclの全てのOS上で利用できるが､試験は32-ビットのWindowsとLinuxに限定された｡

REQUIREMENTS:

   Tcl-8.4.4 or higher, with the latest 8.6.x recommended.
   PostgreSQL-9.1.x or higher, with the latest 10.x or 9.6.x recommended.

   Recent testing used the following:
      Database server: PostgreSQL-9.6.6 and 10.1.
      Client on Linux: Tcl-8.6.5.
      Client on Windows XP: ActiveState Tcl-8.6.0 and Tcl-8.5.14
   (Older version of PostgreSQL and Tcl might work but are no longer tested.)
   Pgin.tcl should be usable on all platforms with Tcl, however current
   testing is limited to 32-bit Linux and Windows platforms.

内容 CONTENTS:

  説明 Documentation:
         註意: zip ファイル配布梱包のみ､この説明書ファイルは ".txt" 拡張子とMS-DOS 行末を有する
    README ........... このファイル
    COPYING .......... pgin.tcl (BSD/Berkeley Open Source)に関する免許情報
    NEWS ............. 配布情報と変更の履歴
    REFERENCE ........  pgin.tcl を使う算譜記述者への参考説明文
    INTERNALS ........ pgin.tcl の内容に拘る幾つかの情報
  Documentation:
         Note: In the zip file distribution only, these documentation
         files have a ".txt" extension and MS-DOS line endings.
    README ........... This file
    COPYING .......... The license for pgin.tcl (BSD/Berkeley Open Source)
    NEWS ............. Release information and change history
    REFERENCE ........ Reference documentation for programmers using pgin.tcl
    INTERNALS ........ Some information about the innards of pgin.tcl

  記述譜 Scripts:

    pgin.tcl ......... 対話機能の完全な実装｡
    pkgIndex.tcl ..... 梱包用 index ファイル
    tkpsql.tcl ....... 対話的データベース問合せに関するwish記述譜の用例
    pgin.tcl ......... This is the complete implementation of the interface.
    pkgIndex.tcl ..... Package index file
    tkpsql.tcl ....... An example wish script for interactive database querying


特性 FEATURES:

+ 完全にtclで記述されている
+ Written completely in Tcl 
+ 全ての標準(元祖､束縛) libpgtcl 命令を仮想的に実装する
+ Implements virtually all the standard (original, bundled) libpgtcl commands
+ 巨大対象操作命令に対応する
+ Supports large object manipulation commands
+ 聴取/通知 を運営する
+ Supports listen/notify
+  NOTIFY に伴うデータ本体を渡すことに対応(PostgreSQL-9.0.0 とそれ以降)
+ Supports passing a payload with NOTIFY (PostgreSQL-9.0.0 and higher)
+ 通告把持子の置換えに対応
+ Supports replacing the notice handler
+ pg_execute 命令を運営する
+ Supports pg_execute command
+ PostgreSQL MD5 challenge/response 認証を運営する
+ Supports PostgreSQL MD5 challenge/response authentication
+ pg_result -cmdTuples は INSERTや DELETE や UPDATE により影響されたリストの個数を返す
+ pg_result -cmdTuples returns the number of tuples affected by an 
  INSERT, DELETE, or UPDATE
+ NULL データベース値を空文字列から区別することに対応｡
+ Supports distinguishing NULL database values from empty strings
+ pg_result -list と pg_result -llist を実装する
+ Implements pg_result -list, and pg_result -llist
+ 除外文字列 escaping strings に関する pg_escape_string と pg_quote と pg_escape_literal [新規: 3.5.0] と  pg_escape_identifier 新規: 3.5.0] を実装する｡
+ Implements pg_escape_string, pg_quote, pg_escape_literal [New: 3.5.0], and
  pg_escape_identifier [New: 3.5.0] for escaping strings.
+ 準備された宣言文を実行する: 送付及び受取り二進データを含む pg_exec_prepared ｡
+ Execute prepared statements with: pg_exec_prepared, including sending
  and receiving un-escaped binary data
+ PostgreSQL の媒介変数をえるには: pg_parameter_status
+ Get PostgreSQL parameters with: pg_parameter_status
+ 一括処理の状態を得るには: pg_transaction_status
+ Get transaction status with: pg_transaction_status
+ 拡張不都合伝言文を利用するには: pg_result -errorField
 これは pgtcl との両立性の為に pg_result -error に適用する様[2.2.0版で]拡張された｡3.5.0 版では更に欄が追加された｡
+ Access expanded error message fields with: pg_result -errorField
  This was extended [at 2.2.0] to also apply to pg_result -error
  for compatibility with pgtcl. More fields were added at 3.5.0.
+ 拡張属性の利用は: pg_result -lxAttributes
+ Access extended attribute information with: pg_result -lxAttributes
+  pg_result -cmdStatus により命令の状態を得る [新規: 2.0.1版]
+ Get command status tag with pg_result -cmdStatus [New: 2.0.1]
+ 解析と実行の分離には: pg_exec_params, 二進符号で安全 [新規: 2.0.1版]
+ Separate parse and execute with: pg_exec_params, binary safe [New: 2.1.0]
+ バイトの 除外/非除外 には: pg_escape_bytea, pg_unescape_bytea [新規: 2.2.0]
+ Escape/unescape bytea with: pg_escape_bytea, pg_unescape_bytea [New: 2.2.0]
+ 問合せ結果の辞書としての戻りは pg_result -dict [新規: 3.3.0]
+ Return query results as a dictionary with pg_result -dict [New: 3.3.0]
+ 通知内での背景処理の処理識別子(PID) の利用 [新規: 3.4.0]
+ Access to process ID (PID) of backend and in notifications [New: 3.4.0]
+ postgresql:// URI 経由 又は keyword/value Tcl リスト経由の接続 [新規: 3.5.0]
+ Connect via postgresql:// URI, or keyword/value Tcl list [New: 3.5.0]
+ 巨大対象内の 64-bit 偏移への対応 [新規: 3.5.0, PostgreSQL-9.3.0 版以上]
+ Supports 64-bit offsets in large objects [New: 3.5.0, PostgreSQL-9.3.0 and up]


制限と違い  LIMITATIONS and DIFFERENCES:

+ pg_connect は dbname 名と区別された､主人名､玄関口の様な､指示項目を使う古い手段に対応しない｡
+ pg_connect does not support the older method using a separate dbname plus
  options for host, port.
+ $HOME/.pgpass 暗証番号ファイルを運営しない｡
+ Does not support $HOME/.pgpass password file.
+ 3版背景系とのみ対話する (PostgreSQL 7.4 以上が必要)｡
+ Only talks to v3 backend (PostgreSQL 7.4 or higher required).
+ TCP/IP 受け口のみ使う(主人は既定で localhostになり､PostgreSQL 中央集中処理系は TCP 受け口を聴かねばならぬ)｡Unixなんちゃらは対応してない｡
+ Uses only TCP/IP sockets (defaults host to localhost, PostgreSQL server must
  be listening on TCP sockets). Does not support Unix Domain sockets.
+ 通告伝言文は問合せ結果を読む間のみ受取る｡
+ Notification messages are only received while reading query results.
+ 出来栄えは見劣りする､特に大量のデータ受取り時には｡
+ Performance isn't great, especially when retrieving large amounts of data.
+ 接続把持子と結果把持子の値は他の実装と異なる形式であるが､誰もこれには依存しない｡
+ The values of connection handles and result handles are of a different
  format than other implementations, but nobody should be relying on these.
+ pg_on_connection_loss はない(PostgreSQL 7.3 では)｡
+ No pg_on_connection_loss (New at PostgreSQL 7.3).
+ 非同期問合せ命令はない(pgtcl と pgtcl-ng に見出された)
+ No asynchronous query commands (found in pgtcl and pgtcl-ng).
+  COPY FROM/TO に関する運営は他の対話譜の版とは非互換である -  pg_copy_read と pg_copy_write を使わねばならず､接続把持子への直接入出力はない｡
+ Support for COPY FROM/TO is not compatible with other versions of the
  interface - must use pg_copy_read and pg_copy_write, no I/O directly to
  connection handle.
+ 他の pgtcl と同様に128個迄の活動結果構造を保有できる(漏洩が捕捉できるので)｡pgin.tcl は限界はなく､結果構造の漏洩も捕捉しない｡
+ With other pgtcl's, you can have up to 128 active result structures (so leaks
  can be caught). pgin.tcl has no limits and will not catch result structure
  leaks.
+ [2.1.0 版で追加]  pg_select や pg_execute の記述譜本体内で"return -code N" (茲で N>4)を使用してはならない､理由は高価が十分定義されてないから｡安全に使用できるのは return と break と continue と error のみ(直接でも､ -code 経由でも)｡
+ [Added at 2.1.0] Do not use "return -code N" (for N>4) in the script
  body for pg_select or pg_execute, because the effect is not well defined.
  You can safely use return, break, continue, and error (either directly
  or via return -code).
+ [2.2.0 版で追加] pg_escape_bytea (及び､稀拡張の pg_unescape_bytea)は全く遅い｡大きなバイト列対象への使用は推奨しない;代りに二進の準備された問合せを使用すべき｡  
+ [Added at 2.2.0] pg_escape_bytea (and pg_unescape_bytea, to a
  lesser extent) is quite slow. Using it on large bytea objects is not
  recommended; you should use binary prepared queries instead.
+ [3.1.0 版で追加] 文字列とバイト列の除外担当譜に $conn 引数を使おうが使うまいが､pgin.tcl は符号化対応の除外を使わない｡
+ [Added at 3.1.0] Whether or not you use the $conn argument to the string
  and bytea escape routines, pgin.tcl does not use encoding-aware escaping.
  This also applies to pg_escape_literal and pg_escape_identifier [at 3.5.0].
+ [3.2.0版で追加] pg_escape_bytea always は返された結果の中で､常に古い '除外' 符号化を使い､ 'hex' 符号化を使うことはない｡
+ [Added at 3.2.0] pg_escape_bytea always uses the older 'escape' encoding
  in the returned result, never the newer 'hex' encoding.


RELEASE ISSUES:

第 3.5.0 版で最近の Libpq 函数に基づく新しい命令が追加されたが､その内の幾つかは PostgreSQL-9.3.0 中央集中処理系に接続された時のみ動く｡これには､64ビット巨大対象偏倚命令と不都合欄符号を含む｡本版開始と共に"pg_result -error" と "pg_result -errorField" 内の不都合符号が大文字小文字を区別することになった｡これは PostgreSQL-9.3.0 の変更に必要な互換性変更である｡
Version 3.5.0 added new commands based on more recent Libpq functions, but
some of these will only work when connected to a PostgreSQL-9.3.0 server. This
includes 64-bit Large Object offset commands, and new error field codes.
Also starting with this release, single-character error field codes in
"pg_result -error" and "pg_result -errorField" are now case sensitive. This
incompatible change was necessary due to changes in PostgreSQL-9.3.0.

第 3.4.0 版とそれ以降は pg_listen 内の把持子通告名称が以前の版と異なる｡もし pg_listen 内で大文字小文字混合の名前を使っている場合､非互換の問題の結果になり得る｡第 3.4.0 版開始と共にpgintcl は経路名称が二重引用である限りは名前を畳み込む｡これは pgtcl-ngの振舞と合致する｡更なる詳細はREFERENCE ファイルと pgintcl 瑕疵#2(old #3410251)を参照されたい｡
Versions 3.4.0 and up handle notification names (also known as channel
names) in pg_listen differently from previous versions. This can result in
compatibility problems if you used mixed-case names in pg_listen. Starting
with version 3.4.0, pgintcl folds the channel name to lower case unless it
is in double quotes. This now matches the behavior of pgtcl-ng. See the
REFERENCE file and pgintcl bug #2 (old #3410251) for more details.

第3.3.0版以降ではtcl8.4以降を要求する｡以前の版はtcl8.3かそれ以降であることを確認していたが､実際は tcl8.3で試験されてない｡
Versions 3.3.0 and up require Tcl 8.4 or higher. Previous versions checked
for Tcl 8.3 or higher, but were not actually tested with Tcl 8.3.

第3.2.0版以降は､もし､ SQL NOTIFY 命令内に非零の正味データが提供されると､正味データ引数を通知聴取処理子手続き函数に渡す｡更なる情報と互換性問題については NEWS ファイルを参照されたい｡

Versions 3.2.0 and up pass a payload argument to a notification listener handler
procedure if a non-empty payload was provided in the SQL NOTIFY command.
See the NEWS file for more information and compatibility issues.

第3版は､ REFERENCE ファイルの記述に従って文字データを符号変換と反符号変換する｡又､接続が中央集中処理系に開かれた時､PostgreSQL 假引数を CLIENT_ENCODING からユニコードに設定する｡これは Pgtcl と pgtcl-ng の振舞と同じである｡これは PostgreSQL にユニコードのデータ( UTF-8として符号化される)が送られ､受取られることを伝える｡
Version 3 does encoding and decoding of character data, as described in
the REFERENCE file. It also sets the PostgreSQL parameter
CLIENT_ENCODING to UNICODE when a connection is opened to the server.  This
is the same behavior as Pgtcl and pgtcl-ng.  This informs PostgreSQL that
UNICODE data (encoded as UTF-8) will be sent and received.

註意すべきは､ pgin.tcl を使う依頼者応用譜はtclが運営しているどの符号系も有し得る｡tclは依頼者符号系とユニコードの間を変換する､又､PostgreSQL中央集中処理系はユニコードとデータベース符号の間を変換する｡これはデータベース符号系が SQL_ASCII 以外を仮定している｡
Note that the client application using pgin.tcl can have any encoding
which Tcl supports. Tcl converts between the client encoding and Unicode,
and the PostgreSQL server converts between Unicode and the database
encoding. This assumes the database encoding is other than SQL_ASCII.

            * * * 警告 CAUTION * * *

 SQL_ASCII 符号系で生成された  PostgreSQL 基礎データ内の文字や平文欄内に非ascii文字を保存してはならない｡SQL_ASCII 符号系は PostgreSQL に対し如何に翻訳すべきかについて何の情報も提供しない､そこで､中央集中処理系は翻訳することができない｡ pgin.tcl を含む tcl対話機能を使う応用譜は､基礎データ内の貯蔵について UTF-8 を使って､この様な文字を符号化することになる､しかし､ PostgreSQL は SQL_ASCII 符号設定に基づくべきことを知らない｡結果は､他の応用譜から正確にデータを利用することが不可能になる｡基礎データ生成の時は常に正しい符号系をしようされたい:譬えば LATIN1 や Unicodeを｡
  Do not store non-ASCII characters in character or text fields in a
  PostgreSQL database which was created with encoding SQL_ASCII.
  The SQL_ASCII encoding provides no information to PostgreSQL on
  how to translate characters, so the server will be unable to
  translate.  Applications using a Tcl interface, including
  pgin.tcl, will encode these characters using UTF-8 for storage
  in the database, but PostgreSQL will not know it due to the
  SQL_ASCII encoding setting.  The result is that it may be
  impossible to access the data correctly from other applications.
  Always use the correct encoding when creating a database: for
  example, LATIN1 or Unicode.

  Pgin.tcl-2.x 及びそれ以前の版は全く､ユニコードとの変換をしないし､依頼者符号系をせっていすることもない｡古い版はどの様な基礎データ符号系内の非ascii文字もできない｡
  Pgin.tcl-2.x and older do not convert to/from Unicode and do not set
  client_encoding at all. These older versions may not work with non-ASCII
  characters in any database encoding.

現在の処､ Pgin.tcl は使用者名や､基礎データ名や､暗証番号のような接続文字列假引数を記録しない｡これらの欄の非ascii文字は多分働かない｡
  At this time, Pgin.tcl does not recode the connection string parameters
  such as Username, Database Name, or Password. Non-ASCII characters in these
  fields will probably not work.


Older Information:
この版と 2.0.0 以前の版との間には幾らかの非互換性がある:
  + pg_parameter_status は最早や全ての假引数を一度に取得できない､
  + "pg_configure nulls" 指示項目は最早や利用できない｡空文字列から
      NULL を識別する唯一の方法は pg_result -getNull を使うことのみ｡
  + 巨大対象呼出不都合の扱いは変更した｡
  +  COPY FROM/TO は pg_copy_read/pg_copy_write を使わねばならない; 
    接続からcopy data の読み書きはできない｡
応用譜がもし変更された振舞に従っていると変更せねばならない｡更なる情報は NEWS ファイルを参照されたい｡
There are some incompatibilities between this release and pre-2.0.0 releases:
  + pg_parameter_status can no longer fetch all parameters at once;
  + "pg_configure nulls" option is no longer available. The only way
    to distinguish NULL from empty string now is with pg_result -getNull.
  + Changes in large object call error handling.
  + COPY FROM/TO must use pg_copy_read/pg_copy_write; you cannot read or
    write copy data from the connection.
You will have to change your application if it relies on behavior which
changed.  See the file NEWS for more information.


装着と使用  INSTALLATION AND USAGE:

搭載用記述譜は無い｡応用譜が利用できる何処かに単に記述譜 "pgin.tcl" を複写するだけである｡応用譜内の頂上水準に､ "source .../pgin.tcl"を挿入されたい､ここで ... はディレクトーである｡これは頂上水準で実行されねばならない､そこで手続き函数内では必要なら下に示す様に uplevel をわれたい｡
There is no install script. Just copy the script "pgin.tcl" anywhere your
application can access it.  In your application, insert "source .../pgin.tcl"
at the top level, where ... is the directory. This must be run at the top
level, so if you need it inside a proc use uplevel as shown below.

任意で､ pgin.tcl を Tcl 梱包として装着し使うこともできる｡ pgin.tcl と pkgIndex.tcl を  Tcl 装着梱包外部函数基本ディレクトリー(又は､ auto_path を拡張もできる:tcl説明書の 'package' と 'pkgMkIndex' を参照されたい)の副ディレクトー内に複写するべき｡次に応用譜で次の要領で積込みできる:
           package require pgintcl

Optionally, you can install and use pgin.tcl as a Tcl package. You should
copy pgin.tcl and pkgIndex.tcl into a sub-directory of your Tcl
installation package library root directory (or you can extend auto_path:
see the Tcl documentation for the 'package' and 'pkgMkIndex' commands).
Then your application can load pgin.tcl with the following:
           package require pgintcl

含まれている "tkpsql.tcl" 記述譜を試してみることができる｡これは基礎データ問合せを発行する為の､簡単な対話的な使用者画像対話譜であり､漠然と Sybase ASA "dbisql" に似ている｡[??]開始するには **ix 体系の上で"wish tkpsql.tcl"と打鍵する; Windows の下ではExplorer からその上で二重軽叩すればよい｡それぞれの問合せの後 F1 を押すか Run 釦を軽叩する必要がある｡
You can use the included "tkpsql.tcl" script to try it out.  This is a
simple interactive GUI program to issue database queries, vaguely like the
Sybase ASA "dbisql" program.  On **ix systems, type "wish tkpsql.tcl" to
start it; under Windows you should be able to double click on it from
Explorer. You need to press F1 or click on the Run button after each query.
