;                                                                      V1.4

                              OSH

          The Overlay History Shell for Backgrounder II

          I - Introduction
          U - Using OSH
          W - Wildcard command repeat
          D - Implementation details
          A - Acknowledgements
:I
Introduction

OSH provides a fast command line editor and recall facility for users of 
Echelon's Z-System with Plu*Perfect's Backgrounder ii task switcher. 

Previously entered commands may be recalled and re-executed, with or 
without editing.  The editing possiblities include cursor movement forward 
and backward by character, word, or command, and deletion of characters, 
words, or commands.  Insertion or deletion is possible anywhere within the 
line.  A list of previously entered commands can be displayed.

In addition, a command line can be automatically repeated for each file 
which matches an ambiguous filename contained in it.

OSH assumes the terminal wraps its cursor from the last column of a line to 
the beginning of the next line, and that <backspace> at the left margin 
takes the cursor to the end of the previous line.
:U
Using OSH

OSH is activated by first installing it as the Backgrounder Overlay Command 
Processor:

        >OCP OSH              and then calling it with no parameters

        >OSH

OSH installs itself as a ZCPR3 shell, and takes over prompting of the user 
for subsequent commands.  Command entry proceeds as normal, but with the 
addition of a number of WordStar-like editing actions.  These are detailed 
in the table on the following page.

Every command which is entered under OSH is saved in a history stack, and 
can be recalled either by stepping back through the stack using ^E, or by 
searching for an entry that matches the string to the left of the cursor by 
typing ^L.  Eventually old commands will be pushed out of the limited-size 
stack, but this is delayed by keeping only the most recent copy of 
identical command lines.  The space available for history storage is about 
850 bytes - enough for 50 short (16 byte) commands or 4 enormous (200 byte) 
ones.

OSH editing commands:

                     +-------+-------+-------+--------+--------+
                     | Back  | Fwd   | Del L | Del R  | Del All|
        +------------+-------+-------+-------+--------+--------+
        | Character  |  ^S   |  ^D   | DEL/BS|  ^G    |        |
        +------------+-------+-------+-------+--------+--------+
        | Word       |  ^A   |  ^F   |  ^W   |  ^T    |        |
        +------------+-------+-------+-------+--------+--------+
        | Command    |  ^Q   |  ^R   |       |        |  ^Z    |
        +------------+-------+-------+-------+--------+--------+
        | Line       |  ^E   |  ^X   |       |  ^Y    |  ^U    |
        +------------+-------+-------+-------+--------+--------+

     ^K    -   Display command history.
     ^L    -   Search for match left of the cursor.
     ^P    -   Remove any special meaning from next character.
     ^V    -   Insert mode on/off.

OSH can take two paramemters:

    >OSH O      switches the shell off

    >OSH R      resets the history stack

OSH is also removed (silently) if a different OCP is loaded.

When OSH is activated by calling it with no parameters, it only becomes 
active in the current (upper or lower) task.  It may also be activated 
manually in the other task, in which case the same history stack is used in 
both tasks.  A possible BGii startup command line is:

     >OCP OSH;OSH;SWAP;OSH;SWAP

Commands entered in background mode bypass OSH completely, and are not 
entered in the history.
:W
Wildcard command repeat

OSH also has a facility for automatically re-executing a command line for 
each file which matches an ambiguous filename specification.  The process 
is started by entering the command 'WILD ' followed by the command line.  
The first token in the line which includes '*' or '?' is assumed to be an 
ambiguous filename, and it is replaced by matching filenames one by one.

The process terminates when the line has been executed with each matching 
name.  It can be manually curtailed by breaking to background mode 
(<SUSPEND>) and typing 'WILD' on its own.  Note that this is only possible 
if the command being repeated is not itself a built-in, so 'WILD TYPE 
*.Z80' (for instance) cannot be interrupted.

During suspension of a WILD repetition it is possible to swap to the other 
task and do some work there.  However, if OSH is also active in that second 
task, it de-activates itself in that task to avoid total confusion.  It is 
still active in the first task though, and the WILD repetition will 
continue when the user returns to it.

The repeated line can be an arbitrarily complicated string of commands, but 
if the ambiguous token does not include a directory specification it is 
evaluated in the directory current at the time the WILD command was 
entered, not that which would be current at the relevant point in the 
command line.  Thus
     B1>WILD C7:;TYPE *.Z80
loses.  What is probably desired is
     B1>WILD TYPE C7:*.Z80

WILD keeps track of where it is up to by counting matches.  Thus the n'th 
matching filename is processed on the n'th execution of the line.  If the 
command being executed creates or deletes files which match the afn (or, 
less likely, rearranges the disk directory in some way) this mechanism 
becomes ill-defined.
:D
Implementation Details

OSH is written in Z80 assembly code and requires a Z80 compatible processor 
to run.  It was developed using Echelon's ZAS and ZLINK, and it uses the 
SYSLIB and Z3LIB libraries.

There is one patchable option, at relative address 13H from the start of 
OSH.OCP.  The byte there determines whether OSH starts in overwrite or 
insert mode (0 = overwrite, 1 = insert).

Implementing a history shell as an OCP has certain advantages over a COM 
file.  The OCP mechanism can be made to save the entire program including 
its data between invocations, so there is no need for a separate history 
file with code to access it.  The command name is guaranteed to be found 
until a different OCP is loaded, so there are no need to establish the 
location of the shell on the path when it installs itself.

The shell's speed has an important effect on the interactive responsiveness 
of a system.  The time used is largely determined by the amount of disk 
activity.  In theory OSH needs 32 sector reads and 32 sector writes between 
commands.  HSH (v1.5) needs a directory search to find the COM file, 65 
sectors reads to load it, another directory search to find the history 
file, a sector read to get the history parameters, 3 sector writes to 
update the history file and a directory search and write to close the 
history file.

Actual measurements show the following overheads for the execution of a 
simple COM file (units are sector reads and writes):

ZRDOS 1.7                                  Base
ZRDOS 1.7 + HSH 1.5                      71R +  5W
ZRDOS 1.7 + BG 1.13                     109R + 34W
ZRDOS 1.7 + BG 1.13 + OSH 1.0           174R + 66W
ZRDOS 1.7 + BG 1.13 + HSH 1.5           279R + 73W

(HSH.COM and HSH.VAR were in the first directory sector).
:A
Acknowledgements

OSH has the "look and feel" of Michael Rubenstein's HSH, because most of 
the command line editing code is based on his C source code.  There are 
differences, but I tried to keep the user-interface essentially the same.

WILD was inspired by Steve Cohen's W shell, which does essentially the same 
thing.  The implementation is completely different, and WILD has none of 
W's restrictions on position of afn, number of parameters, etc.

Trademarks:

Backgrounder ii       --  Plu*Perfect Sytems
Z-System              --  Echelon, Inc.
WordStar              --  Microsoft Corp.
kgrounder ii       --  Plu*Perfec