  ***  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
