CmdTimer plugin for Take Command / TCC/LE

beta version 0.92.2     2019-11-18

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 using the 64-bit version of Take Command, take CmdTimer-x64.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 command: CMDTIMER

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 CODEindicates text which must be typed exactly as shown.
CODEindicates optional text, which may be typed as shown or omitted.
Bold italicnames a required argument; a value must be supplied.
Regular italicnames 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-command

/B:show the timer: Default, Statusbar, Text, or Off
/C:set the timer text colors
/Drestore plugin defaults
/Kreset the command counter to 0
/Rrestore plugin settings from the registry
/Ssave current settings to the registry
/T:time in seconds for a command to be ‘slow’; 0 disables
/Zreset the total time to zero
slow-commandcommand 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-command 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-command if it contains percent signs, redirections, or any other troublesome characters. Slow-command must be the last item on the command line. Any options which follow are presumed to be for slow-command, not for CMDTIMER.

Specify - (a single hyphen) to remove any existing slow-command.


By default, CmdTimer displays the elapsed time when a command finishes. /B: controls this behavior. The supported values are:

/B:Dthe default behavior: use Take Command’s status bar if available, text otherwise
/B:Suse the status bar only
/B:Tuse text only
/B:Ooff; 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-command 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-command 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

Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

CmdTimer is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

Download:

You can download the current version of the plugin from http://prospero.unm.edu/dl/cmdtimer.zip or ftp://prospero.unm.edu/cmdtimer.zip.