3 Known Problems and Workarounds
4 Differences from SunSoft ToolTalk
6 Examples on IRIS Workstations
- 1 -
1. Introduction
ToolTalk is an interprocess message passing facility
developed and licensed by SunSoft. It is used by
independent applications to communicate with each other
without having direct knowledge of each other. Applications
communicate by creating and sending ToolTalk messages. The
ToolTalk service receives these messages, determines the
recipients, then delivers the messages to the appropriate
ToolTalk client applications.
For detailed documentation, please read the following
manuals:
o ToolTalk Programmer's Guide (available as an option)
o ToolTalk Setup and Administration Guide.
Developers are encouraged to read both of these manuals.
Note: Packaged with this software is a separate sheet that
contains the Software License Agreement. This
software is provided to you solely under the terms
and conditions of the Software License Agreement.
Please take a few moments to review the Agreement.
This document contains the following chapters:
1. Introduction
2. Installation Information
3. Known Problems and Workarounds
4. Differences from SunSoft ToolTalk
5. Documentation Notes
6. Examples on IRIS Workstations
1.1 Release_Identification_Information
Following is the release identification information for
ToolTalk:
- 2 -
Software Option Product ToolTalk
Version 1.2.1 (Corresponds
to SunSoft ToolTalk
1.0.1)
Product Code ToolTalk 1.2.1
System Software Requirements IRIX 5.2
1.2 Hardware_Requirements
You should have at least 16 Mbytes of RAM to run ToolTalk.
Furthermore, many of the programs have large address spaces
and therefore use a large amount of swap space. Silicon
Graphics suggests that if you see the tools being killed due
to lack of swap space, you increase the swap space by using
the ``swap'' administrative interface.
1.3 On-Line_Release_Notes
After you install the on-line documentation for a product
(the relnotes subsystem), you can view the release notes on
your screen.
If you have a graphics system, select ``Release Notes'' from
the Tools submenu of the Toolchest. This displays the
grelnotes(1) graphical browser for the on-line release
notes.
Refer to the grelnotes(1) man page for information on
options to this command.
If you do not have a graphics system, you can use the
relnotes command. Refer to the relnotes(1) man page for
accessing the on-line release notes.
1.4 On-line_man_Pages
The following man pages are provided on-line with ToolTalk:
install_tt(1) tt_type_comp(1)
ttcopy(1) ttmv(1)
ttrm(1) ttrmdir(1)
ttsession(1) tttar(1)
ttapi(3) ttdbserverd(8)
ttdbck(8)
To access an on-line man page, type:
man
- 3 -
1.5 Product_Support
Silicon Graphics, Inc., provides a comprehensive product
support and maintenance program for its products. If you
are in North America and would like support for your Silicon
Graphics-supported products, contact the Technical
Assistance Center at 1-800-800-4SGI. Otherwise, contact
your support provider.
- 1 -
2. Installation_Information
This chapter lists supplemental information to the IRIS
Software Installation Guide. The information listed here is
product-specific; use it with the installation guide to
install this product.
2.1 ToolTalk_Subsystems
The ToolTalk Execution product includes these subsystems:
tooltalk_eoe.sw.links Installation links for sw
subsystem
tooltalk_eoe.sw.runtime ToolTalk run-time environment
tooltalk_eoe.man.links Installation links for man
subsystem
tooltalk_eoe.man.pages Man pages
tooltalk_eoe.man.relnotes Release notes
The ToolTalk Development product includes these subsystems:
tooltalk_dev.man.links ToolTalk Development man page
links
tooltalk_dev.man.manpages ToolTalk Development man pages
tooltalk_dev.man.relnotes ToolTalk release notes
tooltalk_dev.sw.dev ToolTalk development
tooltalk_dev.sw.examples ToolTalk examples
tooltalk_dev.sw.links ToolTalk development
2.2 ToolTalk_Subsystem_Disk_Space_Requirements
This section lists the subsystems (and their sizes) of the
ToolTalk option.
When you install this option for the first time, the
subsystems marked "default" are the ones installed
automatically if you use the ``go'' menu item. To install a
different set of subsystems, use the ``install,''
``remove,'' ``keep,'' and ``step'' commands in inst to
customize the list of subsystems to be installed, then
select the ``go'' menu item.
- 2 -
Note: The listed subsystem sizes are approximate. Refer to
the IRIS Software Installation Guide for information
on finding exact sizes.
Subsystem Name Subsystem Size
(512-byte blocks)
tooltalk_eoe.sw.links (default) 10
tooltalk_eoe.sw.runtime (default) 4700
tooltalk_eoe.man.links (default) 10
tooltalk_eoe.man.manpages (default) 52
tooltalk_eoe.man.relnotes (default) 36
tooltalk_dev.man.links (default) 1
tooltalk_dev.man.manpage (default) 58
tooltalk_dev.man.relnotes (default) 36
tooltalk_dev.sw.dev (default) 4340
tooltalk_dev.sw.examples (default) 379
tooltalk_dev.sw.links (default) 2
2.3 Installation_Method
All of the subsystems for ToolTalk can be installed using
IRIX. You do not need to use the miniroot. Refer to the
IRIS Software Installation Guide for complete installation
instructions.
2.4 Prerequisites
You must be running IRIX 5.2 to use Version 1.2.1 of this
product.
The following prerequisites external to ToolTalk apply to
the tooltalk_eoe.sw.runtime subsystem:
o You must have installed the execution C library
(eoe1.sw.lib).
o You must have installed the X11 execution environment
(x_eoe.sw.eoe).
o You must have installed the TCP/IP networking support
(eoe2.sw.tcp).
The following prerequisites external to ToolTalk apply to
the tooltalk_dev.sw.dev subsystem:
- 3 -
o You must have installed the IRIS Development Option
(dev).
o If you are developing ToolTalk applications that use X
and Motif, you must have installed the X11 Execution
Environment mentioned above, the X11 Development
Environment (x_dev.sw), the Motif Execution-Only
Environment (motif_eoe), and the Motif Development
System (motif_dev).
Note: The tooltalk_dev images is mentioned here, but is
bundled as part of the developer's option.
Within ToolTalk, the following prerequisites apply:
o tooltalk_eoe.sw.links must always be installed.
o tooltalk_eoe.sw.links must be installed for
tooltalk_dev.sw.links.
o tooltalk_dev.sw.links must be installed for
tooltalk_dev.sw.dev.
o tooltalk_eoe.man.links must be installed for the
tooltalk_eoe.man.manpages subsystem.
2.5 Other_Installation_Information
ToolTalk uses an installation architecture that makes it
easy to relocate the bulk of the installed files to
directories that have extra space. All the ToolTalk files
are installed under the directory /usr/ToolTalk, then those
files are linked back to the appropriate spots under /usr.
Therefore, if you do not have enough disk space on /usr to
install the ToolTalk tools, you can install them on an
auxiliary disk and link them back to /usr automatically.
Here is one example of appropriate commands for installing
locally on a disk named /disk3 (execute as root):
ln -s ../disk3/ToolTalk /usr (location of target of inst)
inst -f /CDROM/dist (location of inst images)
go
These commands link the /usr/ToolTalk directory to the
/disk3 disk, where there is enough space to hold the tools.
The files are then installed on /disk3, and the
tooltalk_eoe.sw.links subsystem and tooltalk_eoe.man.links
subsystem install links pointing to those files from /usr.
In another example, if you want to install ToolTalk on a
file server and have users mount the software from there,
- 4 -
first install the software on the server as usual:
inst -f /CDROM/dist
- 5 -
Then mount the server's files from server:/usr/ToolTalk on
the user's machine as /usr/ToolTalk and install sw and man
links subsystems:
inst -f /CDROM/dist
keep all
install tooltalk_eoe.sw.links
install tooltalk_eoe.man.links
go
2.6 Search_path
The ToolTalk commands are installed in the directory
/usr/ToolTalk/bin. They are linked from the directory
/usr/sbin. You should include /usr/sbin in your search
path.
- 1 -
3. Known_Problems_and_Workarounds
This chapter describes the known problems with the 1.1
version of ToolTalk.
o The Object Types (otypes) and the related ToolTalk
enhanced shell commands (ttcopy, ttmv, etc.) should be
used for prototyping systems only.
o If you see the message:
Warning: couldn't acquire X selection
it is possible that ToolTalk has started two
ttsessions. The older of these sessions is not active.
You can kill the inactive session with the IRIX kill
command.
o If the default ttsession is killed, it leaves a
property on the X root window defining that session.
To locate the property, type:
xprop -root | fgrep _SUN_TT_SESSION
Or, if you are running in a ClearCase view, type:
xprop -root | fgrep _SGI_TT_SESSION_
To remove the property, type:
xprop -root -remove
- 2 -
o If you have a ptype defined, but the program that is
autostarted on behalf of that ptype does not declare
itself to be that ptype, ToolTalk continues to start
the same program. If this happens, kill the ttsession
process and the many instances of the autostarted
program, and fix your program to declare itself
properly. For example, in the example program
tt_sgi_service, tt_ptype_declare is called before
tt_session_join. This also points out the importance
of declaring the ptype before joining the session.
o By default, ToolTalk tries to connect to the X display
defined by the DISPLAY environment variable to
determine what ttsession to join. The call to
XOpenDisplay (which connects to the X display) can fail
in several ways:
- If DISPLAY is set to a machine that is running
Pandora, the Silicon Graphics (SGI) login, the SGI
Xlib prints out the following warning:
Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server
There is currently no way to suppress this
warning. Because you probably do not want to
connect to a message server on this machine in
this case, set your DISPLAY environment variable
to the machine running the desired ttsession.
- If DISPLAY is set to a machine that is running XDM
(X Display Manager) as the login, a call to
XOpenDisplay hangs and might eventually return
with the following message:
XIO: fatal IO error 32 (Broken pipe) on X server
"(null)" after 0 requests (0 known processed)
with 0 events remaining. The connection was
probably broken by a server shutdown or KillClient.
Once again, you can set DISPLAY to avoid this
condition. If you are programming to handle this
condition, one solution for detection without
hanging is to set a timer surrounding the call to
tt_open (which calls XOpenDisplay). You can do
this by setting a signal handler for the SIGALRM
signal, and setting the alarm for how long you
will give XOpenDisplay to connect or fail.
- 3 -
- A third possible failure is if the DISPLAY is set
to a machine (server) that is not running the X
server (Xsgi). In this case, the call to
XOpenDisplay returns nil but takes a long time.
Again, it makes sense to set the DISPLAY
appropriately.
o If two clients require the same ptype service, but have
joined different files, simultaneous autostart handles
both requests successfully, but the second client
receives a reply with state TT_FAILED. This happens
when both clients have scope=TT_FILE_IN_SESSION.
o SunSoft ToolTalk sets the SIGPIPE signal handler for
clients unconditionally to SIG_IGN. This overrides any
previous setting for this signal handler. In SGI
ToolTalk, if the SIGPIPE signal handler of the client
is set to anything other than SIG_DFL (default), it is
left unchanged. Set your signal handlers before
calling ToolTalk.
o Point-to-point notices that do not have a handler set
for them are ignored, instead of an error code being
returned from tt_message_send(). The workaround is to
always name your recipient (via
tt_message_handler_set()) when you send a point-to-
point (that is, TT_HANDLER) message. Because no error
message is returned if you do not, make sure always
name your recipient.
o If you create a message, then send it more than once,
subsequent sends are not reliable. This is not supposed
to work at all! Do not send the same message more than
once; create a new message each time.
o When tt_close is called, more than just the default
proc ID is closed. Other proc IDs obtained via earlier
tt_open calls cause the TT_ERR_PROCID error when they
are used. The workaround is to call tt_open() right
after calling tt_close(). That creates a new proc ID
and causes it to be the default proc ID. Then call
tt_default_procid_set() to set the default proc ID to
be one of your ``real'' proc IDs. Note that this is
relevant only if you are juggling multiple proc IDs in
the same process, which is not the typical case.
o TT_ERR_OVERFLOW is not currently reported when
thousands of queued messages are sent and never
delivered. The workaround is to make sure the receiver
proceeds normally by calling tt_message_receive.
- 1 -
4. Differences_from_SunSoft_ToolTalk
4.1 Not_Supported_in_Silicon_Graphics_ToolTalk
o The Classing Engine is a SunSoft database used for
typing information (for example, given a file, what
type is it, what icon is used for this type?). This is
used in Sun OpenWindows, and is not part of ToolTalk.
Some of the ToolTalk commands have options that use the
Classing Engine in the SunSoft implementation. The
Classing Engine options are not supported in the
Silicon Graphics (SGI) implementation.
o The SunSoft implementation of ToolTalk supports a des
authentication option and uses secure RPC. This is not
supported in the SGI ToolTalk implementation.
o The SunSoft implementation of ToolTalk supports
internationalization of error/warning messages. This is
not supported in the SGI ToolTalk implementation. The
error message strings can be found in Appendix C of the
ToolTalk Programmer's Guide (available as an option).
4.2 Restricted_Support_in_SGI_ToolTalk
o The following examples in tooltalk_dev.sw.examples
(/usr/ToolTalk/examples) do not run on IRIS
workstations: ttsample1, Sun_EditDemo, ttmon. They are
included for illustrative purposes only. However, two
examples have been written to run on IRIS systems,
ttsample1_sgi and
ttsample2_sgi_client/ttsample2_sgi_service. These new
examples are presented in Chapter 6.
o The following libraries are needed when binding in
either the shared or non-shared ToolTalk libraries:
/usr/lib/libc.so
/usr/lib/libX11.so
4.3 Changes_in_SGI_ToolTalk
o The SunSoft implementation of ToolTalk has a program
named ttcp for copying files containing ToolTalk
objects. In SGI's implementation, ttcp is a test
program for TCP and UDP performance. The SunSoft
ToolTalk ttcp command has been renamed ttcopy in SGI
ToolTalk.
- 2 -
4.4 Additional_Functionality_of_SGI_ToolTalk
By default, a ToolTalk client process connects to a default
ToolTalk message server (ttsession). Silicon Graphics has
modified the default behavior to include the concept of the
CASEVision/ClearCase view. By default, if ToolTalk clients
are running in a CASEVision/ClearCase view, the ttsession
will be started in the view and dedicated only to processes
in the view. This overrides the SunSoft ToolTalk default
mechanism. If the ToolTalk client is not running in a
CASEVision/ClearCase view, it connects to the ttsession in
the same manner as in the SunSoft ToolTalk implementation.
(See CASEVision/ClearCase for details on what it means to be
in a view).
- 1 -
5. Documentation_Notes
The ToolTalk documentation (except for this Release Note)
was written by SunSoft. For Silicon Graphics ToolTalk, the
documentation has been modified to eliminate references to
SunSoft, SunOS, OpenWindows, the Classing Engine, and other
Sun proprietary terms. However, the goal was to remain as
close to the SunSoft documentation as possible.
- 1 -
6. Examples_on_IRIS_Workstations
ttsample1_sgi is a ported version of ttsample1. It uses X
and Motif instead of Xview and compiles and runs on IRIS
workstations.
ttsample2_sgi_client and tt_sample2_sgi_service combine to
make a new example in Silicon Graphics ToolTalk that
demonstrates the ptype and autostart capabilities. If you
want to build and run these programs, you must have:
o X11 Development Environment (x_dev.sw)
o Motif Execution-Only Environment (motif_eoe)
o Motif Development System (motif_dev)
in addition to having the prerequisites listed in Section
2.4.
To build these programs, type:
% cd /usr/ToolTalk/examples
% cp *sgi* /usr/tmp
% cd /usr/tmp
% mkdir ~/.tt
The next command merges a new ptype into ~/.tt/types.xdr if
this file exists.
% make -f Makefile.sgi all
You are now ready to run. Type:
% ttsample1_sgi
- 2 -
You can now move the Send slider, then press the Broadcast
button. This sends a message to ToolTalk, which is then
received by ttsample1_sgi, and the Receive slider will be
updated.
% ttsample2_sgi_client
Again, you can send the value. This time a new process,
ttsample2_sgi_service, is autostarted. The new process
receives the message and replies, updating the original
calling client, ttsample2_sgi_client. In this case, the
service returns the value ((val_in + 1) %100) to show that
the service is responsible for setting the new value and
sending it back in the reply.
% killall ttsession
This kills the ToolTalk server that was autostarted to
service these examples. You should also quit or kill the
example programs.