pg_listen
Prev | 4.5.Notification and Notice Processing Commands | Next

## pg_listen

pg_listen — 非同期通知伝言文の呼出を設定する Set a callback for asynchronous notification messages

## 構文 Synopsis

    pg_listen ?-pid? conn notifyName ?callbackCommand?

## 説明 Description

`pg_listen` は PostgreSQL 中央集中処理系からの非同期通知伝言文を聴く要求を生成､変更､予約解消する｡`callbackCommand` 假引数によって､要求が設立され､又は既に実在する要求の命令文字列が置換される｡ `callbackCommand` 假引数なしでは､先行する要求が予約解消される｡ `pg_listen` creates, changes, or cancels a request to listen for asynchronous notification messages from the PostgreSQL server. With a `callbackCommand` parameter, the request is established, or the command string of an already existing request is replaced. With no `callbackCommand` parameter, a prior request is canceled.

`pg_listen`要求が確立された後､指定された命令文字列は､何時であれ中央集中処理系から届いた与えられた名前を通知伝言文が担って､指定された命令文字列が実行される｡これはどの PostgreSQL 依頼応用譜が､その名前を参照する通知命令を発行する時も生じる｡命令文字列はTcl 暇巡回から実行される｡これはTkで書かれ応用譜の通常の暇状態である｡非Tcl 対話機能内では､入力されるべき暇巡回を惹き起こす､更新や､ vwait を実行することができる｡ After a `pg_listen` request is established, the specified command string is executed whenever a notification message bearing the given name arrives from the server. This occurs when any PostgreSQL client application issues a NOTIFY command referencing that name. The command string is executed from the Tcl idle loop. That is the normal idle state of an application written with Tk. In non-Tk Tcl shells, you can execute `update` or `vwait` to cause the idle loop to be entered.

`pg_listen` を使用している時は直接 SQL 宣言文の LISTEN や UNLISTEN を起動しないほうが好い｡ pgtcl は これらの宣言文を使用者に発行することに気を付けている｡しかし､自分自身に通知伝言文を送りたい場合は､ `pg_exec` かその関連命令を使って SQL NOTIFY を起動されたい｡ You should not invoke the SQL statements LISTEN or UNLISTEN directly when using `pg_listen`. pgtcl takes care of issuing those statements for you. But if you want to send a notification message yourself, invoke the SQL NOTIFY statement using `pg_exec` or a related command.

## 引数 Arguments

`-pid`

  もし存在する場合は `callbackCommand` が追加の假引数を与られることを指し示し､それは通知を送られる依頼者の背景処理認識番号(PID)である｡ If present, indicates that the `callbackCommand` should be given an additional parameter which is the backend process ID (PID) of the client which sent the notification.

`conn`

  通知や予約解消の為に聞くべき接続体の把持子｡ The handle of the connection on which to listen for notifications or cancel listening.

`notifyName`

  聴取を開始又は中止すべき通知条件の名前｡PostgreSQL-9.0の開始と伴に､ PostgreSQL取扱い説明書によって通信路として参照される｡これは SQL 名の如く扱われる: ??小文字???? 引用符で包まれない限り(下の註意参照)｡ The name of the notification condition to start or stop listening to. Starting with PostgreSQL-9.0, this is referred to as a channel by the PostgreSQL documentation. This is treated like an SQL name: downcased, unless enclosed in double quotes. (See notes below)

`callbackCommand`

  もし存在すると､合致通知が到達した時実行すべき命令文字列｡ない場合､合致通知の為の､既存の文字列が予約解消される｡命令文字列は Tcl 手続き函数の名前であるべきで(多分､指定された導入引数を伴う)､それは､もし `-pid`指示項目が使われ､且つ､通知本体の為の通知任意追加の引数を受容れると､ PID を通資するための引数を受容れる｡詳細は下の註意参照｡ If present, provides the command string to execute when a matching notification arrives. If absent, an existing command string for matching notification is canceled. The command string should be the name of a Tcl procedure (possibly with leading arguments specified), which accepts an argument for the notifying PID if the `-pid` option was used, and also accepts an optional additional argument for the notification payload. See the notes below for details.

## 返り値 Return Value

なし｡もし不都合が生じるとTcl不都合が発せられる｡ Nothing. Throws a Tcl error if an error occurs.

## 註意 Notes

`notifyName` (又は通信路)は引用されない限り大文字小文字区別なしと看做されるが､互換性の為 SQL は SQL NOTIFY 内で通信路の名前を扱う｡即ち､pg_listen は､二重引用で括られない限り､名前を小文字に変換する｡もし二重引用の中であれば(それは､tcl解析譜に渡すことに抵抗せねばならない､譬えば {"MyChannel"}の如く)引用符号は剥がされ且つ名前は文字の大きさが畳まれない｡ The `notifyName` (or channel) is considered case insensitive unless quoted, for compatibility with way SQL treats the channel name in the SQL NOTIFY command. That is, `pg_listen` converts the name to lower case, unless it is enclosed in double quotes. If it is in double quotes (which must be protected to get past the Tcl parser, for example as `{"MyChannel"}`) then the quote marks are stripped and the name is not case folded.

註意: pgtcl-ng は常に notifyName 上では大文字込みを畳むか引用の剥ぎ取りをした｡pgintcl は､しかし乍ら､3.3.0版以降迄は､notifyName 假引数上では､どのような大文字小文字畳も引用剥がしもしなかった｡最大限の互換性の為に､ notifyName に関して且つ SQL NOTIFY内では､引用で括らない小文字を使え｡ Note: pgtcl-ng always did case folding or quote stripping on notifyName. pgintcl, however, did not do any case folding or quote stripping on the notifyName parameter until after version 3.3.0. For maximum compatibility, use only unquoted lower case values for notifyName and in SQL NOTIFY.

PostgreSQL-9.0 の開始と伴に､通告伝言文は､ PostgreSQL 取扱い説明書によるデータ本体として参照する｡データ本体を伴う通告文を送るべきsqlの例は: 　 Starting with PostgreSQL-9.0, a notification message can include a payload string. An example of SQL to send a notification with payload is:

    NOTIFY my_channel, 'the payload'

その条の為の､聴取者を設定する為のｔｃｌ命令はこの様に見える: The Tcl commands to set up a listener for that condition might look like this:

    proc my_listener {{payload ""}} {
        ....
    }
    pg_listen $db_conn my_channel my_listener

手続き函数は､単一の記述譜引数として pg_listen 命令内で固定の引数を伴い､データ本体の前に追加の引数を受容れる為に定義され得る｡ 　 The procedure can be defined to accept additional arguments before the payload, with the fixed arguments supplied in the pg_listen command as a single script argument.

    proc my_listener2 {command_arg {payload ""}} {
        ....
    }
    pg_listen $db_conn my_channel [list my_listener2 Command1]

もし NOTIFY 伝言文がデータ本体文字列を含んでいると､ Pgtcl はこれを聴取者命令命令への追加の引数として含むことになる｡もし NOTIFY 伝言文がデータ本体文字列を含んでない場合､又はデータ本体として空文字列を含むか､9.0.0 PostgreSQL より前の版のデータベースに接続した場合､聴取者命令に追加の引数は供給されない｡これは使用者が聴取者命令に追加引数を有する必要性と､引数を要求されない理由である｡ If the NOTIFY message includes a payload string, Pgtcl will include this as an additional argument to the listener command. If the NOTIFY message does not include a payload string, or includes an empty string as a payload, or you are connected to a pre-9.0.0 PostgreSQL database, then no additional argument will be supplied to the listener command. This is why you need to have an optional argument to your listener command, not a required argument.

データ本体文字列を通告命令に渡すことはpgtclng-1.8.0 and pgintcl-3.2.0で追加され､ PostgreSQL-9.0.0 又はそれ以上のデータベース中央集中処理系に接続された時のみ働く｡ Passing a payload string to the notification command was added in pgtclng-1.8.0 and pgintcl-3.2.0, and only works when connected to a PostgreSQL-9.0.0 or higher database server.

### 警告 Caution

Pgtcl 対話譜の以前の版の為の符号命令は､全ての聴取者呼戻し命令への追加の引数を含むよう更新されるべきである｡もし､追加の引数を有するように聴取者呼戻し命令を更新せず､且つ､通告qsl内にデータ本体を決して含まない場合､使用者の記述譜はどのような問題も生じない｡但し､註意すべきは､データベースに接続できる誰かが通告を送り得る(もし､彼らが､ pg_listen 命令内に使われる通信路名を知っていると)､且つ､それがデータ本体を含み得る｡もし､使用者の聴取者呼戻しがデータ本体引数を期待しない場合､もしこの様なデータ本体引数を受取らない場合､背景不都合(それは記述譜を終わらせるかも終わらせないかもしれない)が発せられる｡ Code written for previous versions of the Pgtcl interfaces should be updated to include an optional argument to all listener callback commands. If you do not update your listener callback command to have an optional argument, and you never include a payload in the notification SQL, your script will not have any problems. However, note that anyone who can connect to the database can send a notification (if they know the channel name used in the pg_listen command), and they can include a payload. If your listener callback does not expect a payload argument, it will throw a background error (which may or may not terminate the script) if it receives such a payload argument.

`-pid` 指示項目は pgtclng-2.0.0 and pgintcl-3.4.0で追加された｡それは便利かもしれない､譬えば､？？？ The `-pid` option was added in pgtclng-2.0.0 and pgintcl-3.4.0. It may be useful, for example, to compare with the connection's own backend process id (see pg_backend_pid to ignore notifications coming from the client itself. See the example below.

## 用例 Example

この部分的用例内で､通知把持子は PID 引数を受容れ､且つ､依頼者自身からの通知を無視する為に､依頼者自身の背景 PID と比較する｡ In this partial example, a notification handler accepts a PID argument and compares it with the client's own backend PID to ignore notifications from the client itself.

    proc my_handler {backend_pid notifier_pid {payload ""}} {
        # Ignore notifications from ourself:
        if {$backend_pid == $notifier_pid} return
        ... continue processing ...
    }
    # 通告 PID 引数を伴い聴取者を確立する｡
    # 命令引数として我々の背景PIDを含む｡
    # Establish a listener, with notifying PID argument.
    # Include our backend PID as a command argument.
    pg_listen -pid $db_conn my_channel [list my_handler [pg_backend_pid $db_conn]]

Prev | Up | Next
4.5.Notification and Notice Processing Commands | Home | pg_on_connection_loss