TOCLIP.DOC documentation for ToClip Version 1.0: 9-Sept-1998 A DOS program to manipulate the Windows 3.1, 3.11, 95, 98 clipboard from a DOS box. Copyright (c) 1998 by Grant B. Gustafson. ALL RIGHTS RESERVED Free for personal use under the Gnu Public License agreement, which is distributed with this source. PURPOSE: Append a file or pipe onto the windows clipboard. Copy a file or pipe to the windows clipboard. Erase the clipboard. Print the clipboard to a file or printer. Append the clipboard to a file. USAGE: toclip infile - Append infile to the clipboard toclip -c infile - Copy infile to the clipboard program | toclip - Append program output to the clipboard program | toclip -c - Copy program output to the clipboard toclip -e - Erase the clipboard toclip -p - Print the clipboard to stdout toclip -p >prn - Print the clipboard to printer prn: toclip -p >outfile - Print the clipboard to outfile toclip -p >>outfile - Append the clipboard to outfile toclip -p | program - Pipe the clipboard binary to program toclip -p outfile - Copy the clipboard binary to outfile Change -p to -u to translate CRLF->LF (unix outfile) Limitation: 60416 bytes of OEM text MS-DOS switches /c, /e, /h, /p, /u make sense instead of the unix style switches -c, -e, -h, -p, -u. Help is invoked for mistakes and also for major errors, like a missing file name. If no file name is given, then stdin is assumed. If this happens by mistake, then hit ctrl-C to abort the program. ============================= INITIAL TEST ============================ An initial test (in a Windows DOS box) for toclip.exe is the following. C:\>toclip this is a test! <== Enter this text ^Z <== and press ctrl-Z C:\>toclip -p this is a test! C:\>toclip this is another test! <== Enter text again ^Z <== and press ctrl-Z C:\>toclip -p this is a test! this is another test! C:\> =========================== FURTHER EXAMPLES ========================== toclip toclip.doc - Append toclip.doc to clipboard (binary append) toclip -c toclip.doc - Copy toclip.doc to clipboard (binary copy) dir | toclip - Append output of "dir" command to clipboard mem | toclip -c - Copy output of "mem" command to clipboard toclip -e - Erase clipboard toclip -p - Print clipboard to stdout (console) toclip -p >tmp.1 - Copy clipboard to file tmp.1 toclip -p >prn - Copy clipboard to the default printer toclip -p >>tmp.2 - Append clipboard to tmp.2 toclip -h - Print helpfile on console toclip -p |grep X - Print clipboard lines containing X toclip -u out.unx - Print clipboard to unix format file out.unx The "dir" command, like most DOS commands, outputs lines terminated by a linefeed character. It is the job of TOCLIP to translate each linefeed into a carriage return plus linefeed pair (CRLF pair). This translation is necessary to convert the text to OEM text for the clipboard. ==================== LINE TERMINATOR TRANSLATIONS ===================== The issue that affects clipboard contents the most is line termination translation, especially the automatic translation done by DOS. Translation of carriage return and linefeed pairs occurs silently in DOS for both input and output. Explained below are the translations made by TOCLIP and DOS. The CRLF (carriage return plus linefeed pair) translations of TOCLIP are as follows: INPUT If the input file to the program TOCLIP is stdin (console), then TOCLIP translates the input to OEM text. This means precisely that each linefeed character is examined to see if it is already part of a CRLF pair. If so, then no translation occurs. Otherwise, the linefeed is an orphan and it is translated to carriage return plus linefeed (CRLF or ascii 13 followed by ascii 10). The input translations are reported when the program exits. No translation occurs if the input file to TOCLIP is a disk file. In particular, "toclip -c filename" copies filename into the clipboard, untranslated. OUTPUT The option -p of TOCLIP writes to the console in binary mode. No translations are done. The option -u of TOCLIP performs a translation. More precisely, each carriage return character (ascii 13) is examined to see if it is part of a CRLF pair. If it is part of a pair, then the carriage return character is stripped from the output. The result is that the output file contains only linefeed characters, unless of course an orphan CR character was in the file (it would be unchanged in the output). The CRLF translations of DOS are as follows: DIR Prints only linefeeds. No CR characters are printed. MEM Prints only linefeeds. No CR characters are printed. VER Prints only linefeeds. No CR characters are printed. > Converts linefeed to CRLF. >> Converts linefeed to CRLF. | No translations. Typically, DOS commands that print output to the console will contain no CR characters, just linefeeds are present. Pipes to TOCLIP.EXE may have surprises because of translations done without your knowledge (by the program itself). Use the status report of TOCLIP.EXE to decide which program is translating what. Beware of testing the results of TOCLIP.EXE translations in a text editor, because most text editors also translate (eg, NOTEPAD in windows). The program TDUMP from Borland, which prints file contents in HEX format, is useful for deciding which program is doing the translation. ======================================================================= NO COST? This software is provided free of charge to individuals and educational institutions. Money is not requested. Free for personal use under the Gnu Public License agreement, which is distributed with this source. ======================================================================= POSTCARDS? Postcards and comments are welcome! GB Gustafson 113 JWB Math Dept Univ Utah Salt Lake City, UT 84112 USA Email: gustafso@math.utah.edu WWW: http://www.math.utah.edu/~gustafso/ Cited product names are trade names. ========================== GNU PUBLIC LICENSE ========================== This software is released as copyrighted material under the GNU PUBLIC LICENSE: NO WARRANTY Because ToClip is licensed free of charge, absolutely no warranty is provided, to the extent permitted by applicable state law. Except when otherwise stated in writing, Grant B. Gustafson provides ToClip "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the ToClip program prove defective, you assume the cost of all necessary servicing, repair or correction. In no event unless required by applicable law will Grant B. Gustafson and/or any other party who may modify and redistribute ToClip be liable to you for damages, including any lost profits, lost monies, or other special, incidental or consequential damages arising out of the use or inability to use (including but not limited to loss of data or data being rendered inaccurate or losses sustained by third parties or a failure of the program to operate with programs not distributed by Grant B. Gustafson) the program, even if you have been advised of the possibility of such damages, or for any claim by any other party. ============================ HARDWARE NEEDED =========================== HARDWARE 8088, 80286, 80386, 80486, 80586, Pentium CPU. ============================ SOFTWARE NEEDED =========================== SOFTWARE MS-DOS compatible operating system under Win3.1, Win3.11, Win95, Win98. Tested with WIN3.1, WIN95. =============================== PACKAGE ================================ The package consists of: toclip.c : C source for the program toclip.exe toclip.exe : The executable, compiled with TC 2.0. toclip.doc : You are reading it. Only toclip.exe is required to run the program. It should be copied to the PATH of the operating system being used (win3, win95, win98). The program does nothing under ordinary DOS, since its purpose is to manipulate the Windows clipboard. Attempts to run the program in a DOS environment without Windows will result in error messages and a help file display, but no action will take place. =============================== NO WARRANTY ============================ The author does not warrant the correctness of the documentation or the function of the program. The author does not warrant uninterrupted or error free operation of the Program. The user is advised to test the program fully. The risk of using this software is exclusively with the user. The author assumes no liability whatever for damages of any kind that might result from using the program. ========== End of File toclip.doc. Last edited 9-Sept-1998. ===========