Category : Display Utilities
Archive   : ZACKIN.ZIP
Filename : CONDRV.DOC

********************************************************************************
Enhanced Console Device Driver, Copyright (c) 1986 Anthony Zackin
********************************************************************************

The syntax of the Enhanced Console Device Driver commands is similar to the DOS
extended screen and keyboard control functions defined in the DOS Technical
Reference Manual. The functions defined here are somewhat more complex since
the data sent to the driver must consist of a set of operations and strings to
enable the creation of the screen display buffer. The basic syntax is:

Esc[{operation-string}:

where `Esc' represents the escape character, ASCII 27 (hexadecimal 1B), and
{operation-string} typically consists of a one-byte operation code (op)
possibly followed by an attribute, one or more sets of row/column coordinates,
and perhaps a string to be placed in the buffer. The op codes may have several
variants which are created by adding 128, 64, 32, etc. to the base value defined
below.

When the Enhanced Console Driver has been installed at system boot time (by a
`DEVICE=CONDRVxx.SYS' entry in the CONFIG.SYS file) all console output displayed
via DOS will be examined for the escape sequences defined below. If a legal one
is found the appropriate operation is performed.


op=0 - Display a window from the current screen buffer (modifier = 128).

Esc[0;{frow};{fcol};{trow};{tcol};{srow};{scol}:
Esc[128;{window};{frow};{fcol};{trow};{tcol};{srow};{scol}:

- displays an explicitly defined window ({frow},{fcol}) through
({trow},{tcol}) of the current buffer; if any of the row or column values
are omitted then the current default values are used (set by Esc[1 ... or
by builtin defaults, normally, 1,1,25,80,1,1); if row/column values are
specified then row/column values to their left may not be omitted

- all arguments are optional
- row 1, column 1 corresponds to the upper left-hand corner of the screen
- {frow};{fcol} (1,1) = starting (from) row,col of the window in the
screen buffer
- {trow};{tcol} (1,MAXCOL) = ending (to) row,col of the window in the
screen buffer
- MAXCOL = 80 when MODE 80 is in effect, 40 when MODE 40 is in effect
- row/column coordinates define a `window' to display, not necessarily
contiguous characters
- if frow,fcol = 4,21 and trow,tcol = 8,60 then only columns 21 through
through 60 inclusive of rows 4 through 8 inclusive will be displayed
- {srow};{scol} (1,1) = starting row,col in the display adapter memory to
which the window defined above in the screen buffer is moved
- initial defaults are in parentheses above
- if op+128 is specified then a window number between 0 and 3 must be
specified as the first argument; window 0 is assumed otherwise
- each screen buffer may have up to four predefined windows which may
be displayed solely by referring to the window number
- any supplied arguments will override the corresponding predefined
values

- Esc[: = Esc[0:
- this sequence is all that is needed to display the currently defined
screen buffer; for example, via a program such as DEFKEY (see below)
use Esc[1 ... to define the default window to be displayed and its
location on the screen and then display it via a PROMPT, e.g., PROMPT
$e[:

- Example:

Esc[0;1;1;5;10;21;1:

- displays the window from row 1, column 1 to row 5, column 10 at
screen location = row 21, column 1; the default window and screen
location values remain unchanged

Esc[: or Esc[0:

- this will display window number 0 from the currently selected buffer

Esc[128;3:

- this will display window number 3 from the currently selected buffer

op=1 - Same as op=0 except that the window is not displayed but rather the
defaults for the next display are reset. This permits one program to define a
buffer and another to display whatever has been defined. (Modifier = 128).

Esc[1;{frow};{fcol};{trow};{tcol};{srow};{scol}:
Esc[129;{window};{frow};{fcol};{trow};{tcol};{srow};{scol}:

- defines the default window parameters for the current window, from
({frow},{fcol}) through ({trow},{tcol}) in the current buffer to
({srow},{scol}) on the screen

- no data are displayed

- Example:

Esc[1;1;1;5;10;21;1:

- resets window number 0 defaults
- data to be displayed will come from row 1, column 1 to row 5,
column 10 of the current buffer
- display will start at screen location = row 21, column 1
- note that one or more of these defaults may be temporarily
overridden by an Esc[0 ... with row/column values specified

Esc[129;3;1;1;5;10;21;1:

- resets window number 3 defaults for the current screen buffer

op=2 - Locate a string within the current screen buffer at a specified row and
column; all characters in the string will be given the specified attribute
({attr}) or will use the currently set default value if {attr} is not specified.
(Modifiers = 128, 64, and 32. The op modifiers are not mutually exclusive but
note that op+96 is not the same as op+64+32.)

Esc[2;{attr};{row};{col};{"string"}:

- op+128 = {attr} omitted (use current screen's current default value)
- op+64 = {row};{col} omitted (start at next position)
- op+32 = row value is added to current row; column is absolute
(row value not incremented if cursor column position = 1)
- op+96 = {row};{col} omitted but assumed to be current row+1;1, viz.,
{CR}{LF} (row value not incremented if cursor column position = 1)

- the current attribute value remains unchanged

- Example:

Esc[2;116;1;1;"HELLO ":
Esc[66;5;"THERE":
Esc[226;"------------------------------------------------------":

- puts `HELLO ' in the first five positions of the buffer as red on
white; `THERE' follows immediately in magenta on black; finally a
line of dashes is displayed in the first position of the next line
using the current default attribute (whatever it has been previously
set to or the initial default, white on black)

op=3 - Same as op=2 except that the default attribute byte for the current
screen is reset if an attribute byte is specified.

Esc[3;{attr};{row};{col};{"string"}:

- the attribute byte for the current screen is reset if specified

- Example:

Esc[2;116;1;1;"HELLO ":
Esc[67;5;"THERE":
Esc[226;"------------------------------------------------------":

- puts `HELLO ' in the first five positions of the buffer as red on
white; `THERE' follows immediately in magenta on black with the
default attribute getting reset accordingly; finally a line of dashes
using the new current default, magenta on black, is displayed
starting in the first position of the next line


op=4 - Clear a window of the current screen buffer, i.e., moves spaces to the
screen buffer window with the specified or current attribute byte. (Modifier =
128.)

Esc[4;{attr};{frow};{fcol};{trow};{tcol}:

- all arguments are optional

- op+128 = {attr} omitted - use the current default attribute value

- the default attribute byte is not updated

- if any of the row or column values (either the from values or both the
from and to values) are omitted then the values used will be the current
settings set by the last op=1 command or by default; note that if {trow}
is to be specified then {frow} and {fcol} must also be but {tcol} needn't

- row/column coordinates define a `window' to clear, not necessarily
contiguous characters
- if frow,fcol = 4,21 and trow,tcol = 8,60 then only columns 21 through
through 60 inclusive of rows 4 through 8 inclusive will be cleared in
the currently active buffer

- Example:

Esc[4;112;20;1;25;80:

- clears the current buffer from row 20, column 1 through row 25,
column 80 to white

Esc[4;0;1;71;25;80:

- clears columns 71 - 80 in all rows of the currently active buffer to
black

Esc[4:

- clears the currently defined window in the current screen buffer;
the default attribute byte for the current screen is used to
determine the background color


op=5 - Same as op=4 except that the current attribute value for the current
screen is reset to the specified value.

Esc[5;{attr};{frow};{fcol};{trow};{tcol}:

- Example:

Esc[5;112:

- clears the currently defined buffer window and resets the current
attribute byte to black characters on a white background


op=6 - Clear (with spaces) from the position after the last located string
(op=2) in the current screen buffer to the end of that line. (Modifier = 128).

Esc[6;{attr}:

- op+128 means {attr} omitted, i.e., use the current attribute value, viz.,
the value set by the last op=3 or op=5 command which specified an
attribute byte
- this is equivalent to specifying Esc[6:

- the attribute value is not reset if specified

- Example:

Esc[2;23;10;1;"*":
Esc[6;0:

- this will put a white asterisk on a blue background in row 10, column
1 of the buffer and clear the remainder of the line to black


op=7 - Same as op=6 except that if an attribute byte is specified, the current
default value will be reset.

Esc[7;{attr}:

- the default attribute value for the current screen is reset if specified

- Example:

Esc[2;23;10;1;"*":
Esc[7;112:


- this will put a white asterisk on a blue background in row 10, column
1 of the buffer and clear the remainder of the line to black; in
addition, the default attribute byte for the current screen will be
reset to white on black


op=8 - Set/reset the BIOS flag to control whether direct BIOS calls as well as
DOS calls will be trapped. Also allows the suppression of keyboard redefinition.
(Modifier = 128).

Esc[8;{flag}:

- if {flag} is a 1 then direct BIOS calls will be trapped
- if {flag} is omitted or anything else then BIOS calls will be ignored by
the driver, i.e., the BIOS trap will be disabled

- Example:

Esc[8;1:

- this will enable the driver to trap direct BIOS calls
- issuing this command before going into BASIC will permit BASIC to
directly stack commands; e.g.,to clear the screen at the end of a
BASIC program one could specify

CMD$ = CHR$(34)+"CLS"+CHR$(34)
PRINT CHR$(27)+"["+CMD$+";13.";


Esc[8:

- this will disable the BIOS call trap

Esc[136;{suppress-count}:

- if op+128 is specified then the flag value controls DOS keyboard
redefinition:
- a count other than 255 will be treated as a suppression count; no DOS
keyboard redefinitions will be interpreted while this value is
non-zero
- a flag value of 255 will decrement the suppression count by 1 only if
the latter is non-zero
- if {flag} is zero or omitted DOS keyboard redefinition will be enabled
- DOS keyboard redefinition is enabled by default

- Example:

Esc[136;2:

- this will disable DOS keyboard redefinition so that programs which
need the native key values will get them and not the redefinitions
- the suppression count will be set to 2 in this case
- NOTE: the {suppress-count} value used here should be one greater than
that for the other commands (CLOCK, for example) since keyboard
redefinition will be re-enabled as soon as the count goes to zero,
NOT on the next `Esc[136' command

Esc[136;255:

- this will decrement the keyboard suppression count by 1; normally
this command will be made part of the system prompt

Esc[136:

- this will re-enable DOS keyboard redefinitions


op=9 - Set the number of screen rows, 25 or 43 (EGA). (Modifier = 32).

Esc[9;{row-number}:

- if {row-number} is omitted, 25 is assumed
- use 43 row mode only with the EGA or equivalent and an enhanced color
display or equivalent


- op+32 means that the next {suppress-count} mode commands not specifying
this modifier will be ignored. When this modifier is specified an extra
argument, {suppress-count}, is expected before the attribute (if
specified) which denotes a number between 0 and 255 indicating the number
of standard (non op+32) commands to ignore. If a value of 255 is used
all non op+32 commands will be ignored until the {suppress-count} is
explicitly reset by a command with a 32 modifier. This option is useful
for temporarily overriding the 43 line mode which may be defined within
a PROMPT string.

- for op+32 the command syntax is:

Esc[41;{suppress-count};{row-number}:

- if all arguments are omitted then {suppress-count} will be
interpreted as zero, viz., permit subsequent non op+32 mode commands

- Examples:

Esc[41;2:

- this will suppress the next two standard mode commands; note that
the third normal mode command, normally from the PROMPT string,
will reset the display to the desired mode as specified by the
prompt string

Esc[41;255:

- suppresses all subsequent standard mode commands until the
{suppress-count} is explicitly reset

- the following is a practical use for this feature; in it it is
assumed that the PROMPT string contains a mode command. We wish to
override the default mode for the duration of the dBASE program.
The CU program is used to define a value for Alt-F1:

CU AF1 "CU MODE 25 SUPPRESS 2}CD\DBASE}DBASE}"

- this sets Alt-F1 to ignore the next two mode commands from the
next two system prompts resulting from the cd and dBASE
commands so that the prompt string will not reset the default
display mode; dBASE is then invoked and, upon the exit of
dBASE, the prompt will reset the display to its standard mode


op=10 - Select the screen buffer. Four buffers are available but only one,
buffer 0, is garanteed to be unaffected by program execution. Buffers 1-3
utilize the graphics memory area of the display adapter and thus will be
destroyed by any application using the graphics mode.

Esc[10;{buffer}:

- {buffer} should be a number from 0 to 3; if omitted then 0 is assumed
- all subsequent screen operations will be directed to the chosen buffer
until that value is reset; initially buffer 0 is the one used

- Example:

Esc[10;1:
Esc[4;0;1;1;1;80:
Esc[2;64;1;35;"A Title":
Esc[1;1;1;1;80;13;1:

- the next issuance of Esc[: will cause line one of buffer one to be
displayed on line 13 of the screen; buffer 0 will be unaffected


op=11 - Sets the CONDRV version and release values in IACA (0000:04F0)

Esc[11:

- no arguments are required


op=12 - Adjust timer on/off, location, and attributes. (Modifiers = 128, 64, 32
and 16).

Esc[12;{attr};{row};{col}:

- all arguments are optional

- clock (HH:MMxx where xx=am/pm) is displayed at specified location with
specified attributes


- if the {row} and/or {col} values are omitted then the clock will not be
displayed

- op+128 means {attr} omitted, i.e., use the current default value, viz.,
the attribute value of the last op=12 which specified an attribute

- op+64 means that the colon will blink

- op+32 means that the next {suppress-count} timer commands not specifying
this modifier will be ignored. When this modifier is specified an extra
argument, {suppress-count}, is expected before the attribute (if
specified) which denotes a number between 0 and 255 indicating the number
of standard (non op+32) commands to ignore. If a value of 255 is used
all non op+32 commands will be ignored until the {suppress-count} is
explicitly reset by a command with a 32 modifier. This option is useful
for temporarily overriding standard clock attributes which may be defined
within a PROMPT string.

- for op+32 the command syntax is:

Esc[44;{suppress-count};{attr};{row};{col}:

- note that if modifier=128 is also used then {attr} should be omitted
and row and col values should immediately follow {suppress-count};
if all arguments are omitted then {suppress-count} will be
interpreted as zero, viz., permit subsequent non op+32 timer commands

- Examples:

Esc[44;2;4;25;35:

- this will suppress the next two standard timer commands and at the
same time put the clock in red on black in about the middle of the
bottom line of the screen. Note that the third normal timer command
perhaps from the PROMPT string will reset the clock display to the
standard values

Esc[44;255:

- suppresses all subsequent standard timer commands until the
{suppress-count} is explicitly reset

- the following is a practical use for this feature; in it it is
assumed that the PROMPT string contains a timer command. We wish to
override the timer for the duration of the 123 session. The CU
program is used to define a value for Alt-F3:

CU AF3 "CU CLOCK cb BLINK SUPPRESS 2 @ 25 35}CD\LOTUS}123}"

- this sets Alt-F3 to move the clock display to line 25, column
35 in black on cyan and to ignore the clock commands from the
next two system prompts resulting from the cd and 123 commands
so that the prompt string will not reset the default clock
display; 123 is then invoked and, upon the exit of 123, the
prompt will reset the clock to its standard mode


- op+16 enables the clock if other arguments are specified or disables the
clock if Esc[28: alone is specified

- the clock MUST be enabled before any clock function will work,
consequently the first clock call at least must contain this modifier
- technically this causes the timer interrupt to be handled by the
console driver and restored to its initial value by disable


- Examples:

Esc[12;112;1;74:

- this will display a black clock on a white background in the upper
right hand corner of an 80 column screen

Esc[12:

- this will turn off the clock


op=13 - Set/clear alarm. (Modifier = 128).

Esc[13;"hh:mmxx";{window}:

- all arguments are optional

- op+128 means just sound the alarm immediately; any other arguments will
be ignored and no pending alarms will be reset

- time ([h]h:mmxx where xx=am/pm) must be specified exactly as clock is
with a leading space if the hour is only one-digit

- {window} describes a screen buffer window in buffer 0 which will be
displayed when the alarm goes off (0 - 3)

- any call made while an alarm is ringing will reset the alarm

- if no arguments are specified, any pending alarm is cleared as well
- depressing both shift keys simultaneously will also reset the alarm;
the system will beep twice to indicate that the alarm has been reset

Examples:

Esc[13;"12:15pm":

- when the timer contains a matching value of "12:15pm" a bell will be
generated about every 30 seconds until the alarm is reset

Esc[13;"12:15pm";1:

- this will additionally display window 1 when the alarm sounds

Esc[13:

- this will clear any pending alarm and will turn off the alarm if it
is going off


op=14 - Control display, location, and attributes of caps and num lock and print
screen toggle. (Modifiers = 128, 32, and 16).

Esc[14;{attr};{row};{col}:

- all arguments are optional

- 7 character lock display is displayed at the specified location with
specified attributes

- if the {row} and/or {col} values are omitted then the locks will not
be displayed

- op+128 means {attr} omitted, i.e., use the current default value, viz.,
the attribute value of the last op=14 which specified an attribute

- op+32 means that the next {suppress-count} lock commands not specifying
this modifier will be ignored. When this modifier is specified an extra
argument, {suppress-count}, is expected before the attribute (if
specified) which denotes a number between 0 and 255 indicating the number
of standard (non op+32) commands to ignore. If a value of 255 is used
all non op+32 commands will be ignored until the {suppress-count} is
explicitly reset by a command with a 32 modifier. This option is useful
for temporarily overriding standard lock attributes which may be defined
within a PROMPT string.

- for op+32 the command syntax is:

Esc[46;{suppress-count};{attr};{row};{col}:

- note that if modifier=128 is also used then {attr} should be omitted
and row and col values should immediately follow {suppress-count};
if all arguments are omitted then {suppress-count} will be
interpreted as zero, viz., permit subsequent non op+32 timer commands

- Examples:

Esc[46;2;4;25;35:

- this will suppress the next two standard lock display commands and
at the same time put the lock display in red on black in about the
middle of the bottom line of the screen. Note that the third
normal lock display command, perhaps from the PROMPT string, will
reset the lock display to the standard values

Esc[46;255:

- suppresses all subsequent standard lock display commands until the
{suppress-count} is explicitly reset

- the following is a practical use for this feature; in it it is
assumed that the PROMPT string contains a lock display command. We
wish to override the lock display for the duration of the 123
session. The CU program is used to define a value for Alt-F1:

CU AF3 "CU LOCK SUPPRESS 2}CD\LOTUS}123}"

- this sets Alt-F1 to turn off the lock display, ignore the lock
display commands from the next two system prompts resulting
from the cd and 123 commands, invoke 123 and then, upon the
exit of 123, the prompt string will turn the lock display back
on in standard format

- op+16 enables the lock display if other arguments are specified or
disables the lock display if Esc[30: alone is specified

- the lock display MUST be enabled before any lock display function will
work, consequently the first lock display call, at least, must contain
this modifier
- technically this causes the keyboard interrupt to be handled by the
console driver and restored to its initial value by disable


- Examples:

Esc[14;112;1;67:

- this will display the locks in black on a white background in the
upper right hand corner of an 80 column screen in columns 67-73

Esc[14:

- this will turn off the lock display



The following is a summary of the attribute byte values; for more details, see
the IBM PC Technical Reference Manual:

Monochrome case: Color case:

0 = non-display 16 * (background color) + (foreground color)
1 = underline
7 = normal 0 Black [Gray] 4 Red [Light red]
112 = reverse video 1 Blue [Light blue] 5 Magenta [Light magenta]
2 Green [Light green] 6 Brown [Yellow]
3 Cyan [Light cyan] 7 White [Bright white]

For both the color and monochrome cases, add 128 to get a blinking field, and
add 8 to get high intensity; high intensity color values are in brackets, [...].


To "stack" commands, i.e., make them available to the next DOS read request use
the following display sequence:

Esc[{command-string}.

where {command-string} may consist of a DOS command in quotes and/or ASCII
decimal character values separated by semi-colons, e.g., `"CLS";13'. You may use
the CU STACK command to effect this, e.g., `CU STACK "CLS}"'.

Stack commands may be issued from the system prompt to allow you to execute a
batch file at every prompt. To do this the special stack commands, `Esc[0.' and
`Esc[1.' are used. Normally when Esc[0. or equivalently, Esc[., is "displayed"
subsequent stack operations will be ignored. When Esc[1. is subsequently
display then the next "display" of Esc[. will re-enable stacking. (Note that
`Esc[1.' is NOT the same as `Esc["1".'; the former represents a binary 1
argument while the latter is the character 1). `$e[.' should be specified after
the stack of the batch file in the prompt prompt string, e.g.,
`$e["BATFILE";13.$e.'. This will suppress subsequent stacking of the batch file
command until specifically reset. Since the system prompt is generated for each
displayed line of a batch file, and at least one must be displaced, e.g., ECHO
OFF, this prevents the batch file from being reinvoked for every prompt caused
by execution of the batch file itself. `ECHO Esc[1.' should be the last
statement in the batch file to permit stacking to be re-enabled for one prompt.
`Esc' refers to the ESCAPE character, ASCII decimal value of 27. It may be
entered into a batch file using EDLIN via `^V[' (Ctrl-V followed by a `[').


DOS key redefinitions may made via the console driver; see the DOS Technical
Reference manual for details. If a console driver command as described above, or
in the DOS Technical Reference manual, is defined as the new definition for a
key, that command will be issued immediately upon depression of the key. No call
to another program such as CU is needed. This is particularly useful for the
immediated display of windows. For example, to display window 1 whenever the
{Home} key is depressed pass the following string to the console driver:

Esc[0;71;27;"[128;1:"p


Note that this is equivalent to the more simple "CU HOME DISP WIND 1".


The CONDRV command of the CU program will append an `{Esc}[' (hexadecimal 27 and
91 respectively) sequence to tbe beginning of the subsequent string argument.
It may be used to issue the above commands explicitly instead of using the more
limited CU syntax. For example, to associate a clear screen command with the
{PgUp} key one could use "CU PGUP CLS}" or

CU CONDRV '0;73;27;91;"2J[13."p'

Note the need to place the '13.' inside of a quoted string to enable the
carriage return to be evaluated when the key is pressed and not when it is
associated with PGUP.