Tornado API Reference : WTX Tcl Library
wtxtclComm [Tcl] - WTX Tcl calls related to target server communications
wtxToolAttach - attach to a target server
wtxToolDetach - detach from a target server
wtxHandle - show the WTX handle stack or set the top element of the stack
wtxTimeout - return or set the current WTX timeout
wtxPath - return a pathname suitable for the environment
wtxHostType - get the host-type code for the current process
wtxTargetName - return the name of the target server attached
wtxToolName - return the name of the current tool
wtxErrorHandler - query or establish an error handler for a connection
msleep - sleep for the specified number of milliseconds
This library contains routines that have to deal with the target server communications. Those routines allow to establish / configure / end communications with the target server to have access to the target through Tcl calls.
wtxToolAttach - attach to a target server
WTX Tcl
wtxToolAttach targetServerName [toolName]
This command attaches to the named target server. It registers the calling process as a tool with the target server, supplying the toolName if given, or wtxtcl otherwise. The target server attached in this way becomes the "default" target server for all further WTX Tcl calls. Each WTX Tcl call may select an explicit connection with the -hwtx handle arguments, using the handle returned by this call in the place of handle.
A WTX handle.
- out of virtual memory
- The tool cannot attach a target server because the host memory is exhausted.
- virtual memory exhausted
- The tool cannot attach a target server because the host memory is exhausted.
wtxtclComm, * wtxtcl, wtxToolDetach
wtxToolDetach - detach from a target server
WTX Tcl
wtxToolDetach [handle | -all]
This command detaches from the target server at the top of the target server stack. If a handle argument is given, that connection is detached regardless of its position in the stack. If -all is given, all WTX connections on the stack are destroyed.
- WTX handle not found
- The tool cannot detach, probably because it was not attached yet.
- no connection stack is associated with this interpreter
- At least one connection handle cannot be closed.
wtxtclComm, * wtxtcl, wtxToolAttach
wtxHandle - show the WTX handle stack or set the top element of the stack
WTX Tcl
wtxHandle [handle]
With no arguments, wtxHandle will return the stack of WTX connection handles in list form. The first element of the list is the top of the stack. If a handle is given as an argument, that handle will be pulled to the top of the stack; it will then become the default handle for WTX Tcl operations.
- WTX handle not found
- The WTX handle stack cannot be popped.
- no connection stack is associated with this interpreter
- At least one connection handle cannot be closed.
wtxtclComm, * wtxtcl, wtxToolAttach, wtxToolDetach
wtxTimeout - return or set the current WTX timeout
WTX Tcl
wtxTimeout [-hwtx handle] [seconds]
With no argument, the current WTX timeout in seconds (and fractions thereof, if the timeout has been set by an application rather than this call) is returned. If an argument is given, the timeout is set to that number of seconds.
The timeout of the default WTX connection is returned or modified if -hwtx is not given; otherwise, the timeout of the named connection is used.
- bad timeout value
- A null or negative timeout value has been requested.
- No WTX connection
- No target server is attached at the present time.
wtxtclComm, * wtxtcl, wtxTargetName, wtxToolName, wtxToolAttach
wtxPath - return a pathname suitable for the environment
WTX Tcl
wtxPath [element...]
With no argument, this function returns the root directory of the Tornado tree. The format of the directory name is the usual one for the host operating system where wtxtcl is running. Optional elements are appended to the result, each separated with the local directory separator character. The special element %H is replaced by the canonical name of the host where wtxtcl is running, and can be used to get a path to host-dependent material in the Tornado tree.
On UNIX hosts, the root of the Tornado tree is the value of the environment variable WIND_BASE. %H is replaced by the name of the host architecture and operating system, e.g., sun4-sunos4, and directory elements are separated with forward slashes. The end of the path has a slash appended.
- WIND_BASE is not set
- No WIND_BASE environment variable has been set.
wtxtclComm, * wtxtcl, wtxTargetName, wtxToolName, wtxToolAttach, wtxHostType
wtxHostType - get the host-type code for the current process
WTX Tcl
wtxHostType
This command returns the host type of the interpreter executing the Tcl code (for example, sun4-sunos4).
wtxtclComm, wtxtcl, wtxPath
wtxTargetName - return the name of the target server attached
WTX Tcl
wtxTargetName
This function returns the name of the default target server, if one is attached.
- No WTX connection
- No target server is attached at this time.
wtxtclComm, * wtxtcl
wtxToolName - return the name of the current tool
WTX Tcl
wtxToolName
This command returns the tool name under which the wtxtcl application is registered with the target server, if the application is connected to one. Otherwise, it returns an empty string.
- No WTX connection
- No target server is attached at this time.
wtxtclComm, * wtxtcl, wtxTargetName
wtxErrorHandler - query or establish an error handler for a connection
WTX Tcl
wtxErrorHandler handle [[proc] tag]
If this function is called with a handle argument only, it returns the name of the Tcl procedure that is installed to handle WTX errors, if any. If proc is given, that Tcl procedure will be invoked whenever a WTX Tcl function that communicates with the target server raises an error.
An error handling procedure should be written to take four arguments: the WTX handle in whose context the error occurred; the command that stimulated the error (in the form of a list); the error message generated; and a tag. The tag argument of the error handler procedure is set to the value of the tag argument given in the wtxErrorHandler command when the handler was attached. If proc is the empty string, any existing error handler is cancelled (and in this case tag is ignored).
Error handlers should always resubmit errors that they do not deal with so that Tcl application code that uses the catch command to process errors will not be disturbed. If an error handler has successfully dealt with an error, it should return a value of the sort expected by the command that stimulated the error. While it is possible to signal an error other than the one the command generated, this may confuse the application code logic by introducing an unexpected error type.
Before installing a new error handler, it may good idea to use the query form of the command to see if an error handler already exists. If so, construct a command that invokes the new error handler followed by the existing one, and install that new command as the error handler.
- WTX handle not found
- The user named an invalid handle.
wtxtclComm, * wtxtcl, wtxTargetName
msleep - sleep for the specified number of milliseconds
WTX Tcl
msleep milliseconds
This function pauses execution of the program for the specified number of milliseconds.
The timer is implemented using the select( ) system call and is not very accurate for small sleep times. No attempt is made to calibrate the delay to take into account the overhead of the Tcl evaluation. You can test the accuracy of the timing in your environment with Tcl's time command:
wtxtcl.ex>time {msleep 50} 100 49944 microseconds per iterationIn this test, according to Tcl's timing support, the call is accurate to -0.11% for a sleep duration of 50 msec.
- invalid time
- A NULL or negative value has been asked for.
wtxtclComm, * wtxtcl