home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Frozen Fish 1: Amiga
/
FrozenFish-Apr94.iso
/
bbs
/
alib
/
d1xx
/
d165
/
conman.lha
/
ConMan
/
ConMan.doc
< prev
next >
Wrap
Text File
|
1988-11-22
|
24KB
|
444 lines
ConMan V1.3
Copyright (c) 1987, 1988 by William S. Hawes
ConMan is a replacement console handler that provides line editing and
command history for any software that uses CON: windows. It runs under
AmigaDOS V1.2 and later, and is completely transparent to other software.
After ConMan has been activated, all CON: windows opened by AmigaDOS will
automatically use the ConMan handler. This includes the console windows
opened by NEWCLI as well as any data input/output windows that your other
software may use.
Features new to ConMan V1.3 include the CND: handler for invisible,
non-blocking type-ahead, the CNX: (extensible) handler for use of the
serial device as a console, improved editing of long lines, and support
for superbitmap windows.
As with prior releases, ConMan is still shareware (user-supported)
software, and I'm pleased to report that the rate of contributions has
increased since that last release. Shareware is a welcome alternative
to the high costs of commercial software, and I hope that you will do
your part to support ConMan and other shareware products.
----- Line Editing -----
ConMan allows you to edit the active (command) line using the left- and
right-arrow keys for cursor positioning. The shifted left-arrow key
skips to the beginning of the current or previous word, and the shifted
right-arrow key skips to the start of the next word.
ConMan supports both insert and overstrike editing modes. The CTRL-A key
toggles between the two modes, and the CTRL-^ key unconditionally selects
insert mode. The default input mode is insert, but you can set the global
-o flag to select overstrike mode. The input mode normally reverts to the
default mode each time you press RETURN, but the global -s ("sticky") flag
will cause the mode to remain set until you change it explicitly.
You can select insert or overstrike mode when you first install ConMan,
and can change it at any time using the SetCMan command utility. Try
experimenting to see which input mode you like best, but note that the
input modes are global and therefore apply to ALL ConMan windows. Refer
to the paragraph on installation for a list of the global option flags.
There are several keys that can be used to delete characters, words, or
the entire line. The DEL key deletes the character under the cursor,
and the BACKSPACE key deletes the character to the left of the cursor.
CTRL-Y deletes from the cursor position to the end of the line, and
CTRL-U deletes from the cursor to the start of the line. CTRL-X deletes
the entire line, in keeping with the default CON: device.
Function keys F7 and F8 can be used to delete words in the backwards and
forwards direction, respectively. They work just like the shifted left-
and right-arrow keys except that the characters are deleted.
CTRL-Z deletes both the current line and any lines that have been typed
ahead (but not yet read); this is very handy if you want to completely
abandon all typed-ahead lines. CTRL-R provides a less drastic recall
by posting the typed-ahead lines back to the command line. CTRL-W clears
the entire window and then redisplays the active line.
The Undo Buffer.
Suppose that you're editing a line and you accidentally hit the up- or
down-arrow key. You've just lost the line, right? Not at all --- just
press the CTRL-- (control-minus) key and the former line will be posted
back to the command line, with the cursor right where you left it!
There is no limit to the number of lines that can be undone, but only
lines that have been changed are added to the undo buffer. All "undo"
lines are discarded when you finally enter RETURN.
Flow Control.
CTRL-S and CTRL-Q have been implemented to hold and release the screen
output, respectively. After pressing the CTRL-S key, all output to the
window will be held until you release it with a CTRL-Q. There is no
direct visual indication that output is being held, so be careful not to
press CTRL-S accidentally.
End-of-File.
ConMan recognizes the CTRL-\ character as an end-of-file and sends a
zero-length block to the task reading from the handler. CTRL-\ can be
used to terminate a copy operation.
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 rendered
as a caret (^) followed by the uppercase alphabetic character. The CTRL-N
(shift-in) and CTRL-O (shift-out) characters are supported by ConMan;
these are non-printable by themselves, but serve to select and unselect
the alternate character set. Miscellaneous non-printable characters are
displayed as a hash mark.
ConMan now allows control sequences can be entered incrementally. For
example, entering ESC, [, 0, and ~ will simulate the effect of an F1 key.
----- Command History -----
ConMan "remembers" the commands that you type and lets you recall them
sequentially using the up- and down-arrow keys. If you go past the line
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 CTRL-B key clears the history buffer.
The history buffer is organized as a fixed-length memory pool with a
default length of 488 bytes. New lines are inserted 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 when you install
ConMan by using the -b option followed by the desired size in bytes.
For example, the command "conman -c -b1000" installs ConMan with a
1000-byte history buffer.
ConMan maintains the history 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 positioned 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 reentered 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 added to the
buffer.
The history mode can be selected when ConMan is installed or by using the
SetCMan utility. Note that ConMan now checks for duplicate entries
irrespective of whether standard or "true" history is selected. If the
current line matches the previous line entered, the line is not reentered.
Minimum Line Length.
You can define a minimum line length to be saved in the history buffer by
using the -LNNN option. The number following the -L is the limit at or
below which lines will not be saved; the default value is 0. For example,
"conman -c -L2" will ignore lines of 2 or fewer characters.
Wrap-Around History.
If you prefer to maintain the command history as a circular buffer rather
than as a stack, try setting the -wrap option with ConMan or SetCMan.
The index will "wrap-around" when it hits the top or bottom of the stack.
Versions 1.1 and later of ConMan include a command called "History" to
save, load, or display the history buffer. Refer to the "history.doc"
file for more information.
----- Function Keys -----
ConMan has several additional editing functions and window control options
that use the function keys.
Key F1 shrinks ("iconifies") the window to its minimum size, and key 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.)
ConMan V1.3 provides a minor enhancement to the zoom feature: if the
window is not exactly at the top of the screen when F2 is hit, it will be
positioned one pixel down from the top, rather than right at the top.
This allows you to slide the screen even if the window covers most of it.
If the window was opened without a sizing gadget, neither F1 or F2 will
have any effect.
Keys F5 and F6 are used to search for commands. If you type a partial
command line and then press F6, ConMan searches in the up-arrow direction
for a line matching up to the cursor position. You can move the cursor
to the right to constrain the search. Key F5 works similarly in the
down-arrow direction.
Keys F7 and F8 delete words in the backwards and forwards direction.
They operate just like the shifted left- and right-arrow keys except that
the words are deleted rather than just skipped over.
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 Definitions -----
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 sets the minimum window size
to allow room for the close gadget and depth gadgets.
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 option character will TOGGLE the corresponding window attribute,
so if you include an option twice, it will cancel the effect. Any
unrecognized attribute characters are ignored, and the closing slash is
optional. My apologies to those who wanted a slash in the title.
Examples: 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 ----
To install ConMan you'll need to copy a few files to your system disk,
but don't worry --- they're all small. Install the file "Conhandler"
(184 bytes) in your L: directory, to keep those bigger handlers company.
Then copy the file "conhandler.library" (6536 bytes) into your LIBS:
directory. Now copy the commands ConMan, SetCMan, and History to your
C: directory; the other command programs are optional. The included
"ExecuteMe" file will handle the installation for you if you'd rather do
it automatically.
If you received ConMan in the form of an ARCed file, first deARC it
and then rename "conlib.lib" to "conhandler.library" and "chandler" to
"conhandler", or use the provided "ARCInstall" script to copy the files.
Once these files have been installed, issue the command "conman -c" to
activate the handler. After you've activated ConMan, open a CLI window
using NEWCLI and check to make sure that the new window has line editing
and command history. Once everything is working properly, you should
place the "conman -c" command in your startup-sequence so that it's always
available.
NOTE: ConMan affects only those windows opened AFTER you activate it!
It would be very impolite indeed to pull the old handler out from under
the existing windows.
You can specify several command line arguments with the ConMan command:
Code Action
------ ------
-bNNNN select buffer size NNNN bytes
-c install as CON: (the default)
-d disable control-C break on write
-lNNN minimum length to save
-o select overstrike mode
-r install as RAW:
-s select "sticky" mode
-t maintain "true history"
-w select "wrap-around" history
These command options can appear in any order and remain in effect until
you reboot the computer. The -q option used in previous releases is now
obsolete, as ConMan writes its copyright to standard output by default.
A separate utility program called "SetCMan" has been provided to modify
or display the global options. You can use SetCMan to change the -o,
-s, -t, or -w options at any time.
Examples: setcman ?
setcman -o -s -t
If you usually operate from WorkBench and only occasionally need a CLI,
you can activate ConMan by using the icons. First double-click on the
"LoadLib" icon to load the conhandler library, and then activate ConMan
by double-clicking the "ConMan" icon. The next CLI you open should now
have the line editing and command history provided by ConMan.
----- Distribution -----
This program is distributed as shareware (user-supported software) to
Amigoid life-forms everywhere! Make sure your friends get a copy.
Your contributions are greatly appreciated and will help me maintain
ConMan as well as develop new products. Send all correspondence to:
William S. Hawes
P.O. Box 308
Maynard, MA 01754
(508) 568-8695
EMail can be sent to any my network addresses:
BIX: whawes CIS: 72230,267 USENET: hawes@dino.ulowell.edu
The suggested contribution is $10 (based on an earlier survey), but any
amount is welcome. The number of registered ConMan users has increased
significantly since the last release, but is still far below what would
be expected for a comparable commercial product.
Commercial vendors are welcome to include ConMan with their products,
provided that it's noted as being shareware and that the documentation
accompanies the software.
----- Other Products -----
I have a couple of other products available commercially. ARexx and
WShell can be found at better dealers**, or you can order them directly
from me at the above address.
ARexx is a multitasking implementation of the REXX language, a high-level
interpreted language designed for macro-processing. ARexx has become the
de facto standard for inter-program communications and can be used as the
macro language for any software package that includes an ARexx interface.
It's both powerful and easy-to-learn, and is well documented in a 150-page
manual. ................................. Only $49.95 (plus $2 shipping)
WShell is a much-enhanced but highly compatible CLI replacement that
offers aliases, built-in and resident commands, concurrent command piping
(as in pgm1 | pgm2 | ... | pgmN), extended prompt/window titlebar fields,
transparent support for REXX macro programs, an "implicit" CD command,
script-bit support, and lots of other features. Isn't it time you put
some mussel into your command environment? Just 50 clams (+ $2 shipping)
** better dealers are those that stock ARexx and WShell.
----- Further Notes -----
ConMan also accepts window specifications in the form "CON:w20480", where
the hex digits following the "w" are the absolute address of an Intuition
window pointer. This allows you to attach a console handler to a window
in a multitasking-safe way (unlike the methods that require setting a
field in the DOS device list). If you're writing in C, you could use
the following sequence 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 window on a custom screen by passing the hex
address of the screen preceded by an "S" in the specification string,
as in "CON:S123abc/10/10/300/100/MyWindow." ConMan will accept "S*" as
a shorthand notation for the front-most screen, so a specification like
"CON:S*/0/0/300/100/Front" would open on whichever screen was in front.
In addition, ConMan now supports superbitmap windows as well. The bitmap
structure is passed as a "B" followed by the hex address, as for example
"CON:B123ABC/0/0/300/100/Super!". The console device currently has some
bugs related to using superbitmaps (for example, the cursor disappears),
but this feature may be handy anyway.
Other Names.
ConMan is actually several DOS handlers rolled into one, and it selects
the desired mode of operation by looking at the name used to open it.
The four special names recognized are CND:, CNX:, PIP:, and RAW:, and all
other names are considered equivalent to CON:.
In order to use ConMan under any name other than CON:, you'll need to add
one or more of the supplied mountlist entries to your DEVS:mountlist file
and then issue the "mount" command. For example, to define ConMan as the
CNC: device, add the CNC: entry to DEVS:mountlist and issue "mount CNC:".
Once you've done this, you can get a ConMan window by specifying a name
like CNC://640/100/MyWindow. This allows the CON: definition to be left
intact, in case there are any incompatibilities between ConMan and your
existing software (but please let me know of any problems!)
The CND: handler, new to V1.3, operates in a mode that allows invisible
(non-blocking) type-ahead. After the line you enter has been read, any
further input is not displayed until the command shell (or other software)
again reads from the console. This gives unimpeded access to whatever
software is writing to the console.
Example: NewCLI "CND://640/100/VAX Head!"
The CNX: handler is also new to V1.3, and provides extensibility by
allowing you to specify any EXEC-level device for the console display.
The display device name and unit are passed immediately following the
handler name, as in "CNX:device-name/unit". For example, you could
specify the serial device as "CNX:serial.device/0", providing an AUX:
handler with full line editing and command history. The display device
must support the standard ANSI control sequences on read and write.
Example: NewCLI CNX:serial.device/0
ConMan is also a pipe-handler responding to the name PIP:NNNN, where
NNNN is the "capacity" of the pipe. It must be opened using a private
packet called ACTION_DOUBLE (value 2000L), and the filehandle you get
from a call to Open("PIP:",2000) counts for two and so can be cloned
by your program. After allocating a filehandle structure (using the
AmigaDOS memory conventions), just copy the filehandle from Open()
into the new structure --- and don't forget to Close() both of them!
My WShell command shell uses the ConMan PIP: device as its pipe handler.
Those of you with AmigaDOS 1.3 (but not yet blessed with WShell) will
appreciate the sly inclusion of the NEWCON: mountlist entry.
Break Signals.
Break signals are generated by typing a control-C, D, E, or F and can be
delivered to any task that has opened, read from, or written to ConMan.
The break-signal handling in ConMan is much more sophisticated than that
in the standard CON: handler, and additional improvements have been made
in V1.3 to eliminate the possibility of signalling a non-existent task.
ConMan is able to signal a task that has only read from or written to the
console -- even if it hasn't opened it -- by holding the break event until
a read or write request arrives.
In addition to the break signals generated by user input, ConMan will
send a control-C break to any task that continues to write to the handler
when it's trying to close. ConMan is in such a "closing" state after the
close gadget on a window has been hit, or if it is a PIP: pipe with only
one open remaining. This automatic "break-on-write" provides a way of
propagating a signal back through a series of piped programs. Auto-break
can be disabled by specifying the -disable option to the ConMan command.
Keymapping.
ConMan supports the Amiga's keymapping facility, which allows you to
reassign the editing functions to the keys of your choice. To do this,
you must first construct a keymap either in assembly language or with
the help of a keymap editor. You can then load the keymap using the
SetMap program on your WorkBench disk. By default SetMap makes a keymap
global; if you want to use a special keymap from just one CLI, you can
use the included KeyMap command to define the desired map. KeyMap with
no arguments will display a list of the available keymaps.
----- What Next? -----
Most of the requested features have been added to ConMan now, but there
are a still a couple of suggestions being considered. Several users have
requested more flexible keymapping features to allow function keys to
be redefined on the fly. Another possibility is an improved "iconify"
state, so that the window can be double-clicked back to the former size.
----- Bugs -----
All known bugs have been fixed in this release, so you should find it to
be very reliable. If you do find a problem, PLEASE report it so I can
fix it!!
Previous versions of ConMan (before 1.3) exhibited a problem associated
with very rapid toggling between the "shrink" and "zoom" window states.
This problem has been fixed by adding a further level of interlocking,
and the F1/F2 keys should now be completely safe. Furthermore, the
underlying cause of the window-sizing problem will be fixed in version
1.4 of Intuition, so there should be no more trouble from this source.
One warning still applies: the console device exhibits serious problems
with 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 strongly urge you avoid console
windows smaller than 80X25 or so.
----- Acknowledgements -----
Special thanks to John Toebes and the Software Distillery for lots of
great suggestions, to Jeff White for the handsome icons, and to the many
contributors who made ongoing development and improvements possible.
-- Bill Hawes (September 28, 1988)