APing plugin for Take Command / TCC / TCC/LE
Version 1.0.3.1 2024-04-03
Charles Dye
Purpose:
This plugin adds a new command, APING.
Its options and syntax are generally similar to the Windows
ping.exe utility, though some of the more obscure
features are not implemented. There are also a handful of
variables to return values from the last ping, and
a few utility functions, as well as a command to
define and list APING macros. Windows XP or later is
required. For IPv6 support, Windows Vista or later is strongly recommended.
Installation:
To use this plugin, copy the files APing.dll
and APing.chm to some known location on your hard
drive. (If you are still using the 32-bit version of Take Command, take
APing-x86.dll instead of
APing.dll.) Load it with a PLUGIN /L
command, for example:
plugin /l c:\bin\tcmd\test\aping.dll
If you copy this file to a subdirectory named PlugIns within your Take Command program directory, it will be loaded automatically when TCC starts.
Plugin Features:
| New commands: | ||||
APING |
APINGHELP |
APINGMACRO |
||
| New functions: | ||||
@APINGMACRO |
@LOOKUPHOST |
@PINGDHCP |
@PINGDNS |
@PINGROUTER |
@PINGTIME |
@PINGWINS |
|||
| New variables: | ||||
_PINGAVG |
_PINGMAX |
_PINGMIN |
_PINGSLOST |
_PINGSRCVD |
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 Commands:
APING — Audibly ping a network host.
Syntax:
APING /4 /6 /A /C /D /E:n /F /G:n /I:ttl /L:size /N:n /O:n /Q /T /W:timeout /X:n /Y:volume hostname…
/4 | use IPv4 | |
/6 | use IPv6 | |
/A | resolve numeric addresses | |
/C | display line numbers | |
/D | disable highlight | |
/E:n | specify error drum | |
/F | set the Don’t Fragment flag | |
/G:n | specify instrument number | |
/I:ttl | specify the Time-To-Live value | |
/L:size | specify the packet size in bytes | (64) |
/N:n | number of ping requests to send | (4) |
/O:n | specify instrument octave | |
/Q | quietly | |
/T | continue until Control-C is pressed | |
/W:timeout | set the timeout value in milliseconds | (3000) |
/X:n | specify op error drum | |
/Y:volume | set the master sound volume; volume is 0 to 100 | |
| hostname… | computer name or IP address |
Options may begin with either a forward slash or a dash. The hostname is required. You can specify more than one hostname; hosts will be pinged in the order given.
Hostname may be #ROUTER,
#DNS, #DHCP, or #WINS (case is not
significant). #ROUTER is the IPv4 address of the router;
#DNS is the IPv4 address of the first DNS server;
#DHCP is the IPv4 address of the first DHCP server;
#WINS is the IPv4 address of the first WINS server. Any of the
above may optionally be followed by a digit 1 to 9,
e.g. #DNS2 for the second known DNS server. (These
macros do not support IPv6.) You can also define your
own macros.
/T pings the host until you press Control-C.
(/N:0 does the same.) If you press Control-Break, you’ll get
a brief report on the number of pings sent and received so far, and the program
will continue pinging.
If you specify both /4 and /6, the one given
first will be tried first, and then the other one if the first fails. If you
don’t specify either, the default is /4 /6 —
try IPv4 first, then IPv6.
For compatibility with ping.exe, options which take arguments
may be split into two options, e.g. /N 10 instead of
/N:10. I dislike this syntax, but it’s there if you want
it.
/G:n specifies
the instrument to play when a packet is returned from the remote computer.
n is a
General MIDI instrument number,
1 to 128. The default is 115, steel drums.
/O:n sets the
octave for successful-ping notes. The range is 0 to 9; not all instruments
will necessarily support the entire range. The default is 5.
/E:n specifies
the percussion instrument to play when a packet is lost.
n is a
General MIDI percussion key,
35 to 81; or 0 to prevent APing from making any sound when a packet
is lost. The default is 66, the low timbale.
/X:n specifies the percussion
instrument to play for operational errors which prevent APing from even
trying to ping the host. Mostly these are internal errors such as failing to allocate
memory, but host-not-found will also make this noise. n is a
General MIDI percussion key,
35 to 81; or 0 to prevent APing from making any sound on op errors.
The default is 58, the vibraslap.
aping www.jpsoft.com
APINGHELP — Open the APing plugin
help file.
Syntax:
APINGHELP /C /F /S /S:text /V topic
/C | select the “Contents” tab |
/F | select the “Favorites” tab |
/S | select the “Search” tab |
/S:text | select the “Search” tab and search for text |
/V | show detailed plugin version info |
| topic | the page to display |
The APINGHELP command will locate and open this plugin’s
help file. In most cases, the internal HELP command, and the F1
and Ctrl-F1 keys, will be more convenient. The main
advantage of this command is that it can be used to open the help file to any
desired topic, not only to the names of commands, functions, and variables.
APINGMACRO — List or change
APING macros.
Syntax:
APINGMACRO /D /L /P #n=value #name=value…
/D | disable highlight |
/L | list all defined macros |
/P | page output |
#n=value | create or delete a macro |
A macro is a number sign followed by a number or a name, used as a shortcut for a hostname. To define a macro, specify a value:
apingmacro #42=www.h2g2.com
To delete a macro, omit the value:
apingmacro #42=
You can change more than one macro at a time:
apingmacro #42=www.h2g2.com #1=skynet.cyberdyne.com
You can create a name instead of a number. A valid name begins with a letter;
may contain letters, digits, and underscores; and may be up to ten characters long.
It may not match any of the magic names ROUTER, GW,
DNS, DHCP, or WINS; or any of the above
followed by a digit, like DHCP2.
apingmacro #jp=www.jpsoft.com
To list all your currently defined macros:
apingmacro /L
Once you have defined a macro, you can use it in the
APING command or the
@PINGTIME function, just like any
other hostname:
aping #jp
echo %@pingtime[#jp]
Macros are stored in the registry. They will survive unloading the plugin or exiting the shell. Macros are shared across all instances of TCC.
New Functions:
@APINGMACRO — Returns the
value of an APING macro.
Syntax:
%@APINGMACRO[#n]
#n | the macro number |
If the specified macro is not defined, this function returns an empty string.
@LOOKUPHOST — Returns an
address for a hostname.
Syntax:
%@LOOKUPHOST[n,hostname]
| n | what to return: |
0: try IPv4 first, then IPv6 | |
4: IPv4 only | |
6: IPv6 only | |
10: try IPv6 first, then IPv4 | |
128: return the canonical name (CNAME record) | |
| hostname | the name to look up; required |
If n is not given, it defaults to 0 (try IPv4 first).
@PINGDHCP — Returns the address of
a DHCP server.
Syntax:
%@PINGDHCP[n]
| n | the index (1-N) of the server to return, or 0 for the number of known DHCP servers |
Only IPv4 is supported. If n is omitted, it defaults to 1 (return the first DHCP server). On any error, this function returns an empty string.
rem List known DHCP servers:
do i = 1 to %@pingdhcp[0]
echo DHCP #%i: %@pingdhcp[%i]
enddo
This function is equivalent to APING’s
#DHCP macro, but can be used in other commands.
@PINGDNS — Returns the address of a
DNS server.
Syntax:
%@PINGDNS[n]
| n | the index (1-N) of the server to return, or 0 for the number of known DNS servers |
Only IPv4 is supported. If n is omitted, it defaults to 1 (return the first DNS server). On any error, this function returns an empty string.
rem List known DNS servers:
do i = 1 to %@pingdns[0]
echo DNS #%i: %@pingdns[%i]
enddo
This function is equivalent to APING’s
#DNS macro, but can be used in other commands.
@PINGROUTER — Returns the address of a
router.
Syntax:
%@PINGROUTER[n]
| n | the index (1-N) of the router to return, or 0 for the number of known routers |
Only IPv4 is supported. If n is omitted, it defaults to 1 (return the first router). On any error, this function returns an empty string.
rem List routers:
do i = 1 to %@pingrouter[0]
echo Router #%i: %@pingrouter[%i]
enddo
This function is equivalent to APING’s
#ROUTER macro, but can be used in other commands.
@PINGTIME — Attempts to ping the
specified host.
Syntax:
%@PINGTIME[hostname,timeout,packetsize,ttl,flags]
| hostname | host name or dotted-quad IP address |
| timeout | in seconds, 1 to 300 (60) |
| packetsize | in bytes, 12 to 65520 (64) |
| ttl | time-to-live, 1 to 255 |
| flags | bitmapped: |
1 try IPv6 first, before IPv4 | |
2 compare reply data against sent data |
The hostname may be a user-defined macro
or one of the predefined macros: #ROUTER, #DNS, and so on.
On success, @PINGTIME returns the response time in milliseconds. On error,
it returns a negative number:
-1 | request timed out |
-2 | host unreachable |
-3 | bad or unknown hostname |
-4 | other errors (out of memory?) |
-10 | data mismatch (only when bit 1 of flags is set) |
@PINGTIME does not set any of the variables or
make a sound.
@PINGWINS — Returns the address of a
WINS server.
Syntax:
%@PINGWINS[n]
| n | the index (1-N) of the server to return, or 0 for the number of known WINS servers |
Only IPv4 is supported. If n is omitted, it defaults to 1 (return the first WINS server). On any error, this function returns an empty string.
rem List known WINS servers:
do i = 1 to %@pingwins[0]
echo WINS #%i: %@pingwins[%i]
enddo
This function is equivalent to APING’s
#WINS macro, but can be used in other commands.
New Variables:
_PINGAVG — Returns the average
ping time.
Returns the average time for returned packets, in milliseconds, during the
last call to APING. If no packets were
received at all, this variable returns 00.
If you specified more than one hostname, this value is for the last one on the command line.)
_PINGMAX — Returns the longest
ping time.
Returns the longest time for a returned packet, in milliseconds, during the
last call to APING. If no packets were
received at all, this variable returns 00.
If you specified more than one hostname, this value is for the last one on the command line.
_PINGMIN — Returns the shortest
ping time.
Returns the shortest time for a returned packet, in milliseconds, during the
last call to APING. If no packets were
received at all, this variable returns 00.
If you specified more than one hostname, this value is for the last one on the command line.
_PINGSLOST — Returns the
number of packets lost.
Returns the number of packets not returned in the last call to
APING.
If you specified more than one hostname, this value is for the last one on the command line.
_PINGSRCVD — Returns the
number of packets received.
Returns the number of packets returned (by the specified host, or by anyone
else) in the last call to APING.
If you specified more than one hostname, this value is for the last one on the command line.
Plugin Defaults Registry Key:
Default options may be set in a registry key:
HKEY_CURRENT_USER\Software\JPPlugins\APing
| Name | Type | Min. | Max. | Default | Unit | Option |
|---|---|---|---|---|---|---|
| Count | REG_DWORD | 0 | — | 4 | pings | /N:n |
| Timeout | REG_DWORD | 0 | 60000 | 3000 | milliseconds | /W:timeout |
| PacketSize | REG_DWORD | 12 | 65520 | 64 | bytes | /L:size |
| Instrument | REG_DWORD | 1 | 128 | 115 | GM instrument no. | /G:n |
| Octave | REG_DWORD | 0 | 9 | 5 | octave | /O:n |
| ErrorDrum | REG_DWORD | 35 | 81 | 66 | GM drum no. | /E:n |
| OpErrorDrum | REG_DWORD | 35 | 81 | 58 | GM drum no. | /X:n |
| NoMidi | REG_DWORD | 0 | — | 0 | boolean | nonzero disables sounds |
User-defined macros are stored in this key as well.
NoMidi Variable:
If an environment variable named NOMIDI is defined when
the plugin is loaded, MIDI will be disabled and APING
will not make any sounds. (The contents of the variable don’t matter,
so long as it contains something.) Setting this variable allows you to use
the plugin on systems which don’t support MIDI:
set nomidi=1
plugin /l c:\bin\tcmd\test\aping.dll
Setting the NoMidi registry variable
to a nonzero value does the same thing.
Paging Options:
APINGMACRO has a /P option to page
output. This option supports two suboptions:
/P:time,lines
| time | time in seconds, or (with a trailing M) milliseconds |
| lines | number of lines to display before pausing |
Both time and lines are optional. The colon is not required, but you must use the comma if you want to specify lines.
rem Scroll every five seconds:
fileinfo /p:5
rem Display ten lines at a time:
fileinfo /p:,10
rem Display twenty lines at a time, and
rem scroll every 2.5 seconds:
fileinfo /p:2500m,20
At the “Press a key to continue” prompt, most keys will advance by another screenful (or lines). But a few keys behave differently:
| A or C | turns off paging, and scrolls continuously |
| Esc or Ctrl-C | aborts the current command |
| / | scrolls half a screen, or half of lines |
| 1 to 9 | scrolls that many lines, e.g. 3 scrolls three lines |
Highlight Variable:
APING and APINGMACRO
both feature highlighted output. You can customize this feature by setting an environment
variable Highlight:
rem Disable highlight:
set highlight=none
rem Set the highlight foreground:
set highlight=bright cyan
rem Set both foreground and background:
set highlight=bri whi on blu
rem Numbers are also supported:
set highlight=46
If the Highlight environment variable is not defined, the plugin will
check the registry for a value named Highlight of type REG_SZ.
The plugin will search, in this order:
• HKEY_CURRENT_USER\Software\JPPlugins\APing | (affects this plugin only) |
• HKEY_CURRENT_USER\Software\JPPlugins | (affects several of my plugins) |
Both commands also have a /D option to disable highlighting.
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.3.1 | 2024-04-03 | NewHelp.cpp v1.0.8.14.
Documented all APINGHELP options. |
| 1.0.3 | 2024-01-05 | Updated to conlist.cpp v1.1 and NewHelp.cpp v1.0.8.13. Documented paging options. |
| 1.0.2.2 | 2023-10-12 | Updated the plugin’s web address. |
| 1.0.2 | 2023-07-10 | Setting the volume with APING /Y automatically
unmutes audio. Updated to the current versions of ParseArgs.cpp,
SoundVol.cpp, and conlist.cpp. |
| 1.0.1.1 | 2023-06-13 | Updated the help system to work around an issue in TCC v20.00.30. |
| 1.0.1 | 2022-12-15 | Improved LookUpHostIP()’s
ability to look up IPv6 addresses. This change affects APING,
@PINGTIME, and @LOOKUPHOST. |
| 1.0.0 | 2021-10-20 | Tweaks to the way help text is displayed.
Documented highlighting, and added a /D option
to both APING and APINGMACRO. |
| 0.76.3 | 2021-02-11 | Changes to allow APing to share a MIDI handle with my other plugins. Also, changed the filenames: APing.dll is now the 64-bit build; the 32-bit version is APing-x86. |
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 http://charlesdye.net/dl/aping.zip.