The "Extended Echo with Color" Assembler Project

"Extended Echo with Color", a multi-functional batch enhancer under DOS and in Windows DOS boxes

|  Home  |
|  Download Extended Echo with Color (xewc121.zip)  |

XEWC V1.21/2004 FREEWARE

XEWC is used in batch programs for DOS and in DOS boxes of Windows 95/98/ME/NT/2000. It works similar to the ECHO command, however, using replacement parameters it is possible to send specific characters and colors to the screen. In addition, several new functions are introduced (see below). The program makes use of the BIOS functions. Redirection of outputs (into a file instead of the screen) is not possible. All characters (including control characters like CR, LF, ESC, TAB, FF, BEL) are sent as characters to the screen. The number sign # is used to start replacement parameters. % parameters can be used in the same way as with the ECHO command.

Invocation example

XEWC Comment 1 :#=07 #=47 Info -#3E Tiger #=07#; Comment 2

Screen output

light-grey letters on red background: Info -> Tiger

The first colon starts the screen output,
#; stops the screen output
#00 to #FF serves as replacement for the hex value of a character to be output

#3E >
#3C <
#22 "
#7C |
#25 %
#26 &
#1B <ESC>
#09 <TAB>
#27 '
#0C FF  (Form Feed)
#07 BEL (Bell)
#40 @
#0D CR alone
#0A LF alone
#5E ^

#V additional new line output (CR+LF) plus deletion of the new line
#P no CR+LF at the end of the line
## outputs # once
#G sends time and date stamp to the screen (German)
#$ sends time and date stamp to the screen (English)
#H sends only the time stamp to the screen
#; as of here the command line is no longer evaluated (comment)

#=00 to #=FF Turns on colored background and colored characters:

Background colors Character colors
0 = black 0 = black
1 = blue 1 = blue
2 = green 2 = green
3 = cyan 3 = cyan
4 = red 4 = red
5 = magenta 5 = magenta
6 = brown 6 = brown
7 = light grey 7 = light grey
8 = dark grey or flashing black 8 = dark grey
9 = light blue or flashing blue 9 = light blue
A = light green or flashing green A = light green
B = light cyan or flashing cyan B = light cyan
C = light red or flashing red C = light red
D = light magenta or flashing magenta D = light magenta
E = yellow or flashing brown E = yellow
F = white or flashing light grey F = white

Whether the background flashes or the light color is displayed with 8...F, depends on the configuration of the computer or on the operating system used.
For compatibility reasons, only the values 0...7 should be used for the background color in case of doubt.
Standard setting is #=07 (black background, light grey characters)

Other functions

#=G Synchronization to the next full second (waits until the next new second),
    reaction on a key stroke: abortion and errorlevel 100
#=H Deletion of the keyboard buffer, generates errorlevel 0 or 1:
    Errorlevel 0, if the buffer was empty
    Errorlevel 1, if the buffer contained characters
#X  or
#=X Bell sound
#U  Sound output 880 Hz, short
#W  Sound output 440 Hz, long
#=Y Clear Screen
#Z  or
#=Z No prompt on a key call (see next)

#[...] Key call

Between the brackets [ ] the characters A...Z, 0...9 and SPACE can be inserted. The program waits for an entry from the keyboard. If the entered character is equal to one of the characters inserted between the brackets, the program is continued and an errorlevel (1...n) is generated. The position of the character between the [ ] determines the value of the errorlevel produced. A...Z means the same as a...z. If SPACE is defined between the [ ], the entry of the ENTER key causes the same as the SPACE key.

Example:  XEWC :#[d7T ]
Result:
D or d  produce errorlevel 1
7 produces errorlevel 2
T or t  produce errorlevel 3
SPACE or ENTER key produce errorlevel 4
ESC produces errorlevel 0 (fixed setting)

A maximum of 40 characters may be inserted between the brackets. If characters are used several times, only the first ones are valid.

Example:  XEWC :#[A 5 u a]
Result:
A or a produce errorlevel 1
SPACE or ENTER key produce errorlevel 2
5 produces errorlevel 3
U or u produce errorlevel 5
ESC produces errorlevel 0 (fixed setting)
Errorlevels 4, 6 and 7 can never be produced because
SPACE and 'a' are used several times.

If a preselected key is pressed, the entered character is output to the screen. Instead of ESC, SPACE or ENTER always a SPACE is output. If this sreen output is not desired, it can be suppressed by inserting #=Z (or #Z) at the beginning of the command line.

Example:  XEWC :#=ZTextText#[ABC123 ]More text
Output:   TextTextMore text
          (the keyboard entry has no effect to the screen output)

#(...) Cursor control

Invocation of #(...) (Cursor control) results in changing shape and/or position of the cursor. Examples:

#(N) or #(ON)  Cursor is turned on  (VGA and higher)
#(F) or #(OFF) Cursor is turned off (VGA and higher)
#(V) or #(VGA) Standard setting for VGA and higher (also MCGA)
#(C) or #(CGA) Standard setting for CGA and higher
#(M) or #(MDA) Standard setting for MDA, HERCULES, EGA
#(B) or #(BIG) Big cursor
#(-)           Thin cursor
#(+)           Wide cursor
#(X46) Cursor jumps to the 46th column (counts from 1 to 80)
#(Y17) Cursor jumps to the 17th row (counts from 1 to 25)
#(R)   Stores (saves) current cursor position in memory 0
#(S)   Puts cursor to position stored in memory 0
#(T)   Stores (saves) current cursor position in memory 1
#(U)   Puts cursor to position stored in memory 1
#(W)   Shifts cursor one position up but not beyond the screen
#(E)   Shifts cursor one position down but not beyond the screen
#(P)   Shifts cursor one position to the left (but not beyond...)
#(Q)   Shifts cursor one position to the right (but not beyond...)

It is possible to specify several parameters within one command,
e.g. XEWC :#(FX53Y12R)Hello#(SN)

In the DOS box of Windows NT/2000, the cursor control is limited. Only cursor movements as well as storing and recovering of cursor position work correctly.
Hiding the cursor or setting to display standards (VGA, CGA etc.) do not work with the emulated DOS box of Windows NT/2000.

#{...} Insertion of a text string from a file

Between the brackets of #{...} the complete path name of that file must be inserted, from which the text string is to be taken in order to send it to the screen. From the file, only a maximum of 80 characters are considered. Possibly existing CTRL-Z or CR/LF characters are omitted.

Example: XEWC :#{C:\TEXTS\SPECIAL\WRITE.TXT}

File names and directory names must meet the DOS specifications. Long file names are not accepted. If the given file is not found, nothing will be sent to the screen (neither an error message).

#+...+ Wait (delay)

Between the two plus signs of #+...+ a number (1 to 65535) must be inserted. The wait function starts a delay (time base is seconds). If a key is pressed during the delay time, the wait function will be aborted and the errorlevel 100 will be set. Numbers greater than 65535 will cause undefined results.

Example: XEWC :#+25+

The plus sign at the end of the inserted number must not be forgotten. Otherwise the function will not work correctly.

#-...- Waiting for a given time (of day)

Between the two minus signs of #-...- a time (of day) (00:00 to 23:59) must be inserted. This function starts a delay, which expires at the given time. If a key is pressed during the delay time, the wait function will be aborted and the errorlevel 100 will be set.
Given time stamps, which are invalid, will cause undefined results. Please note, that hours and minutes must be given in two digits each.

Example: XEWC :#-00:09-
or:      XEWC :I am waiting until 09:05 #-09:05- #$

In the second example, the time stamp is sent to the screen after the time has elapsed (for checking the correct function). The minus sign at the end of the inserted time must not be forgotten. Otherwise the function will not work correctly.

Working with variables (mainly used with counters and timers)

The XEWC program works with two variables, which can have sizes of -32767...0...+32767 as signed integers. The two variables are addressed with #!.... (variable 1) and #:.... (variable 2).

The following examples show the possible applications. The numbers can be specified with or without sign, e.g. 200 or +200 (positive number) or -200 (negative number):

#!-200! Variable 1 is set to -200
#!N     Variable 1 is negated (sign - instead of + or vice versa)
#!=     Variable 1 is sent to the screen (with sign plus 5 digits)
#!_     Variable 1 is processed as an amount of seconds and displayed
        in the format HH:MM:SS (hours:minutes:seconds)
        (variable 1 must be a positive number here, 0...+32767)
#!6548? Variable 1 is compared to the number +6548. Result:
          Errorlevel 3 if variable 1 is greater than the number
          Errorlevel 2 if variable 1 is equal to the number
          Errorlevel 1 if variable 1 is less than the number
#!34+   Variable 1 is increased by 34
#!72-   Variable 1 is decreased by 72
#!-32*  Variable 1 is multiplied by -32
#!18/   Variable 1 is divided by 18, the result is rounded down
          to a signed integer
#!K     Variable 1 is entered on the keyboard.
          Example: XEWC :#=30 How many copies to print? #!K#!= copies
          After invocation with #!K a number of -32767...0...32767
          has to be entered on the keyboard. Other values cause errors.
          The entry is terminated by the ENTER key. After pressing
          the ENTER key, the cursor moves back to the first position
          of the entered number.
#!{...} Variable 1 is loaded from that file, whose name is inserted
          between the brackets {}. Example: XEWC :...#!{C:\XEWC\VAR1.VAR}
          The specified file must contain a valid number -32767...+32767.
          Examples for file contents: 5 -67 +00008 -056
#!(...) Variable 1 is copied to that file, whose name is inserted
          between the brackets (). Example: XEWC :...#!(C:\XEWC\VAR1.VAR)

#:200:  Variable 2 is set to +200
#:N     Variable 2 is negated (sign - instead of + or vice versa)
#:=     Variable 2 is sent to the screen (with sign plus 5 digits)
#:_     Variable 2 is processed as an amount of seconds and displayed
        in the format HH:MM:SS (hours:minutes:seconds)
        (variable 2 must be a positive number here, 0...+32767)
#:-548? Variable 2 is compared to the number -548. Result:
          Errorlevel 3 if variable 2 is greater than the number
          Errorlevel 2 if variable 2 is equal to the number
          Errorlevel 1 if variable 2 is less than the number
#:34+   Variable 2 is increased by 34
#:72-   Variable 2 is decreased by 72
#:50*   Variable 2 is multiplied by 50
#:-18/  Variable 2 is divided by -18, the result is rounded down
          to a signed integer
#:K     Variable 2 is entered on the keyboard.
          For further description see #!K
#:{...} Variable 2 is loaded from that file, whose name is inserted
          between the brackets {}. Example: XEWC :...#:{C:\XEWC\VAR2.VAR}
          For further description see #!{...}
#:(...) Variable 2 is copied to that file, whose name is inserted
          between the brackets (). Example: XEWC :...#:(C:\XEWC\VAR2.VAR)

#!:+  Variable 1 is increased by the value contained in variable 2
#!:-  Variable 1 is decreased by the value contained in variable 2
#!:*  Variable 1 is multiplied by the value contained in variable 2
#!:/  Variable 1 is divided by the value contained in variable 2,
        the result is rounded down to a signed integer
#!:!  Variable 1 is exchanged with variable 2
#!:?  Variable 1 is compared to variable 2. Result:
        Errorlevel 3 if variable 1 is greater than variable 2
        Errorlevel 2 if variable 1 is equal to variable 2
        Errorlevel 1 if variable 1 is less than variable 2
#!:_  Variable 1 copies the value from variable 2,
        variable 2 remains unchanged

#!:\  Variable 1 is divided by the value contained in variable 2.
        Results: variable 1 contains the result of division
                 variable 2 contains the undevided rest (modulo)

#:!+  Variable 2 is increased by the value contained in variable 1
#:!-  Variable 2 is decreased by the value contained in variable 1
#:!*  Variable 2 is multiplied by the value contained in variable 1
#:!/  Variable 2 is divided by the value contained in variable 1,
        the result is rounded down to a signed integer
#:!:  Variable 2 is exchanged with variable 1
#:!?  Variable 2 is compared to variable 1. Result:
        Errorlevel 3 if variable 2 is greater than variable 1
        Errorlevel 2 if variable 2 is equal to variable 1
        Errorlevel 1 if variable 2 is less than variable 1
#:!_  Variable 2 copies the value from variable 1,
        variable 1 remains unchanged

The contents of the variables are lost when the computer is rebooted or in case of warm or cold start. If the DOS box of WIN95/98/ME/NT/2000 is closed, the variables may also be destroyed. If variables are to be stored and reloaded, the functions #!{...} #!(...) #:{...} #:(...) may be used.

The variables use the RAM memory addresses of the so-called Intra Application Communication Area, ICA (40h:00F0h to 40h:00FFh) for their storage. If another program also uses these memory addresses, the variables may fail.
The tests, executed using the variables, were successful on all test computers (different computer types old and new, DOS and DOS boxes).

Remarks:
- All results can only be correct, if the value range does never exceed -32767...0...+32767.
- Division by 0 is not possible. This division does not perform anything.
- The number 0 cannot be negated (-0 and +0 are identical, so they are always displayed as +00000).

Creation of return codes (errorlevels)

Return codes can be produced at any position of the command line. If more than one return code are produced, the last one will be saved and can be evaluated by IF ERRORLEVEL then. Setting a return code: #R00 to #RFF (hex value causes the code of 0...255).

#,.., Special function: checking for a given drive letter

If a valid drive letter is inserted between the two commas, e.g. #,d:, an errorlevel is set, depending on the drive letter. A: causes errorlevel 1, Z: causes errorlevel 26.
If no valid drive letter is inserted between the two commas, error- level 0 is generated. Errorlevel 0 is also output in the following cases:

#,c, the colon is missing
#,C: the second comma is missing
#,c:\ this is a directory, not a drive
#, C:, the blank must not exist
#,C:x, undefined x

In batch files may be a line such as XE :#,%1,
If the first parameter of the command line is D: for example, %1 will be accepted as a valid drive letter.

Program details

The XEWC program was completely written in assembly language. Upper and lower case letters have the same meaning if used together with # parameters (#3a is identical to #3A). The program may be distributed free of charge (freeware). Never distribute the program without its documentation and the enclosed example batch files.

Used memory addresses of the ICA (40h:00F0h to 40h:00FFh):
----------------------------------------------------------
F0 F1  F2 F3    F4 F5 F6 F7 F8 F9 FA FB  FC FD  FE FF
#(rs)  #(tu)                             #:...  #!...
cursur position ------still unused-----  variables

Valid-HTML401  Valid-CSS