💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Utilities › Mikes.Shellv1.0.D… captured on 2024-02-05 at 11:44:59.

View Raw

More Information

⬅️ Previous capture (2023-01-29)

-=-=-=-=-=-=-

	
** Note: Version 1.0 lacks the MACRO program described in the following

documentation.  It will be present in version 2.0, if I decide to release
it.  Also in version 2.0, Multitasking, improved clock commands, a
notebook/calendar feature, probably with a timed reminder option tied into
the clock routine, I haven't decided yet, a COPY command, a TYPE command,
an interrupt-driven keyboard buffer routine, and a couple little extras that
won't be mentioned here because I haven't thought of them yet.

                        *********************************
                        *                               *
                        *        Michael's Shell        *
                        *          Version 1.0          *
                        *                               *
                        *          A.K.A. SHELL         *
                        *                               *
                        *     Courtesy of the author,   *
                        *         Michael Pender        *
                        *         Copyright 1989,       *
                        *      all rights reserved.     *
                        *                               *
                        *********************************

This program is shareware, it costs $30.  For your $30 you get the newest version on disk, written documentation, source code, two free upgrades, and a list of other shareware products I make.  I reserve the right to refuse any agency the right to reproduce this in any form.

I believe in the basic concept of Shareware, that software should be cheap,
and that you should be able to try a piece of software before shelling over
your money.  Individuals should feel free to copy this program for their own
use.  If you like it send me the $30, maybe you'll like the newest version
even better.  If you know me at all, you know that I tend to upgrade programs
I write almost constantly.

If you decide you don't like it, give it to a friend.  I'm far from rich,
and this particular project took me over two years and some investment to
complete.  I write this stuff as a hobby, and I don't expect to make any real
money at it, but you could always surprise me. :^)

If the medium doesn't work out and I feel like I'm getting taken, I won't
stop writing the stuff, I just won't share it anymore.

I can also be reached to answer questions.

Michael Pender c/o Worcester Polytechnic Institute
100 Institute Rd., Worcester, Ma. 01609.  Box 1942
Bitnet:   greyelf@wpi.bitnet
Internet: greyelf@wpi.wpi.edu

Background:

I started this program some two years ago.  It was originally named Disk
Commander, when I tried to implement it under DOS 3.3.  Then I called it
Michele for a while (My Shell, get it?) after my last girlfriend (read
that girlfiend).  Now I just call it SHELL (I was going to call it C.SHELL
but decided to put it to rest).  I had a lot of ideas that didn't work out
(What do you mean I can't call DOSCMD with a VERIFY request?), and found
a few errors in the Prodos 8 Technical Reference Guide the hard way, but
all in all it seems to work, and it makes programming under Prodos BASIC
a little easier to handle.  Well at any rate it makes one slightly less
likely to tear their hair out because of a dumb mistake.

Shell itself is an external command for Prodos.  It intercepts commands
after Prodos is done with them, but before BASIC gets a crack at them.
It intercepts the external command vector, and saves the pointer to the
next external command, but for reasons discussed later you will see why
it is not advisable to load other external commands before SHELL, as
SHELL may interfere with their operation.  The theory is simple, if the
command makes it to SHELL, it is either a command for SHELL, a BASIC
command, or someone goofed typing.  SHELL goes to its default directory,
looks for a command of the name typed, and if a file of that name is found
it is loaded and executed using the Prodos smart run (dash) command.

The program is effectively a new programming environment.  The nature of the
command structure is extensible, making the setup very easy to customize
to one's tastes.  My younger sister found it amusing to create commands
to respond to swearing.

The program serves three main functions:

1. The extensible shell allows for a person to create their own commands
   to simplify tasks under BASIC.  The shell also allows a means of support
   for custom drivers for different computers.  For my computer (a Laser 128)
   I wrote a custom clock routine (too cheap/poor to buy one) that taps mouse
   interrupts.  Non-ROM devices are not only possible under Prodos, but may
   now be made convenient, just use the included INSTALL program and custom
   drivers are automatically loaded on startup.  I wrote a routine a while
   back to intercept the printer output for slot #1 and drive my electronic
   typewriter (and the manufacturer's said its not Apple-compatible :^)).
   Now all I need is a good no-slot digitizer, hmmmmm...

2. To relieve some of the possibility for errors.  The GO command for
   example makes a backup of your program in case you need to revert
   back.  Ever accidentally delete a line in a program and can't figure
   out what it was?  The recall command can usually repair a program
   accidentally NEWed out of existance.  The NEW command itself was
   altered to allow one to back out.  And even the BYE command can
   be recovered from using BOOTSLOT's zero function.  These commands
   are not perfect, nothing is, but they can prevent some minor
   catastrophes that I've encountered before.

3. To make a friendlier user-interface.  The shell allows for nearly
   English command recognition.  In future versions this shall be
   improved upon.  The control-key replacements make some tasks
   easier, and the user-definable macros should handle the rest.  Also
   various editor functions have been added, allowing one to insert
   and delete characters while doing ordinary input, as well as giving
   a purpose to the TAB and DEL keys on your apple's keyboard.

Using SHELL:

If you bought the disk you're all set, the program will boot up, and
install itself.  This is fine if all you want to do is copy the
program disk and store BASIC programs on the same disk.  However
many people will be transferring this to another disk (/ram is a
good choice).

This has its benefits and drawbacks.  Selecting a different disk
as home for your commands has been made rather easy to do.  Just
set the prefix to the directory you want, using the PREFIX command,
and -/WOS/SHELL (assuming its still on the WOS disk) to invoke
the shell.  SHELL will read the current prefix and store this as
the directory in which to ALWAYS find its commands.  You can change
the command directory prefix using the CPREFIX shell command.
This is done because in ordinary programming you may change your
current prefix several times.  Some of the commands do this themselves.
If the prefix is set, SHELL always knows where to look.  But remember,
YOU MUST SET THE PREFIX BEFORE INVOKING SHELL!!!!

Once SHELL is invoked it loads in at $4000, and checks if it is already
present.  If not it relocates to the absolute address $9600.  Yes, I
said ABSOLUTE ADDRESS.  Programmers beware!!  This was necessary both
to save me work, because I couldn't figure out how the bitmap worked,
and because the nature of the program requires it.  SHELL must be
invoked before other external commands you may choose to use.  For example,
if you had the very popular utility DOGPAW on disk, and you loaded it
before SHELL, depending on your use of directories you might end up
just reloading the program every time you issued the DOGPAW command.
SHELL would go to disk, looking for a file called DOGPAW.  Finding it
it would load it.  DOGPAW would see that it was already present in
memory and would return to BASIC.  Hence, DOGPAW wouldn't work properly.

Also the absolute address is a convenience to programmers who wish
to write routines compatible with SHELL, not only because you know where
it is, but when your routine is invoked SHELL made a copy of the
input buffer, telling Prodos not to parse the parameters, but storing
the command library prefix in a buffer at $9700, the command as it
appeared in the input buffer at $9800, and the prefix followed by the
name of the routine at $9900.  The library prefix is stored as length,
prefix (high bit clear), the input buffer is an exact replica, and
the buffer at $9900 is the string length, prefix followed by the routine
name.  This allows commands to have parameters that BASIC.SYSTEM would
not recognize and would generate an error for.
  
Every command you type after SHELL is installed that is not a normal
Prodos command under BASIC.SYSTEM command will be looked for on disk
in the volume specified.  This includes basic commands like NEW or
LIST.  So for speed, it is advisable to make your default prefix on a
ramdisk, also because you'll know exactly what commands are there:
copy only the ones you use.

Any command you create and place in the COMMANDS directory then becomes
part of your available disk-based command set, you need not turn the
power off or reboot or any such thing.  BE WARNED!!!  Fooling with some
of the BASIC commands can have side effects.  If you make a BASIC program
called LIST and then go to list a different program you just lost it
when the BASIC program named LIST was loaded into memory.  You could either
make an EXEC file called LIST that calls the BASIC code as I did with NEW,
or you could use :LIST which will be interpreted as a BASIC command, not
a disk command.  The second method is by far more dangerous, since you
only need forget once.

Macros are also supported.  Just set up an EXEC file of any form you choose,
call it by a letter name (A-Z, one character only), and place it in the MACRO
directory (inside the COMMANDS directory).  Then just type the open-apple
(open-triangle for us Laser users) and the letter, and that macro will execute.
See the notes on the MACRO command for more details.

Included commands:

These commands are invoked by just typing their name after the SHELL program
has been loaded into memory and executed.

BACKUP:

Certain commands, such as the GO command make a copy of the program in memory
before continuing.  The program is saved on disk as a file called BKP.  This
is because some of the commands are written partly in BASIC, and it just
wouldn't do to accidentally wipe out hours of work by typing a command you
weren't familiar with.  Hence the purpose of the BACKUP command.  Whenever you
make a major step forward in a program use the GO command to run it instead.
Then should you make a major error and accidentally wipe out part of your
program, merely typing BACKUP will revert to the last version saved.

See also GO, NEW, and RECALL.

BOOTSLOT:

This is actually a program I wrote independently before SHELL was yet
completed.  BOOTSLOT is a SYS file, making it easy to run from many program
selectors, including the BASIC.SYSTEM quit code.  BOOTSLOT was originally
written to allow people with selector programs to chose a slot with a
non-Prodos volume to boot.  That is, if a person has a Prodos formatted 3.5
inch drive in slot 7, which comes up automatically when they turn on the
power, and they want to boot from a device in slot 6 (say a 5 1/4 inch disk
with a game in DOS 3.3 on it), all they need do is select the BOOTSLOT
program, and then press the number key for the appropriate slot they wish
to boot from, in this case, the '6' key.

BOOTSLOT has another important feature however.  If you're working in BASIC
and you use the BYE command to leave by accident, normally your program
would be lost without hope.  But the 0 option allows a person to exit back
to the last system program that was running (sort of).  Unfortunately to
have this feature work the program itself had to be set up as a system
program, so it must load in at $2000, possible disturbing other system
programs.  In general, don't expect the 0 option to allow you to return to
your favorite word processor or modem program, but it will allow you to
return to BASIC quite nicely, where your program should be fine.


	
**  One warning, if your program is so long that it extends into the the

Hi-res page one area, part of the program may be destroyed when BOOTSLOT
itself loads in.  This only applies to programs longer than 6144 bytes
(roughly 13 blocks on disk or bigger).

C80:

This is a very simple command provided for demonstration purposes that
effects a PR#3 command, followed by the CATALOG command.

CLOCK:

This short routine (don't confuse short with simple, this routine was a pain
in the foot to write) places a little clock in the upper left corner of the
screen.  It is quite accurate, provided the user does little disk access.
This is because interrupts are deactivated during disk accesses, and the
routine is driven by the interrupts of a mouse card in slot 4.  If you
have a mouse card in slot 4 (no mouse necessary), you can install the clock
by typing the clock command.  Being interrupt driven clock is easily forced
off though, so to reconnect it at any time, just use the clock command
again.  As it is currently configured, the clock command shows elapsed time 
wince the routine was activated.  This is to remind certain people (myself
included) that they've been spending too much time at the box and they 
could use a good stiff cup of tea or some sleep.


	
** Warning, disconnect the clock command before entering another system

program.  Just press reset once to disconnect it.

See also ICLOCK.

CPREFIX:

This command allows one to change the command library prefix after the SHELL
program has already been installed.  Normally SHELL selects the prefix
directory active when it is first installed, but CPREFIX allows one to
change it on the fly.  If you copied all the commands to a ramdisk say, and
wanted to change the prefix so SHELL would look there instead, or if you
goofed, and hadn't set the prefix before running SHELL, this allows one to
change the prefix to something new.

The new volume/directory selected need not be online at the time CPREFIX is
used.

ECHO:

This command issues a PR#1 command to the system, turning on the printer
for most Apples with printers, then it issues the Ctrl-I I SSC command,
enabling the output of text to the screen and printer simultaneously.
This command too is provided for as a demonstration.

EJECT5/EJECT7:

These commands allow apple users without a convenient means of ejecting a
disk in a 3.5 inch apple drive to eject the disk easily.  As the name
implies, just type the command, and the disk pops out.  


	
** Warning, no attempt is made to close files before popping the disk

out.  Do so at your own risk.

GO:

The GO command is much like issuing the run command from BASIC, except that
it also makes a copy of the current program in memory, and saves it on disk
as a file named BKP.  This is useful because it is no more inconvenient than
typing RUN (hell its even one character shorter), but you have a current
backup of your file in case all hell were to break lose.

See also the BACKUP command.

ICLOCK:

This routine is much like the CLOCK command in the way it processes interrupts.
Unlike the CLOCK command however, ICLOCK stands for Invisible CLOCK.  Unlike
its friend CLOCK, ICLOCK does not place a clock in the corner of the screen,
rather it is used for time and date-stamping files for Prodos.  Like CLOCK
however it is easily removed, and easily re-activated by using the ICLOCK
command.  Both clocks will not run at the same time, only the first one 
installed will.  This clock is slightly less obvious when it is disconnected,
but an easy test exists.  Press control-g (with SHORT deactivated), or
PRINT CHR$(7).  If it sounds like a warble, the routine is active.
Press RESET to deactivate.

ICLOCK reads the current time and date from Prodos, so if you've used a
routine other than DATE or TIME to set the time, it will still work.


	
** Press reset to deactivate the ICLOCK routine before entering another

system program.

See also CLOCK, TIME, DATE.

NEW:

The NEW command is activated like the others, when you type the word NEW
in immediate mode.  Many was the time I accidentally wiped a program out
of this world with the NEW command under Applesoft.  This command is very
similar, it just prompts you to make sure you know what you're doing before
it continues to wipe your program out of existance.

See also GO, BACKUP, and RECALL.

RECALL:

This is a very short machine language program I wrote a few years ago to
bring an Applesoft program back from the dead under DOS 3.3.  It works
just as well under Prodos.  Supposing you've neglected to avail yourself
of the GO command recently, and the back-out now option of NEW, and went
ahead and wiped your basic program out anyway.  RECALL will rebuild the
Applesoft pointers, allowing you to bring that program back from the dead.
Using the GO and BACKUP commands is preferable, because RECALL will rebuild
the last Applesoft program in memory, which just might be the BASIC part of
the NEW command itself.  But if you're in a bind, or you didn't happen to
use my modified NEW command, you're probably in luck.

(Just for safety learn how this works on an unimportant file first, huh?)

See also GO, BACKUP, and NEW.

SHORT:

This command redefines the output of a few of the control keys, the TAB key
and the DEL key.  On a Laser the selection of keys should be obvious, as for
the most part they correspond to the function keys atop the keyboard.

This program reroutes the input vector from slot #1.  Since most people have
Their printer card in this slot, it should not be a problem.  To then access
the driver a person need only type IN#1 to connect to it at any time,
or IN#0 to disconnect it.

The program itself relocates the necessary data and protects itself by 
lowering HIMEM.  Therefore it is always available after being loaded.
The loader itself checks to make sure it is not already present in memory
before loading it in again.

Laser Key    Value     Function
TAB          Ctrl-I    Like pressing the forward arrow key 5 times.
                        Makes editing much quicker.
DEL          ASCII 127 Backspaces once, types space, and backspaces
                        again.
F1           Ctrl-@    Enters monitor by typing CALL-151 (return)
F2           Ctrl-A    Leaves monitor by typing 3D0G (return)
F3           Ctrl-B    Types CAT (return) for a 40 column catalog.
F5           Ctrl-D    Types TEXT:LIST (return)
F6           Ctrl-E    Types POKE 33,33 (return)
F7           Ctrl-F    Types LOAD (no return)
F8           Ctrl-G    Types SAVE (no return)
F9           Ctrl-L    Types PREFIX (no return)

See also MACRO

VLIST:

This command notes the current online volumes and displays them to the
screen.  The command itself is quite simple, but this command is not
included merely for demonstration purposes.  The current prefix is
maintained, so you needn't worry about accidentally saving something on
the wrong volume.  However, if no prefix had been set before calling 
this command, the prefix after will be set to the prefix of the current
drive.

VSET:

This command is actually a BASIC program I wrote independently.  Its another
one of the many program selectors available.  This one however is accessible
at the stroke of the letters VSET.  It uses a smart run command (-) so 
it can run BASIC, Binary, Exec, or System files, assuming of course the
program can normally be run using the dash command.  That is, come system
programs would overlay on BASIC, so they are not allowed to load via the
dash.   

Programmer's notes:

BASIC:

Shell works well at the command level, but you will find that commands
set up as EXEC files don't respond well to activation within a program,
some of these will be corrected by version 2.0, but the tools available
to an assembly language programmer are also more limited in some ways.
There are many Prodos commands that cannot be executed from assembly level.
My advice, stick to the non-exec commands from inside your programs, or
if you really neeed that function, look at its create file to see how
it was done.

The clock routine will prove useful from inside BASIC programs for
timing sorts, or for calendar programs you may write, or whatever.
In the next version of Shell I will set up a pointer to a buffer 
that will contain the clock information.  The clock is accurate
to 1/60 second (under 17 milliseconds), which should be fine for
timing things under BASIC, it is just inconvenient with the current
program.  As I said, in the next release of SHELL (probably about
two weeks if I have much time on my hands).

Assembly Language:

As mentioned earlier Shell loads in at an ABSOLUTE address to allow
easier access to its buffers.  This is not very important in this
version, but in subsequent versions i plan to install smart commands,
that is, if you type TYPE filename, the TYPE command itself will
begin by checking SHELL's buffer to see if a filename was already given.

A command like CPREFIX would check to see if a prefix was supplied
with the command, why bother querying the user if they already typed
it?  But as I said, that's the next version.

SHELL is very extensible, one could even say ultimately extensible, and
it works with most (well ALL the ones I've tried) Prodos external commands,
and will probably work with any future command, so long as it is
relocatable, or self-relocating.

Feel free to create your own commands for SHELL, that's why I made it.
If you come up with something really good, let me know, maybe I'll include
it in the next version (it will of course be listed under your name).

Disclaimer:

I have no association with the Laser series of computers (other than owning
one), and no relation to Apple computer.  Products mentioned such as
DOS 3.3 and Prodos are the trademarks/copyrighted products of Apple Computer
Co.