Read Me


--------------------------------------------------------
 Display Dumper (DispDump) ver. 0.5 by Tomasz Lasko
--------------------------------------------------------

	Hi, my name in Polish is Tomasz Łaśko, but if you don't have an appropiate font
or just don't how to spell it, just use Tomasz Lasko - that's ok for me, I know from my
own experience that it's a lot easier for foreign people to call me this way :) I like making
different interesting projects. The are many of them, but they are mostly experimental,
so I learn and see how things work, and can then apply them in real projects like the
Display Dumper utility, which I present briefly below. This project is hosted at
SourceForge ( http://dispdump.sf.net ) as I decided to release it as an open source project,
because I like the idea :)

A few of my other projects you may find on my website: www.tomasz.lasko.pl.
If you have ANY thoughts to share with me or other people, then it will be a pleasure to
receive it, just take a minute or two and send me an e-mail ( tomasz@lasko.pl ) or
visit project's SF.net website and post on a forum, send a feature request etc.


-----------------------------------
 Contents of this README file:
-----------------------------------

 0. Disclaimer
 1. What is DispDump?
 2. Why DispDump? 
 3. System requirements
 4. Current status and features
 5. How to use DispDump
 6. Compilation/installation info
 7. Credits
 8. More info


==================================
 0. Disclaimer
==================================

	ALTHOUGH I HAVE TESTED THIS UTILITY, I CANNOT GUARANTEE THAT IT WILL NOT CAUSE YOU ANY DAMAGE
SO YOU HAVE TO USE THIS SOFTWARE AT YOUR OWN RISK!!!


==================================
 1. What is DispDump?
==================================

	DispDump is an abbreviation of the full tool's name: "Display Dumper". The utility gives you
remote control of a PC running MS-DOS (which e.g. does not have a monitor display attached to it).
The screen image (currently text mode only) is taken from the graphics card and transferred to other
computer via serial link and displayed there using ANY serial link terminal emulation software.

	It is an open source project, hosted at SourceForge (sf.net).

You can download it from its official website: http://dispdump.sf.net


==================================
 2. Why DispDump?
==================================

	Once upon a time I had the following problem: I had a PC with Linux and DOS installed earlier
with the help of a connected monitor display. After the instalation I did not have any monitor for a
long time, but it was ok for me as I have been runing only Linux and logging into it from a laptop
(that's why I did not need any monitor) through LAN network, and even optionally through a serial link
if the LAN did not work. But once upon a time a I had to configure an old SCSI controller card and
I could do it only by executing the SCSI controller's setup-BIOS located inside the card's ROM chip,
and this program was 16bit. The only possibility was to run it from DOS, but in this case there was
no way of logging into this system remotely. I needed a specific tool and because I could not find
any suitable program I decided to create my own DOS program which is a substitution of the monitor display,
because it takes the screen image from the graphics card memory and sends it through the serial link,
so after creating the tool (which fortunately took me only one day) I could still work remotely.
Now I am publishing it to the open source community so anybody who potentially will ever need this
kind of program can just download and use it :)


==================================
 3. System requirements
==================================

	As I stated above, the aim for the program is remote control of a computer running MS-DOS,
so it runs on MS-DOS and requires from you to have a COM1/COM2 serial port. The program runs in
background (as a TSR) and uses 16 kB of memory. It has been tested on MS DOS 7.1 (MS Windows 98 DOS).

	On the other computer that is connected (through a "NULL modem" cable) to our MS-DOS machine,
you may use ANY serial link terminal emulation software and the computer itself may be ANY machine
architecture which supports 9,6 kbit/s RS-232 serial link.


==================================
 4. Current status and features
==================================

	Currently the program is version 0.5. It has ALL basic functionality, but also has command line
parameters which do not work, because I have not implemented them yet. The reason is that I wrote the program
in only one day, but plan to add extra functionality later. Below I present the features that are already
implemented and the ones that are to be added or improved in some far future. The future is "far" because
currently there is no need for these extra features, at least for me :), beacuse like I said, ALL the basic
functionality is already working. But if there is anybody who needs them soon then please spend a moment
and drop me an e-mail, so I will try to do some work :)


Currently implemented features:

- Runs in background of MS-DOS (as a TSR, using 16 kB of memory)
- 9600 bps transfer through COM1 or COM2 (selection available through command line parameters)
  (9600 bps is the limitation of BIOS API, but this API is the quickest to use - program made in 1 day:) )
- The receiving machine can be ANY machine architecture which supports 9,6 kbit/s RS-232 serial link,
  you may use ANY serial link terminal emulation software, and the terminal size should be 80x25.
- Screen dumping triggered by two events (you can select one or both of them):
	- timer (e.g. every 3 seconds)
	- key press / Print-Screen-key press (I called it Magic Key / MKey trigger)
- 3 methods of screen dumping:
	- Two ASCII modes: sending just a stream of ASCII characters (without color information)
		- Mode 10: sending all the characters, so the last line ends and a new empty one comes below,
		  recv. terminal size should be 80x26
		- Mode 11: sending all but the last character, so the last line's end is not reached,
		  recv. terminal size should be 80x25
	- Binary mode: inlc. color information
		- Mode 20: sending all the characters, sending raw bytes from gfx card: char, color, ...
		  no recv. terminal exists which could support this mode (maybe I'll make one in the future)
- Debug screen logger
- You cannot turn off the program unless you reboot your MS-DOS system,
  do not run another instance of the program if one is already running.


Candidates for future features (ordered according to their priority):

- Higher speeds of transfer (max transfer speed at least 115kbps)
- Other text screen modes (not only 80x25)
- Creation of a terminal which understands binary modes and screen color information
- 4th method of screen dumping:
	- Binary mode 21: including cursor position
- ... or maybe using Linux/vt100/etc... console escape characters to encode colors... and cursor position?
- ... and sending only differences between each frames, not the whole screen each time
- An option to specify communication time-out
- Possibility to unload the TSR program without having to reboot the MS-DOS system
- maybe some graphical modes in the future?


You can find some screenshots on the project's website - I have ran the Display Dumper under DOS in a virtual machine
and connected to the virtual machine through a virtual serial port driver 'com0com' which is also hosted at SourceForge
and I also recommend you this tool. The screenshots show the same things when you use two serial port clients
(which I described in 'Some HINTS' below)


==================================
 5. How to use DispDump
==================================

	The idea of using DispDump is as follows: you run the program under DOS and it goes to the background
as so called TSR (Terminate and Stay Resident), now it sends the text screen content (the screen mode must
be text mode of size 80x25) through the serial link. So you connect some other machine to it using a serial
link and use ANY terminal emulation program (port settings: 9600bps, 8 data bits, no parity, 1 stop bit).
You should also set the size of the terminal window to 80x25 or 80x26 depending the ASCII mode you have selected.
Now just throw away your monitor display and watch the screen from the DOS system through the serial link,
and just have a good fun :)

	You must be aware of several things about how the program runs, before you actualy run it.
Firstly, it is recommended to read the utility description and the features list above.
Secondly, here is the actual program options syntax:

DISPDUMP [OPTIONS] [DUMP_MODE]

All options are... optional :) The dump mode too.
So if you do not specify them the program will use its default values.

Options:
----------------

Boolean options - each option is a letter; upper case letter means TRUE (on), lower case letter means FALSE (off):

B/b	turn on/off blocking-transfer communication mode during the interrupt (default: B -> on)
		I recommend to leave it as default, except you experience some long delays or hang problems
K/k	turn on/off key-press interrupt screen dump trigger (default: K -> on)
		This means that if this trigger is on, the program will dump the screen through the serial link
		everytime you press a key. Note that there the program reacts in a special way when you press
		the Print Screen key, but this is still experimental.
		Please see also the 'c <timer>' option (below).

L/l	turn on/off debug logger (default: l -> off)
		This logger is really for DEBUG purposes - and for debugging hardware interrupts, so unless you
		read the source code you will not know what it means, but! I recommend that you use it once or twice
		at the very beginning just to be sure that the program actually works. The logger "messages"
		are displayed as a text on blue background somewhere in the upper area of the screen.

Integer options - each option is a letter (case does matter) followed by an integer value

c <timer>	timer value for timer screen dump trigger. This means that you can tell the program to dump the screen
		through the serial link every e.g. 3 seconds. The value is the number of PC clock interrupts,
		which occur approx. 18.2 times per second. So 3 seconds would be 18.2 x 3 = 55
		If you use the value 0 (zero) you will DISABLE the timer trigger.
		The default value is 50 (almost 3 seconds).
		Please see also the 'K/k' option (above).

t <timeout>	serial link transport timeout. This option has been crated as experimental and currently does not work.
		It even may be removed in some future version of the tool. So in other words: just forget it ;)

u <unit>	serial link transport unit number. Currently supported values: 0 -> COM1 (default), 1 -> COM2


Grab modes:
----------------

As listed in the features list, there are 3 methods/modes of screen dumping.
You just give the mode number (10, 11 or 20) as the last parameter:
	- Two ASCII modes: sending just a stream of ASCII characters (without color information)
		- Mode 10: sending all the characters, so the last line ends and a new empty one comes below,
		  recv. terminal size should be 80x26
		- Mode 11: sending all but the last character, so the last line's end is not reached,
		  recv. terminal size should be 80x25
	- Binary mode: inlc. color information
		- Mode 20: sending all the characters, sending raw bytes from gfx card: char, color, ...
		  no recv. terminal exists which could support this mode (maybe I'll make one in the future)

Some examples:
----------------

Running the program for the first time with logger turned on ('L'), timer trigger disabled ('c 0')
and screen dump mode 11 selected:

dispdump L c 0 11

Running the program whithout the keypress trigger ('k') so it doesn't "pause" to send the screen everytime you press
something, instead you see the screen every 2.2 seconds (=40/18.2):

dispdump k c 40


And REMEMBER:
----------------
First of all, there is a possibility that the program may hang the system. I recommend that you use the
debug logger (the 'L' parameter) for the first time you run the program, just to make sure that
every thing is working. You just should see some characters on a blue background on the screen when 
you trigger the keyboard and/or timer trigger.

And secondly, even if the program is working just great, currently ther is no possibility to turn off the program
unless you reboot your MS-DOS system. So do not run another instance of program if one is already running, because
you will have a mess sent over the serial cable, or even there is a possibility that the system will go bananas :)


Some HINTS:
----------------

1)
If you test the program and find the most usefull configuration and now you want to make it start every time
you run your MS-DOS (and e.g. you do not/will not have the monitor display anymore) and want to access this MS-DOS
machine only remotely, then I advise that you execute the program through AUTOEXEC.BAT.
For example you put the following line at the end of the AUTOEXEC.BAT file:

C:\My\Tools\DispDump.exe c 0

2)
The serial terminal emulation programs to connect to the Display Dumper can be for example Minicom under Linux
and HyperTerminal under Windows because it is a standard utility of every Windows system.
But HyperTerminal truncates at least one top line of screen, and I could not find the option to resize the
"screen" area (I have read that when you set terminal type to VT100(J), you can do something about the "screen"
area size but under Win XP this is not it). So instead of HyperTerminal under Windows you may use ComListener program,
which I have put into the binary package of DistDump (DistDump-<ver>-bin.zip). This program is a modified version
of an example for an open-source serial port library which you can find here: http://home.ict.nl/~ramklein/Projects/Serial.html
If you want to, I can send you the source code of my version of this program.


==================================
 6. Compilation/installation info
==================================

	The BINARY package is a complete tool package, you do not have to have anything other.
It contains three .exe programs, and each of them you can run independently just as it is, without any need any extra files.
They do not even need each other to work :) These programs are:

	DispDump.exe	- the Display Dumper utility itself
	DispDOld.exe	- the old/debug version of the utility, use it only if you experience some problems.
			  (Please note that the debug logger is on by default in this version!)
	ComListener.exe	- a serial link client program which I recommend to use instead of HyperTerminal (see 'Some HINTS' above).

	The SOURCE code is written for Borland C/C++ for DOS and follows its standards. It probably will not work on other compilers,
unless they are really accepting Borland's stuff (like interrupt keyword or BIOS serial port utility functions).


==================================
 7. Credits
==================================

	I would like to thank guys who made the tools I have used:
		- com0com by Vyacheslav Frolov and com2tcp by for testing DispDump,
and Ramon de Klein - Windows serial communication library and the ability to make the ComListener tool)
and God for the things I have in my head :)

==================================
 8. More info
==================================

	You can find more info on the project's official website: http://dispdump.sf.net and also by mailing me
directly: tomasz@lasko.pl or using SourceForge services like project's forums, bug tracker, feature request tracker etc.