|
ActiveTcl User Guide
|
|
|
- NAME
- fconfigure - Set and get options on a channel
- SYNOPSIS
- fconfigure channelId
- fconfigure channelId name
- fconfigure channelId name value ?name
value ...?
- DESCRIPTION
- -blocking
boolean
- -buffering
newValue
- -buffersize
newSize
- -encoding
name
- -eofchar
char
- -eofchar
{inChar outChar}
- -translation
mode
- -translation
{inMode outMode}
- auto
- binary
- cr
- crlf
- lf
- STANDARD
CHANNELS
- SERIAL PORT
CONFIGURATION OPTIONS
- -mode
baud,parity,data,stop
- -handshake
type
- -queue
- -timeout
msec
- -ttycontrol
{signal boolean signal boolean ...}
- -ttystatus
- -xchar
{xonChar xoffChar}
- -pollinterval
msec
- -sysbuffer
inSize
- -sysbuffer
{inSize outSize}
- -lasterror
- SERIAL PORT
SIGNALS
- TXD(output)
- RXD(input)
- RTS(output)
- CTS(input)
- DTR(output)
- DSR(input)
- DCD(input)
- RI(input)
- BREAK
- ERROR CODES (Windows
only)
- RXOVER:
- TXFULL
- OVERRUN
- RXPARITY
- FRAME
- BREAK
- SEE ALSO
- KEYWORDS
fconfigure - Set and get options on a channel
fconfigure channelId
fconfigure channelId name
fconfigure channelId name value ?name value
...?
The fconfigure command sets and retrieves options for
channels.
ChannelId identifies the channel for which to set or
query an option and must refer to an open channel such as a Tcl
standard channel (stdin, stdout, or stderr),
the return value from an invocation of open or socket, or the result of a channel
creation command provided by a Tcl extension.
If no name or value arguments are supplied, the
command returns a list containing alternating option names and
values for the channel. If name is supplied but no
value then the command returns the current value of the
given option. If one or more pairs of name and value
are supplied, the command sets each of the named options to the
corresponding value; in this case the return value is an
empty string.
The options described below are supported for all channels. In
addition, each channel type may add options that only it supports.
See the manual entry for the command that creates each type of
channels for the options that that specific type of channel
supports. For example, see the manual entry for the socket command for its additional
options.
- -blocking boolean
- The -blocking option determines whether I/O operations
on the channel can cause the process to block indefinitely. The
value of the option must be a proper boolean value. Channels are
normally in blocking mode; if a channel is placed into nonblocking
mode it will affect the operation of the gets, read, puts, flush, and close commands; see the documentation
for those commands for details. For nonblocking mode to work
correctly, the application must be using the Tcl event loop (e.g.
by calling Tcl_DoOneEvent or invoking the
vwait command).
- -buffering newValue
- If newValue is full then the I/O system will
buffer output until its internal buffer is full or until the flush command is invoked. If
newValue is line, then the I/O system will
automatically flush output for the channel whenever a newline
character is output. If newValue is none, the I/O
system will flush automatically after every output operation. The
default is for -buffering to be set to full except
for channels that connect to terminal-like devices; for these
channels the initial setting is line. Additionally,
stdin and stdout are initially set to line,
and stderr is set to none.
- -buffersize newSize
- Newvalue must be an integer; its value is used to set
the size of buffers, in bytes, subsequently allocated for this
channel to store input or output. Newvalue must be between
ten and one million, allowing buffers of ten to one million bytes
in size.
- -encoding name
- This option is used to specify the encoding of the channel, so
that the data can be converted to and from Unicode for use in Tcl.
For instance, in order for Tcl to read characters from a Japanese
file in shiftjis and properly process and display the
contents, the encoding would be set to shiftjis. Thereafter,
when reading from the channel, the bytes in the Japanese file would
be converted to Unicode as they are read. Writing is also supported
- as Tcl strings are written to the channel they will automatically
be converted to the specified encoding on output.
If a file contains pure binary data (for instance, a JPEG
image), the encoding for the channel should be configured to be
binary. Tcl will then
assign no interpretation to the data in the file and simply read or
write raw bytes. The Tcl binary command can be used to
manipulate this byte-oriented data.
The default encoding for newly opened channels is the same
platform- and locale-dependent system encoding used for interfacing
with the operating system.
- -eofchar char
- -eofchar {inChar
outChar}
- This option supports DOS file systems that use Control-z (\x1a)
as an end of file marker. If char is not an empty string,
then this character signals end-of-file when it is encountered
during input. For output, the end-of-file character is output when
the channel is closed. If char is the empty string, then
there is no special end of file character marker. For read-write
channels, a two-element list specifies the end of file marker for
input and output, respectively. As a convenience, when setting the
end-of-file character for a read-write channel you can specify a
single value that will apply to both reading and writing. When
querying the end-of-file character of a read-write channel, a
two-element list will always be returned. The default value for
-eofchar is the empty string in all cases except for files
under Windows. In that case the -eofchar is Control-z (\x1a)
for reading and the empty string for writing.
- -translation mode
- -translation {inMode
outMode}
- In Tcl scripts the end of a line is always represented using a
single newline character (\n). However, in actual files and devices
the end of a line may be represented differently on different
platforms, or even for different devices on the same platform. For
example, under UNIX newlines are used in files, whereas
carriage-return-linefeed sequences are normally used in network
connections. On input (i.e., with gets and read) the Tcl I/O system automatically
translates the external end-of-line representation into newline
characters. Upon output (i.e., with puts), the I/O system translates
newlines to the external end-of-line representation. The default
translation mode, auto, handles all the common cases
automatically, but the -translation option provides explicit
control over the end of line translations.
The value associated with -translation is a single item
for read-only and write-only channels. The value is a two-element
list for read-write channels; the read translation mode is the
first element of the list, and the write translation mode is the
second element. As a convenience, when setting the translation mode
for a read-write channel you can specify a single value that will
apply to both reading and writing. When querying the translation
mode of a read-write channel, a two-element list will always be
returned. The following values are currently supported:
- auto
- As the input translation mode, auto treats any of
newline (lf), carriage return (cr), or carriage
return followed by a newline (crlf) as the end of line
representation. The end of line representation can even change from
line-to-line, and all cases are translated to a newline. As the
output translation mode, auto chooses a platform specific
representation; for sockets on all platforms Tcl chooses
crlf, for all Unix flavors, it chooses lf, for the
Macintosh platform it chooses cr and for the various flavors
of Windows it chooses crlf. The default setting for
-translation is auto for both input and output.
- binary
- No end-of-line translations are performed. This is nearly
identical to lf mode, except that in addition binary mode also sets the
end-of-file character to the empty string (which disables it) and
sets the encoding to binary (which disables encoding
filtering). See the description of -eofchar and
-encoding for more information.
- cr
- The end of a line in the underlying file or device is
represented by a single carriage return character. As the input
translation mode, cr mode converts carriage returns to
newline characters. As the output translation mode, cr mode
translates newline characters to carriage returns. This mode is
typically used on Macintosh platforms.
- crlf
- The end of a line in the underlying file or device is
represented by a carriage return character followed by a linefeed
character. As the input translation mode, crlf mode converts
carriage-return-linefeed sequences to newline characters. As the
output translation mode, crlf mode translates newline
characters to carriage-return-linefeed sequences. This mode is
typically used on Windows platforms and for network
connections.
- lf
- The end of a line in the underlying file or device is
represented by a single newline (linefeed) character. In this mode
no translations occur during either input or output. This mode is
typically used on UNIX platforms.
The Tcl standard channels (stdin, stdout, and
stderr) can be configured through this command like every
other channel opened by the Tcl library. Beyond the standard
options described above they will also support any special option
according to their current type. If, for example, a Tcl application
is started by the inet super-server common on Unix system
its Tcl standard channels will be sockets and thus support the
socket options.
If channelId refers to a serial port, then the following
additional configuration options are available on Windows and Unix
systems with a POSIX serial interface:
- -mode
baud,parity,data,stop
- This option is a set of 4 comma-separated values: the baud
rate, parity, number of data bits, and number of stop bits for this
serial port. The baud rate is a simple integer that
specifies the connection speed. Parity is one of the
following letters: n, o, e, m,
s; respectively signifying the parity options of ``none'',
``odd'', ``even'', ``mark'', or ``space''. Data is the
number of data bits and should be an integer from 5 to 8, while
stop is the number of stop bits and should be the integer 1
or 2.
- -handshake type
- (Windows and Unix). This option is used to setup automatic
handshake control. Note that not all handshake types maybe
supported by your operating system. The type parameter is
case-independent. If type is none then any handshake
is switched off. rtscts activates hardware handshake.
Hardware handshake signals are described below. For software
handshake xonxoff the handshake characters can be redefined
with -xchar. An additional hardware handshake dtrdsr
is available only under Windows. There is no default handshake
configuration, the initial value depends on your operating system
settings. The -handshake option cannot be queried.
- -queue
- (Windows and Unix). The -queue option can only be
queried. It returns a list of two integers representing the current
number of bytes in the input and output queue respectively.
- -timeout msec
- (Windows and Unix). This option is used to set the timeout for
blocking read operations. It specifies the maximum interval between
the reception of two bytes in milliseconds. For Unix systems the
granularity is 100 milliseconds. The -timeout option does
not affect write operations or nonblocking reads. This option
cannot be queried.
- -ttycontrol {signal boolean signal
boolean ...}
- (Windows and Unix). This option is used to setup the handshake
output lines (see below) permanently or to send a BREAK over the
serial line. The signal names are case-independent. {RTS
1 DTR 0} sets the RTS output to high and the DTR output to low.
The BREAK condition (see below) is enabled and disabled with
{BREAK 1} and {BREAK 0} respectively. It's not a good
idea to change the RTS (or DTR) signal with active
hardware handshake rtscts (or dtrdsr). The result is
unpredictable. The -ttycontrol option cannot be
queried.
- -ttystatus
- (Windows and Unix). The -ttystatus option can only be
queried. It returns the current modem status and handshake input
signals (see below). The result is a list of signal,value pairs
with a fixed order, e.g. {CTS 1 DSR 0 RING 1 DCD 0}. The
signal names are returned upper case.
- -xchar {xonChar xoffChar}
- (Windows and Unix). This option is used to query or change the
software handshake characters. Normally the operating system
default should be DC1 (0x11) and DC3 (0x13) representing the ASCII
standard XON and XOFF characters.
- -pollinterval msec
- (Windows only). This option is used to set the maximum time
between polling for fileevents. This affects the time interval
between checking for events throughout the Tcl interpreter (the
smallest value always wins). Use this option only if you want to
poll the serial port more or less often than 10 msec (the
default).
- -sysbuffer inSize
- -sysbuffer {inSize
outSize}
- (Windows only). This option is used to change the size of
Windows system buffers for a serial channel. Especially at higher
communication rates the default input buffer size of 4096 bytes can
overrun for latent systems. The first form specifies the input
buffer size, in the second form both input and output buffers are
defined.
- -lasterror
- (Windows only). This option is query only. In case of a serial
communication error, read
or puts returns a general
Tcl file I/O error. fconfigure -lasterror can be called to
get a list of error details. See below for an explanation of the
various error codes.
RS-232 is the most commonly used standard electrical interface
for serial communications. A negative voltage (-3V..-12V) define a
mark (on=1) bit and a positive voltage (+3..+12V) define a space
(off=0) bit (RS-232C). The following signals are specified for
incoming and outgoing data, status lines and handshaking. Here we
are using the terms workstation for your computer and
modem for the external device, because some signal names
(DCD, RI) come from modems. Of course your external device may use
these signal lines for other purposes.
- TXD(output)
- Transmitted Data: Outgoing serial data.
- RXD(input)
- Received Data:Incoming serial data.
- RTS(output)
- Request To Send: This hardware handshake line informs
the modem that your workstation is ready to receive data. Your
workstation may automatically reset this signal to indicate that
the input buffer is full.
- CTS(input)
- Clear To Send: The complement to RTS. Indicates that the
modem is ready to receive data.
- DTR(output)
- Data Terminal Ready: This signal tells the modem that
the workstation is ready to establish a link. DTR is often enabled
automatically whenever a serial port is opened.
- DSR(input)
- Data Set Ready: The complement to DTR. Tells the
workstation that the modem is ready to establish a link.
- DCD(input)
- Data Carrier Detect: This line becomes active when a
modem detects a "Carrier" signal.
- RI(input)
- Ring Indicator: Goes active when the modem detects an
incoming call.
- BREAK
- A BREAK condition is not a hardware signal line, but a logical
zero on the TXD or RXD lines for a long period of time, usually 250
to 500 milliseconds. Normally a receive or transmit data signal
stays at the mark (on=1) voltage until the next character is
transferred. A BREAK is sometimes used to reset the communications
line or change the operating mode of communications hardware.
A lot of different errors may occur during serial read
operations or during event polling in background. The external
device may have been switched off, the data lines may be noisy,
system buffers may overrun or your mode settings may be wrong.
That's why a reliable software should always catch serial read operations. In
cases of an error Tcl returns a general file I/O error. Then
fconfigure -lasterror may help to locate the problem. The
following error codes may be returned.
- RXOVER:
- Windows input buffer overrun. The data comes faster than your
scripts reads it or your system is overloaded. Use fconfigure
-sysbuffer to avoid a temporary bottleneck and/or make your
script faster.
- TXFULL
- Windows output buffer overrun. Complement to RXOVER. This error
should practically not happen, because Tcl cares about the output
buffer status.
- OVERRUN
- UART buffer overrun (hardware) with data lost. The data comes
faster than the system driver receives it. Check your advanced
serial port settings to enable the FIFO (16550) buffer and/or setup
a lower(1) interrupt threshold value.
- RXPARITY
- A parity error has been detected by your UART. Wrong parity
settings with fconfigure -mode or a noisy data line (RXD)
may cause this error.
- FRAME
- A stop-bit error has been detected by your UART. Wrong mode
settings with fconfigure -mode or a noisy data line (RXD)
may cause this error.
- BREAK
- A BREAK condition has been detected by your UART (see
above).
close, flush, gets, puts, read, socket, Tcl_StandardChannels
blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation, encoding, filter, byte array, binary
Copyright © 1995-1996 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.