Quick Function Description

ILTER is a program which, as the name suggests, can filter something. It can filter the keyboard, thereby rearranging the keys. It can filter the screen output, thereby allowing output from programs written with the special Danish characters Æ, Ø and Å located at [, \ and ] to be printed as the characters Æ, Ø and Å. And it can filter the printer and RS-232 in- and output.

System requirements

ILTER requires an IBM PC or close compatible running DOS 3.1 or later. Your computer doesn't have to be 100% compatible, as long as your specifications for INT 10h, INT 14h, INT 16h and INT 17h are the same as for the IBM PC. See the note later in this manual about the functions that FILTER intercepts.

Calling syntax

  FILTER [<Device> [<FileName> | ? | <Char>=<Char> | OFF | ON] | ? ]

    <Device>            is the name of the device you wish to communicate
                        with (KBD (Keyboard), BRC (BIOS Read Character),
                        BWC (BIOS Write Character), PRN (Printer), SRI
                        (Serial (RS-232) Input), SRO (Serial (RS-232) output)
    <FileName>          Is the name of a translate table file of excactly
                        256 bytes length.
    <Char>              Is any character specification.

The following device names are supported by FILTER
BRCBIOS Read Character(Reading from screen)
BWCBIOS Write Character(Writing to screen)
SRIRS-232 input(Reading)
SRORS-232 output(Writing)
ie. whenever you want to do something about the keyboard translation, you should use the KBD device.
More detailed explanation is coming later on in the manual.

Detailed Description for normal use

o install FILTER you just type FILTER on the command prompt and then FILTER will install itself. By default it will work with US-ASCII to DK-ASCII conversion, but this can be changed by loading new translate tables. An example of a normal startup sequence, where you wish to use the translate file XLATE.KBD for the keyboard and disable all the other devices:

FILTERInstall FILTER resident
FILTER KBD XLATE.KBDLoad KBD translate table
FILTER BRC OFFTurn off BRC device
FILTER BWC OFFTurn off BWC device
FILTER PRN OFFTurn off PRN device
FILTER SRI OFFTurn off SRI device
FILTER SRO OFFTurn off SRO device

Using the FILTER program from DOS

s shown in the syntax diagram, there are many options you can give the FILTER program on the command tail, and it will then pass along this information to the resident part of FILTER. You have the following command tail options:

       FILTER <device> <filename>       Load XLATE table from file
       FILTER <device> ?                Show converted characters
       FILTER <device>                  Toggle enabled state of a device
       FILTER <device> OFF              Disable a device
       FILTER <device> ON               Enable a device
       FILTER <device> <char>=<char>    Set a single XLATE character
       FILTER ?                         Show a brief command summary
       FILTER                           Show the state of the devices

where <device> must be one of the following:

       KBD      -       The Keyboard (Input)
       BRC      -       The screen (Input)
       BWC      -       The screen (Output)
       PRN      -       The Printer (Output)
       SRI      -       RS232 (Input)
       SRO      -       RS232 (Output)

he <char> parameter supports four different methods of defining a character: <char>, #<HexVal>, $<HexVal> or <DecVal>. If the entered parameter is only one character long, it will be considered a character. Otherwise it will be either a decimal or hexadecimal number, depending on if the first character is '#' or '$'. This means that to enter character 7 (^G) you must enter 07, #7 or $7 to make FILTER know it is a number and not a character.

ach of these command tail options are described seperately below. If the resident part of FILTER hasn't been installed yet, it will be installed before executing your command.

FILTER <device> <filename>
Loads the file specified by the <filename> into the XLATE table for the specified <device>. The length of the file must be 256 bytes excactly for the load to work. You can use the accompanying program INSFILTR to maintain XLATE tables. If the filename doesn't specify a file type, it will default to the same type as the name of the device.
FILTER <device> ?
Shows a list of all the characters the XLATE table will change for the device. The format of the print is <char1>=<char2> where Æ=[ for the KBD device means that any press on the Æ key will be sent to the program as a [.
FILTER <device>
Disable/Enable the device. This option is also possible via the keyboard (see later). Each time this command is run, the state for the specifed device toggles between Enabled and Disabled.
FILTER <device> OFF
Turns off the device.
FILTER <device> ON
Turns on the device.
FILTER <device> <char>=<char>
Sets a single character in the XLATE table. FILTER PRN £=# ensures that any IBM pound charcters will be printed on the printer as a hash character, or as a pound character on English Non-IBM printers.
Prints a short text describing the syntax of the command tail options.
Shows the status of the four devices, their Active/Inactive state and the name of the last file loaded.

Disabling or enabling the devices from the keyboard

henever an application programs asks for input via BIOS (or via DOS, as DOS uses BIOS), FILTER will intercept some of the key strokes. These key strokes allows you to turn the devices on or off. I've decided to use the same way of disabling as the national keyboard drivers do (in case you didn't know; you can disable your national keyboard driver with Cltr-Alt-F1 and enable it again with Ctrl-Alt-F2), but with F3-F10 instead. The key layout is as follows:

F3Disable keyboard deviceF4Enable keyboard device
F5Disbale BIOS Read Char deviceF6Enable BIOS Read Char device
F7Disable BIOS Write Char deviceF8Enable BIOS Write Char device
F9Disable Printer deviceF10Enable printer device
All of these keys must be pressed with Ctrl+Alt to be recognized.

nfortunately I ran out of F-keys when implementing the RS232 filter, so you can only disable these with the FILTER program.

Detailed Description for advanced users and programmers

s stated earlier, FILTER can convert characters from the keyboard and from and to the screen, but that is not all it does.

t can also rearrange the output to the printer, allowing conversion from IBM-ASCII to DK-ASCII, ie. the IBM character Æ (character 146) to be written to the printer as a [ (character 91), which many Danish printers will print as an Æ.

ILTER can also provide conversion on the INT 14h (RS232) interrupt, allowing you to use FILTER with FOSSIL drivers. If you don't know what a FOSSIL is, it is a standard protocol that provides interrupt-driven I/O via the standard INT 14h interface (which normally isn't interrupt-driven). A FOSSIL is normally only used when running BBS software.

ou can also use it when logging on to bulletin boards. If you specify the Keyboard to translate Æ to [ then your communications software (ProComm, Telix or whatever) will receive a [ when you press Æ and the BBS will then echo a [ back to you. If you then specify the BIOS write to convert [ to Æ, it will be printed as an Æ, even if the BBS thinks you typed a [. To complete the transfer you could then specify the BIOS read to convert Æ to [, which will ensure that if your comm. software reads the character off the screen using the BIOS, it will receive a [. As this is such a useful feature for Danes (and I'm a Dane), I have made FILTER use this system as default.

The various devices intercepts the following functions:
BRCINT 10h, function 08h
BWCINT 10h, functions 09h, 0Ah, 0Eh and 13h
KBDINT 16h, functions 00h, 01h, 10h and 11h
PRNINT 17h, function 00h
SRIINT 14h, function 01h
SROINT 14h, function 02h

ie., when you read a key via INT 16h, FILTER will call the original INT 16h driver and then convert the character according to the map. When you read a character off the screen, FILTER will first read the real character and then look this up in the BRC map. When writing to the screen or printer, FILTER will convert the character received and pass the converted character along to the original driver.

Programming FILTER from your own programs

ILTER installs itself as a HeartWare Multiplex driver, with driver no. 2.

See the page regarding HeartWare resident program interface standard for more information on the HeartWare way of doing things.

FILTER recognizes several functions. The function request number is defined as two nibbles, where the high nibble defines the action you want to do, and the low nibble defines the device:

High nibble:Action
0Read XLATE table 
1Write XLATE table*
2Set XLATE char*
3Set "active" flag*
Low nibble:Device:
1KBD (Keyboard) 
2BRC (BIOS Read Character) 
3BWC (BIOS Write Character) 
4PRN (Printer) 
5SRI (Serial Input) 
6SRO (Serial Output) 
The functions marked with a star can also be executed
using the FILTER program from DOS.

This means, that if you want to set the XLATE table for the BWC device, you must load AL with 13h.

FILTER's multiplex number is 2, and you thus have to call FILTER in the following way:

        		MOV	AH,87h
        		MOV	AL,<Func>
        		MOV	CX,2
        		MOV	DX,5553h
        		INT	2Fh

provided the other registers are set up previously. For compatibility with an earlier version of FILTER, it also recognizes multiplex D5h for programming, but this compatibility may be removed later on. Use the HeartWare Multiplex standard to call FILTER if you want to be compatible with new versions of the software.

The various function groups requires the following parameters:
0ES:DIPointer to where FILTER should copy XLATE table to.
1DS:SIPointer to where FILTER should copy XLATE table from.
2BHCharacter to convert
 BLCharacter to convert BH to
3BLEnable (=1) or disable (=0) device

Note to users of NANSI

f you are using NANSI.SYS as your ANSI driver, you will notice that the modifications you make to the BWC device will have no effect whatsoever. This is because NANSI does not use BIOS to write characters. Instead it pokes the characters directly into the screen memory, making it impossible for FILTER to do anything with the characters. NANSI will, however, accept changes to the KBD device, but if you have used KBD to rearrange the S and D keys and then used BWC to arrange them back again (this will make programs receive a D when you press S (and vice versa)), it will print an S on the screen. There is no cure for this other than removing NANSI.SYS from the CONFIG.SYS file.

Companion programs

ith the FILTER program is also a companion program, INSFILTR, that can set up the translate tables for the FILTER program. It is very simple to use, with on-screen context-sensitive help. Just start it up and press F1 for help, and you will be guided through. If you ever get stuck or don't know what your options are at any point, just press F1 and INSFILTR will give you a screenfull of text telling you.

Generally speaking, the program can define translate tables either on disk, or directley into the FILTER program. There are four options to facilitate the transfer of translate tables between INSFILTR and FILTER or the disk:

LOADLoads (reads) a translate table from the disk
SAVESaves (writes) a translate table to the disk
READReads a translate table from one of the FILTER devices
WRITEWrites a translate table to one of the FILTER devices.

Various notes

ILTER has internal logic that prevents a character to be converted twice if one of the filtered routines calls another filtered routine in the same category, ie. I have noticed that on some machines, when you use INT 10h, function 0Eh, it will print the required character by calling INT 10h, function 09h. If you then had BWC to convert an S to a D and a D to an S and were to write an S using INT 10h, function 0Eh, it would first be converted into a D and then back into an S. This is prevented by letting the FILTER program watch the "communication" of the functions and if one function isn't finished when another is received, no conversion is made.

hen you use the keyboard method of turning the devices on or off, FILTER will "eat" the Ctrl-Alt-F3 to F10. If you actually want to pass along a Ctrl-Alt-F3 to F10 to a program, you must type it twice just after each other. The first one will be obeyed by FILTER and the second one will be passed along to the running program.


Installs FILTER (if not installed already) and shows a short status report.
Installs FILTER (if not installed already) and loads a keyboard translate table into FILTER.
Installs FILTER (if not installed already) and shows which characters are translated to which characters for the keyboard device.
Activates the KBD device and Tells FILTER that whenever a user presses X on the keyboard, it should be converted to a Y.
Show which characters are converted to which characters for the KBD device.

Output is of the form <char1>=<char2> and tells that <char1> will be converted to <char2>. If you have started up the FILTER program and executed the example above, it would report this:

        Status for device KBD:
        X=Y     å=}     Å=]     æ={     Æ=[     ø=|     Ø=\     
which tells you that any press on X on the keyboard will be translated into a Y, å into } etc.
Disables the keyboard device.