OOMMF Home next up previous contents index
Next: OOMMF Launcher/Control Interface: mmLaunch Up: OOMMF Documentation Previous: OOMMF Architecture Overview


Command Line Launching

Some of the OOMMF applications are platform-independent Tcl scripts. Some of them are Tcl scripts that require special platform-dependent interpreters. Others are platform-dependent, compiled C++ applications. It is likely that some of them will change status in later releases of OOMMF. Each of these types of application requires a different command line for launching. Rather than require all OOMMF users to manage this complexity, we provide a pair of programs that provide simplified interfaces for launching OOMMF applications.

The first of these is used to launch OOMMF applications from the command line. Because its function is only to start another program, we refer to this program as the ``bootstrap application.'' The bootstrap application is the Tcl script oommf.tcl. In its simplest usage, it takes a single argument on the command line, the name of the application to launch. For example, to launch mmGraph, the command line is:

tclsh oommf.tcl mmGraph
The search for an application matching the name is case-insensitive. (Here, as elsewhere in this document, the current working directory is assumed to be the OOMMF root directory. For other cases, adjust the pathname as appropriate.) As discussed earlier, the name of the Tcl shell, rendered here as tclsh, may vary between systems.

If no command line arguments are passed to the bootstrap application, by default it will launch the application mmLaunch.

Any command line arguments to the bootstrap application which begin with the character + modify its behavior. For a summary of all command line options recognized by the bootstrap application, run:

tclsh oommf.tcl +help

The command line arguments +bg and +fg control how the bootstrap behaves after launching the requested application. It can exit immediately after launching the requested application in background mode (+bg), or it can block until the launched application exits (+fg). Each application registers within the OOMMF system whether it prefers to be launched in foreground or background mode. If neither option is requested on the command line, the bootstrap launches the requested application in its preferred mode.

The first command line argument which does not begin with the character + is interpreted as a specification of what application should be launched. As described above, this is usually the simple name of an application. When a particular version of an application is required, though, the bootstrap allows the user to include that requirement as part of the specification. For example:

tclsh oommf.tcl "mmGraph 1.1"
will guarantee that the instance of the application mmGraph it launches is of at least version 1.1. If no copy of mmGraph satisfying the version requirement can be found, an error is reported.

The rest of the command line arguments which are not recognized by the bootstrap are passed along as arguments to the application the bootstrap launches. Since the bootstrap recognizes command line arguments which begin with + and most other applications recognize command line arguments which being with -, confusion about what options are provided to what programs can be avoided. For example,

tclsh oommf.tcl +help mmGraph
prints out help information about the bootstrap and exits without launching mmGraph. However,
tclsh oommf.tcl mmGraph -help
launches mmGraph with the command line argument -help. mmGraph then display its own help message.

All the OOMMF applications accept the standard options listed below. Some of the OOMMF applications accept additional arguments when launched from the command line, as documented in the corresponding sections of this manual. When an option argument is specified as <0|1>, 0 typically means off, no or disable, and 1 means on, yes or enable.

-version
Display the version of the application and exit.

-help
Display a help message and exit.

-tk <0|1>
Disable or enable Tk. Tk must be enabled for an application to display graphical widgets. However, when Tk is enabled, on many platforms the application is dependent on an X Windows server. If the X Windows server dies, it will kill the application. Long-running applications which do not inherently use display widgets support disabling of Tk with -tk 0. Other applications which must use display widgets are unable to run with the option -tk 0. To run those applications that require -tk 1 on a Unix system with no display, one might use Xvfb .

-cwd directory
Set the current working directory of the application.

-console
Display a console widget in which Tcl commands may be interactively typed into the application. Useful for debugging.

In addition, those applications which enable Tk accept the Tk options like -display. See the Tk documentation.

The bootstrap application should be infrequently used by most users. The application mmLaunch provides a more convenient graphical interface for launching applications. The main uses for the bootstrap application are launching mmLaunch, launching pimake, launching programs which make up the OOMMF Batch System and other programs which are inherently command line driven, and in circumstances where the user wishes to precisely control the command line arguments passed to an OOMMF application or the environment in which an OOMMF application runs.

Platform Issues

The Tcl script oommf.tcl begins with lines like:

#!/bin/sh
# \
exec tclsh "$0" ${1+"$@"}
On most Unix platforms, if oommf.tcl is marked executable, the interpreter tclsh (on the execution path) will be invoked to interpret the script. If the Tcl shell program cannot be invoked by the name tclsh on your computer, edit the first lines of oommf.tcl to use the proper name. Better still, use symbolic links or some other means to make the Tcl shell program available by the name tclsh. The latter solution will not be undone by file overwrites from OOMMF upgrades.

If in addition, the directory .../path/to/oommf is in the execution path, the command line can be as simple as:

oommf.tcl appName
from any working directory.

On Windows platforms, because oommf.tcl has the file extension .tcl, it is normally associated by Windows with the wish interpreter. The oommf.tcl script has been specially written so that either tclsh or wish is a suitable interpreter. This means that simply double-clicking on an icon associated with the file oommf.tcl (say, in Windows Explorer) will launch the bootstrap application with no arguments. This will result in the default behavior of launching the application mmLaunch, which is suitable for launching other OOMMF applications. (If this doesn't work, refer back to the Windows Options section in the installation instructions.)


OOMMF Home next up previous Contents index

OOMMF Documentation Team
January 15, 2004