CLIanywhere Version 1

                       Created by Ray Lambert in 1990


Overview.

    CLIanywhere is a utility which allows you to open a CLI or Shell on
_any_ screen in your system.  When CLIanywhere is executed, it will cause a
new CLI or Shell to be created on the _topmost_ open screen.  CLIanywhere is
meant to be used with programs such as PopCLI or DMouse.  These programs
allow you to execute a command at the touch of a hot-key (usually
Left-Amiga+Esc) and are most often used to open a new CLI window by
executing "NewCLI" (or "NewShell").  Most of these programs also allow you
to specify the command to be executed.  If you specify "CLIanywhere" as the
command to execute, you can create a new CLI or Shell on the frontmost
screen at virtually anytime just by pressing the hot-key.


Usage.

    CLIanywhere only operates from CLI.  You may execute it from the command
line and then (quickly) move the screen that you want to open a CLI on to
the front, however, CLIanywhere does not take any special steps to ensure
that method of usage will work -- it is really meant for PopCLI-type
programs.  Perhaps in the future this will be supported better.
    Using CLIanywhere from a PopCLI-type program is just as easy as
executing any other program in the same manner.  It may be neccessary to
provide a complete path name for CLIanywhere; see the documentation for your
PopCLI-type program for more information.  CLIanywhere is PURE which means
it can be made resident -- in this case a path name may not be neccessary.
(Making CLIanywhere resident also causes your new CLI to open significantly
faster -- since CLIanywhere is only 564 bytes long, making it resident seems
like a pretty good idea!)
    CLIanywhere allows you to place the command that you wish it to execute
on its command line -- if space characters are neccessary in the command, NO
additional quoting is neccessary.  Alternately, you may place the command
that you wish to execute in a file called "s:CLIanywhere.cmd".  CLIanywhere
will read this file to get your command.  Note that only the first line of
this file will be executed -- any additional lines are ignored.  (See the
enclosed sample file).
    If a command is specified neither on the command line nor in the file
mentioned above, CLIanywhere will use the following default command:

             c:NewShell "NEWCON:0/11/640/50/ CLIanywhereShell "

    Note that it is possible to use CLIanywhere to execute programs other
than "NewShell" and "NewCLI".  In fact, you can use CLIanywhere to execute
nearly any program that opens a window on Workbench, and doing so will cause
that program's window(s) to open on the topmost screen, in the same manner.
    Using CLIanywhere in conjunction with the enclosed program,
"OpenScreen", it is possible to maintain multiple Workbench screens, each
with their own icons, CLI, etc.!!!  (Try creating a screen with OpenScreen,
opening a CLI or Shell on it with CLIanywhere, and then run "LoadWB" from
the new CLI...)  Please read the enclosed documentation for OpenScreen.


How It Works.

    CLIanywhere uses a simple but obscure 'trick' to fool Intuition into
thinking that the topmost screen at any given time is the Workbench screen.
This 'trick' causes no ill effects to the system, and CLIanywhere's
implementation of this 'trick' does not produce any lasting or noticable
modifications to your environment.  The trick works like this:

    All Intuition screens have a 'screen type' value associated with them.
Currently in Workbench 1.3 there are two types called WBENCHSCREEN
(Workbench) and CUSTOMSCREEN (all others).  Workbench 2.0 will introduce one
new screen type, PUBLICSCREEN, however this will have no effect on
CLIanywhere's performance.
    When Intuition tries to find the Workbench screen, it searches the list
of all screens to find the first one which is a WBENCHSCREEN type.  The
screen list is always sorted by topmost to bottommost.
    CLIanywhere temporarily changes the screen type value of the topmost
screen to WBENCHSCREEN (saving its original value) and then executes the
command you give it.  Assuming that the command you give it is "NewShell" or
"NewCLI", Intuition opens the CLI or Shell window on what it thinks is the
Workbench screen, but which we all know is really whatever the topmost
screen is (which could _really_ be Workbench of course).
    Once the command is finished executing, CLIanywhere replaces the topmost
screen's _real_ (saved) 'type' value.  (For you programmer-types reading
this, all of what I describe is done in a protected manner, using
LockIBase(), etc.  However, I cannot keep IntuitionBase locked while I
execute the command because that command will most likely request that a
window be opened, which of course is not possible while IntuitionBase is
locked (result == deadlock).  Therefore, I must save a pointer to the
screen.  Once the command is done executing, I lock IntuitionBase again and
restore the old flag value ONLY IF my saved screen pointer is the same as
the TopMost screen pointer after I re-lock IntuitionBase.  Thus, I am fully
protected.  See the source code for more information.)


Disclaimer.

    Although the trick that CLIanywhere uses is not officially supported by
Commodore (which therefore puts it into the 'hack" category), it does safely
work under all versions of Workbench through 2.0 (yes, I've tested it on 2.0
and it works fine).  I suggest that when you first install CLIanywhere that
you test it a few times (without anything running that could be lost) to be
sure it works properly (and to put your mind at ease [grin]).  This is
especially important to do after you've installed a new version of
Workbench.  I do not expect you to find any problems, however I have not
tested the program in a large number of different system configurations, so
it is possible that it may conflict with something (though I highly doubt
it).  All of this translates to one simple statement:  USE THIS PROGRAM AT
YOUR OWN RISK -- THE AUTHOR ASSUMES NO RESPONSIBILITY FOR THE USE OR MISUSE
OF THIS PROGRAM AND MAKES NO GAURANTEE THAT IT WILL WORK AS DESCRIBED ON ALL
SYSTEMS.


Warnings.

    Some programs do not like to cooperate with strange windows that appear
on their custom screens.  Programs which do not tolerate uninvited windows
usually have good reasons for behaving as such.  In addition, you must
remember that custom screens are really supposed to be private, and
therefore are not required to accomodate uninvited windows.  Deluxe Paint,
for example, doesn't tolerate strange windows on its screen because of
performance reasons -- one of the reasons that DPaint is so fast and
powerful is because it fully takes advantage of the short cuts that are
allowed a custom screen; for example, it does not respect layers.  CygnusEd
Professional also behaves this way and for the same reason -- its
super-fast, blitter-based text scrolling would not be so fast if it took the
time to consider layers.  In fact, most programs which refuse to cooperate
do so for performance reasons, and fail to do so mainly because they ignore
layers (layers is a concept built into Intuition which makes multiple
windows possible).
    Generally, you can still open an uninvited CLI window on a screen which
ignores layers as long as you do not activate other windows on the screen
while your uninvited CLI is there.  For example, it is possible to open a
CLI on CygnusEd's screen, use the CLI and then close it as soon as you're
done with it, with no problem.  However, if you try to type into your
document or scroll the screen while the CLI is there you will end-up with a
mess!  A program such as CygnusEd may open its own windows on its screen,
however this does not imply that it will cooperate with _your_ CLI window.
Usually if a program does open its own windows, it will disable all of its
functions which override the layer system.  For example, when CygnusEd opens
a window (such as its file requester) you are not allowed to type into your
document or scroll through it.
    I have never had a crash as a result of opening an uninvited CLI window
on a private screen.  Nevertheless, I suggest that you avoid doing this with
programs that don't fully cooperate.  If you insist on doing this however,
you should use care.
    Although there are programs which act as I've described, you'll find
that the vast majority of programs do cooperate.

    I must make one final warning which is probably most important of all.
When you open an uninvited CLI window on some program's private screen, that
program has no knowledge at all of your window's existence.  It is possible
that a program may attempt to close its screen while your visiting CLI
window is open on its screen.  While it is very unlikely that this will
actually cause a crash, it is not good practice to allow this to happen.
Therefore, you should NEVER instruct a program to close it's screen before
first closing your visiting CLI window.  Even if this does not crash your
Amiga, you _will_ lose some memory and other resources (at least until you
reboot).
    Enclosed in this archive is a program called "ScreenWatch" which will
help protect you from accidently closing a screen while there is still a
window open on it.  It will also protect you from programs which decide to
close their custom screens on their own (without your instructing them to).
ScreenWatch is a very small program and works quite effectively -- if you
intend to use CLIanywhere I strongly suggest that you also use ScreenWatch
as well.  Please read the enclosed documentation for ScreenWatch.


Legal stuff.

    CLIanywhere is public domain.  I have included the source code so that
other programmers can see how this trick works.  Also, this documentation
has some important warnings and disclaimers in it.  Because of this, I
request that this documentation and the enclosed source code are distributed
together with the executable, without exception.  I would also very much
like the accompanying programs, ScreenWatch and OpenScreen, and their source
code and documentation, to be distributed with CLIanywhere as well.


Get to know me!

    If you have any questions, suggestions, flames, propositions, etc., I
can be reached at the following places:

People/Link:  Analog*Kid    (log on often)

BIX:          AnalogKid     (log on sparsely)

U.S. Snail:   Ray Lambert
              PO Box 1253
              Westport, Massachusetts  02790

Phone:        (508) 677-9217