|
Ed Beroset
Last modified: Fri Jan 16 22:24:03 2004 |
|
The toclip.asm program is a small command line utility program which allows one to redirect the output of a command line program to the Windows clipboard. It was originally written for Windows 95, but it is has been tested under Window 3.1, OS/2, and Windows 98. It does not work under Windows NT. I haven't tried newer versions of Windows, but toclip should work under Windows ME.
I've used this program often in the last several years. The primary purpose has been to allow me to capture the output of a program to the clipboard so that I can paste the result into an email message or usenet news article.
For example, let's say I wanted to email the source code of this program to someone. I could attach it as a file, or I could put the source code right into the message. If I wanted to do the latter, I could do it like this:
type toclip.asm | toclip
or even more simply:
toclip < toclip.asm
You could copy a directory listing into the clipboard like this:
dir *.asm | toclip
In fact, any program that prints to the STDOUT device (i.e. it prints to the screen in a way that allows redirection) can be used with toclip. There are limitations, however. Only 64K of text is copied into the clipboard, so if there is more than that, it will be silently truncated.
The flow of the program is quite simple. Each of the following sections describes one aspect of the program. The list follows in the same order as the program listing, so it may be useful to follow the source code as you're reading this description.
First, toclip resizes itself in memory. It does so by calculating the size of its data plus code plus stack and then issuing a DOS_RESIZE_MEM (int 21h, function 4ah) request. This step is only necessary because not all linkers are smart enough to allow requests of just the right amount of memory. Specifically, Borland's tlink.exe, at least as of version 6.10 that I am using, doesn't have a means by which the maximum and minimum sizes can be specified. By contrast, Microsoft's link.exe (in this case I am using version 5.60.339) has command line switch /CPARM which allows setting this allocation parameter.
If link.exe is used with /CPARM (or some equivalent method is used), the resizing code could be removed.
At least as far back as Windows 3.1, there has been support for some functions labelled "WinOldApp". These WinOldApp functions allow console programs using the old DOS style calls some access to Windows functions. One series of these functions are the clipboard functions. You can find a fairly complete description of these functions in Ralf Brown's famous interrupt list. Specifically you might be interested in reading about Int 2F/AX=1700 and the actual clipboard paste operation which is Int 2F/AX=1703. I won't describe these operations here, since they're pretty well described in those documents. As an aside, anybody who's writing assembly language programs for DOS or on PC machines in general is strongly encouraged to download and use Ralf's interrupt list.
The program first checks to see if the WinOldApp functions are available and exits with an error message if they are not. It next opens the clipboard and then clears the clipboard to dump whatever might already be in there. If you omit this step, the program will still work, but if the clipboard already were to contain text that might be rendered as either text or OEM text, the two won't always have the same data. This can lead to strange results when pasting from the clipboard into other applications. Try it for yourself and experiment.
toclip.asm next attempts to allocate a 64k memory buffer. If the allocation fails, the program ends with an error message. The buffer is used to hold the data read from STDIN. I have used 64k pretty arbitrarily. It was convenient because it's a nice round number and it's also the largest size one can use with the DOS Read from Handle function which is used to read in the data immediately after the buffer area is allocated. After that, the data is pasted into the clipboard using Int 2F/AX=1703.
Note that the program never explicitly frees the allocated memory. This is permitted without causing memory leaks because DOS automatically frees all allocated memory when the program terminates.
|
Ed Beroset
Last modified: Fri Jan 16 22:24:03 2004 |
|