Frozen Fish 2: PC/frozenfish_august_1995.bin/bbs/d01xx/d0100.lha/Conman/conman.doc

Text File | 1987-09-07 | 14KB | 281 lines

=========================================================================
                              ConMan V1.0
                 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 at
the cursor, and can be "toggled" with the CTRL-A key.  The 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 can 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 active 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 (like CTRL-L) are displayed
as a caret (^) followed by the uppercase alphabetic character.
Miscellaneous non-printable characters are displayed as a hash mark.


Command History.
Previously-entered lines can 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 history buffer is organized as a fixed-length memory "pool" with a
default length of 488 bytes.  Each new line is entered at one end, and
the oldest lines are "pushed off" the other end to make room.  The number
of lines that can be saved depends on their lengths, but is generally in
the range of 25 to 30.  The default size can be changed by modifying a field
in the library structure.

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

In "true history" mode, every line is re-entered into the history buffer,
even if it wasn't modified after being recalled.  The history pointer is
always reset (to the most recent line) whenever a line is placed into the
buffer.

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


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.

Function key F9 moves the screen to the front or back of the display, and
F10 moves the window to the front or back.  Both keys act as "toggles"
provided that you don't deactivate the window or screen.  These keys are
useful when you're working with multiple windows or screens and need to
peek at the one in back.


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 */

You can open a console 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 can 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 listed below.

   Option Character                 Default Value
   ----------------                 -------------
   A <==> Activate                  Activated
   B <==> BackDrop                  Not a backdrop
   C <==> Close gadget              No close gadget
   D <==> Depth gadgets             Depth gadgets
   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/   a borderless backdrop window.
         CON:10/10/300/100/Fixed/acm    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.)  Place the file "Conhandler" (184 bytes) in your
SYS:L directory, to keep all those bigger handlers company.  Copy the
file "conhandler.library" (5912 bytes) into 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 "chandler", or use the provided
"ARCinstall" script to copy the files.

Once these files are present, execute "ConMan" (976 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.)  You can specify several
command-line arguments when you execute ConMan:

   Code    Action
   ----    ------
   -c      install as CON: (the 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
you reboot the computer.  The -q option is recommended if the ConMan command
is inserted 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.  You can 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]

The suggested contribution (based on the shareware survey below) is $10,
but any amount is welcome.

Shareware Survey.
Special thanks to all those contributed while ConMan was still in its
beta-test stage!  The contributions received for the four beta releases
are summarized below:

   Amount      Received
   ------      --------
   $ 5.00          2
    10.00         13
    12.50          1
    15.00          6
    20.00          4

Since $10 is by far the most popular amount, it is hereby declared the
"suggested contribution".

Cast your vote for inexpensive software!  Distribution as shareware is
advantageous to both the producer and consumer.  You get to decide what
products to support, but without your support the authors will have to
direct their efforts elsewhere.  Which way will you vote?


Further Notes.
ConMan answers to several names in addition to "CON:".  You can define a
"CNC:" device using the "mount CNC:" command after appending the included
"mountlist" file to your DEVS:mountlist.  The CNC: device can then be
opened just like a CON: window.  This allows the CON: definition to be
left intact in case there are any imcompatibilities between ConMan and
your existing software ...  but please let me know of any problems!.

The ConMan handler was specifically designed to simplify the process of
writing a "command shell".  Since the handler is built as a library,
a number of the internal functions can be brought out to assist external
programs that use the console.  I have built the "C" header file and
binding routines required to call the library functions, and will be
documenting the programming aspects of the handler at some point.
Stay tuned for more information.

I'm planning to add a few new features in a future release of the handler.
Several people expressed interest in having the handler not display
typed-ahead lines, so that a currently-running program can write freely to
the screen and lines will be displayed only as they are read.  This is
fairly easy to implement, and will be selectable using a global flag.

Another planned option is to make the control key actions selectable.
I'll probably define a table of possible actions and let you match them
up with control keys.  This again is easy to implement.


Bugs.
One known bug occurs when the handler is being used in RAW: mode with
the ED editor.  The editor works fine until it exits, whereupon it GURUs
with an 8700004 code.  Other utilities work fine with the handler in
RAW: mode.

Problems have been reported about incompatibilities between ConMan and
ABasic, the first basic shipped with the machine (remember V1.0?).
I no longer have ABasic, having long ago recycled the disk (my current
system disk, actually).  Once I get a new copy to play with, maybe the
problem can be cleared up.

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, but until I find a
a reasonable work-around, 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, I highly recommended that you avoid
console windows smaller than 60X25 or so.


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 (08/25/87)