## Tcl9.0.3/Tk9.0.3 Documentation > Tcl Commands > refchan

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    refchan — 応答通信路のAPI操作子命令 Command handler API for channels implemented in Tcl code
  構文 SYNOPSIS
  説明 DESCRIPTION
  必須の副命令 MANDATORY SUBCOMMANDS
    cmdPrefix initialize channel mode
    cmdPrefix finalize channel
    cmdPrefix watch channel eventspec
  任意指定の副命令 OPTIONAL SUBCOMMANDS
    cmdPrefix read channel count
    cmdPrefix write channel data
    cmdPrefix seek channel offset base
      start
      current
      end
    cmdPrefix configure channel option value
    cmdPrefix cget channel option
    cmdPrefix cgetall channel
    cmdPrefix blocking channel mode
    cmdPrefix truncate channel length
  註意 NOTES
  EXAMPLE
  SEE ALSO
  KEYWORDS

### NAME

refchan — 応答通信路のAPI操作子命令 Command handler API for channels implemented in Tcl code

### 構文 SYNOPSIS

chan create mode cmdPrefix
cmdPrefix blocking channel mode
cmdPrefix cget channel option
cmdPrefix cgetall channel
cmdPrefix configure channel option value
cmdPrefix finalize channel
cmdPrefix initialize channel mode
cmdPrefix read channel count
cmdPrefix seek channel offset base
cmdPrefix watch channel eventspec
cmdPrefix write channel data

### 説明 DESCRIPTION

応答通信路の為のTcl水準の操作子は､何といっても副命令群を伴う命令である(用語としての集団といえる､と言うのも恰も namespace ensemble create に生成されたような命令である故に､但し､如何なる意味でも応答通信路の為の､操作子の実現は namespace ensemble と結ばている訳ではないが; APIを運用している oo::class を如何に構成するかは､下の EXAMPLE を参照されたい)｡註意 cmdPrefix は chan create への呼び出し中に何が指定されても､又､複数の引数を構成しても; 前置される処で多数の語に拡張されることになる｡ 　 The Tcl-level handler for a reflected channel has to be a command with subcommands (termed an ensemble, as it is a command such as that created by namespace ensemble create, though the implementation of handlers for reflected channel is not tied to namespace ensembles in any way; see EXAMPLE below for how to build an oo::class that supports the API). Note that cmdPrefix is whatever was specified in the call to chan create, and may consist of multiple arguments; this will be expanded to multiple words in place of the prefix.

全ての可能な副命令の操作子は initialize と finalize と watch の運用が必須である｡他の副命令の運用は必須ではない｡ Of all the possible subcommands, the handler must support initialize, finalize, and watch. Support for the other subcommands is optional.

#### 必須の副命令 MANDATORY SUBCOMMANDS

cmdPrefix initialize channel mode
  この副命令の起動は､この cmdPrefix が指定された新しい channel を受取る為の､最初の呼出しになる｡通信路とその状態の軌跡を保持するのに必要な如何なる内部データ構造の構築もこの副命令の担当である｡ An invocation of this subcommand will be the first call the cmdPrefix will receive for the specified new channel. It is the responsibility of this subcommand to set up any internal data structures required to keep track of the channel and its state.

  この手順の戻り値は何といっても cmdPrefix によって運用された全ての副命令の名前を含むリストである｡これは､更に､応答通信路用のAPIのどの版がこの命令処理子によって使用されるかTcl核心に伝える｡ The return value of the method has to be a list containing the names of all subcommands supported by the cmdPrefix. This also tells the Tcl core which version of the API for reflected channels is used by this command handler.

  この手段により発信されたどの不具合も通信路の生成を中断し､通信路は何も作成されなくなる｡発信された不具合は chan create に発信された不具合として現れることになる｡不具合以外の如何なる例外も(譬えば､ break 等)不具合(に変換され)として取扱われる｡ Any error thrown by the method will abort the creation of the channel and no channel will be created. The thrown error will appear as error thrown by chan create. Any exception other than an error (e.g., break, etc.) is treated as (and converted to) an error.

  註意: もし､通信路の生成がこの失敗の故に､中断されたら､finalize 副命令が呼ばれることはない｡ Note: If the creation of the channel was aborted due to failures here, then the finalize subcommand will not be called.

  mode 引数は､把持子に､この通信路が読込みか､書き出しか､両用かの､どの為に開かれたかを告げる｡それは､ read か write のいずれかの文字列を含むリストである｡そのリストは空かもしれないが､通常は少なく共一つの要素を含む｡ The mode argument tells the handler whether the channel was opened for reading, writing, or both. It is a list containing any of the strings read or write. The list may be empty, but will usually contain at least one element.

  この副命令は､選択された様式が cmdPrefix によって運用されてなければ､不具合を発信せねばならない｡ The subcommand must throw an error if the chosen mode is not supported by the cmdPrefix.

cmdPrefix finalize channel
  この副命令の起動は､この cmdPrefix が指定された channel を受取る､最後の呼出しになる｡それは､Tcl核心によって保持された通信路のデータ構造が破壊される直前に生成される｡この命令処理子は channel にこれ以上決して接見してはならない｡この副命令の呼出しに伴って､この通信路に割付けられた､全ての原資は消去されねばならない｡ An invocation of this subcommand will be the last call the cmdPrefix will receive for the specified channel. It will be generated just before the destruction of the data structures of the channel held by the Tcl core. The command handler must not access the channel anymore in no way. Upon this subcommand being called, any internal resources allocated to this channel must be cleaned up.

  この副命令の戻り値は無視される｡ The return value of this subcommand is ignored.

  もしこの副命令が不具合を発行すると､この不都合を発信して貰う為に､その起動により惹き起こされる命令(普通には chan close)が出現する｡なんであれ不具合以外の例外(譬えば break 等)は不具合(に変換され)として扱われる｡ If the subcommand throws an error the command which caused its invocation (usually chan close) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as (and converted to) an error.

  この副命令はinitialize 中に通信路形成が中断されると起動されない(上述参照)｡ This subcommand is not invoked if the creation of the channel was aborted during initialize (See above).

cmdPrefix watch channel eventspec
  この副命令は､指定された channel が､eventspec に列挙された行事に興味を有す旨 cmdPrefix に通知する｡この引数はどの read と write も含むリストである｡リストは空でもよく､それは通信路が如何なる行事の通知も受けたくないとの合図である｡その状況では､処理子は行事の生成は全く不可能にする｡ This subcommand notifies the cmdPrefix that the specified channel is interested in the events listed in the eventspec. This argument is a list containing any of read and write. The list may be empty, which signals that the channel does not wish to be notified of any events. In that situation, the handler should disable event generation completely.

  警告: この副命令のどの様な返り値も全て無視される｡これは副命令や､ break や､ continue や､誂えた返り値 によって発信された全ての不都合が含まれている｡ Warning: Any return value of the subcommand is ignored. This includes all errors thrown by the subcommand, break, continue, and custom return codes.

  この副命令は､ chan postevent と相互に干渉する｡ watch への最後の呼出しの中で列挙されていない行事を告げようとすると､不具合を発信する為に chan postevent を惹き起こす｡ This subcommand interacts with chan postevent. Trying to post an event which was not listed in the last call to watch will cause chan postevent to throw an error.

#### 任意指定の副命令 OPTIONAL SUBCOMMANDS

cmdPrefix read channel count
  この任意指定の副命令は､使用者が通信路 channel からデータを要求する時に呼ばれる｡ count は幾らのバイトの個数が必要かを指定する｡もし､副命令が運営されていなければ､この命令に扱われる通信路から読むことは不可能である｡ This optional subcommand is called when the user requests data from the channel channel. count specifies how many bytes have been requested. If the subcommand is not supported then it is not possible to read from the channel handled by the command.

  この副命令の返り値は要求されたデータ bytes と看做される｡もし､返ったデータが要求より多くのバイトを含んでいると､不都合が合図され､後々 read を遂行した命令(通常は gets か read)から発信される｡しかし､要求より少ないバイトは許容される｡ The return value of this subcommand is taken as the requested data bytes. If the returned data contains more bytes than requested, an error will be signaled and later thrown by the command which performed the read (usually gets or read). However, returning fewer bytes than requested is acceptable.

  註意すべきは､何も返らない(0バイト)は EOF が通信路に届いたとの高階層への通知である｡ EOF が届いてないにも拘らず通信路のデータがないことをすぐさま通知する為には不都合 "EAGAIN"を発信する必要がある､即ち､この様に Note that returning nothing (0 bytes) is a signal to the higher layers that EOF has been reached on the channel. To signal that the channel is out of data right now, but has not yet reached EOF, it is necessary to throw the error "EAGAIN", i.e. to either

      return -code error EAGAIN

  若しくは or

      error EAGAIN

  更に加えて､何であれ､負の整数番号を有する不都合は､高い階層に､C言語水準の変数"errno"にこの数の絶対値を設定させ､系の不都合を通知することを引起す｡しかし､註意すべきであるが､この様な不都合番号とその意味の間の厳密な対応はOSに依存する｡ For extensibility any error whose value is a negative integer number will cause the higher layers to set the C-level variable "errno" to the absolute value of this number, signaling a system error. However, note that the exact mapping between these error numbers and their meanings is operating system dependent.

  譬えば､ Linux では､両者は For example, while on Linux both

      return -code error -11

  及び and

      error -11

  は､文字列"EAGAIN"を使った可読性がある上述の例と等価であるが､ BSD ではそうではなく､ -35 と等価である｡ are equivalent to the examples above, using the more readable string "EAGAIN", this is not true for BSD, where the equivalent number is -35.

  しかし､記号文字列は系を超えて同じであり､内部的に正しい番号に変換される｡不都合番号以外の値はこのような記号への対応を有していない｡ The symbolic string however is the same across systems, and internally translated to the correct number. No other error value has such a mapping to a symbolic string.

  もし､それ以外の何かの不都合が発信されると､この不都合を発信して貰う為に､その起動により惹き起こされる命令(通常は gets か read)が現れる｡不都合の範囲を越えた例外は何であれ(譬えば break 等)､不都合として取り扱われ､また不都合に変換される｡ If the subcommand throws any other error, the command which caused its invocation (usually gets, or read) will appear to have thrown this error. Any exception beyond error, (e.g., break, etc.) is treated as and converted to an error.

cmdPrefix write channel data
  この任意附加の副命令は､使用者が通信路 channel にデータを書込む時に呼ばれる｡ data 引数は､文字ではなくバイトを含む｡この通信路に関する､どの様な型の翻訳(EOL 文字番号体系)も､既に､構成設定されている｡もし､この副命令が運営されていなければ､この命令に扱われる通信路に書くことは不可能である｡ This optional subcommand is called when the user writes data to the channel channel. The data argument contains bytes, not characters. Any type of transformation (EOL, encoding) configured for the channel has already been applied at this point. If this subcommand is not supported then it is not possible to write to the channel handled by the command.

  この副命令の返り値は通信路によって書かれたバイトの個数と看做される｡なんであれ数でないと不具合の合図を引起すことになり､その合図は､後々､書込みを実行させた命令によって発生させられる｡負数は書込み失敗をほのめかす｡処理子に与えたバイト個数より大きな返り値や零は禁止され､Tcl 核心に不都合を告げる原因になる｡ The return value of the subcommand is taken as the number of bytes written by the channel. Anything non-numeric will cause an error to be signaled and later thrown by the command which performed the write. A negative value implies that the write failed. Returning a value greater than the number of bytes given to the handler, or zero, is forbidden and will cause the Tcl core to throw an error.

  今現在､通信路が書込み用にデータを受取れないことを合図するには､不都合 "EAGAIN"を発信する必要がある､即ち､この様に To signal that the channel is not able to accept data for writing right now, it is necessary to throw the error "EAGAIN", i.e. to either

      return -code error EAGAIN

  or

      error EAGAIN

  更に加えて､何であれ､負の整数番号を有する不都合は､高い階層に､C言語水準の変数"errno"にこの数の絶対値を設定させ､系の不都合を通知することを引起す｡しかし､註意すべきであるが､この様な不都合番号とその意味の間の厳密な対応はOSに依存する｡ For extensibility any error whose value is a negative integer number will cause the higher layers to set the C-level variable "errno" to the absolute value of this number, signaling a system error. However, note that the exact mapping between these error numbers and their meanings is operating system dependent.

  譬えば､ Linux では､両者は For example, while on Linux both

      return -code error -11

  及び and

      error -11

  は､文字列"EAGAIN"を使った可読性がある上述の例と等価であるが､ BSD ではそうではなく､ -35 と等価である｡ are equivalent to the examples above, using the more readable string "EAGAIN", this is not true for BSD, where the equivalent number is -35.

  しかし､記号文字列は系を超えて同じであり､内部的に正しい番号に変換される｡不都合番号以外の値はこのような記号への対応を有していない｡ The symbolic string however is the same across systems, and internally translated to the correct number. No other error value has such a mapping to a symbolic string.

  もし､それ以外の不都合が発信されると､この不都合を発信して貰う為に､その起動により惹き起こされる命令(通常は puts)が現れる｡不都合を超えた例外は何であれ(譬えば break 等)､不都合として取り扱われ､また不都合に変換される｡ If the subcommand throws any other error the command which caused its invocation (usually puts) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as and converted to an error.

cmdPrefix seek channel offset base
  この追加的な副命令は､通信路 channel に対する chan seek と chan tell 要求の取扱を担当する｡もし､運営されていなければ､この通信路に対して捜索することは不可能である｡ This optional subcommand is responsible for the handling of chan seek and chan tell requests on the channel channel. If it is not supported then seeking will not be possible for the channel.

  base 引数は組込みの chan seek の引数と同じである､即ち: The base argument is the same as the equivalent argument of the builtin chan seek, namely:

  start
    捜索は通信路の先頭を始点とする｡ Seeking is relative to the beginning of the channel.

  current
    捜索は現在の捜索点を始点とする｡ Seeking is relative to the current seek position.

  end
    捜索は通信路の終端を始点とする｡ Seeking is relative to the end of the channel.

  この offset は前方又は後方へ捜索すべきバイト数を指示する整数である｡正数は前方へ､負数は後方への捜索を意味する｡通信路は限定された捜索のみを提供することがある｡譬えば､受け口は前方を捜索できるが､後方はできない｡ The offset is an integer number specifying the amount of bytes to seek forward or backward. A positive number should seek forward, and a negative number should seek backward. A channel may provide only limited seeking. For example sockets can seek forward, but not backward.

  この副命令の戻り値は､最初から勘定した､通信路の(新しい)場所として扱われる｡この値は零以上の整数の筈である｡もしこの副命令が不具合を発行すると､この不具合を発信して貰う為に､その起動により惹き起こされる命令(普通には chan seek か chan tell)が出現する｡なんであれ不具合error以外の例外(譬えば break 等)は不都合として取り扱われ､また不都合に変換される｡ The return value of the subcommand is taken as the (new) location of the channel, counted from the start. This has to be an integer number greater than or equal to zero. If the subcommand throws an error the command which caused its invocation (usually chan seek, or chan tell) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as and converted to an error.

  引数の offset/base の組合せとしての 0/現在 は chan tell 要求を合図する､即ち､現在の位置に対する相対位置を捜索するのではなく､現在位置に等しい位置を新しい位置とさせて､それが返される The offset/base combination of 0/current signals a chan tell request, i.e., seek nothing relative to the current location, making the new location identical to the current one, which is then returned.

cmdPrefix configure channel option value
  この副命令は､通信路 channel の型固有の指示項目の設定を担当する｡ option 引数が書込むための指示項目を指し示し､ value 引数が指示項目に設定する値を指し示す｡ This optional subcommand is for setting the type-specific options of channel channel. The option argument indicates the option to be written, and the value argument indicates the value to set the option to.

  この副命令は､一回につき一つより多くの指示項目の更新をすることはない; これは､ Tcl 通信路核心の中に実装された振舞いである｡ This subcommand will never try to update more than one option at a time; that is behavior implemented in the Tcl channel core.

  この副命令の返り値は無視される｡ The return value of the subcommand is ignored.

  もしこの副命令が不都合を発信すると､この不都合を発信して貰う為に(再)構成設定､又は問合せを遂行する命令(普通には fconfigure か chan configure )が出現する｡ error の範囲を超えるどの様な例外(譬えば break 等)も処理され不都合に変換される｡ If the subcommand throws an error the command which performed the (re)configuration or query (usually fconfigure or chan configure) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as and converted to an error.

cmdPrefix cget channel option
  この副命令は､通信路 channel に対して､型固有の指示項目の一つを読むときに使用する｡もし､この副命令が運営されていると､副命令 cgetall が同じく､運営されていなければならない｡ This optional subcommand is used when reading a single type-specific option of channel channel. If this subcommand is supported then the subcommand cgetall must be supported as well.

  この副命令はoption で指定した値を返す｡ The subcommand should return the value of the specified option.

  もしこの副命令が不都合を発信すると､この不都合を発信して貰う為に(再)構成設定､又は問合せを遂行する命令(普通には fconfigure か chan configure )が出現する｡ error の範囲を超えるどの様な例外(譬えば break 等)も処理され不都合に変換される｡ If the subcommand throws an error, the command which performed the (re)configuration or query (usually fconfigure or chan configure) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as and converted to an error.

cmdPrefix cgetall channel
  この副命令は､通信路 channel の全ての型固有の指示項目を読むときに使用する｡もし､この副命令が運営されていると､副命令 cget も同じく､運営されていなければならない｡ This optional subcommand is used for reading all type-specific options of channel channel. If this subcommand is supported then the subcommand cget has to be supported as well.

  この副命令は全ての指定項目とその値のリストを返す｡このリストは偶数個の要素を有する筈である｡ The subcommand should return a list of all options and their values. This list must have an even number of elements.

  もしこの副命令が不都合を発信すると､この不都合を発信して貰う為に(再)構成設定､又は問合せを遂行する命令(普通にはfconfigure か chan configure )が出現する｡ error の範囲を超えるどの様な例外(譬えば break 等)も処理され不都合に変換される｡ If the subcommand throws an error the command which performed the (re)configuration or query (usually fconfigure or chan configure) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as and converted to an error.

cmdPrefix blocking channel mode
  この追加的副命令は通信路 channel を同期方法への変更を取り扱う｡この mode 引数は論理値である｡真値は経路が同期方法に設定されていることを意味し､偽値はこの経路が非同期であることを意味する｡ This optional subcommand handles changes to the blocking mode of the channel channel. The mode is a boolean flag. A true value means that the channel has to be set to blocking, and a false value means that the channel should be non-blocking.

  この副命令の返り値は無視される｡ The return value of the subcommand is ignored.

  もしこの副命令が不都合を発行すると､この不都合を発信して貰う為に､その起動により惹き起こされる命令(普通には fconfigure か chan configure )が出現する｡ error の範囲を超えるどの様な例外(譬えば break 等)も処理され不都合に変換される｡ If the subcommand throws an error the command which caused its invocation (usually fconfigure or chan configure) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as and converted to an error.

cmdPrefix truncate channel length
  この任意追加の副命令は､ 通信路channelに関する根本的データの長さの変更を取り扱う｡ その長さは､lengthに設定される｡ This optional subcommand handles changing the length of the underlying data stream for the channel channel. Its length gets set to length.

  もしこの副命令が不都合を発行すると､この不都合を発信して貰う為に､その起動により惹き起こされる命令(普通にはchan truncate )が出現する｡ error の範囲を超えるどの様な例外(譬えば break 等)も処理され不都合に変換される｡ If the subcommand throws an error the command which caused its invocation (usually chan truncate) will appear to have thrown this error. Any exception beyond error (e.g., break, etc.) is treated as and converted to an error.

### 註意 NOTES

Tcl の C言語対話機能内で定義された通信路内で運用されている幾つかの機能は､ Tcl 水準に反映されている通信路には利用できない｡ Some of the functions supported in channels defined in Tcl's C interface are not available to channels reflected to the Tcl level.

函数Tcl_DriverGetHandleProc は運営されていない; 即ち､応答通信路はOS固有の処理子を有していない｡ The function Tcl_DriverGetHandleProc is not supported; i.e., reflected channels do not have OS specific handles.

函数 Tcl_DriverHandlerProc は運営されていない｡この駆動函数は棚に重ねられた通信路のみに適している､即ち､変換である｡応答通信路は常に基本通信路であり変換ではない｡ The function Tcl_DriverHandlerProc is not supported. This driver function is relevant only for stacked channels, i.e., transformations. Reflected channels are always base channels, not transformations.

函数 Tcl_DriverFlushProc は運営されていない｡その理由は､現在のTcl の一般の入出力層はこの函数をどこにも全く使用しない｡従って､Tcl水準の運営は意味がない｡これは将来変わりうる(此処で定義されたAPIの拡張とその版番号の変化をつうじて)将来何時か函数が使用できるかもしれない｡ The function Tcl_DriverFlushProc is not supported. This is because the current generic I/O layer of Tcl does not use this function anywhere at all. Therefore support at the Tcl level makes no sense either. This may be altered in the future (through extending the API defined here and changing its version number) should the function be used at some time in the future.

### EXAMPLE

これは文字列から読む通信路を如何に生成するかを例証する｡ This demonstrates how to make a channel that reads from a string.

    oo::class create stringchan {
        variable data pos
        constructor {string {encoding {}}} {
            if {$encoding eq ""} {set encoding [encoding system]}
            set data [encoding convertto $encoding $string]
            set pos 0
        }

        method initialize {ch mode} {
            return "initialize finalize watch read seek"
        }
        method finalize {ch} {
            my destroy
        }
        method watch {ch events} {
            # これは必ず必要であるが､何も行事を送らないので
            # ここでは無視する
            # Must be present but we ignore it because we do not
            # post any events
        }

        # 読出し可能の通信路に存在しなければならない
        # Must be present on a readable channel
        method read {ch count} {
            set d [string range $data $pos [expr {$pos+$count-1}]]
            incr pos [string length $d]
            return $d
        }

        # この手段は任意附加であるが下の様に便利である
        # This method is optional, but useful for the example below
        method seek {ch offset base} {
            switch $base {
                start {
                    set pos $offset
                }
                current {
                    incr pos $offset
                }
                end {
                    set pos [string length $data]
                    incr pos $offset
                }
            }
            if {$pos < 0} {
                set pos 0
            } elseif {$pos > [string length $data]} {
                set pos [string length $data]
            }
            return $pos
        }
    }

    # 今や現実値を生成する
    # Now we create an instance...
    set string "The quick brown fox jumps over the lazy dog.\n"
    set ch [chan create read [stringchan new $string]]

    puts [gets $ch];   # 全文字列の印刷	# Prints the whole string

    seek $ch -5 end;
    puts [read $ch];   # 最後の語の印刷	# Prints just the last word

### SEE ALSO

chan, transchan

### KEYWORDS

API, channel, ensemble, prefix, reflection
Copyright © 2006 Andreas Kupries <andreas_kupries(at)users.sourceforge.net>