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 configuration options via the Configuration menu in the Map Editor

  • setting environment variables

  • remote execution of modules

The Configuration menu provides an interface to where the settings are stored in the Windows registry and replaces the _explorerrc and Explorer.config of earlier releases of IRIS Explorer.

A.1 The Configuration Menu

IRIS Explorer reads configuration information from the registry 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

This information is stored in the user-specific part of the registry, so different settings can be stored for each user. The settings may be exported to a file or imported from a file to facilitate transfer of settings from one user or machine to another.

A.1.1 Configuration Menu Options

Note that some of the options on the Configuration menu are only available when the Map Editor is empty.

A.1.1.1 General

The General Configuration dialog box allows users to set values for the following configuration options:

  • default map, module and data directories

  • the size of the shared memory arena (the sum of the megabyte and kilobyte values is used; an arena size of zero – 0 in both boxes – means that shared memory is not used)

  • the size of the Map Editor grid (for use when the Grid On option on the Layout menu is on)

The user can also turn the following on or off:

  • Warnings about unknown widgets in maps. Turning this option off is useful if a module's widgets have changed since the map was created, for example.

  • Confirmation when exiting the Map Editor or before deleting the Map Editor contents (via File|New or Edit|Destroy All)

  • Confirmation of whether a module's log file (if visible) is to be deleted when the module is destroyed

  • Replacement of a module if the module dies

  • Whether modules are saved in alphabetical order within a map

Clicking on the OK button will update the settings; clicking on Cancel will discard any new changes.

A.1.1.2 Librarian

The Librarian dialog box enables the user to edit the module search paths and categories displayed in the Module Librarian.

The search path is a list of directories (folders) in which IRIS Explorer looks for modules and maps. New directories can be added to the list by typing the full path, for example

in the text slot underneath the list of existing search paths.

The directory specification can include the EXPLORERHOME environment variable (set automatically by IRIS Explorer on startup) in either of the forms shown below:

where mymodules is the name of the directory under the IRIS Explorer root directory. Then click on the Add button to add this path to the list. The new path is added to the bottom of the list; to rearrange the search order, click on the path to be moved to select it and then click on the up or down arrow buttons to the right of the Add, Edit and Remove buttons.

To edit a path already in the list, click on the path you wish to edit to select it and then click on the Edit button. The selected path will appear in the type-in text box. Use the Add button to return the modified path to the the search list, as detailed above.

To remove a path from the list, select it by clicking on it, then click on the Remove button.

The Categories area lists the category names that will be displayed in the Module Librarian. For each category name, there is a corresponding list of modules.

Use the Add... button to bring up the New Category dialog box. Type the name for the new category in the Category Name text box. To specify all modules from a particular directory or directories for this category, type the path in the text box at the bottom of the Paths area and click on the Add button to add this path to the list. The Edit and Remove buttons allow the selected path to be modified or deleted from the list respectively. The names of individual modules for this category are entered in the type-in slot at the bottom of the Names area. The Librarian looks for these modules in the search paths defined in the previous dialog box. Use the Add button to add the module to the list, or select a module from the list and click on Edit or Remove to modify the name or delete it from the list. Click on OK to accept these changes or Cancel to ignore any new changes.

The Edit... button brings up the Edit Category dialog for the selected category, which works in a similar way to the New Category dialog just described. The category name and the paths and names already defined for the category are displayed and can be added to, edited or removed in the same way as in the New Category dialog box. Click on OK or Cancel to accept or reject the changes respectively.

The Names sections of the New Category and Edit Category dialog boxes can also accept shell wildcards such as * and ?. For example, the Readers category contains the entry Read* in the Names list, which finds all modules which begin with the letters ‘Read’ in the search paths.

Click on the OK button to accept any changes; the Librarian will be automatically updated. Click on Cancel to abandon any changes.

A.1.1.3 Wire Settings

The Wire Settings dialog box allows the user to select a different wire color for each data type and to choose whether multiple connections between the same two modules are shown as multiple wires or just one wire. Click on the OK button to accept the changes, the Cancel button to reject the changes or the Default button to return to the default settings. See Section for more details.

A.1.1.4 License

The License option from the Configurations menu brings up the Install IRIS Exporer License dialog box. This provides an interface for installing the license management software required for IRIS Explorer to run. Follow the instructions given in the dialog box to install the licensing software.

A.1.1.5 Remote Hosts

The Remote Host Configuration dialog box can be used to specify how new LCs (local communication servers) are started on remote host machines when you select the New Host option from the File menu.

Host name is the name of the remote machine.

rsh command line specifies the remote shell command (usually rsh). If the word HOST appears in this command line, the hostname is substituted in its place when executing the command. If the word HOST does not appear in the command, it is appended to the end.

The Explorer location entry can be used as a means of specifying the directory where IRIS Explorer is installed on a remote UNIX machine (if it is not installed in the default location /usr/explorer). This removes the need for the directory to be specified (via the EXPLORERHOME environment variable) in your startup script (e.g. .cshrc) on the remote machine (at least for the purposes of connecting from the Windows machine). This option should only be used with remote UNIX hosts. For Windows hosts it should be left as ${EXPLORERHOME} as the remote shell daemon on the remote host knows where IRIS Explorer is installed.

Type the required details into the text slots, then click on Add to add a host to the list. To remove a host from the list, click on the hostname in the list to highlight it, then click on the Delete button. To edit an entry in the list, click on the hostname in the list, then click on Edit. This will remove that entry from the list, displaying the details in the text slots. Amend the details as required, then click on Add to return the entry to the list.

Click on OK to accept any changes or Cancel to discard them.

A.1.1.6 Advanced

The Advanced Configuration dialog box may be used to set various advanced options.

The Temporary directory slot is used to select the directory where temporary files are written. This is %EXPLORERHOME%\tmp by default.

The Visual C++ directory specifies the top-level directory where the Microsoft Visual C++ compiler is installed. By default this is

C:\Program Files\Microsoft Visual Studio

The Visual Fortran directory is the top-level directory for the Microsoft Visual Fortran compiler. This directory is usually the same as the Visual C++ top-level directory. You only need to specify the Visual Fortran top-level directory if it is in a different location. If you have set up the environment variables such that compilers can be run from the command line, you do not need to specify either of these paths here.

The Diagnostics text slot can be used to run IRIS Explorer in various debugging modes:

  • mdtofile – the module debugger sends output to a file in %EXPLORERHOME%\tmp\mcw-debug instead of to the debugging log window for the module.

  • mdall – run all the modules using the module debugger. All output goes to files in %EXPLORERHOME%\tmp\mcw-debug in this case.

If you select the Prescan new librarians for port types option, IRIS Explorer does an initial background search to gather the port type information when it starts up or when the (local) Librarian has been updated via Display|Update. This saves time when you first select Search|Ports from the Librarian. If this option is not selected, the port type information is collected the first time a port search is done, so this first search takes longer than subsequent searches.

The Shared memory arena buffer specifies the minimum amount of shared memory (in megabytes) to leave free when creating a shared memory arena. If the shared memory arena size (set in the General Configuration dialog box) is less than the shared memory arena buffer then the arena size value is used as the buffer value.

The Base address of shared memory arena text slot allows the user to specify a hexadecimal value the where the shared memory arena will start in memory (e.g. 0x40000000).

Click on the OK button to accept any changes in this dialog box, or click on the Cancel button to abandon any changes.

A.1.2 Importing and Exporting Configuration Files

The configuration settings can be exported to a plain text file via the Export option on the Configuration menu. Selecting this option enables the user to choose a filename and location for the file via a pop-up file browser dialog.

Files generated by the Export facility can be imported back into IRIS Explorer via the Import facility. There are two options for importing a configuration file: Import (merge) and Import (replace). In both cases, a file browser dialog allows the user to select the file to import. The merge option merges the settings in the file with the existing settings, whilst the replace option replaces all the settings with those from the file.

A.2 IRIS Explorer Environment Variables

By default, the IRIS Explorer system is installed in directory C:\EXPLORER50. When the IRIS Explorer program is started up, it automatically sets its own copy of the environment variable EXPLORERHOME to point to the directory in which the IRIS Explorer system has been installed. The user no longer needs to set an environment variable to facilitate this.

You can still use the EXPLORERHOME environment variable to specify, for example, paths for maps and modules. When a map is saved, where appropriate the full module paths are automatically replaced by path specifications that include the EXPLORERHOME environment variable; this facilitates running maps on one machine that were created on another (e.g. if the copies of IRIS Explorer were installed to different locations on the two machines). See Section A.1.1.2 above for more details. In file selector dialog boxes the Windows specification of the environment variable can be used, for example %EXPLORERHOME%\maps\simple.map could be typed directly into the File name: text slot.

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 (Windows NT/2000).

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[9].

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.

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 File menu of the Map Editor, 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 another Windows machine, which must also have IRIS Explorer installed, or 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. You are referred to the documentation for your UNIX version of IRIS Explorer for more information about CXGLTYPE.

A.3.2 The rsh, rshd and cxRshd Utilities

In order to make a connection between two machines, IRIS Explorer uses the Windows rsh utility. This is a utility which is also standard on machines running the UNIX operating system.

Typically on UNIX machines, 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).

As part of Windows, only the rsh half of the system is supplied; a Windows user can therefore send commands to be executed by the rshd on a remote UNIX system, but not vice versa.

For this reason, a version of the daemon is supplied for use on Windows machines with IRIS Explorer. This daemon, named cxRshd, has limited capabilities; it cannot process general purpose requests from remote machines, but only requests of a type required for use by IRIS Explorer. In fact, the format of these requests is exactly that used to connect two copies of IRIS Explorer running on UNIX machines.

This ensures that it is possible to mix Explorer modules between a UNIX and a Windows machine without the local machine needing to know what operating system the remote machines uses. If the remote machine happens to use UNIX, then the regular rshd daemon on that machine will process the rsh request to start the parts of IRIS Explorer necessary to launch modules; if the remote machine is Windows, the job will be done by cxRshd.

A.3.3 Starting the IRIS Explorer Remote Shell Daemon cxRshd

If you intend to run IRIS Explorer on one machine, either under Windows or UNIX, and during your IRIS Explorer session launch modules on a Windows machine connected by network, you must first ensure that the cxRshd daemon is running on the remote Windows machine in order to process requests from the first machine. Under the bin directory of the installed copy of IRIS Explorer on the remote machine there exists an executable file called cxRshd.exe.

Start cxRshd running, and you should see a message like this:

Starting the IRIS Explorer remote shell daemon ...

where %EXPLORERHOME% stands for the root directory of the installed copy of IRIS Explorer. If you have already started cxRshd previously and it is still running, you will see a message like this:

Starting the IRIS Explorer remote shell daemon ...
%EXPLORERHOME%\bin\cxRshd: cannot start daemon because the rsh port
is already in use (possibly by another copy of this program).

This message is harmless if cxRshd is already running. However, it is possible that cxRshd is not running, but that some other third-party program (for example another remote shell daemon) is running and monitoring for input on the rsh port. If this is the case, remote copies of IRIS Explorer will not be able to run modules on this machine, because whichever program is monitoring the rsh port will not be able to process the commands sent by IRIS Explorer. In this case, it will be necessary to stop the program which is monitoring the rsh port, and start cxRshd instead. Alternatively, the supplied program SH.EXE could be used if you do not wish to stop the other remote shell daemon. In this case contact NAG for further information on the running of the SH.EXE program.

The cxRshd executable will start running in its own window. Any output from cxRshd (see Section A.3.3.1) will appear in this window. Destroying the window (for example by closing it, or by issuing a control-C interrupt in it), will kill the IRIS Explorer remote shell daemon.

As a rudimentary test that cxRshd is running correctly, go to another machine that is networked to this machine and has an rsh command. Issue an rsh command to see if cxRshd responds. For example, if you started cxRshd on venus, which is networked together with a machine named mars, at a command prompt on mars type:

rsh venus hello

If cxRshd is operating correctly, you should get back a message like this:

venus: IRIS Explorer rshd: sorry - the remote shell daemon you have
contacted is for IRIS Explorer use only
rsh: can't establish connection

This means that the cxRshd daemon on venus has received your request to execute the command hello, but, not recognising hello as coming from another IRIS Explorer, doesn't know what to do but send an apologetic message back.

A.3.3.1 Starting cxRshd in Verbose Mode

When you start cxRshd, you may optionally start it in verbose mode by using the /verbose switch. In this case, whenever a connection is made, cxRshd will output a short message saying where the message came from and what the command was. For example, on venus:

venus> cxRshd /verbose

On mars:

mars> rsh venus hello

When cxRshd on venus receives the command from mars, it will report something like the following:

cxRshd: request received from user mick on mars (
cxRshd: the command is "hello"

A.3.4 Networking Issues

In order for rsh, rshd and cxRshd to collaborate properly, your machine must be correctly configured for Networking.

When IRIS Explorer on one machine (say mars) attempts to contact IRIS Explorer on another machine (say venus), the message sent includes details of a socket on mars through which IRIS Explorer on venus can communicate. The socket details include the hostname of mars as mars is known to itself.

For example, if mars is in domain nag.co.uk, then the message sent to the cxRshd or rshd on venus may include the information "-socket mars.nag.co.uk 1365 183", or it may just be "-socket mars 1365 183". In either case, venus must know how to contact mars.nag.co.uk or mars respectively; if it does not, the socket connection cannot be made. Thus, if the message from mars identified itself only as mars, but venus only knows of a machine named mars.nag.co.uk, the connection may fail.

If you experience problems when attempting to run modules on a networked machine, try using the Network utility in the Windows control panel, and ensure that TCP/IP software is installed (‘TCP/IP Protocol’ should appear in the list ‘Installed Network Software’). If it is not installed, click on the ‘Add Software’ button and follow the instructions – you will need your Windows system installation CD or diskettes.

The Network utility allows you to configure TCP/IP to use DNS (the Domain Name System), whereby information about the names and addresses of networked machines is stored in one place (on a name server), or to use the simpler method of storing names and addresses in the LMHOSTS and HOSTS files (e.g. in \WINNT\SYSTEM32\DRIVERS\ETC\HOSTS). Which method you use depends on the requirements of your network site.

A.3.5 Troubleshooting

  • If when you use the New Host ... option from the File menu on the Map Editor, you get an error popup window saying

    Local Controller on "venus": unknown host
    then the local machine simply knows nothing about venus. If venus is indeed a genuine networked machine, then it may simply be the case that you need to add the name and address of venus to the HOSTS file before trying again.
  • If when you use the New Host ... option from the File menu on the Map Editor, you get an error popup window saying

    Local Controller on "venus": Could not exec the local controller
    then venus is contactable, but probably does not have the remote shell daemon (cxRshd or rshd) running.
  • If when you use the New Host ... option from the File menu on the Map Editor, a blank "Librarian on venus" window pops up, and then IRIS Explorer hangs (i.e., no more modules can be launched), then probably the remote shell daemon running on venus has received the message asking for an IRIS Explorer local controller to be started, but the socket connection between the two machines has not been made.

    This may be because the remote machine (venus) does not recognise the name of the local machine (see Section A.3.4). Try looking in the IRIS Explorer log file to see what message was sent to the remote machine. The log file is created by IRIS Explorer in the IRIS Explorer temporary directory %EXPLORERHOME%\tmp, where %EXPLORERHOME% is the root directory of the installed copy of IRIS Explorer on the local machine. In the log file you should see something like this

    May 10 16:02:10
      gc:0 gc[00118]: Launching a remote local controller using the
                      following command:
    May 10 16:02:10
      gc:0 gc[00118]: rsh venus -n sh -c
                      '${EXPLORERHOME-/usr/explorer}/lib/lc lc
                      -socket mars.nag.co.uk 1036 118 -tag 1 -fork'
    ensure that, outside IRIS Explorer, from venus you are able to connect to the machine mentioned in the socket description – in this case, mars.nag.co.uk. The easiest way to do this is to issue an rsh command from venus:
    rsh mars.nag.co.uk dir

    If you get in reply something like

    mars.nag.co.uk: unknown host
    then you need to configure venus to recognise mars.nag.co.uk using the steps outlined previously for mars, e.g. by editing the HOSTS file on venus.

[9] The modules DisplayImg, GenerateColorMap, Render, TransformGen, and WaveFormColorMap cannot be run across a network.