*** TCAP console I/O capture utility *** Version 3.1. Freeware. TCAP written by Tim D. Kannel Copyright(c) 1999 Tim Kannel Distribution ------------------- This program is freeware. Distribute as much as you want, as long as the required files are present and without modification. The required files are TCAP.COM and README.TXT (this file). The API package (API.ZIP and the files it contains) is not required in distributions of TCAP, but cannot be distributed independently of TCAP. If the API package is included, the only required file is API.TXT. ------------------- Contents -------- - Disclaimer - Description of TCAP - Using the TCAP environment variable - Long-filename support - Single-Program Console Capture - Making Programs TCAP-aware (TCAP API) - Known bugs - Changes since version 3.0 - Changes since version 2.0 - Changes since version 1.0 - Author Contact Information - Getting the latest version of TCAP - Other programs from the author Disclaimer ---------- The author of this program is not liable for any damage caused by use of this program. Due to the nature of this program (a TSR background utility) your system could potentially become unstable, so use with caution. Description ----------- TCAP is a text capturing utility. Console I/O is copied to a file. TCAP's purpose is somewhat like the "script" program available on Unix systems, with respect to its ability to log text from the console while it is running, but it has many additional features. It can remain resident in memory (i.e., as a TSR program) to capture text from several programs or commands, or capture text from a single program. Both program output and text input by the user are captured. Captured text input does not include editing characters, such as backspaces; only the final text is captured. TCAP captures text from all three standard file handles (stdin, stdout, and stderr). Although TCAP was designed to capture text from DOS programs, it can also capture output from Windows console programs (and user input under certain circumstances). The text capture is to a file specified by the user on the command-line, and starts as soon as TCAP exits to DOS. The capture ends when TCAP is removed from memory with the "/U" uninstall command-line switch. The text capture can also be turned on or off at other times as described below. File output to the capture file is buffered; several methods are used to make sure that the buffer can be written to disk as often as necessary. The size of TCAP's internal buffer can be specified on the command-line. In the event that the buffer was not large enough to capture everything a warning message will be displayed when TCAP is uninstalled, and TCAP will exit to DOS with a nonzero return value ("errorlevel"). If this happens then increase the buffer size. The default buffer size is 8 KB, but the minimum size of 6 KB should be large enough to avoid an incomplete capture. Note that bell characters (ASCII 7) are converted to spaces, so no beep will be emitted and the bell character will not appear in the capture file. Usage information: TCAP [options] [filename] [/C command [parameters]] /? display a help screen /B=size specify Buffer size in kilobytes (minimum=6, maximum=64, default=8) /ON turn capturing ON /OFF turn capturing OFF /OVERWRITE destroy initial contents of capture file /APPEND Append text to capture file (default) /N No filename swap (with /C option only) /P+ or /P- enable or disable Path searching (with /C option only) /I make entire command-line case-Insensitive /L+ or /L- enable or disable use of Long filenames /Lx prevent filename shortening when long names are unavailable /Q quiet mode /U stop text capture and Uninstall TCAP filename specify the name of the capture file (defaults to TCAP.TXT) /C run and capture text from 'command', using the indicated parameters A slash (/) or dash (-) can be used to indicate an option. The options are always case-insensitive (e.g., "/ON", "/on", and "-On" are all equivalent). By default, the name of the capture file and anything after the /C switch (if present) is case-sensitive. To force everything to be case-insensitive (with everything uppercased) use the /I option. (The /I option is primarily for compatibility with previous versions of TCAP.) Long-filename support is discussed in a separate section below. The /C, /N, and /P options are also explained in a separate section below. The /ON and /OFF options control capturing without having to install/uninstall TCAP several times; when capturing is OFF TCAP remains active in memory but does not capture any text. ON is the default setting. The buffer size is fixed once TCAP is installed. The other options may be used at any time (though they may be ignored if TCAP is already resident). A different capture file can be specified when running a command (i.e., when using the /C option); specifying a filename at some other time when TCAP is already installed will not generate an error, it will simply be ignored. /OVERWRITE vs. /APPEND: Normally TCAP does not modify the existing contents of the capture file; the /OVERWRITE option causes TCAP to overwrite the initial contents. This only affects the first time the file is opened while TCAP is initializing; during capturing the file is always appended. These options will be ignored if TCAP is already installed. The /OVERWRITE and /APPEND options may be abbreviated as /OVR and /APP respectively. These shortcuts may be removed in future versions, so it is recommended that the long forms be used. The "quiet" mode (the /q option) prevents TCAP from displaying the informational messages during installation or un-installation. Error messages are unaffected by this option. If necessary, TCAP will clear all attributes of the capture file, including the read-only attribute. Setting the file to read-only does not prevent capturing. Also note that TCAP is smart enough not to use an executable as a capture file - if the name of the capture file has a ".com",".exe", or ".bat" extension TCAP will terminate with an error message. Using the TCAP environment variable ----------------------------------- As of version 3.1, TCAP supports the use of a TCAP environment variable (as specified with the DOS "SET" command) for specifying default command-line options. The syntax of the value of this variable is similar to the command-line syntax. Options specified with this environment variable are processed before the regular command-line, so the command-line options have precedence. Not all options are supported in the environment variable; those which aren't supported will simply be ignored. The following options may be used with the TCAP environment variable: /B, /ON, /OFF, /OVERWRITE (and /OVR), /APPEND (and /APP), /N, /P, /L, and /I. Specifing the /I option in the environment variable has no effect. If you want the actual command-line to be case-insensitive then you must specify the /I option on the command-line, not in the TCAP environment variable. Normally, non-option parameters in the environment string are ignored. However, if you wish to change the name of the default capture file you can do so in the environment string by preceding the name with an asterisk (*). For example, if you want the default capture file name to be "capture.txt" then set the environment string as follows: set tcap=*capture.txt A different filename can then optionally be specified on the command-line to override this default setting. Long-filename support (/L option) --------------------- TCAP supports long filenames when run under Windows 95/98 (but not under ordinary DOS). This applies to both the name of the capture file and the name of executables used with the /c option. The /L option enables or disables long-filename support, using one of three modifiers (plus, minus, or the x character): /L+ enables use of the long-filename feature (the default) /L- disables use of the long-filename feature /Lx forces use of long filenames /L+ and /L- determine if TCAP will attempt to detect whether the operating system provides support for long filenames. If /L- is specified then this detection does not take place and no attempt is made to use long filenames. If /L+ is specified then long filenames can be used if TCAP detects that the operating system supports it. (If the detection fails, like if TCAP is run under ordinary DOS, then the usual 8.3-style filenames are used instead). If /Lx is specified and /L- is not specified then TCAP will terminate with an error message if long-filename support is not available. This option is intended to be used when a long name is given for the capture file and truncation of that name is undesirable. For example, if the name of the capture file is "alongname.txt" but long filenames are not available, the /Lx option will prevent the filename from being shortened to "alongnam.txt". The /Lx switch has no effect when /L- is specified. It is assumed that when long-filename support is explicitly disabled with /L- that a long name will not be specified. If you want to use a filename that contains spaces then enclose the name in double quotes. (TCAP will always parse a quoted filename as such even when long filename support is disabled as discussed above; this means that a quoted filename will not generate syntax errors, regardless of whether long filename support is enabled.) The /L option only affects the name of the capture file, it does not affect the names of executables used with the /c option. Single-Program Console Capture (/C, /N, and /P command-line options) ------------------------------ TCAP can capture text from the console during the execution of a single program. The program to capture text from is specified after the /C command-line option, with any parameters for the program specified afterwards. (Any TCAP options must before the /C option.) The command name must include the extension. TCAP does not have to installed before using this option. If TCAP is not installed beforehand it will not be installed afterwards (i.e., the installation is temporary). If TCAP is already installed it saves some of its internal state and restores it when the command completes execution. This includes whether capturing was enabled or disabled; the command will be executed with capturing enabled, unless the /OFF switch is used. TCAP switches the active capture file while running the command. For example, if TCAP was installed with a capture file of TCAP1.TXT and TCAP is later run with "TCAP /C PROG.EXE" the console I/O produced by PROG.EXE will be captured to the default file (TCAP.TXT), not TCAP1.TXT. A new capture file may be specified for PROG.EXE; it doesn't have to be the default. When PROG.EXE terminates the original capture file is restored (e.g. TCAP1.TXT). If you want TCAP to continue writing to the original capture file then use the /N command-line option. (Note that if the default name is used in both cases the filename switch has no effect anyway). The /N option takes effect whether a new name is specified or not; i.e., if both the /N option is used and a new filename is specified, the /N option has precedence. By default, TCAP will search for the executable in the current directory and in the PATH (if necessary). If you do not want TCAP to perform this search then use the /P- option, in which case the executable must either be in the current directory or the full path must be given. TCAP will also detect batch files and run a secondary copy of COMMAND.COM to execute the batch file. Note that this relies on the path-searching feature (TCAP does not use the COMSPEC environment variable), so COMMAND.COM must be in the PATH and path-searching must be enabled. If you disable path-searching with the /P- option then use something like the following to run a batch file: tcap /c c:\command.com /c prog.bat Regardless of whether TCAP is installed previously or not, TCAP will terminate with the return value ("errorlevel") of the executed program. (Exception: TCAP may return a nonzero value if buffer overflow occurred, in this case the command's return value is ignored.) Making Programs TCAP-aware (programming information) -------------------------- Programmers who want to make their programs TCAP-aware can do so using the new TCAP API. TCAP-aware programs can determine if TCAP is currently running, whether it is currently capturing console I/O, and also disable or enable capturing. See API.TXT for more information. Known bugs ---------- - text input: backspaces and characters that were edited out may appear in the capture file, although this is not likely. This problem only occurs if a program does character-by-character input (using DOS services). This was more of a problem with previous versions, not version 3.0+ (version 3.0+ captures input on a line-by-line basis whenever possible). DOS programs typically do not get input character-by-character; however, I have noticed that Windows console programs will do so. Changes since version 3.0 ------------------------- - added /overwrite and /append options - command-line options can use the '-' (dash) character (or the slash as before) - the command-line is case-sensitive by default (meaning that TCAP won't uppercase everything unless the /i option is used). Options are still case-insensitive (the case-sensitive parts are the name of the capture and anything following the /c option). - an error is generated if the command-line contains the name of more than one capture file (instead of just using the last-specified name) - auto-run of batch files (specifying command.com is no longer required) - added PATH-search for executables - added support for specifying default options with the TCAP environment variable - quiet mode (/q option) - minimum buffer size has been increased again Changes since version 2.0 ------------------------- - default file name is now TCAP.TXT (used to be OUTPUT.TXT) - added ability to execute another program directly and capture text while it is running (/C command-line option) - added /ON and /OFF switches to control when capturing is performed - bug fix: TCAP can now handle backspaces and other cursor movement when text is being input (the captured text looks like the final input, not everything that appeared while editing) - bug fix: TCAP is much less likely to hang the computer during a buffer flush. - minimum buffer size has been changed from 2K to 4K. (This is to prevent TCAP from corrupting its own code and data.) - added API for TCAP-aware programs (see API.TXT) - minor changes / bug fixes Changes since version 1.0 (version 1.0 was never released) ------------------------- - capture method has changed (now works in Win95 DOS-box) - size of internal buffer can now be specified on the command-line - more than one command-line parameter is parsed (if more than one is present), version 1.0 ignored any parameters after the first one - several changes were made to make the program more stable Contact Information ------------------- Please send bug reports, comments, or suggestions to the email address listed below. Feedback is greatly appreciated. If submitting a bug report please include any pertinent information, including the name of the operating system, the operating system version, and the names of any other memory-resident utilities. Program author: Tim Kannel email: tdkannel@bitstream.net Getting the Latest Version of TCAP ---------------------------------- The primary site for TCAP is the Simtel software archive: ftp://ftp.simtel.net/pub/simtelnet/msdos/sysutl/tcapxx.zip ('xx' is the version number, e.g. '31' for version 3.1) TCAP may also be available on other software sites, but those sites may not have the most recent version. Other Programs/Libraries From The Author ---------------------------------------- DOS-based programs - FTPDIF - finds differences in FTP directory listings. A new index file is written that includes information on what changed. Includes other features such as user-comments and a log file (the log lists only the changes, not the entire index). This program is available on Simtel as FTPDIFxx.ZIP in the msdos/00_info directory, where 'xx' is the version number. The URL for version 2.1 is ftp://ftp.simtel.net/pub/simtelnet/msdos/00_info/ftpdif21.zip This program may eventually be removed from Simtel (since I no longer consider this program to be worth much), but it will always be available via email. I may also make the C++ source code available to anyone that requests it. - Dewey is a C++ library for a text-mode user interface. It includes windows, menus, and an event-driven architecture. Standard components include checkboxes, radio buttons, push-buttons, text windows, etc. Dewey is an improved version of Al Steven's DFlat++ library. The source code is in the public domain. Dewey is not directly available; it can be obtained through email. Windows-based programs - PowerSnag - a Windows program that can download portions of a web site for off-line viewing (similar to PC Magazine's SiteSnagger but considerably more advanced). PowerSnag is not directly available; it can be obtained through email. - I've also written a simple web server. It supports HTTP 1.0 (GET and POST methods), including execution of CGI programs. (This web server was used locally during some of the testing for PowerSnag.) The executable for this server is available through email. End of READ.ME