Generic Tcl Server (GENTLE)

NOTE: gentle was written back in 1994, when core Tcl didn't include networking, an event loop, and multiple interpreters. Those features are now available in a platform-independent form in the core Tcl - see the socket, vwait, and interp commands - so gentle's reasons for existence are not as compelling as they once were. In other words, most of what I programmed for gentle in C can now be done in Tcl itself and you might consider sticking with the standard Tcl shell (tclsh), dynamically loading any extensions you write.

Overview

gentle (GENeric TcL sErver) is a network server program that provides each network client with its own Tcl interpreter. When gentle receives a command from a client, it passes the command to that client's interpreter for execution. A client Write message command allows the interpreter to send responses back to the client. gentle can also be run in tty mode (i.e., you type commands in at the command line).

Some background documents:

"Generic Card Debugger" (sometime in 1994)

presents my original inspiration for gentle. Hardware engineers in our department use hand-crafted software to exercise and monitor their in-house-designed VLSI ASICs mounted on VME cards. This memo describes a script-programmable card debugger, which was the inspiration for gentle.

"C'est Moi!" (February 16, 1995)

shows how an early version of gentle was coupled with a Tk-based GUI, moi, for the purpose of monitoring and controlling our VxWorks systems. I subsequently developed a Motif equivalent to moi, called plum, which resulted in a reworking of the display classes so that the same status page definitions could be used by both the Tk and Motif versions of the GUI.

Invocation

UNIX invocation:

    % gentle [-daemon] [-debug] [-file pathname]
             [-initial command] [-listen port]
             [-null] [-tty] [-verify level] [-vperror]

VxWorks invocation:

    -> sp gentle, "[-debug] [-file pathname]
                   [-initial command] [-listen port]
                   [-null] [-tty] [-verify level] [-vperror]"

where

-daemon

causes gentle to become a daemon process.

-debug

enables debug output (written to stdout).

-file pathname

specifies a Tcl script file that is to be loaded and executed when a client is created. This option is just shorthand for "-initial 'source pathname'".

-initial command

specifies a Tcl command that is to be executed when a client is first created.

-listen port

specifies a network server port (i.e., service name or port number) at which gentle will listen for connection requests from clients. Multiple server ports can be monitored for connection requests by repeating this option for each different port.

-null

creates a null client, i.e., a gentle client for which there is no external client. The initial Tcl command (see the -file and -initial options) executed by the null client should do whatever is necessary for the client to persist. This client should not execute any of the gentle client commands.

-tty

enables the monitoring of stdin. Tcl commands entered on standard input are read and executed. By default, gentle does not monitor standard input.

-verify level

enables malloc(3) heap verification. If level is 0 (the default), malloc(3) behaves normally. If level is 1, the system checks the arguments passed to malloc(3) and the heap blocks immediately affected by each call. If level is 2, the system verifies the integrity of the entire heap on each call to malloc(3). Running at level 2 is useful for detecting inadvertent corruption of your allocated memory. This option is only supported if gentle is linked with my libmalloc library or, under SunOS, if gentle is linked with the system's /usr/lib/debug/malloc.o file; see the SunOS documentation on malloc(3) for more information.

-vperror

turns aperror() message output on. aperror() messages are low-level error messages generated by libgpl functions; normally, they are disabled. If enabled, the messages are output to stderr.

Networking Commands

The following commands are used to establish network connections:

tcpCall server?@host? ?-connect command? ?-error command? ?-input command? ?-nowait? ?-timeout seconds?

establishes a client connection with server on host. The tcpCall command returns a handle that can be used in subsequent "connection operation" commands (e.g., for reading from and writing to the connection).
The -timeout option allows you to limit how long gentle will block while attempting to establish the connection. If the -nowait option is specified, gentle does not block on the connection attempt. In this case, the connection handle returned by tcpCall should not be used until the connection is finally established (which you'll know if you specify a -connect command).
Asynchronous input is appended to the -input command and the resulting command is executed. In the absence of the -input option, the input is directly interpreted as a Tcl command.

tcpListen server ?-connect command? ?-error command?

creates a network port at which the application listens for connection requests from clients. The tcpListen command returns a handle that can be used in subsequent "listener Answer" commands.

The following operations can be applied to a listening port (listener is the handle returned by a "tcpListen" command):

listener Answer ?-error command? ?-input command?

waits for and answers the next connection request received on the listener's port. The Answer command returns a handle that can be used in subsequent "connection operation" commands (e.g., for reading from and writing to the connection).

listener Close

closes the listening port.

listener Poll

returns 1 if a connection request is waiting to be answered and zero otherwise.

The following operations can be applied to a network connection (connection is the handle returned by a "tcpCall" or "listener Answer" command):

connection Close

closes the network connection.

connection Peer

returns the name (i.e., the Internet address) of the host at the other end of the network connection.

connection Poll

returns 1 if the network connection has data waiting to be read and zero otherwise.

connection Read ?-timeout seconds?

reads the next line of input and returns it as the command's result string. If no timeout is specified, the application waits until the next message is received.

connection Read buffer ?-timeout seconds?

reads data from the network connection into a memory buffer; the amount of data read is determined by the size of the memory buffer. If no timeout is specified, the application waits until the next message is received. buffer, the handle returned by a "buffer" command, is returned as the Read command's result string. This form of the "connection Read" command is useful for receiving binary data over a network connection.

connection Write buffer ?-nowait ?-complete command??

writes the contents of a memory buffer to the network connection. buffer is the handle returned by a "buffer" command. This form of the "connection Write" command is useful for sending binary data through a network connection. The -nowait option queues up the data for writing in the background; command, if specified, is executed when the output is complete.

connection Write string ?-nowait ?-complete command??

writes the specified string to the network connection. The -nowait option queues up the data for writing in the background; command, if specified, is executed when the output is complete.

XDR Networking Commands

The XDR networking commands are similar to the basic networking commands except that the message text is sent as an XDR string embedded in an XDR network record. The following commands are used to establish "XNET" connections:

xnetCall server?@host? ?-connect command? ?-error command? ?-input command? ?-nowait? ?-timeout seconds?

establishes a client connection with server on host. The xnetCall command returns a handle that can be used in subsequent "connection operation" commands (e.g., for reading from and writing to the connection).
The -timeout option allows you to limit how long gentle will block while attempting to establish the connection. If the -nowait option is specified, gentle does not block on the connection attempt. In this case, the connection handle returned by xnetCall should not be used until the connection is finally established (which you'll know if you specify a -connect command).
Asynchronous input is appended to the -input command and the resulting command is executed. In the absence of the -input option, the input is directly interpreted as a Tcl command.

xnetListen server ?-connect command? ?-error command?

creates a network port at which the application listens for connection requests from clients. The xnetListen command returns a handle that can be used in subsequent "listener Answer" commands.

The following operations can be applied to a listening port (listener is the handle returned by a "xnetListen" command):

listener Answer ?-error command? ?-input command?

waits for and answers the next connection request received on the listener's port. The Answer command returns a handle that can be used in subsequent "connection operation" commands (e.g., for reading from and writing to the connection).

listener Close

closes the listening port.

listener Poll

returns 1 if a connection request is waiting to be answered and zero otherwise.

The following operations can be applied to a network connection (connection is the handle returned by a "xnetCall" or "listener Answer" command):

connection Close

closes the network connection.

connection Peer

returns the name (i.e., the Internet address) of the host at the other end of the network connection.

connection Poll

returns 1 if the network connection has data waiting to be read and zero otherwise.

connection Read ?-timeout seconds?

reads the next line of input and returns it as the command's result string. If no timeout is specified, the application waits until the next message is received.

connection Write string

writes the specified string to the network connection.

HTTP Commands

The HTTP commands allow you to set up a Tcl-programmable HTTP server. (Since the networking commands can be used to talk to an HTTP server, gentle has no HTTP client-specific commands.) A gentle interpreter can listen for connection requests from HTTP clients (e.g., WWW browsers) at one or more network ports using one or more instances of the following command:

httpListen server ?-connect command? ?-error command?

creates a network port at which the application listens for connection requests from HTTP clients. The httpListen command returns a handle that can be used in subsequent "listener operation" commands. The -connect command is executed when a connection request is received; this command, if specified, should directly or indirectly execute a "listener Answer" command to actually accept the connection request.

The following operations can be applied to an HTTP listening port (listener is the handle returned by an "httpListen" command):

listener Answer ?-error command? ?-input command?

waits for and answers the next connection request received on the listener's port. The Answer command returns a handle that can be used in subsequent "client operation" commands. The -input option is currently unsupported. An incoming HTTP request is assembled, line-by-line, into a Tcl command:

"method URI version client header body"

where method is GET, HEAD, or POST; client is the client handle returned by "listener Answer"; header is a list of the lines in the message header; and body is the body (text only) of the message. Once assembled, the command is executed. As you can see, you need to define GET, HEAD, and POST commands, most likely as Tcl procedures; for example:

proc GET {URI version client header body} {
    ...
}

listener Close

closes the listening port.

listener Poll

returns 1 if a connection request is waiting to be answered and zero otherwise.

The following operations can be applied to a connection with an HTTP client (client is the handle returned by a "listener Answer" command):

client Close

closes the network connection to the client

client Peer

returns the name (i.e., the Internet address) of the client's host.

client Poll

returns 1 if a message from the client is waiting to be read and zero if not.

client Read

reads the next line of input from the client and returns it as the command's result string.

client Read buffer

reads data from the client into a memory buffer; the amount of data read is determined by the size of the memory buffer. buffer, the handle returned by a "buffer" command, is returned as the Read command's result string. This form of the "client Read" command is useful for receiving binary data from a client.

client Write buffer ?-nowait ?-complete command??

writes the contents of a memory buffer to a client. buffer is the handle returned by a "buffer" command. This form of the "client Write" command is useful for sending images and other binary data to a client. The -nowait option queues up the data for writing in the background; command, if specified, is executed when the output is complete.

client Write string ?-nowait ?-complete command??

writes the specified string to the client. The -nowait option queues up the data for writing in the background; command, if specified, is executed when the output is complete.

Memory Access Commands

(A signal handler is used to trap bus errors and access violations.)

The address commands manipulate %p pointers (used in the other memory access commands):

address -input ?-format format? location

converts a user-specified address to the host pointer representation (i.e, in "%p" format).

address ?-format format? ?-offset numBytes? location

performs address arithmetic. The byte offset is added to location and the resulting address is returned in the specified format ("%p" is the default).

address -delta base ?-offset numBytes? location

determines the offset in bytes between two addresses, location and base.

dump ?-count numBytes? ?-decimal? ?-hexadecimal? ?-octal? ?-text? location

dumps the contents of one or more memory locations in any of several formats. Each line of the dump is written back to the client with an [MD] prefix; the final line of the dump has an [ME] prefix.

fill value start ?end? ?-count number? ?-format format? ?-signed? ?-type dataType? ?-unsigned?

replicates a value throughout a range of memory.

find value start ?end? ?-count number? ?-format format? ?-signed? ?-type dataType? ?-unsigned?

searches for a value in a range of memory. If the value is found, the find command succeeds and the address at which the value was found is returned as find's result. If the value is not found, the find command fails.

The following commands read values from and store values in memory locations. Different data types are supported: signed and unsigned bytes, chars, shorts, ints, longs, floats, doubles, and strings.

peek ?-address format? ?-format format? ?-signed? ?-type dataType? ?-unsigned? ?-write? location

returns the value from an arbitrary memory location. The -write option provides a short-hand for "client Write [peek ...]".

poke ?-format format? ?-signed? ?-type dataType? ?-unsigned? ?-write? location value

stores a value in an arbitrary memory location.

Memory Buffer Commands

Arbitrary binary data can be handled using gentle's buffer commands:

buffer ?size? ?-load file? ?-static address?

creates a memory buffer of size bytes. The -load option causes the contents of the specified file to be loaded into the buffer; in this case, size is optional and defaults to the size of the file. The memory buffer is dynamically allocated on the heap; the -static option returns a buffer that references a pre-existing memory region (e.g., in global memory). The buffer command returns a handle for the memory buffer that can be used in subsequent "buffer operation" commands.

The following operations can be applied to a memory buffer (buffer is the handle returned by the "buffer" command):

buffer Address ?-offset numBytes?

returns the base address of the memory buffer in a form suitable for using in a "peek" or "poke" command.

buffer Destroy

destroys the memory buffer. If the -static option was not specified when the buffer was created, then the memory region referenced by the buffer is deallocated and returned to the heap.

buffer Load fileName ?-offset numBytes? ?-length numBytes?

loads the contents of a file into the memory buffer.

buffer Save fileName ?-offset numBytes? ?-length numBytes?

saves the contents of the memory buffer to a file.

buffer Size

returns the size in bytes of the memory buffer.

Shared Memory Commands

The commands in this group are used to access named, shared memory segments. Under UNIX, the standard shmXXX(2) functions are used to create and map to segments; naming is provided by an ndbm(3) database. Under VxWorks, segments are simply allocated on the heap and shared naming is managed through the system symbol table. (See my shared memory utilities for more information.)

map name ?-address location? ?-size numBytes?

maps a named, shared memory segment into the gentle process' address space. The map command returns a handle for the mapped segment that can be used in subsequent "segment operation" commands.

The following operations can be applied to a mapped, shared memory segment (segment is the handle returned by the "map" command):

segment Address ?-offset numBytes?

returns the base address of the shared memory segment in a form suitable for using in a "peek" or "poke" command.

segment Load fileName

loads the contents of a file into the shared memory segment.

segment Save fileName

saves the contents of the shared memory segment to a file.

segment Size

returns the size in bytes of the shared memory segment.

segment Unmap

unmaps the shared memory segment.

Client Commands

The following commands are used to communicate with the gentle client (remember that there is one interpreter per client):

client Poll

polls the client for input and returns -1 if the client connection is broken, 0 if there are no pending messages, and 1 if there are messages waiting to be read.

client Read

reads and returns the next message from the client.

client Write message

outputs a message to the client.

Miscellaneous Commands

Odds and ends:

ping

Pong! "[GE] You rang?" is written back to the client.

timer interval ?-cancel command? ?-expire command? ?-periodic?

creates a one-shot or cyclic timer that, upon expiration (or on each firing for a cyclic timer), executes a Tcl command. The timer command returns a handle for the timer that can be used in a subsequent "timer Cancel" command. If a timer is explicitly cancelled before its interval expires, the -cancel command is executed.

timer Cancel

cancels a timer.

tod ?-format format? ?-local? ?-seconds?

returns the current time-of-day, either GMT or, if -local is specified, local time. If the -seconds option is specified, the time is returned as the number of seconds since January 1, 1970. Otherwise, the time-of-day is returned in a strftime(3) format, format, or, if the -format option is not specified, in the following format: "YYYY-DOY-HH:MM:SS.TTT".

xbm string ?-reverse?

returns the X bitmap representation of a string. The XBM format is textual, so the bitmap is returned as a string. By default, the image contains black text on a white background; the -reverse option produces a white-on-black image. The font is currently hard-coded (in my asc2xbm() library function).

MEDS Commands

Master Controller Communications

The first group of MEDS commands are used to communicate with a MEDS Master Controller:

mcrOpen server?@host? ?-nowait? ?-connect command? ?-error command?

establishes a network connection with the Master Controller running on the specified host. If a connection is not immediately established and the -nowait option was specified, gentle will periodically attempt (in the background) to connect to the controller until the connection is finally established. The -connect command, if specified, is executed when a connection is successfully established; the -error command is executed when the connection is broken. The mcrOpen command returns a handle for the connection that can be used in subsequent "controller operation" commands.

controller Close

closes the connection to a Master Controller.

controller Connected

returns 1 if the connection is up and 0 if the connection has been broken.

controller Poll

returns 1 if input is pending and 0 if not.

Subsystem Operations

Commands in the next group direct the Master Controller to apply an operation to specific subsystems; if no subsystem is specified, the operation is applied to all of them. The -timeout option controls how long gentle will wait for a response from the Master Controller; the default is forever.

controller Disable ?subsystem(s)? ?-timeout seconds?

controller Enable ?subsystem(s)? ?-timeout seconds?

controller Flush ?subsystem(s)? ?-timeout seconds?

controller NoOp ?subsystem(s)? ?-timeout seconds?

controller Reset ?subsystem(s)? ?-timeout seconds?

controller ShutDown ?subsystem(s)? ?-timeout seconds?

controller Test ?subsystem(s)? ?-timeout seconds?

controller Zero ?subsystem(s)? ?-timeout seconds?

Application Commands

The following commands initiate actions on the MEDS system:

controller Activate setupFile ?-version N? ?-timeout seconds?

activates the processing of incoming data.

controller Distribute source destination user?@host?
?-account name? ?-password password? ?-request number? ?-target subsystem? ?-timeout seconds?

initiates the construction and transfer of a data set to a user on a remote host. source is the name of the Packet Assembly Table file used to build the data set; destination is the full pathname on the user's host of the to-be-generated data set. The -request option can be used to assign a user-chosen ID to this request; the default is zero. The -target option specifies the subsystem which will process this request; the default is the Data Set Processor.

controller ListCatalogs ?wildcardSpec? ?-write? ?-timeout seconds?

retrieves a list of the currently available configuration catalogs. The wildcard specification, which defaults to "*", allows you to filter the list. If -write is not specified, the ListCatalogs command returns the list of catalogs as a Tcl list, each of whose elements is a triplet containing the name, version number, and description of a catalog. If -write is specified, the list is written back to the client, one catalog per line. Each line has a [CD] prefix, except for the last, which has a [CE] prefix.

controller ListDataSets ?-session ID? ?-write? ?-timeout seconds?

retrieves a list of the currently available data sets. The -session option can be used to narrow the list down to a particular session; the default is to list data sets from all of the sessions. If -write is not specified, the ListDataSets command returns the list of data sets as a Tcl list, each of whose elements is the name of a data set. If -write is specified, the list is written back to the client, one data set per line. Each line has a [DD] prefix, except for the last, which has a [DE] prefix.

controller LoopBack text ?-timeout seconds?

sends a loopback command to the Master controller and returns the controller's response (i.e., text).

controller SendStatus ?interval? ?-timeout seconds?

initiates the sending of subsystem status blocks to a client on the remote host. If no time interval is specified, a single snapshot of the status blocks is taken and sent to the remote client. If a time interval is specified, a new snapshot is taken and sent every interval seconds.

controller TimeSpan sensor start length ?-repeat? ?-timeout seconds?

requests the generation of a time-span data set for sensor, beginning at time start and continuing for length minutes. -repeat specifies that the time span should automatically repeat.

MEDS Commands (VxWorks only)

The commands in this section make use of operating-system-dependent MEDS functions and are only available under VxWorks.

The following commands are used to store, retrieve, and display MEDS alias definitions:

getAlias name

returns the value bound to a name.

putAlias name value ?-global?

adds a name-value mapping to the local or global alias tables.

showAlias

lists the defined aliases on standard output (which you may or may not be able to see!).

The various types of memory regions supported in the MEDS environment are mapped into a gentle interpreter's address space by the following commands (note that these memory regions are distinct from gentle's shared memory regions):

mapGPA ?target? ?-offset numBytes?

returns the address of the Global Parameter Area (GPA) on the specified card.

mapPCA ?target? ?-offset numBytes?

returns the address of the Processor Communications Area (PCA) on the specified card.

mapRAM name ?-make size? ?-offset numBytes?

returns the address of a named region of global memory, creating it if it doesn't already exist.

mapSCB ?target? ?-offset numBytes?

returns the address of the MEDS System Control Block (SCB) on the specified card.

mapSTS name ?-make size? ?-offset numBytes?

returns the address of a named status block in global memory, creating it if it doesn't already exist.

mapTCA ?target? ?-offset numBytes?

returns the address of the Task Control Area (TCA) on the specified card.

Last, but not least:

logEvent code text ?-timeout seconds?

logs an event message to the MEDS event logger.

waitInit ?target? ?-timeout seconds?

waits for the MEDS initialization of a card to complete. The default target is the card on which gentle is running.

EPOCH Commands

Network Communications

The following commands are used to establish network connections with EPOCH processes:

epcCall server?@host? ?-connect command? ?-error command? ?-events database? ?-input command? ?-nowait? ?-timeout seconds?

establishes a client connection with server on host. The epcCall command returns a handle that can be used in subsequent "connection operation" commands (e.g., for reading from and writing to the connection).
The -timeout option allows you to limit how long gentle will block while attempting to establish the connection. If the -nowait option is specified, gentle does not block on the connection attempt. In this case, the connection handle returned by epcCall should not be used until the connection is finally established (which you'll know if you specify a -connect command).
Asynchronous input is appended to the -input command and the resulting command is executed. If the incoming message is an event message and the -events option was specified, the formatted text of the event message is appended to the -input command. Otherwise, a list is constructed from the named variables in the message: "{ {name1 value1} ... {nameN valueN} }".

epcListen server ?-connect command? ?-error command?

creates a network port at which the application listens for connection requests from clients. The epcListen command returns a handle that can be used in subsequent "listener Answer" commands.

The following operations can be applied to an EPOCH listening port (listener is the handle returned by a "epcListen" command):

listener Answer ?-error command? ?-input command?

waits for and answers the next connection request received on the listener's port. The Answer command returns a handle that can be used in subsequent "connection operation" commands (e.g., for reading from and writing to the connection).

listener Close

closes the listening port.

listener Poll

returns 1 if a connection request is waiting to be answered and zero otherwise.

The following operations can be applied to an EPOCH network connection (connection is the handle returned by a "epcCall" or "listener Answer" command):

connection Close

closes the network connection.

connection Peer

returns the name (i.e., the Internet address) of the host at the other end of the network connection.

connection Poll

returns 1 if the network connection has data waiting to be read and zero otherwise.

connection Read ?-timeout seconds?

reads the next message and returns it as the command's result string. If no timeout is specified, the application waits until the next message is received. If the incoming message is an event message and the -events option was specified when connection was created, the formatted text of the event message is returned as the result of the Read. Otherwise, a list is constructed from the named variables in the message: "{ {name1 value1} ... {nameN valueN} }".

connection Write type ?-stamp? ?{name1 value1} ... {nameN valueN}?

writes a message of the given type to the network connection. The name/value pairs are encoded as a set of named variables and transmitted as the body of the message.

Global Variables

The following command is used to initialize access to EPOCH global segments:

GlobSeg stream?@host? ?-bind command?

initializes access to a global segment. stream?@host? specifies the spacecraft stream and the host on which the stream's global server is running; command is a Tcl command to be executed whenever a significant event in the life of the segment occurs.

The GlobSeg command returns a handle that can be used in subsequent "segment operation" commands (e.g., for looking up global variables):

segment Bind command

specifies a Tcl command to be executed when a significant event in the life of the segment occurs.

segment Destroy

terminates access to the global segment.

segment Find name

looks up a global variable by name in the segment.

segment Get name

retrieves the current value of a global variable.

segment Set name value

sets the value of a global variable. (Not Yet Implemented)

The Find command above returns a handle that can be used in subsequent "global operation" commands (e.g., for retrieving the value of a global variable):

global Bind command

specifies a Tcl command to be executed when a global variable is updated or deleted. (Not Yet Implemented)

global Destroy

terminates access to the global variable.

global Value

returns the global's current value.

[incr Tcl] Classes

The Region Class

Region (definition file) is an object class for mapped memory regions. When a region object is created, the named memory region is mapped into the task's address space. An internal database of field addresses and types is created using the Define method. The values in individual fields can be stored and retrieved using the Set and Get methods, respectively.

Region objectName regionName ?-mapFunction functionName?

maps to the memory region identified by regionName using the specified map function, which defaults to "mapRAM" on a VxWorks MEDS system. The Region command returns a handle, objectName, that can be used in subsequent "region method" commands; if objectName is "#auto", a system-generated object name is returned.

The following methods are used to define the fields in a memory region (region is the handle returned by the "Region" command):

region Fill ?type ?numElements??

region Define ?type ?numBytes??

The following methods are used to store and retrieve arbitrary information about a memory region (region is the handle returned by the "Region" command):

region GetInfo key

region SetInfo key value

The following methods are used to access individual fields in a memory region (region is the handle returned by the "Region" command):

region Get fieldName ?index ?stride??

region IndexedAddress fieldName index stride

region Set fieldName value ?index ?stride??

The DataSampler Class

DataSampler (definition file) is an object class for a data sampler. Multiple data samplers can be created with different sampling rates. Each data sampler keeps a list of sample requests; every N seconds, the sampler evaluates each request (e.g., it gets the value of the variable being sampled and writes it to the client).

DataSampler objectName ?-updateInterval numSeconds?

creates a data sampler that samples data every numSeconds (defaults to 5.0 seconds). The DataSampler command returns a handle, objectName, that can be used in subsequent "sampler method" commands; if objectName is "#auto", a system-generated object name is returned.

The following methods can be applied to a data sampler (sampler is the handle returned by the "DataSampler" command):

sampler Start tag request

initiates the sampling of a data item. tag is a client-specified identifier for the item; request is a gentle command that is evaluated to sample the value of the data item.

sampler Stop tag

stops the sampling of the data item identified by tag.

sampler Sample

samples all of the requested data items, sending each value to the client in a "[DS] tag value" message. This method is automatically invoked by an internal timer that fires at sampler's update rate.

The HTML Page Class

Page (definition file) is an object class used for dynamically generating HTML pages.

Page objectName ?-bodyAttributes attributes? ?-interval numSeconds? ?-title text? ?-version HTTPVersion?

creates an object that regenerates an HTML page every numSeconds (defaults to 15.0 seconds). The Page command returns a handle, objectName, that can be used in subsequent "page method" commands; if objectName is "#auto", a system-generated object name is returned.

The following methods can be applied to a page (page is the handle returned by the "Page" command):

page Add field

adds a field (e.g., a row, column, or section) to the page.

page Generate

dynamically generates the HTML page. The Generate method is recursively invoked for each object (e.g., rows, columns, and sections) on the page.

page Repeat

sets a timer so that the HTML page is regenerated numSeconds from now. Generate calls Repeat after each update, so this method is normally not called directly.

The HTML Row Class

Row (definition file) is an object class used for dynamically generating the HTML for a row of information.

Row objectName ?-rowAttributes attributes? ?-tableAttributes attributes? ?-title text?

creates an object that generates the HTML for a row of information. The Row command returns a handle, objectName, that can be used in subsequent "row method" commands; if objectName is "#auto", a system-generated object name is returned.

The following methods can be applied to a row (row is the handle returned by the "Row" command):

row Add field

adds a field (e.g., a column or section) to the row.

row Generate client

dynamically generates the HTML for the fields in the row.

The HTML Column Class

Column (definition file) is an object class used for dynamically generating the HTML for a column of information.

Column objectName ?-rowAttributes attributes? ?-tableAttributes attributes? ?-title text?

creates an object that generates the HTML for a column of information. The Column command returns a handle, objectName, that can be used in subsequent "column method" commands; if objectName is "#auto", a system-generated object name is returned.

The following methods can be applied to a column (column is the handle returned by the "Column" command):

column Add field

adds a field (e.g., a row or section) to the column.

column Generate client

dynamically generates the HTML for the fields in the column.

The HTML Section Class

Section (definition file) is an object class used for dynamically generating the HTML for one section of an HTML page.

Section objectName ?-title text?

creates an object that generates the HTML for one section of an HTML page. The Section command returns a handle, objectName, that can be used in subsequent "section method" commands; if objectName is "#auto", a system-generated object name is returned.

The following methods can be applied to a section (section is the handle returned by the "Section" command):

section Add label updateCommand

adds a labeled field to the section. When the Generate method is invoked, HTML is generated for label and the value resulting from the evaluation of updateCommand.

section Generate client

dynamically generates the HTML for each field in the section.

Source Code

In addition to the files below, you will need a Tcl (version 7.3 or later) library and, optionally, an [incr Tcl] (version 1.5 or later) library. The distribution below was built with Tcl version 8.3 (Linux RPM) and [incr Tcl] version 3.2 (Linux package).

gentle.tgz (658K)