K9.DOC
documentation for K9 version 8/20/86
DPB

///////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////


K9 is a multipurpose resident utility intended primarily to make life easier
for programmers. It may be of some use to others as well, though user-
friendliness has not been a design objective, especially in the documentation,
which assumes a considerable understanding of DOS. K9 is named after Dr.
Who's equally loyal, equally mindless, and equally squirrelly assistant.


///////////////////////////////////////////////////////////////////////////


THIS SOFTWARE IS DISTRIBUTED UNDER THE SHAREWARE CONCEPT. The usual shareware
"rules" apply. Anyone making regular use of K9 is requested to send $25 to:

David P. Babcock
110 West Grant, #27-D
Minneapolis MN 55403

Contributors' comments and suggestions are welcome via CompuServe (73307,2441)
or by mail anytime.


///////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////

Users of the Leading Edge Model D must not use K9 without reading HOT KEYS
(below) carefully!! This information may be of use to other clone owners
as well.


///////////////////////////////////////////////////////////////////////////

INVOCATION
----------

K9 is meant to be invoked at boot time from a batch file. It's safest that
way because it will be below any transient programs. K9 returns a DOS
errorlevel of 0 if it loads successfully, and 1 if it finds itself already
resident. It occupies 16K.

A click may be heard from the speaker when K9 loads. This is from
initialization of K9's microsecond timer and is not cause for concern.

K9 requires DOS v. 2.0 or later. An attempt to load it under an earlier
version of DOS will return an error message and a DOS errorlevel of 255.


AUTOMATIC FUNCTIONS
-------------------

The DOS keyboard buffer is expanded from 15 to 142 characters.

The screen is turned off after 30 minutes of keyboard inactivity. The cursor
may or may not remain visible. Any keystroke restores the screen. This
function works on IBM machines or close compatibles and with most EGA cards.

The DOS editor functions are extended to include F7 and F8 as recalling
previous command lines. The most recent 256 bytes are maintained in a
circular buffer that may be traversed backward via F7 or forward via F8. The
least recent command line in the buffer may be missing one or more leading
characters. The command is displayed as though the user had typed Escape,
clearing the command line, and then the entry, but has not typed Enter. The
DOS editor keys F1-F6 work as usual.

The F7 and F8 keys can be extended to work within programs by setting the "W"
switch to a non-zero value. This applies only to text entered via the DOS
buffered input function, as in DEBUG, SYMDEB, or EDLIN. This input is
maintained in a separate buffer, so that command lines will be recalled at the
command prompt and text previously entered during the current execution of the
program will be recalled while in the program. The program text buffer is
cleared each time a program is loaded, and an attempt to use F7 or F8 if the
buffer is empty will cause the function key to revert temporarily to its non-
K9 definition. Thus, programs that define F7 and F8 for their own use can run
without interference from K9, even with the "W" switch set, as long as they
have not used the DOS buffered input function.

A microsecond-resolution timer is started any time INT 21H is executed with
AH=0FFh, and stopped when INT 21H is executed with AH=0FEh. The elapsed time
in microseconds modulo 54925 (one timer tick) is displayed on the screen. The
interrupt service routine preserves all registers and flags. Assuming the
code to stop the timer is

mov ah,0FEh
int 21h

the timing is from the first instruction after the first INT to but not
including the "mov" instruction. The timer will be inaccurate if invoked
while the speaker is operating. If it is suspected that the microsecond
counter is overflowing, this can be tested by noting whether repeated
invocations show instances of significantly longer elapsed times (indicating
one or more timer tick interrupts from the hardware) in accordance with
probability.


COMMAND LINE PARAMETERS
-----------------------

On loading, K9 will scan the command line tail for parameters. A parameter is
any alphabetic character, with lower case mapping to upper case. The
corresponding switch is set based on the character following the alphabetic
character, as follows. All switches are defined in such a way that the
machine behaves as much like a non-K9'd machine as possible if K9 is invoked
with no command tail.

following character parameter value
------------------- ---------------
- 0
+ 1
0..9 0..9
other 1

Any missing switch is set to 0.

The following switches are defined:

switch definition
------ ----------

A only [A]lt key sequences are hot. (See HOT KEYS below.)

B A [B]/W monitor is being used with a color card.
0 = NO (DEFAULT)
other = YES.

C display time of day in upper right corner of
screen.
0 = OFF (DEFAULT).
1 = display only at command prompt.
2 = display all the time.

D implement [D]vorak keyboard.
0 = Qwerty (DEFAULT), any other=Dvorak.

E pause the system and notify the user if a DOS [e]rrorlevel of
at least the switch value is being returned by a non-resident
process to its parent. (0 = OFF [default].)

F see "K" switch.

H park hard disk [H]eads at every command prompt.
0 = no (DEFAULT).
1 = yes.

I On Alt-13, check to see if the interrupt vector table contains
any addresses higher than K9 but below 0C8000h, and refuse to
remove K9 if any such are found unless the segments are
identical to what they were when K9 was loaded.

0 = yes (DEFAULT). This option makes it very unlikely that
K9 will let itself be removed unless it is the highest item
in memory, thus avoiding fatal corruption of the memory
allocation chain.
1 = no. This allows for situations where orphan vectors may
be in the table. With this option, the user must be much
more careful not to try to remove K9 if there are any
resident utilities above it, since the only check will be
that there is no program running.

K If non-zero, any K9 function request must be preceded by
pressing a specific control [K]ey and function key
simultaneously. The required control key is based on the K
switch:

1 = right Shift key
2 = left Shift key
4 = Ctrl key
8 = Alt key

The [F]unction key is based on the value of the F switch. If
F is zero, F10 is selected. If F is any other value (X), then
FX is selected.

The F switch is meaningless if K is zero.

L select [L]ist device for Alt-7 (1=LPT1:, 2=LPT2:,
3=LPT3:. DEFAULT (0) = LPT1:.

P define Shift-[P]rtSc.
0 = BIOS-defined function (DEFAULT).
1 = save screen to disk.
2 = Shift-PrtSc has no function.

In mode 1, the contents of the screen are saved in a file in
the root directory of the current drive, whose name is the
number of timer ticks since midnight in hex, with an extension
of .SCR. Carriage return-line feed sequences are inserted,
and any character less than 20h or greater than 7Fh is
replaced with a space, so that the resulting file will dump to
a printer without external processing. The file-naming method
allows successive screen saves with the assurance that an
ASCII sort by name of files generated during a calendar day
will produce a chronological ordering.

When the screen is saved, the name of the save file is written
at the top of the screen. (The name of the most recent file
name may be recovered by Alt-6/Ctrl-F (see below).) K9's
usual procedure of restoring the screen that existed before
its write operation on the next keypress operates here, too;
but in this case the result can be startling if there was much
screen activity since the screen save request was made. For
eaxmple: you enter DIR for a lengthy directory, and in the
middle of it request a screen save. This request is served,
the save file name is flashed at the top of the screen
(uselessly in this case), and the directory resumes, returning
eventually to the command prompt. Your first keystroke here
will recall the screen that was up when the save file message
was flashed. Nothing is harmed, but the screen may look
funny. (Of course Alt-8/Ctrl-H will clear it.)

Q set AT keyboard typematic delay to Q [q]uarter seconds, in
range 1-4. DEFAULT=2 quarter seconds (same as AT's boot
value). This does not work on some compatibles, including the
latest versions tested of the PC's Limited AT and the Sperry
IT (even with an IBM keyboard), though the Sperry was tested
only with the keyboard dipswitch in the "IT" position. The
function is known to work on the IBM PC-AT, the Victor V286,
the Eclipse ECS, and the Amax AT-3000.

R set AT keyboard typematic repetition [r]ate to value as
follows (DEFAULT=10.0 cps, same as AT's boot value):

1 = 30.0 cps (fastest allowed by AT)
2 = 20.0 cps
3 = 15.0 cps
4 = 10.0 cps (standard AT rate)
5 = 8.0 cps
6 = 5.5 cps
7 = 4.0 cps
8 = 2.7 cps
9 = 2.0 cps (slowest allowed by AT)

S (for internal use)

W Extend F7 and F8 to work [W]ithin programs.


HOT KEYS
--------

While resident, K9 is accessible to the user by the Alt key being held down
while a decimal number is entered THROUGH THE NUMERIC KEYPAD, or, if the 'A'
switch is zero, alternatively by Ctrl and a letter key. The latter
possibility is offered only because some clones, notably Leading Edge, don't
buy K9's method of distinguishing Alt-keypad combinations from anything else
that generates the same ASCII value.

If the "K" switch is non-zero, this request must be preceded by a control-key-
plus-function-key combination (whose effect may be canceled by Alt-0). See
the description of the "K" switch for a further description of this. If the
"K" switch is non-zero and K9 is awaiting a request, the K9 logo will appear
in the upper right corner of the screen (overriding the clock if a clock
option is selected).

If any K9 operation puts anything on the screen, the existing screen is first
saved. It will be restored by the next keystroke other than the PrtSc key or
either Shift key. If it is desired to restore the screen without having DOS
or the current program read a keystroke, the Alt key is handy.


Defined functions are as follows. The second key combination listed is
allowed unless the 'A' switch is non-zero.


==============================================================================

Alt-1/Ctrl-A: Display system status, consisting of:

CPU (8086/88, 80186/188, 80286/88, or V20/V30)
presence or absence of numeric coprocessor
number of parallel ports
number of serial ports
equipment identification byte, per IBM definition
total memory
memory currently free
(This tells how much memory is available for allocation by DOS. Note that
this will always be 0 at the command prompt, since COMMAND.COM does not
free memory until it starts a new process.)
ROM date
numeric coprocessor registers and flags, if a numeric coprocessor was found
(The display is based on names given in the Intel manual and is
straightforward. The only item that may not be immediately obvious is
"remainder." This is the result of C0*4 + C3*2 + C1, which is the remainder
left by an FPREM operation. Exception flags and pointers are not
displayed.)

==============================================================================

Alt-2/Ctrl-B: Invoke calculator. This may also be used for number base
conversions.

Alt-2 requires a numeric coprocessor, the author having written this function
mainly to get the hang of writing for the 8087 in the first place. Arguments
are given in RPN format. Operators are +, -, *, /, ** (power), SQR, SQRT, LN,
LOG2, LOG10, PE (E to power), P2 (2 to power), AIN (arithmetic inverse, or
unary minus), GIN (geometric inverse, or 1/x), SIN, COS, TAN, COT, SEC, CSC,
DEG (degrees to radians), RAD (radians to degrees), ASIN, ACOS, ATAN, ACOT,
and ! (factorial). Operators may be entered in upper or lower case. Operands
may be entered in base 2, 8, 10, or 16, or standard or scientific floating-
point format. Base identifiers (postfix) are: 2: 'B' or 'b'; 8: 'Q' or 'q';
10 (default): 'D' or 'd'; 16: 'H' or 'h' or 'X' or 'x.' A leading hex literal
is not allowed. Alpha constants recognized are PI and E. Arguments to trig
functions are in radians (values in degrees must be converted with the DEG
operator). Inverse trig functions do not allow negative arguments (if one is
supplied, its absolute value is used), and results are in radians, which may
be converted to degrees with the RAD operator.

Output is displayed below the parameter line in scientific notation floating
point with 15 digits of precision. On the line below this, binary, octal,
decimal, and hexadecimal representations of the least significant 32 bits of
the whole portion of the result are displayed, truncated toward 0, with the
exception that if the result is outside the range -(2^63-1) .. 2^63-1, 0 is
displayed. (0 may, of course, be a valid result--user examination is
required.)

The calculator may be exited by pressing the Enter key when it is awaiting
input if nothing else has been entered.

The truncation (rather than rounding) of the whole number portion can give the
appearance of a conflict between the floating point output and the whole
number output in certain calculations. The following was taken from the
screen after an actual calculation:

30 deg sin sqr 30 deg cos sqr + 50000 *
+5.00000000000000e+004
1100001101001111b 141517q 49999d C34Fh

The trig identity is known to produce 1, which, multiplied by 50000, gives
50000. The floating point output does give this. However, the whole number
is given as 49999. This is because, cos(30) being irrational, the actual
calculation through the "+" may yield a result that is only approximately 1,
because of rounding errors. In this case the identity yields a result that is
less than 1, but by so little that multiplying it by 50000 gives 50000 exact
to fifteen significant digits. To people, this is 50000. But to the numeric
coprocessor, it isn't, and when the coprocessor is told to truncate this
number, it does so.

==============================================================================

Alt-3/Ctrl-C: Display the ASCII character set. Each character is displayed in
hexadecimal, decimal, and character representations.

==============================================================================

Alt-4/Ctrl-D: Display the state of all switches, and allow changes. The
format for changes is the same as in the command tail at startup.

==============================================================================

Alt-5/Ctrl-E: Toggle between Qwerty and Dvorak keyboard modes. (This may also
be done via the 'D' switch in Alt-4/Ctrl-D, but allowance is made for the fact
that the user who finds the wrong keyboard layout may not know where the 'D'
key is.)

==============================================================================

Alt-6/Ctrl-F: This copies the most recent file name generated by Shift_PrtSc
to the DOS keyboard buffer.

==============================================================================

Alt-7/Ctrl-G: Send commands to a printer using an extended Epson command set.
Not all commands are supported by all Epson or Epson-compatible printers. The
following commands are implemented. Those marked with an asterisk turn an
option on if entered in upper case, and off if entered in lower case. The LPT
number may be selected via the L switch.

(A)ll [flush the printer buffer]
* (B)old
* (C)ondensed
* (D)ouble strike
* (E)lite [12 CPI instead of 10]
(F)orm feed
* (H)igh bit strip
* (I)talics
* (L)etter quality
* (M)ini [form length = 8 1/2" instead of 11"]
(N)ew [reset printer]
* (O)ut [enable paper out sensor]
* (P)roportional print
(R)everse line feed
* (S)kip over perf 1"
* (T)wo [skip over perf 2"]
* (U)nderline
* (W)ide ["expanded"]
* (Z)ero slash
(~) Carriage return

==============================================================================

Alt-8/Ctrl-H: Clear screen, do not home.

==============================================================================

Alt-9/Ctrl-I: [Not used, to leave Alt-9 available to enter an ASCII Tab]

==============================================================================

Alt-10/Ctrl-J: Terminate the current process and restore the interrupt vector
table. This (usually) gets out of programs that are hung up in loops, or from
which the user wants to escape but doesn't know how. It restores all
interrupt vectors to whatever they were after K9 finished loading. Open file
handles are not closed unless the particular DOS version or implementation
takes care of it. A DOS errorlevel of 0 is returned.

==============================================================================

Alt-11/Ctrl-K: Park hard disk heads. If this is attempted while not at the
command prompt, the heads are left alone and a message appears.

==============================================================================

Alt-12/Ctrl-L: [Not used, to leave Alt-12 available to enter an ASCII Form Feed]

==============================================================================

Alt-13/Ctrl-M: Remove K9 from memory. This request will be refused if a
program is running, or if the I switch is 0 and there are any interrupt
vectors pointing above K9 but below segment 0C800h that are different from
what they were when K9 was loaded. (This is to try to avoid the corruption
that would occur if the user tried to remove K9 while memory was allocated
above it.) Removal of K9 does not restore the AT keyboard typematic
parameters if those were changed.

//////////////////////////////////////////////////////////////////////////


APPLICATION NOTES
-----------------

One user reports that K9 and DOSEDIT make a nice combination. DOSEDIT allows
inter-line editing while in DOS, avoiding the somewhat awkward (at least to
normal people) DOS editing keys. It appears to be in the public domain.
Also, the original version of K9, circa July 1985, got along perfectly with
SuperKey. K9 was then in C (it is now in assembler), but the logic of the
keyboard intercepts is the same, so maybe K9 and SuperKey still get along. We
would like to hear from someone on that.

If used along with SideKick, K9 should be loaded after SideKick. This allows
the F7 and F8 keys to work properly within SideKick's calculator, for users
who prefer (or, for lack of a numeric coprocessor, must use) that calculator.

K9 gets along fine with CodeSmith-86 (which helped bring it to life in the
first place), SYMDEB, and DEBUG. We would be interested to hear of
compatibility or lack thereof with other debuggers.


//////////////////////////////////////////////////////////////////////////


TECHNICAL NOTES
---------------

Of possible interest in multiple screen environments, or for heaven knows what
other reasons: K9 uses BIOS to write to the screen, with the exception of the
clock and the ASCII table, which write directly to the video buffer.

K9 is written in assembler and assembled with Phoenix Technologies' LPASM, v.
2.00.