  ***  TCAP console I/O capture utility  ***
  Version 3.2. Freeware. TCAP written by Tim D. Kannel
  Copyright(c) 1997-2002 Tim Kannel

  Distribution
  ------------
  This program is freeware. Distribute as much as you want, as long as none
  of the files have been modified and all of the required files are present.
  The required files are TCAP.COM and README.TXT (this file). The "PAD" (Portable
  Application Description) XML file is not required, but should be included.

  The addition of any files not included in the official TCAP distribution (as provided
  in the Simtel software archive) requires permission; such permission is granted if the
  files are clearly documented as additions included by the distributor, otherwise explicit
  permission must be obtained from TCAP's author.
  ------------

  Contents
  --------
  - Disclaimer
  - Supported operating systems
  - Description of TCAP
  - Using the TCAP environment variable
  - Long-filename support
  - Single-Program Console Capture
  - Making Programs TCAP-aware (TCAP API)
  - Known bugs
  - Change history
  - 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.

  Supported operating systems
  ---------------------------
  TCAP has been tested under MS-DOS 5.0, and under the console environments of Windows 95
  and Windows Millenium Edition. Although it has not been used under Windows 98, TCAP should
  work under that operating system as well. Unfortunately, however, TCAP will not function
  correctly under Windows NT or Windows 2000 (and probably Windows XP too).
  Note that certain display-related DOS drivers, such as ANSI.SYS, may interfere with TCAP;
  it is recommended that such drivers not be used if you wish to use TCAP. Other DOS
  utilities, such as DOSKEY, should not negatively affect TCAP.
 
  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 7 KB should be large enough to avoid an incomplete
  capture.
     Note that bell characters (ASCII code 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=7, maximum=64, default=8)
         /ON[-I|-O]    turn capturing ON
         /OFF[-I|-O]   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 batch files or other programs written to use 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 or uninstall TCAP several times; when capturing is OFF TCAP remains
  active in memory but does not capture any text. ON is the default setting.
  Unless specified otherwise, the /OFF and /ON switches automatically affect
  capturing of both user input and program output; if you which to change the
  capture state of only one of them then specify "-I" (for input) or "-O" (for output)
  after the normal switch, for example, "tcap /off-i" or "tcap /off-o".

  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, Windows 98, or
  Windows Millenium Edition (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. (Note: the input- and output-specific capture flags
  specified with the "-i" and "-o" components of the /off and /on switches
  are not changed automatically or saved.)
     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 captured text could not
  be saved to the capture file because of an error; in this case the command's
  return value is ignored.)

  Note about long command lines under Windows: Since TCAP is a DOS program there
  is a limit on the length of command lines that can be passed to the program
  specified as part of the single-program capture mode, even if that program
  is a Windows console program (which support much longer command lines).
  That limit is slightly less than 128 characters. However, there is a
  work-around, using the "cmdproxy" companion program included in the
  TCAP distribution. As an example, suppose you were running TCAP as follows:
	tcap /c prog.exe <really long args>
  where "<really long args>" is a series of command line arguments that
  exceeds the DOS command-line limit. To use the cmdproxy program, run TCAP
  as follows:
	tcap /c cmdproxy.exe prog.exe <really long args>

  cmdproxy.exe is a small Windows console program that obtains the
  complete command line and passes it to the target program. It may
  be used even if the command-line does not exceed the DOS limit, but it
  isn't necessary to do so. (Legal note: the TCAP disclaimer applies
  to tcap.com and any companion programs, such as cmdproxy.exe.)

  Making Programs TCAP-aware  (programming information)
  --------------------------
    Programmers who want to make their programs TCAP-aware can do so
  using the TCAP API. TCAP-aware programs can determine if TCAP is
  currently running, whether it is currently capturing console I/O, and
  can also disable or enable capturing. The API package, which includes
  documentation of the interrupt-level interface and example C source code
  for issuing the interrupts, is availabe upon request (if you're
  interested send an email to the address provided below).

  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
      some Windows console programs will do so.

  Changes since version 3.1
  -------------------------
    - addition of -i and -o components to /off and /on switches
    - addition of cmdproxy.exe companion program
    - minimum buffer size has been increased again
    - documentation changes
	- added section in this file about supported operating systems
	- PAD XML file added
    - The programming interface (API) documentation is no longer
      included in the normal TCAP distribution; it has been
      removed since that information is probably not of any interest
      to most people (if anyone). It is available upon request.

  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.
    - added API for TCAP-aware programs (see API.TXT)
    - minor changes and 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@attbi.com


  A request from me: it has come to my attention over the years that TCAP is
  being used in some school computer labs, probably to assist students
  in turning in results from computer-related assignments (which is something
  that I did myself back in my college days). I would appreciate a note
  from the instructor about such use, providing the name of the school,
  a short description of the computer environment and course, and any other
  information deemed relevant. This is not a request for payment for such use,
  nor would any such information be provided to anyone else. I'd simply like
  to know for what purposes TCAP is being used for, especially if it is something
  other than use on a home computer.

  Getting the Latest Version of TCAP
  ----------------------------------
    The primary distribution site for TCAP is the Simtel software archive:
	http://www.simtel.net/pub/pd/11141.shtml

    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
    - Dewey is a C++ programming 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.
      Availability: via 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 more advanced).
      Availability: via 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.)
      Availability: via email


End of readme.txt
