Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d0xx/d081/conman.lha/Conman/conman.doc

Text File | 1987-06-30 | 15.0 KB | 306 lines

==========================================================================
                             ConMan V0.99B
                  Copyright (c) 1987 by William S. Hawes
==========================================================================

ConMan is a replacement console handler that provides line editing and
command line histories.  It runs under AmigaDOS (V1.1 or V1.2) and is
completely transparent to any application program that uses CON: windows.
Once installed, all windows opened by AmigaDOS will automatically use the
ConMan handler.  This includes command windows opened by NEWCLI as well
as any data input/output windows that your program uses.

In addition to the basic line-editing functions, ConMan provides a number
of "standard" control-key options, several function-key definitions, and a
procedural interface designed to assist "shell" programs and other utilities.
It can also be opened as a (switchable) RAW: mode handler and as a 'pipe'.


Line Editing.
ConMan allows you to edit the active (command) line using the left- and
right-arrow keys for cursor positioning.  The DEL key removes the character
under the cursor, and the BACKSPACE key deletes the character to the left
of the cursor.  The shifted left-arrow key skips to the beginning of the
current or previous word, and the shifted right-arrow key skips to the
position beyond the end of the current or next word.

The editing mode may be set to either insert or overstrike characters, and
is toggled by the CTRL-A key.  This input mode is controlled by two global
flags maintained in the ConHandler library structure.  One flag determines
the mode in effect when the window is first opened and after each line is
entered, and defaults to "insert."  The other flag determines whether the
mode is "sticky" -- whether it remains set or reverts to the initial setting
after each line is entered.  The mode flags may be selected when you first
install ConMan, and can be changed at any time using the provided SetCMan
command utility.  Try experimenting with the input modes to see which you
prefer.  Note that these are global flags and therefore apply to ALL ConMan
windows.

Several control keys are provided to delete all or part of the active line.
CTRL-X deletes the entire line, while CTRL-Y deletes from the cursor position
to the end of the line.  CTRL-Z deletes both the current line and any lines
that have been entered (but not yet read); this is very handy if you want to
completely abandon all typed-ahead lines.  CTRL-R provides a less drastic
recourse by recalling entered lines one at a time and posting them back to
the command line.

CTRL-S and CTRL-Q have been implemented to hold and release the screen
output, respectively.  While the CTRL-S action is not strictly necessary,
since entering any character will halt output to the screen, it is a standard
control option.  CTRL-W clears the entire window and refreshes the command
line.

One other control character is recognized:  CTRL-\ sends an end-of-file
(a zero-length block) to the task reading from the handler.

All characters not explicitly required for editing purposes are passed on
to the command line.  In order to provide a consistent display, characters
that might cause interference with the display (e.g. CTRL-L) are displayed
as a caret followed by an uppercase alphabetic.  Miscellaneous non-printable
characters are displayed as a hash mark.


Command History.
Previously-entered lines may be recalled sequentially with the up-arrow key.
If you go past the one you want, the down-arrow key will retrieve the next
(more recent) line.  The shifted up-arrow key recalls the oldest line, and
shifted down-arrow recalls the most recent line.

The command history can be maintained in one of two modes.  In the default
mode, recalled lines are not reentered into the history buffer unless the
line was "touched", and the history index pointer is left set at the
retrieved line.  This mode is convenient if you often go back deep into
the buffer to retrieve sequences of commands.

In "true history" mode, every line is reentered into the history buffer,
even if it was recalled and not modified.  The history pointer is always
reset (to the most recent line) whenever a line is placed into the buffer.

The history mode may be selected when ConMan is installed or by using
the SetCMan utility.

The history buffer is organized as a fixed-length memory "pool" with a
default length of 488 bytes.  The number of lines that can be saved depends
on the line lengths, but is generally in the range of 25-30.  The default
size may be changed by modifying a field in the library structure, but let
me know if this is too small (or too big; we don't want to waste memory.)


Function Keys.
Four function keys have been assigned default actions.  Key F1 shrinks
("iconifies") the window to its minimum size, while F2 "zooms" the window
to its maximum size (usually the entire screen.)  Both keys act as "toggles",
and shrunken windows may be zoomed (and vice-versa.)  If the window was
opened without a sizing gadget, neither F1 or F2 will have any effect.

Key F9 "dips" the screen to 3/4 of the display height, and should be useful
if you're working with multiple screens and need to peek at the one in back.
F10 rearranges a window from front-to-back, and acts as a toggle provided
that you don't deactivate the window.


Window Definition.
ConMan accepts the standard AmigaDOS window specifications.  For example,
"CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size,
beginning in position (160,50).  The numeric parameters are truncated
against the maximum screen size, so a larger-than-normal window may be
safely specified (for those of you using "morerows").  The default size
is the full screen width and height.  ConMan computes the minimum size
for the window based on the length of the title and the gadgets present.
The actual size of the window is used as the upper bound for the minimum,
so very small windows (e.g. "con:0/0/1/1/") can be specified.

ConMan also accepts a specification in the form "CON:w20480", where the
hex digits following the "w" are the absolute address of an Intuition
window pointer.  If you're writing in 'C', the following sequence would
serve to open a window and attach a DOS console to it:

      window = OpenWindow(&newwindow);   /* get a window          */
      sprintf(buffer,"CON:W%x",window);  /* build the name string */
      file  = Open(buffer,MODE_OLDFILE); /* open a console stream */

Windows may be opened on a custom screen by including the screen pointer
in the specification string, as in "CON:S123abc/10/10/300/100/MyWindow".

Various Intuition options and gadgets may be selected by including a list
of attributes after the window title.  Here's how it works:  Put another
slash ('/') after the window title, and follow it with any of the attribute
options below:

   A ==> Activate          default: activated
   B ==> BackDrop                   not a backdrop
   C ==> Close gadget               no close gadget
   D ==> Depth gadget               depth gadget
   M ==> Move (drag) gadget         drag gadget
   N ==> NoBorder                   border (sorry, 'B' was used)
   R ==> Refresh (SMART/SIMPLE)     smart refresh
   S ==> Sizing gadget              sizing gadget
   Z ==> Zero-Zero                  not a GZZ

Each attribute serves to TOGGLE the corresponding windows flag, so including
an attribute twice will cancel the effect.  A closing slash is optional.
For those of you who wanted a slash in your titles:  sorry.

Example: CON:10/10/300/100/Behind/nb/  creates a borderless backdrop window.
         CON:10/10/300/100/Fixed/acm   creates a nonactivated window, with
                                       a close gadget, that won't budge.

Installation.
ConMan requires that two files be copied to your SYS: disk (don't worry,
they're both small.)  File "My-Handler" (184 bytes) must be placed in the
SYS:L directory, to keep all those bigger handlers company.  The file
"conhandler.library" (5816 bytes) must be placed in the your LIBS:
directory, which is normally SYS:LIBS.  If you received ConMan in the form
of an ARCed file, be sure to rename "conlib.lib" and "myhandlr," or use
the provided "install" script to copy the files.

Once these files are present, execute ConMan (988 bytes) to install the
handler.  This command should only be run once, as it allocates 20 bytes
of memory for the handler name string which won't be released (there is no
provision in DOS for removing a handler, anyway.)  Several command-line
arguments may be specified when ConMan is executed:

   -c ==> install as CON: (default)
   -o ==> select overstrike mode
   -q ==> execute "quickly" (don't open a window)
   -r ==> install as RAW:
   -s ==> select "sticky" mode
   -t ==> maintain "true history"

These command options may appear in any order and remain in effect until
the computer is rebooted.  The -q option is recommended if the ConMan
command is to be placed in your startup script (SYS:s/startup-sequence).

A separate utility program called SetCMan (136 bytes) has been provided to
modify some of the global mode flags.  Use SetCMan to change the -o, -s,
or -t options at any time.
Examples: conman  -c -q -t
          setcman -o -s -t

Distribution.
This program is to be distributed as shareware to Amigoid life-forms
everywhere!  Make sure your friends get a copy.  Comments and contributions
will be appreciated and may be sent to:

      William S. Hawes        (bix: whawes)
      P.O. Box 308
      Maynard, MA 01754
      [phone]

Additional documentation and the assembler source code will be available
in the near future.

I will be other releasing other Amiga products, both through shareware and
normal commercial channels.  Watch for:
   ARexx ... the REXX language for the Amiga (June, 1987)
   Mini-Shell ... just enough DOS (August, 1987)


Further Notes.
This is the last Beta version before the "final" (is anything ever final?)
release of ConMan.  Some debugging code still remains here.  Function key
F5 toggles a flag that causes a DisplayBeep everytime a "WaitForChar"
packet is dispatched.  Most programs will not use the "WaitForChar" function,
since a Read to the CON: device will block until characters are available
anyway.  F6 toggles a flag that DisplayBeeps whenever a "break" signal is
passed on (i.e. is applied to your hapless task).  Also, an extraneous
message port (called 'MyCon') will appear in the Ports list.  These testing
features will go away RSN.

The program was developed and tested under V1.2; at least one V1.1
dependency was found and fixed (DoIO to the console device scratched D7).
Let me know if other problems exist.  I spent a lot of time making it
work using the DOS handler-loading mechanism so that it would be backwards
compatible.

A passing note:  The interaction of the "shrink" and "zoom" keys proved
to be a little trickier than it first appeared; I ended up spending the
better part of a day finding state transitions that seemed intuitive.
Anyone who doesn't like the current implementation is invited to submit a
state diagram with the desired transitions ...

One warning with regard to the "shrink" and "zoom":  rapid toggling between
window states will crash the machine.  The problem appears to be an
interaction between Intuition and the console device, and I looking for a
reasonable work-around before adopting an ugly kludge.  Until then, take
it easy on the keys, OK?

An additional warning: the console device exhibits serious problems with
supporting windows below some minimum size.  Opening windows of certain
sizes (e.g. con:0/0/10/20/) may cause the machine to crash, whether or not
ConMan is active.  For these reasons, it is highly recommended that you
avoid console windows smaller than 60X25 or so.


Function Key Interrupts.
The ConHandler library provides routines to support a push-down stack of
function-key contexts so that user programs can receive interrupts related
to keyboard events.  Whenever a function key event (or more generally,
any raw event) occurs, the console handler first calls the user-supplied
function at the top of the context stack.  Your function is free to "eat"
the event, change it to something else, or take any other action.  Some
restrictions apply (after all, these are asynchronous events), but this
should allow for some interesting programming.  A separate program called
"SideShow" has been included as an example of function-key processing.
The full source code to "SideShow" is available for programmers interested
in using the interrupt facilities.  Note to interested programmers:  let me
know if you'd like to try out the procedural interface and I'll post the
necessary header files and binding routines.


Using ConMan as a 'Pipe' Handler.
ConMan can be mounted as a 'pipe' handler, a facility often used in "shell"
programs for interprocess communications.  A 'pipe' is opened simultaneously
for read and write, and the characters written into it are queued up to be
read.  The maximum size for the pipe is specified when it is opened; once
this limit is reached, any processes writing into it will be put to sleep
until some characters have been read.  The default size for the ConMan
'pipe' device is 4000 bytes.

Mounting ConMan as a pipe handler requires the use of the mount command,
and therefore works only under v1.2 of the operating system.  Place the
included mountlist file in your DEVS: directory (or append it to the
existing file), and then issue the command "mount pip:".

Opening a pipe is accomplished by a call to the DOS Open() function with
a special argument code.  The initial open counts as TWO opens, assuming
that the returned filehandle will be copied by the caller.  Since copying
DOS structures is tricky, a function called DupFileHandle() is available
in the ConHandler library.  A code fragment to open a 10,000 byte pipe
device might look like this:

      ConHandlerBase = OpenLibrary("conhandler.library",0);

      fh1 = Open("pip:10000",999L);
      fh2 = DupFileHandle(fh1);

      .
      .
      .
      Close(fh1);                   /* close the first   */
      Close(fh2);                   /* close the second  */

Note that if you want to use the higher-level 'C' library functions with
the 'pipe' filehandles, you'll have to arrange to get the DOS filehandles
into the appropriate I/O structures.

Normally one filehandle will be given to a "producer" (writer) process,
and the other will go to a "consumer" (reader) process.  Each is free to
close their half of the pipe at any time; the pipe handler closes only
after BOTH filehandles have been closed.


Bugs.
The only known bug occurs when the handler is being used in RAW: mode
with the ED editor.  The editor works fine until it exits, whereupon the
window closes and ED (not me) GURUs with a "8700004" code.  The problem
seems to be timing-related; if a second open is obtained on the RAW:
window, ED exits without any problems.


Acknowledgements.
Special thanks to John Toebes and the Software Distillery for all the great
suggestions, and to everyone who called in with comments or contributions.

                                    WSH (06/02/87)