Snapshot plugin for Take Command / TCC / TCC/LE
Version 1.2.0.3 2023-10-16
Charles Dye
Purpose:
This plugin provides a command to save a snapshot
of the current console screen buffer, reload the snapshot
file later on, and display basic information
about snapshot files. Snapshot files save all of the text and color
in the console buffer, plus the current cursor position, code page info,
the computer name, and a time stamp. You can save your console data with
SNAP and restore it later with
SNAP /R, even in a different console
session or after rebooting. You can even copy a snapshot file to a
different computer and resume your console session there.
Installation:
To use this plugin, copy Snapshot.dll to
some known location on your hard drive. (If you are still using the 32-bit
version of Take Command, take Snapshot-x86.dll
instead of snapshot.dll.) Load the plugin
with a PLUGIN /L command. For example:
plugin /l c:\bin\tcmd\test\snapshot.dll
If you copy the .dll file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.
Syntax Note:
The syntax definitions in the following text use these conventions for clarity:
BOLD CODE | indicates text which must be typed exactly as shown. |
CODE | indicates optional text, which may be typed as shown or omitted. |
| Bold italic | names a required argument; a value must be supplied. |
| Regular italic | names an optional argument. |
| ellipsis… | after an argument means that more than one may be given. |
New Command:
SNAP — Save, restore, or show
information about console snapshot files.
To save the console to a snapshot file:
SNAP /O /Q filename
/O | overwrite an existing file |
/Q | quietly |
If no filename is specified, or if it names
a directory, a name will be generated based on the date and time. Quote
the filename if it contains spaces or other
special characters. If the file already exists and you didn’t
specify /O, you’ll get an error message.
snap myscreen.snap
If the action succeeds, the filename will be stored in the
_LASTSNAP internal variable. If it
fails for any reason, _LASTSNAP will
be set to *ERROR*.
(The .snap extension is a suggestion only. You can give snapshot files any extension you like, or none at all.)
To restore the console from a snapshot file:
SNAP /R /Q filename
/Q | quietly |
The filename is required. Quote it if it contains spaces or other special characters.
snap /r myscreen.snap
The previous contents of the console screen buffer will be lost. The
console window will not be moved, but it may be resized to better accomodate
the screen buffer layout. Note that SNAP cannot resize Take
Command tabs. If you try to load a snapshot file into a Take Command tab
window and the console image is a different size than the tab window, then
SNAP will will exit with an error message.
• Note: SNAP /R replaces the
REVIEW command from earlier versions of this plugins. If you
want to use the old command, you can create an alias:
alias review=snap /r
To show information about snapshot files:
SNAP /I /N: /S filename…
/N: | disable features: |
D — do not search into hidden directories (only useful with /S) | |
E — do not display file-not-found errors | |
J — do not search into junctions (only useful with /S) | |
O — skip non-Snapshot files | |
S — do not show footers | |
Z — do not search into system directories (only useful with /S) | |
/S | search into subdirectories |
You may supply multiple filenames.
Wildcards ? and * are supported. If no
filename is given, the default is all
files in the current directory.
snap /i *.snap
Note: SNAP /I replaces the
SNAPINFO command from earlier versions of this plugins. If
you want to use the old command, you can create an alias:
alias snapinfo=snap /i
New Variable:
_LASTSNAP — Return the
filename of the last snapshot.
This variable is useful because the SNAP
command will automatically generate a filename if one was not specified.
The returned filename will be enclosed in double quotes (whether they are
needed or not.) If any error was detected when taking the last snapshot,
the string *ERROR* will be returned instead. If the
SNAP command has not been called yet,
_LASTSNAP returns an empty string.
Startup Message:
This plugin displays an informational line when it initializes. The
message will be suppressed in transient or pipe shells. You can disable it
for all shells by defining an environment variable named NOLOADMSG,
for example:
set /e /u noloadmsg=1
Snapshot File Format:
A snapshot file consists of a 40-word header, followed by a series of data words. Data words are either screen characters or special codes. Offsets and sizes are all given in words, not bytes.
| — Snapshot File Format — | |||
|---|---|---|---|
| Offset | Name | Size | Notes |
| 0 | Signature | 4 | 0x6E53 0x7061 0x6873 0x746f — magic signature used to identify snapshot files |
| 4 | Header version | 1 | always 1 in this version |
| 5 | Year | 1 | if 0, the entire time stamp is considered absent/invalid |
| 6 | Date | 1 | month in the high byte, day in the low byte |
| 7 | Time | 1 | hour in the high byte, minute in the low byte |
| 8 | Second | 1 | seconds in the low byte; day of the week in the high byte |
| 9 | UTC Bias | 2 | difference between local time and UTC, in minutes |
| 11 | Console columns | 1 | columns in the console screen buffer, e.g. 80 for an 80-column console |
| 12 | Console rows | 1 | rows in the console screen buffer, e.g. 1000 for a 1000-row console buffer |
| 13 | Cursor column | 1 | column location of the cursor within the screen buffer |
| 14 | Cursor row | 1 | row location of the cursor within the screen buffer |
| 15 | Color | 1 | default screen attributes; the “current color” is initially set from this value |
| 16 | Input code page | 2 | |
| 18 | Output code page | 2 | usually the same as the above |
| 20 | Window rows | 1 | height of the visible portion of the screen buffer, in character rows |
| 21 | — | 1 | unused; always 0 in this version |
| 22 | Checksum | 2 | CRC32 of raw console buffer data |
| 24 | Computer name | 16 | NetBIOS computer name (Unicode) |
| 40 | data | — | screen characters, and other codes as below |
| — Special Codes in File Data — | ||||
|---|---|---|---|---|
| Value | Name | Followed by | Size | Notes |
| 0xFFF9 | RepeatCode | count char | 3 | repeat character char count times; if count = 0, repeat 65536 times |
| 0xFFFA | RepeatSpaceCode | count | 2 | repeat space count times; if count = 0, repeat 65536 times |
| 0xFFFB | EscapeCode | char | 2 | treat char literally, not as a special code; used to protect any value ≥ 0xFFF0 |
| 0xFFFC | ColorCode | attr | 2 | use screen attribute attr for following characters |
| 0xFFFD | EndOfDataCode | — | 1 | no more data follows; fill to end of buffer with spaces in the default color |
Acknowledgments:
This plugin was inspired by the SAVECON and RSTRCON
commands in older versions of Vincent Fatica’s 4CONSOLE plugin. The idea is
the same as Vincent’s, but the implementation and file format are different.
A snapshot file is usually less than half the size of an equivalent SAVECON
file.
I compress the binary using UPX. The shutter sound effect is from WyomingWebdesign.com (dead link; try via the WayBack Machine). The CRC-32 code was lifted almost unchanged from Practical Algorithms for Programmers by Andrew Binstock and John Rex, Addison-Wesley, 1995.
Registry Silence:
By default, SNAP and SNAP /R
make a sound to signal successful operation. In both modes, you can use /Q to disable the sound.
If you prefer, you can also create a registry value to disable sounds:
| Registry key: | HKEY_CURRENT_USER\SOFTWARE\JPPlugins\Snapshot (checked first) |
HKEY_LOCAL_MACHINE\SOFTWARE\JPPlugins\Snapshot (checked if the value Quiet does not exist in the above) | |
| Value name: | Quiet |
| Value type: | REG_DWORD |
| Data: | any nonzero value will disable sounds |
Changes:
| 1.2.0.3 | 2023-10-16 | Tweaked ShowCmdHelp() to include VER_PATCH. |
| 1.2.0.2 | 2023-10-12 | Updated the plugin’s web address. |
| 1.2.0.1 | 2023-07-24 | Updated ParseArgs.cpp to the current version. |
| 1.2.0 | 2021-09-13 | Major rewrite to combine the old REVIEW and SNAPINFO
commands into SNAP, and to support high-order Unicode characters. Reduced
the plugin’s memory usage. Now SNAP /I supports /S
to search into subdirectories. Much cleanup of the code. Added the ability to disable sounds through the registry.
Changed the filenames; now Snapshot.dll is the 64-bit build. Tweaked the version
info structure. |
| 1.1.0 | 2014-10-29 | Changes for TCC v17 compatibility. |
| 1.0.2 | 2013-04-23 | Converted to Visual Studio 2010; updated the plugin’s web address. |
| 1.0.1 | 2011-02-22 | SNAP filename is now optional; added _LASTSNAP; fixed exit codes for internal commands. |
| 1.0.0 | 2011-01-07 | Initial release. |
Status and Licensing:
This plugin is © Copyright 2023, Charles Dye. Unaltered copies of the binary and documentation files may be freely distributed without restriction. I make no guarantee and give no warranty for its correct operation. If you find bugs, you can report them in the JP Software support forum.
Download:
You can download the current version of the plugin from http://charlesdye.net/dl/snapshot.zip.