CmdTimer plugin for Take Command / TCC / TCC/LE
Version 1.0.2.3 2023-11-16
Charles Dye
Purpose:
This plugin implements an automatic command timer, which starts every time you press Enter at the command line. If TCC is running in a Take Command tab, the duration of each command is displayed in the status bar when the command completes.
CmdTimer can also run a command automatically after a command executes, if it took longer than a specified time to finish. You could, for example, beep the computer’s speaker after any command which takes ten seconds or more.
Installation:
To use this plugin, copy CmdTimer.dll to
some known location on your hard drive. (If you are still using the 32-bit
version of Take Command, take CmdTimer-x86.dll
instead of CmdTimer.dll.) Load the plugin
with a PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\cmdtimer.dll
If you copy this file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.
Plugin Features:
New variables: _CMDCOUNT,
_CMDTICKS, _CMDTIME,
_CMDTOTALTICKS, _CMDTOTALTIME,
_LASTCMD, _TICKS
New functions: @TICKSTOTIME,
@TICKSTOTIMED
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:
CMDTIMER — Display or change
CmdTimer plugin settings.
Syntax:
CMDTIMER /B:n /C:n /D /K /R /S /T:n /Z slow-cmd
/B: | show the timer: Default, Statusbar, Text, Both, or Off |
/C: | set the timer text colors |
/D | restore plugin defaults |
/K | reset the command counter to zero |
/R | restore plugin settings from the registry |
/S | save current settings to the registry |
/T: | time in seconds for a command to be ‘slow’; 0 disables |
/Z | reset the total time to zero |
| slow-cmd | command to execute if the last command was slow |
A ‘command’ is any line you type at the prompt. It might be a single command, or it might be multiple commands, a batch file, or whatever. The timer starts automatically when you press Enter, and stops when the prompt is displayed again. If you run a command without pressing Enter, e.g. by a keystroke alias, it will not be timed or counted.
(Want to execute a command without starting the timer? Press Ctrl-Enter.)
If a command takes a long time to execute, slow-cmd
will be run automatically after it finishes. Use /T:n
to set the minimum duration for a slow command; the default is 10 seconds.
/T:0 disables this feature. Use backquotes around
slow-cmd if it contains percent signs, redirections,
or any other troublesome characters. slow-cmd
must be the last item on the command line. Any options which follow
are presumed to be for slow-cmd, not for
CMDTIMER.
Specify - (a single hyphen) to remove any existing
slow-cmd.
By default, CmdTimer displays the elapsed time when a command finishes.
/B: controls this behavior. The supported values are:
/B:D | the default behavior: use Take Command’s status bar if available, text otherwise |
/B:S | use the status bar only |
/B:T | use text only |
/B:B | both text and status bar |
/B:O | off; do not display the timer |
Only the first letter is significant; /B:D is the same as
/B:DEFAULT. The ‘text’ mode displays the timer in the
upper right corner of the console window. It does not write to standard
output.
/D restores the plugin’s default settings: status bar or
text, bright white on blue text, 10 seconds for a slow command, no
slow-cmd defined.
/S saves the current plugin settings to the registry; they will
be used by default the next time the plugin is loaded.
/R restores all plugin settings from the registry. If you
have not yet saved any settings with CMDTIMER /S, this option
won’t do anything.
You can customize the format of the status bar timer with an environment
variable named CMDTIMERFMT. Use strong quotes around the value to
prevent variables from being expanded prematurely. The expanded value should
fit on a single line of text — fewer than 80 characters. The
default is equivalent to SET CMDTIMERFMT=` [%_CMDCOUNT] %_CMDTIME `
rem Don't display the timer:
cmdtimer /b:off
rem Beep after any command which takes five seconds or longer:
cmdtimer /t:5 beep 880 10
rem Test with a slow command:
delay 5
rem Pop up a message box instead:
cmdtimer `msgbox /o OK "Slow Command" %@upper[%_lastcmd] took %_cmdtime`
delay 5
rem Text timer, bright yellow on green:
cmdtimer /b:text /c:"bright yellow on green"
rem The same as above, only terser:
cmdtimer /b:t /c:0x2e
rem Restore the plugin's default settings:
cmdtimer /d
rem Customize the status bar format:
set cmdtimerfmt=` %_lastcmd - %_cmdtime `
rem Return to the default format:
unset cmdtimerfmt
New Variables:
_CMDCOUNT — Returns the
number of times the command timer has been started.
This counter starts at 0 when the plugin is loaded, and is incremented every
time you enter a new command line. You can reset it with
CMDTIMER /K. This feature might
be useful for computing average durations.
_CMDTICKS — Returns the
duration of the last command, in 100 ns ticks.
The command timer continues to run until the prompt is displayed again. If you use this variable in a command, it may return a value less than what is later displayed in the status bar. While Windows reports in 100-nanosecond units, the actual resolution varies between systems and is typically much less.
_CMDTIME — Returns the
duration of the last command as H:MM:SS.mmm.
The command timer continues to run until the prompt is displayed again. If you use this variable in a command, it may return a value less than what is later displayed in the status bar.
_CMDTOTALTICKS — Returns the
total of command durations, in 100 ns ticks.
While Windows reports in 100-nanosecond units, the actual resolution varies
between systems and is typically much less. You can reset this total with
CMDTIMER /Z.
_CMDTOTALTIME — Returns the
total of command durations as H:MM:SS.mmm.
While Windows reports in 100-nanosecond units, the actual resolution varies
between systems and is typically much less. You can reset this total with
CMDTIMER /Z.
_LASTCMD — Returns the first
word from the last command line entered.
This might be useful in slow-cmd to identify the offending command. Note that “the first word” is a fairly naïve notion of what constitutes a command.
_TICKS — Returns the system
time, in 100 ns ticks.
_TICKS exposes the Win32
GetSystemTimeAsFileTime()
function, which this plugin uses to time commands. The value returned is documented
as the number of 100-nanosecond intervals since January 1, 1601 at 0:00:00 UTC. It
is, therefore, big.
New Functions:
@TICKSTOTIME — Converts
a count of 100 ns ticks to H:MM:SS.mmm format.
Syntax:
%@TICKSTOTIME[ticks]
@TICKSTOTIME exposes an internal function used by _CMDTIME
and _CMDTOTALTIME. Ticks
can be very large; it’s an unsigned 64-bit integer. The ‘hours’ value in
the returned string can therefore also be quite big.
@TICKSTOTIMED — Converts
a count of 100 ns ticks to DDD H:MM:SS.mmm format.
Syntax:
%@TICKSTOTIMED[ticks]
This function works like @TICKSTOTIME,
except that it further breaks the returned value out into days and hours.
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
Changes:
| Version: | Date: | Changes: |
|---|---|---|
| 1.0.2.3 | 2023-11-16 | Do not show the “Plugin not loaded” message in a transient or pipe shell. When it is shown, include the plugin’s name. |
| 1.0.2.2 | 2023-10-16 | Tweaked ShowCmdHelp() to include
VER_PATCH. |
| 1.0.2.1 | 2023-10-12 | Updated the plugin’s web address. |
| 1.0.2 | 2021-12-22 | No longer link to TakeCommandIPC() dynamically. That hasn’t been necessary for a long long time. |
| 1.0.1 | 2021-12-21 | Fix for an issue calling TakeCommandIPC() on 32-bit TCC. |
| 1.0.0 | 2021-07-08 | First release. |
Status and Licensing:
This plugin is © Copyright 2024, 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 operation. If you find a problem, you can report it in the JP Software support forum.
Download:
You can download the current version of the plugin from https://charlesdye.net/dl/cmdtimer.zip.