queue [-h hostname|-H hostname] [-i|-q] [-d spooldir] 
      [-o|-p|-n] [-w|-r] -- command.options

qsh  [-l ignored] [-d spooldir] [-o|-p|-n] 
     [-w|-r] hostname command command.options 

-h hostname

--host hostname

force queue to run on hostname.

-H hostname

--robust-host hostname

Run job on hostname if it is up.

-i|-q

--immediate|--queue

Shorthand for the (now spooldir) and queue (queue spooldir).

[-d spooldir]

[--spooldir spooldir]

With -q option, specifies the name of the batch processing directory, e.g., matlab

-o|-p|-n

--half-pty|--full-pty|--no-pty

Toggle between half-pty emulation, full-pty emulation (default), and the more efficient no-pty emulation.

-w|-r

--wait|--batch

Toggle between wait (stub daemon; default) and return (mail batch) mode.

-v

--version

Version

--help

List of options

The defaults for qsh are a slightly different: no-pty emulation is the default, and a hostname argument is required. A plus (+) is the wildcard hostname; specifying + in place of a valid hostname is the same as not using an -h or -H option with queue. qsh is envisioned as a rsh compatibility mode for use with software that expects a rsh-like syntax. This is useful with some MPI implementations; see See section Running GNU Queue with MPI and PVM..

Start the Queue system on every system in your cluster (as you defined in queue.h) by running queued or queued -D & from the directory in which queued is installed.

The later invocation places queued in debug mode, with copious error messages and mailings, which is probably a good idea if you are having problems. Sending queued a kill -HUP will force it to re-read the profile files and ACL lists, which is good when you wish to shut down a queue or add hosts to the cluster. queued will also periodically check for modifications to these files.

If all has gone well at this stage, you may now try submitting a sample job to the system. I recommend trying something like queue -i -w -p -- emacs -nw. You should be able to background and foreground the remote EMACS process from the local shell just as if it were running as a local copy.

Another example command is queue -i -w -- hostname which should return the best host (i.e., least loaded, as controlled by options in the profile file; See See section Configure a Job Queue's profile File) to run a job on.

The options on queue need to be explained:

-i specifies immediate execution mode, placing the job in the now spool. This is the default. Alternatively, you may specify either the -q option, which is shorthand for the wait spool, or use the -d spooldir option to place the job under the control of the profile file in the spooldir subdirectory of the spool directory, which must previously have been created by the Queue administrator.

In any case, execution of the job will wait until it satisfies the conditions of the profile file for that particular spool directory, which may include waiting for a slot to become free. This method of batch processing is completely compatible with the stub mechanism, although it may disorient users to use it in this way as they may be unknowingly forced to wait until a slot on a remote machine becomes available.

-w activates the stub mechanism, which is the default. The queue stub process will terminate when the remote process terminates; you may send signals and suspend/resume the remote process by doing the same to the stub process. Standard input/output will be that of the 'queue' stub process. -r deactivates the stub process; standard input/output will be via email back to the users; the queue process will return immediately.

-p or -n specifies whether or not a virtual tty should be allocated at the remote end, or whether the system should merely use the more efficient socket mechanism. Many interactive processes, such as EMACS or Matlab, require a virtual tty to be present, so the -p option is required for these. Other processes, such as a simple hostname do not require a tty and so may be run without the default -p. Note that queue is intelligent and will override the -p option if it detects both stdio/stdout have been re-directed to a non-terminal; this feature is useful in facilitating system administration scripts that allow users to execute jobs. [At some point we may wish to change the default to -p as the system automatically detects when -n will suffice.] Simple, non-interactive jobs such as hostname do not need the less efficient pty/tty mechanism and so should be run with the -n option. The -n option is the default when queue is invoked in rsh compatibility mode with qsh.

The -- with queue specifies `end of queue options' and everything beyond this point is interpreted as the command, or arguments to be given to the command. Consequently, user options (i.e., when invoking queue through a script front end, may be placed here):

#!/bin/sh
exec queue -i -w -p -- sas $*

or

#!/bin/sh
exec queue -q -w -p -d sas -- sas $*

for example. This places queue in immediate mode following instructions in the now spool subdirectory (first example) or in batch-processing mode into the sas spool subdirectory, provided it has been created by the administrator. In both cases, stubs are being used, which will not terminate until the sas process terminates on the remote end.

In both cases, pty/ttys will be allocated, unless the user redirects both the standard input and standard output of the simple invoking scripts. Invoking queue through these scripts has the additional advantage that the process name will be that of the script, clarifying what is the process is. For example, the script might called sas or sas.remote, causing queue to appear this way in the user's process list.

queue can be used for batch processing by using the -q -r -n options, e.g.,

#!/bin/sh
exec queue -q -r -n -d sas -- sas $*

would run SAS in batch mode. -q and -d sas options force Queue to follow instructions in the sas/profile file under Queue's spool directory and wait for the next available job slot. -r activates batch-processing mode, causing Queue to exit immediately and return results (including stdout and stderr output) via email.

The final option, -n, is the option to disable allocation of a pty on the remote end; it is unnecessary in this case (as batch mode disables ptys anyway) but is here to demonstrate how it might be used in a -i -w -n or -q -w -n invocation.