-- Hints for Setting Up and Using XGTERM and XIMTOOL

Hints for Setting Up and Using XGTERM and XIMTOOL

Since work on the xgterm and ximtool utilities (as well as xtapemon and the GUI facilities, in general) is still actively in progress complete user documentation for these programs is not yet available. Information on basic usage is available however in the archive with the binaries (see the ".info" files in the pub/v2103-beta directory), some examples are given in the FAQ, and questions are always answered by contacting site support. What follows is an overview of each of the tasks and examples of how they are commonly used; feel free to contact us if you have any questions not answered here.

In what follows below there are many examples showing the use of X resources to override the default resources of the X11IRAF utilities. Users need to know about these things in order to customize the software and workaround configuration problems, but some caution is advised because 1) this software is still under development and things such as resource names and defaults are likely to change in future releases, and 2) it is possible to make any X program fail to function correctly if one is not careful when overriding resource values. If an X11IRAF program fails to function correctly after an upgrade it may be wise to comment out the relevant resources in your .Xdefaults file to make sure they are not the source of the problem.

xgterm

The xgterm utility is essentially the well-known xterm with an improved graphics capability; it can be used as a replacement for xterm whether IRAF is being run or not. It also serves as the system software for the new IRAF GUI applications and is required to run them. Currently binaries are only provided for Sun systems but the source code is available for those willing to port it to other platforms (something we will be doing as IRAF is upgraded to V2.11 on those systems in the next year). Some features of xgterm such as color graphics are only available when the program is used with V2.10.3BETA and later versions of IRAF, but it may also be used as the graphics terminal for earlier releases of IRAF where users will still benefit from the full screen cursor, interactive dialog capability (status line), and type-ahead capability.

Users on monochrome workstations may find that the graphics cursor is not visible because the default cursor color is indistinguishable from the background color on a monochrome display. This can be fixed by changing the "crosshairCursorColor" resource either by putting the line

        XGterm*gterm.crosshairCursorColor:      white

in the .Xdefaults file and restarting the window system (or resource manager), or by setting it on the command line using

        % xgterm -xrm "*crosshairCursorColor:white"

Another common question is how to set the graphics window geometry to be a specific size (e.g., customized for spectroscopic applications). As with gterm the graphics window geometry can be specified with the "-G" or "%geom" flag on the command line, for instance,

	% xgterm -G 1100x350+10-10	   # or alternatively
	% xgterm %1100x350+10-10

will produce a wide rectangular graphics window in the lower portion of the screen suitable for examining spectra. The geometry may also be specified in the user's .Xdefaults file by specifying

	XGterm*tekGeometry:		1100x350+10-10

Lastly, users often wish to change the background or text colors used for graphics plots (under V2.10.3BETA) from their defaults. The background and text colors are set using a combination of X resources to set the predefined colors, and an IRAF environment variable to say which colors are used for text, background, axis labels, etc. The color resources are named `color0' through `color9'; colors zero and one are the background and foreground colors, respectively, and default to white on black. These resources and their builtin default values are as follows:

Xgterm*gterm*color0: black Xgterm*gterm*color1: white Xgterm*gterm*color2: red Xgterm*gterm*color3: green Xgterm*gterm*color4: blue Xgterm*gterm*color5: cyan Xgterm*gterm*color6: yellow Xgterm*gterm*color7: magenta Xgterm*gterm*color8: purple Xgterm*gterm*color9: darkslategray

On some older workstation monitors darkslategray (color9) may appear too dark and a color such as slategray may be preferable.

The environment variable glbcolor defines the mapping of box-plot attributes onto the predefined graphics colors. It is predefined in V2.10.3BETA as

        set glbcolor = "pt=3,fr=9,al=3,tl=6,ax=5,tk=5"

where the attribute codes are as defined in the table below.

pt - plot title fr - viewport frame (the background around the plotting area) al - axis labels tl - tick label ax - axis tk - tick gr - grid between tick marks

The numbers in glbcolor refer to the color numbers mentioned earlier, for example, "tk=5" indicates that the tick marks are drawn using color number 5 (cyan). To make use of xgterm color graphics you should have the following set in your login.cl or loginuser.cl file:

	stty xgterm

Color graphics is enabled only if you are using V2.10.3BETA or a later version of IRAF, but using X resources you can still change the background and foreground colors when working with an earlier version of IRAF. Resources for the text window are the same as for xterm.

ximtool

With the new network device driver in V2.10.3BETA (see accompanying article) ximtool and IRAF support three different types of communication for image display. ximtool itself will listen on and accept a connection from each of these inputs (ximtool can also support simultaneous input from multiple clients). Users who were just getting comfortable with private FIFO pipes and graphcap files may be confused by the new protocol so we present some common scenarios and recipes for dealing with the various display problems users are likely to encounter.

1) Basic usage:

For users running ximtool and IRAF on a personal workstation with no other users, there is no setup required at all other than to start ximtool. Older versions of IRAF will display using the FIFO pipes in /dev, while in V2.10.3BETA and later versions of IRAF, Unix domain sockets will be tried first, by default. Since ximtool listens for incoming connections on all input channels, no special flags or configuration is required to display an image in either case.

2) X-terminal users and multiple users on a single host:

With V2.10.3 systems, X-terminal users (and others) on multi-user servers no longer need to set up private FIFOs since the Unix domain sockets guarantee there will be no conflicts between users (provided there is only one ximtool per user). It is recommended however that the FIFO pipes be disabled in ximtool if SAOimage is being run on the same host, to avoid any possible conflict with SAOimage users not using private FIFOs. The FIFO pipes are disabled by setting the "input_fifo" ximtool resource to "none"; TCP/IP sockets are disabled by setting the "port" resource to zero. This can be done on the command line using, e.g.,

	% ximtool -xrm "*input_fifo:none" -xrm "*port:0"

This command can easily be aliased, but the X resources can also be permanently set by adding the following lines to the .Xdefaults file:

	XImtool*port:		0
	XImtool*input_fifo:	none

These values will take effect the next time the window system is started or can be loaded immediately using the command:

	% xrdb -load ~/.Xdefaults

ximtool can then be started without any command line arguments and only the Unix domain socket will be used. These sockets are created automatically and will be unique for each user to avoid conflicts.

For V2.10.2 and earlier versions of IRAF, only FIFO pipes are available for communication so private FIFO pipes and graphcap files are still required in these cases. The pipes are created as before but ximtool must be started to use these pipes instead of the /dev defaults. For example,

         % ximtool -xrm "*input_fifo:/<path>/imt1i" \
		   -xrm "*output_fifo:/<path>/imt1o"

or in the .Xdefaults file specify:

	XImtool*input_fifo:	/<path>/imt1i
	XImtool*output_fifo:	/<path>/imt1o

Note that the "input_fifo" takes the "imt1i" pipe and vice versa; this is opposite of the (confusing) pipe naming convention used by SAOimage.

3) Users running ximtool on a remote machine who are logged into IRAF on their home machines (or vice versa):

The traditional approach to this is to set the node environment variable to, e.g., "foobar", and rely on IRAF networking to display the images using the FIFO pipes. This still works fine but what happens if you are trying to display to a machine at a remote site that isn't in your local IRAF network? In this case you would need to use the TCP/IP socket to connect to the ximtool running on the remote machine. Before logging in to IRAF (on your home machine) you would first set the Unix environment variable IMTDEV to specify the connection type. For example,

	% setenv IMTDEV		inet:5137:foo.bar.edu

This says to use an `inet' connection on port `5137' to node `foo.bar.edu.' The IMTDEV definition overrides the normal IRAF connection scheme so there is no need to reset or unset your node environment variable once logged in. On the remote machine (assuming there are local IRAF users) you would disable the FIFO pipes and the Unix domain sockets using something like:

	% ximtool -xrm "*input_fifo:none" -xrm "*unixaddr:none"

Note that the Unix domain sockets should be unique so disabling them isn't strictly necessary.

The typical use for this feature is when you are running ximtool on the local workstation with IRAF executing on a remote machine somewhere on the Internet, and IRAF networking is not available between the two hosts. IMTDEV allows the remote IRAF session to display directly to your local ximtool. Another way to solve this problem would be to run ximtool remotely, setting the Unix environment variable DISPLAY to cause XLIB to display to the X server on your local workstation. It is much better to use IMTDEV however, as since ximtool executes locally, once the image frame buffers have been loaded over the network everything else executes locally, and ximtool functions such as zoom and pan or frame blink will execute much faster than with a remote X display.

4) Users who want more than one ximtool:

Since ximtool has multiple frame buffers users should consider whether they really need two ximtools in the first place. Usually it is preferable to load two or more frames and blink or tile the frames to view the different images.

If there is a need to run multiple ximtools then the easiest way to do this is to control them from different IRAF sessions so that different socket numbers can be assigned to each session; each ximtool would be started with a different socket number as well. For example, in the first xgterm window you would define the socket and start ximtool using

	% setenv IMTDEV		unix:/u2/smith/iraf/dev/IMT1%d
	% ximtool -xrm "*input_fifo:none" -xrm "*port:0" \
		  -xrm "*unixaddr:/u2/smith/iraf/dev/IMT1%d" &

In a second xgterm window you change the socket number slightly and start things using

	% setenv IMTDEV		unix:/u2/smith/iraf/dev/IMT2%d
	% ximtool -xrm "*input_fifo:none" -xrm "*port:0" \
		  -xrm "*unixaddr:/u2/smith/iraf/dev/IMT2%d" &

Each IRAF session will write to a different socket, and each ximtool will be listening on a different socket. It should be noted that something similar can also be done using either FIFOs or TCP/IP sockets for the connection, similarly entries can be defined in a graphcap file naming each socket but it is cumbersome to switch the setting of stdimage between image display calls.

xtapemon

xtapemon is a magtape status monitor and display utility. You use it to display the status of an IRAF tape job while it is running. TCP/IP sockets are used for communication, so the IRAF tape job and xtapemon may be on the same host machine or on different hosts. All V2.10 versions of IRAF support tape status output (including even VMS/IRAF).

In the simplest use the xtapemon task is started in the background prior to using the tape. The tapecap IRAF environment variable is set to enable status output, for example,

	cl> set tapecap = ":so"
	cl> allocate mta
	cl> rfits mta 1-999 images

At this point the xtapemon window will display the status of the tape as the images are being read. If xtapemon is being run on a client machine and the IRAF session is started on a server, the tapecap is set to send output through a TCP/IP connection to that node using the syntax

	cl> set tapecap = ":so=<node>"

where is the name of the local machine. On the other hand, if both IRAF and xtapemon are being run locally, but the tape is on a remote node, status may be displayed using

	cl> rfits "ursa!mta[:so=pisces]" 1-999 images

where "ursa" is the remote machine with the drive and "pisces" is the local machine. The quotes are necessary in order to pass the full name to the task.

Mike Fitzpatrick, Doug Tody

This document was translated by ms2html v1.8 on 21Jan95.