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 possible 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 to oommf.tcl 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 that 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 that does not begin with the character + is interpreted as a specification of which 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 that are not recognized by the bootstrap are passed along as arguments to the application the bootstrap launches. Since the bootstrap recognizes command line arguments that begin with + and most other applications recognize command line arguments that begin with -, confusion about which options are provided to which 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 displays its own help message.

Most 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. The -help command line option can also be used to view the complete list of available options. When an option argument is specified as <0|1>, 0 typically means off, no or disable, and 1 means on, yes or enable.

-console

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

-cwd directory

Set the current working directory of the application.

-help

Display a help message and exit.

-nickname <name>

Associates the specified name as a nickname for the process. The string name should contain at least one non-numeric character. Nicknames can also be set at launch time via the Destination command in MIF 2.x files, or after a process is running via the nickname command line application. Nicknames are used by the MIF 2.x Destination command to associate Oxs output streams with particular application instances. Multiple -nickname options may be used to set multiple nicknames. (Technical detail: Nickname functionality is only available to processes that connect to an account server.)

-tk <0|1>

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

-version

Display the version of the application and exit.

In addition, those applications which enable Tk accept additional Tk options, such as -display. See the Tk documentation for details.

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 that 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

On most Unix platforms, if oommf.tcl is marked executable, it may be run directly, i.e., without specifying tclsh. This works because the first few lines of the oommf.tcl Tcl script are:

#!/bin/sh
# \
exec tclsh "$0" ${1+"$@"}

When run, the first tclsh on the execution path is invoked to interpret the oommf.tcl 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 correct 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 Documentation Team
May 11, 2021