FilerHRun 1.21 (20 Jan 2003)  Musus Umbra, 2003
```````````````````````````` ```````````````````

Since no serious problems have come to light in the past year
or two, I've decided that this version of FilerHRun may as well
lose the *beta* tag and restrictive distribution thingies.

To whit: you may distribute FilerHRun freely provided that the
source code and this help-text is included in any such copies and that
no charge is made for it - this is free software.

Please also see the Licence section below.

-- Musus Umbra, 18.06.01


What is it?
```````````
FilerHRun is a tiny module which runs as a task in the desktop.

It's function is to provide an alternative to the Filer_Run command
that avoids the two major pitfalls of that command.

In addition, FilerHRun provides a few *commands that can be used
to execute specified commands if a named Wimp task is (not) running and
also to quit running tasks.

See below for more details.


Why not use Filer_Run?
``````````````````````
There are some times when you quite specifically do not want to use
Filer_Run.

Here's what happens when you issue "*Filer_Run Foo":

   1. The Filer queues the request until it can gain control of the machine.
   2. The Filer reads the filetype of file 'foo'
   3. If the shift key is held down, the filetype is 'munged' to &FFF
      (TextFile) so that the file will be loaded into an editor.
   3. A DataOpen message is broadcast to all active tasks, offering them
      the file.
   4. If no app. claims the file then the Filer uses the appropriate
      Alias$@RunType_* variable and Wimp_StartTask to start up a new task
      to handle the file.

There are two places that this can go pear shaped, and those are stages 2
and 3.

Specifically, if you want to Filer_Run an Obey file, you do not want the
user to lean on shift (probably accidentally) and end up with it in a text
editor.

Also, some applications will open any file and read its 'header' to see if
they recognise it (eg. a sound sample editor might open any file and check
for RIFF at the start).  Normally this is fine, but if the file that's being
run is in PipeFS then you're stuffed: the data is deleted after it has been
read just once.

Here's what FilerHRun does:

   1. FilerHRun queues the request until it can gain control of the machine.
   2. The module tries to execute the request using Wimp_StartTask.

This means that FilerHRun can be used for some things that Wimp_StartTask
simply can't, and also that the two problems mentioned above are bypassed.

On the other hand, it does mean that FilerHRun isn't really any good for
loading/running /files/ (since it never offers them to running applications),
but it's superb for running /applications/ and/or other commands.



*IfTask and *IfNTask
````````````````````
Often you'll want to do something like run a task if it isn't already running,
perhaps to make WebServe start automatically when Fresco does, or whatever.

For this purpose, FilerHRun supplies two commands, *IfTask and *IfNTask.
Actually, they're both the same command.  *IfNTask just does the opposite
of *IfTask, IYSWIM.  I'll describe *IfTask here, but everything also
applies to *IfNTask.

The command syntax is:

   *IfTask ["]<task name>["] <command>

Note the double-quote characters which are required if the task name
contains a space character but are otherwise optional.  If, for some
ungodly reason, you need to include a " character in the task name, use
"" to do so.

Note also that the name comparison is case sensitive.

The <command> is executed using OS_CLI, so if you want to start a task
up then you're best off using something like *FilerHRun, etc.

Examples:

   *IfNTask "Acorn WebServe" FilerHRun <webserve$dir>
   *IfTask "My App" Error My App is already running!
   *IfNTask FilerHRun Error The FilerHRun task isn't running!


*KillTask and *KillAllTask
``````````````````````````
Sometimes you need/want to be able to quit a desktop application from
the command line (in an obey file, from a taskwindow, etc) and this is
where *KillTask comes in.

The command syntax is:

    *KillTask ["]<task name>["]

The task name is checked as per *IfTask (qv).

*KillTask will try to quit the first matching task that is running (the
order is as stated in the Task Manager's Task window).  *KillAllTask will
try to quit each running tasks whose name matches that given.  This can
be useful if you have (accidentally, I hope) run a gazillion of something...

Both commands are implemented as a special case of the *FilerHRun command.
The main thing to bear in mind is that the quits will only be attempted
when the FilerHRun task next gains control of the desktop.  Also, FilerHRun
and KillTask commands will be serviced in order.



Other things to know about
``````````````````````````
FilerHRun GSTranses it's first argument (and only that one), so you can safely
use system variables for this.

FilerHRun cares not what the argument(s) are:  it'll try to start them with
Wimp_StartTask, whatever.

FilerHRun makes no attempt to ensure that there's enough memory available
to start the command - that's your job.

There's no upper limit on the number of queued commands[1].  Each command will
be issued when FilerHRun next gets control of the machine, but only one
command will be issued at a time (ie. the FilerHRun task will call Wimp_Poll
between commands).  Commands/quits are issued in the order they were presented.

FilerHRun is a module task.  That means that you can quit it without killing
it...  but then any new/pending commands won't be executed...  *KillTask
FilerHRun is, of course, possible...  but probably not useful ;)

When the desktop task isn't running, all the *commands will still work.
No commands/quits will be issued, however, until the desktop task is restarted
(using *Desktop_FilerHRun [from another task], or *Desktop).

The *KillTask commands work by sending a wimp UserMessage (17) with message
code 0 (Message_Quit) to the named task.  A properly behaved task should
quit without fuss when it receieves this message.  No prompts for unsaved work,
no chance to stop the quit, nothing...

RMReiniting the module will clear out any pending commands/quits.



[1] OK, strictly speaking there is:  the commands are stored in blocks claimed
from the RMA.  Since the RMA has an upper limit on its size (4Mb on RO3.1
machines, for instance) and there's a fixed overhead of at least 12 bytes
per command, there /is/ a limit ;)



Installation
````````````
This version of FilerHRun is identical to the previous *beta* version except
that this help text has been updated and the whole thing is now supplied
in an application directory.

The suggested installation is to place the !FilerHRun app. within your PreDesk
directory.



Licence and Disclaimer
``````````````````````
This software is the intellectual property of Musus Umbra.

Permission is granted for unlimited personal use & modification.

Permission is granted for use in third party projects/software provided
that the entirety of FilerHRun (ie. the module, source code, and help-text)
are included unaltered and that no charge is made for FilerHRun - supply it
alonside your software if this is a problem.  IYSWIM.

As usual with freeware, there is no warranty of any kind. The author cannot
be held responsible for any loss/damage arising from the use/inability to
use this software. It is the user's responsibility to determine the fitness
of this software for any purpose they put it to.

(But if it doesn't work, I will try to help :-)



Contacting the Author
`````````````````````
I can most easily be contacted by email as musus@verelanthe.co.uk or failing
that, musus@umbrarum.freeserve.co.uk should also reach me.

I have a website at http://www.verelanthe.co.uk/musus/

The work required to make filerHRun 32-bit compatible was done by
Philip Ludlam http://www.philipnet.com

