A Configuring Your IRIS Explorer Environment

A Configuring Your IRIS Explorer Environment

This appendix explains how to configure various aspects of your system in order to use IRIS Explorer more effectively. It includes:

  • modifying your .explorerrc file

  • configuration commands

  • setting environment variables

  • remote execution of modules

  • running the X server

A.1 The .explorerrc Configuration File

IRIS Explorer reads configuration information from files on start-up. This information tells IRIS Explorer, among other things:

  • where to look for modules

  • how to configure the Module Librarian

  • what size the memory arena should be

  • where and how to run remote modules

This information can come from two separate files, one global to the host machine and one private to the user. The global configuration file is in $EXPLORERHOME/Explorer.config, where $EXPLORERHOME is the root directory of IRIS Explorer on your machine and the private copy is in the user's home directory in the file called .explorerrc.

Both the Explorer.config and .explorerrc files can contain commands that configure IRIS Explorer. The file $EXPLORERHOME/sample.explorerrc contains an example of some of the commands, and a copy of this provides a useful starting point for the creation of a private .explorerrc file.

The syntax is line-oriented; a backslash at the end of a line indicates that the next line is a continuation. Exclamation marks (!) at the beginning of a line designate comments (but the # sign will also work). The line syntax is as follows:

command [arguments] [modifiers]

The first word designates the command, and subsequent fields designate arguments or modifiers to the command. Either single or double quotation marks may be used to surround arguments that contain embedded blank characters.

Most arguments to commands may encode UNIX environment variables using the shell dollar-sign notation. For example, $EXPLORERHOME will expand to the value of the environment variable EXPLORERHOME, as will ${EXPLORERHOME}. The C-shell tilde ~ notation for designating home directories is recognized as well. However, strings surrounded by single quotation marks (apostrophes) are not expanded in this manner.

If the file permissions are set to be executable, the file will be executed and the output read as the configuration file. If IRIS Explorer recognizes the #!CPP notation, the file is run through the C preprocessor and all environment variables are defined to the C preprocessor as C preprocessor symbols. This means you can use conditional statements for values such as hostname, which makes the file more flexible.

If you use the #!CPP notation in your .explorerrc file, then you must use ! rather than # at the beginning of a comment line.

This is an example of a typical .explorerrc file. Comments start with an exclamation mark (!) in column 1.

! Look for modules in my local directory
modulepath -append ~/explorer/modules

! Set the directory where the arena and pipes go
set tempdir /usr/tmp/explorer

! Add some frequently used modules into the shelf
category shelf Render DisplayImg IsosurfaceLat ReadImg\
   ReadLat Contour

! Put the Geometric modules into their own category
category Geometry BoundBox Contour IsosurfaceLat \
   IsosurfacePyr LatToGeom PyrToGeom \
   PickLat ReadGeom VolumeToGeom

! Increase the maximum arena size for larger data sets
set arenasize 24mb

! Define some remote hosts
host willard

A.1.1 Configuration Commands

The commands that are accepted in an IRIS Explorer configuration file are described below. Optional portions are enclosed in square brackets. Ellipses denote that the previous argument may be repeated any number of times.

A.1.1.1 modulepath

The module path is a list of directories in which IRIS Explorer looks for modules and maps. The default list contains only $EXPLORERHOME/modules, but the Explorer.config file shipped with IRIS Explorer extends it. You can reset module paths from scratch, or you can extend them using the -append or -prepend modifiers.

The modulepath command states where to look for modules.

modulepath [-prepend] path ...
modulepath [-append] path ...

This command defines a list of directories to be used. By default, the existing module path is extended by the list for directories (this is equivalent to using the -append modifier). The default path value is $EXPLORERHOME/modules. Used alone, the command clears the module path to the default path value. If the -prepend modifier is used, the path is added at the head of the current directory list.

A.1.1.2 set

You can use the set command to set the temporary directory and the size of the arena.

set tempdir

IRIS Explorer uses a number of temporary files during its execution. While almost all of these are small, the shared memory arena file can get quite large.

set tempdir path

The set tempdir command states where to place any temporary files that may be needed during the course of execution, such as named pipes and shared memory arena files, if applicable. Typically, such files are placed in a uniquely named subdirectory of the directory. The default value for the base directory is /usr/tmp.

Because shared memory arenas can become large, it is often advantageous to place the tempdir somewhere else.

set arenasize

On some workstations, modules use shared memory for data communications. The shared memory is mapped into a file that resides on disk as determined by the set tempdir command above.

set arenasize string

For a shared memory system, make the maximum size of the shared memory arena the designated size.

string should be a number optionally followed by mb or kb for megabytes and kilobytes, respectively. This option may also be set from the command line. The default size is 32Mb.

A.1.1.3 category

Defines a new Module Librarian category with the name name and containing the list of modules given.

category name [-append] [-filter] [arg] modulelist

where modulelist consists of a list of modules, or directories, or both.

The -append modifier appends a list of modules to a specified category. The list of modules can contain module names, such as GenLat, or directory names. In the latter case, the directory is added to the module path, and all modules and maps in the directory are added to the category. For example,

category myModules ~/explorer/modules

adds all modules in directory ~/explorer/modules to the category myModules. You can use the -filter modifier with an arg to filter the list of modules against the argument pattern. The arg accepts shell wildcards such as *, ? and [. For example,

category Readers -filter Read* $EXPLORERHOME/Modules

puts all the Read* modules in directory $EXPLORERHOME/Modules in a category called Readers.

There is a designated category in the Module Librarian called shelf. Modules in the shelf category are displayed in a small panel at the bottom of the Librarian's window.

A.1.1.4 host

Modules are organized by categories and by hosts in the Module Librarian. When you execute IRIS Explorer, host names defined in the .explorerrc file will be listed on the Hosts menu in the Module Librarian window, and modules can be executed on those machines (provided contact can be established and permission is obtained to do so).

The command used by IRIS Explorer to start the LC (local communication server) on a remote host hostname is

remoteshellcommand hostname shellcommand

where remoteshellcommand normally is rsh and shellcommand is the command that will be invoked on the remote machine to start the LC. You can specify the hostname and optionally an alternative for remoteshellcommand in the .explorerrc file:

host hostname [-command rshellcommand]

If rshellcommand contains blanks it must be enclosed in quotation marks. For example, the specification

host bob -command "myrsh -x"

means that IRIS Explorer will use

myrsh -x bob shellcommand

when a request is made to run modules remotely on host bob. The command shellcommand is defined by IRIS Explorer and cannot be changed by the user. If the word HOST appears in remoteshellcommand the hostname is substituted in its place when executing the command. Therefore, you can use the command:

host bob -command "rsh HOST -l joe"

to start a remote LC under the account joe on bob. If the word HOST does not appear in the command, it is appended to the end. Hence, the following two lines are functionally equivalent:

host superhost -command "rsh HOST"
host superhost -command "rsh"

The default remoteshellcommand rsh may not be appropriate for all installations, because rsh does not allow for password prompting and the associated protections. If required, you can use the host command to define cxrexec as the remoteshellcommand. Other UNIX programs may be used instead of rsh and crexec, depending on local conventions.

A.2 IRIS Explorer Environment Variables

By default, the IRIS Explorer system is installed in directory /usr/explorer.

Under normal circumstances there is no need to use the environment variable EXPLORERHOME, but if you choose to install IRIS Explorer in a directory other than the default, then you will need to set EXPLORERHOME to point to the installation directory.

There are also several environment variables that pertain to the building and installation of new modules. They are described in Section 2.8 of the IRIS Explorer Module Writer's Guide (UNIX).

If your display is not capable of displaying OpenGL, then you can configure IRIS Explorer to use the MesaGL rather than the standard OpenGL version of all rendering modules. The MesaGL version renders via X using version 1.2.8 of the Mesa 3D graphics library. Modules for which there is an OpenGl and MesaGL version are ColorEditor, Render, RenderRemote, TransformGen, ViewGeom and VolumeRender.

The environment variable CXGLTYPE determines which version of the modules is going to be used. You will need to set this variable to mesagl if you require MesaGL rendering modules, while the value opengl will lead to using the OpenGL rendering modules (this is the default value).

There is no need to set this variable if you wish to use the standard OpenGL rendering modules.

A.3 Remote Execution of Modules

The general idea of IRIS Explorer is that you initially run it on your own workstation, but then you can use it to run some modules on remote workstations.

Each machine that you use to execute modules remotely must have most of IRIS Explorer installed on it. In general, the version installed remotely must match the version installed on the local machine.

Remote execution means that all of IRIS Explorer will initially be running on the remote machine, but the user interface will appear on the local machine[12].

A.3.1 Making a Connection to a Remote Machine via IRIS Explorer

To start a local controller process on a remote machine use the New Host... option of the Hosts menu on the Librarian, and enter the host name in the pop-up window. On successful connection, a new Librarian window will appear from where it will be possible to launch modules on the remote machine which interact with modules running on the local machine, with data being passed from one module to another just as though all modules were running on the local machine.

The remote machine may be any of the UNIX machines which can run their own versions of IRIS Explorer. In theory, there is no limit to the number of different machines that can be connected in this way.

IRIS Explorer executes the .cshrc file on the remote UNIX machine when starting up the remote Librarian. If IRIS Explorer is not located in the default directory /usr/explorer on the remote UNIX machine, the environment variable EXPLORERHOME needs to be set to the location of IRIS Explorer in the .cshrc file. You must also define the environment variable LM_LICENSE_FILE to indicate the location of the FLEXlm license file. Finally, it may be necessary to define the environment variable CXGLTYPE in the .cshrc file.

An alternative way of starting a local controller process on a remote machine is by using the Hosts menu on the Librarian and selecting one of the hosts specified. Names of remote hosts are added to this menu by specifying them with the host command in the .explorerrc configuration file. The definition of hosts via the host command allows more flexibility in the way an LC is started on a remote machine.

A.3.2 The rsh and rshd Utilities

In order to make a connection between two machines, IRIS Explorer uses the UNIX rsh utility; other utilities may also be used, see the host command and cxrexec utility.

Typically, the rsh system consists of two parts; the rsh (remote shell) utility itself, and the rshd (remote shell daemon) utility. The remote shell daemon is a background process which simply waits to be contacted by rsh commands issued from other machines. Thus, while working on one UNIX machine, one may issue an rsh command to execute a program on another; for example, the command

rsh venus pwd

would send a message to the machine venus asking it to run the command pwd. On venus, which of course must be connected to the local machine by some kind of network, the message is received and executed by the rshd remote shell daemon (assuming that the machine which originated the command has permission to execute programs on venus; this fact is determined by the daemon).

On UNIX platforms, IRIS Explorer also provides an alternative to rsh, which is cxrexec. It is capable of prompting for a password.

By default IRIS Explorer uses the rsh(1) command to start the LC on remote machines. This takes place only the first time you create a Librarian or launch a module on a remote machine. In order for IRIS Explorer to be able to start LCs, rsh to those machines must work. For example, if you want to launch modules on a host named labserver, verify that you have access via rsh to that machine by typing the following command:

rsh labserver pwd

If it responds with the name of your remote home directory, all is well. If it responds with Permission denied you need to enable rsh. You can enable access to that machine by creating a file named .rhost in your remote home directory. See the rsh(1) manual page for details.

A.3.3 The cxrexec Utility

IRIS Explorer provides an alternate command similar to rsh that can prompt for a password. This command, cxrexec, uses the rexec library call and prompts for a password in a small pop-up window. For example, if access to a host named securehost requires a password, the following line in .explorerrc will result in the password prompt being issued:

host securehost -command cxrexec

The command cxrexec has the same command line options as rsh. Either command can be modified in .explorerrc to add options. However, when additional rsh or cxrexec options are listed, the entire command must be enclosed in quotation marks:

host superhost -command "cxrexec HOST -l guest"

A.3.4 What to Do if IRIS Explorer Is Not Installed in /usr/explorer

If IRIS Explorer is not installed in the directory /usr/explorer, then you must either:

  • create a symbolic link from /usr/explorer to the actual installation directory.

    If your system uses shared libraries you must install the symbolic link.

  • define an environment variable, EXPLORERHOME, to contain the name of the directory where it is installed. See Section A.2.

For example, if IRIS Explorer on the machine billiejoe is located at /usr/local/explorer, then you must set EXPLORERHOME to be /usr/local/explorer in the .cshrc file (see csh(1)).

Suppose that on the remote machine bob, IRIS Explorer is located at /usr/people/jim/explorer. Then the .cshrc file in your home directory on host bob must contain this line:

setenv EXPLORERHOME /usr/people/jim/explorer

The easiest thing to do is to install IRIS Explorer in the same location on all machines, which by default is /usr/explorer.

A.3.4.1 Using the Switch Statement in a Shared .cshrc

If you have a single .cshrc file on several workstations, each of which may have IRIS Explorer installed in a different location, you can use the csh switch statement to set EXPLORERHOME correctly according to the current machine.

For example:

switch (`hostname`)
case billiejoe:
      setenv EXPLORERHOME /usr/local/explorer
case bob:
      setenv EXPLORERHOME /usr/people/jim/explorer

The character ` surrounding hostname in the previous example is an accent grave, not an apostrophe.

A.4 Running the X Server

The type of visual you run on your X server determines the number of colors available for modification, and this affects how many GenerateColormap modules you can run at one time.

A.4.1 Selecting a Visual

The X server supports several classes of color visuals. Each visual class uses a different method to display color. The GenerateColormap module is designed to function properly with the PseudoColor and TrueColor visual classes. The PseudoColor visual uses the hardware colormap to display a small number of colors from a much larger palette of possible colors. The TrueColor visual class writes colors directly to the graphics frame buffer.

The visual classes have a depth that specifies the number of bit planes it uses for display. A PseudoColor visual with a depth of 8 displays 256 colors at one time; one with a depth of 12 displays 4096 colors. The TrueColor visual supports depths of 24 and 12 bits. The 24-bit TrueColor visual can display 8 bits for red, green and blue, or over 16 million possible colors at one time. The 12-bit TrueColor visual displays 4096 colors at one time, with 4 bits for red, green and blue.

Choosing the best visual depends on your workstations hardware and the other applications you run. Your workstation must have at least as many bit planes as the depth of the visual that you choose. You generally want to run the 24-bit TrueColor visual if you can; otherwise, try the 12-bit TrueColor or PseudoColor visuals.

High-quality applications should run properly with any of these visuals, but other applications may not. Some applications, such as those that do color table animation, may not run with a TrueColor visual. Some applications may make assumptions about the depth of a PseudoColor visual, for example, that the color index will fit into 8 bits. You can start with the highest quality visual supported by your workstation, try your other applications, and then adjust the visual to fit your system's capabilities.

See your local documentation on how to reconfigure the X server.

[12] This sense of remote execution is different from that offered by the X Window System, which lets you remotely log into a workstation on which IRIS Explorer is installed, reset the DISPLAY environment variable to reference your own screen, and then run IRIS Explorer.