APing plugin for Take Command / TCC / TCC/LE

beta version 0.76.3     2021-02-11

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 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 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 Commands:

APING — Audibly ping a network host.

Syntax:
APING /4 /6 /A /C /E:n /F /G:n /I:ttl /L:size /N:n /O:n /Q /T /W:timeout /X:n /Y:volume hostname…

/4use IPv4
/6use IPv6
/Aresolve numeric addresses
/Cdisplay line numbers
/E:nspecify error drum
/Fset the Don’t Fragment flag
/G:nspecify instrument number
/I:ttlspecify the Time-To-Live value
/L:sizespecify the packet size in bytes(64)
/N:nnumber of ping requests to send(4)
/O:nspecify instrument octave
/Qquietly
/Tcontinue until Control-C is pressed
/W:timeoutset the timeout value in milliseconds(3000)
/X:nspecify op error drum
/Y:volumeset 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 /V topic

/Cselect the “Contents” tab
/Fselect the “Favorites” tab
/Sselect the “Search” tab
/Vshow detailed plugin version info
topicthe 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. This command 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 /L #n=value #name=value…

/Llist all defined macros
#n=valuecreate 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]

#nthe 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]

nwhat 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)
hostnamethe 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]

nthe 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]

nthe 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]

nthe 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]

hostnamehost name or dotted-quad IP address
timeoutin seconds, 1 to 300 (60)
packetsizein bytes, 12 to 65520 (64)
ttltime-to-live, 1 to 255
flagsbitmapped:
     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:

-1request timed out
-2host unreachable
-3bad or unknown hostname
-4other errors (out of memory?)
-10data 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]

nthe 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

NameTypeMin.Max.DefaultUnitOption
CountREG_DWORD04pings/N:n
TimeoutREG_DWORD0600003000milliseconds/W:timeout
PacketSizeREG_DWORD126552064bytes/L:size
InstrumentREG_DWORD1128115GM instrument no./G:n
OctaveREG_DWORD095octave/O:n
ErrorDrumREG_DWORD358166GM drum no./E:n
OpErrorDrumREG_DWORD358158GM drum no./X:n
NoMidiREG_DWORD00booleannonzero 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.

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:

VersionDateChanges
0.76.32021-02-11Changes 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:

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.

APing 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/aping.zip or ftp://prospero.unm.edu/aping.zip.