LPING - a Win32 ping-like batch utility to wake-up ISDN lines.


Introduction
------------

LPING.EXE is a small Win32 console-mode ping-like utility, written with 
Microsoft Visual C/C++ v6.0, which is used to 'wake-up' an ISDN line (ie:
cause it to dial and connect to an ISP) prior to using applications which
make use of the ISDN link.

The utility has been written with the intent that it should be used within
Windows 95/98 batch scripts (files with a .BAT extension) and also
Windows NT 3.x/4.0/Windows 2000 batch scripts (files with a .BAT or .CMD 
extension), but may also be used at a COMMAND.COM/CMD.EXE prompt as
necessary.


Background
----------

I am fortunate to be able to afford an ISDN connection to my ISP. Whilst the
dial-up times are significantly quicker than a standard dial-up modem link,
using a regular application, such as Netscape Communicator, Eudora etc. to
initiate the ISDN dial-up seems to lead to unpredictable results. Sometimes
the application being used will wake-up the link successfully and operate as
normal; at other times the application will time-out (the infamous Eudora 
10060 error, for example) just at the point where the link has been 
established.

To negate this type of situation, LPING.EXE has been written and is used as
a precursor, to wake-up the ISDN link before using applications which use it,
thus avoiding any timeout errors and the problems which that may cause.


Usage
-----

The program is executed using the syntax:

LPING <IP address of host to ping>

for example:

LPING 172.16.32.100

If the program is executed without a command-line argument, the program will
display usage information. For example:

LPING
Usage: LPING <host's IP address>

Note that because of potential DNS timeout issues when pinging a host using
the program, DNS names are NOT supported as a command-line argument.

If the program is supplied either an invalid IP address or host name, the
program will display the following text before terminating:

Unable to resolve address for target <command-line argument>

For example:

LPING www.fred.com
Unable to resolve address for target www.fred.com

When executed with a valid command-line argument, LPING.EXE will ping the
specified IP address every five (5) seconds (one second on the first
attempt) until the host is contactable. After each unsuccessful ping attempt,
LPING.EXE will display the following message text:

Target appears to be currently unreachable.

When the specified host becomes available, LPING.EXE will display the 
following message text, sounding a beep twice in the PC's internal speaker as
it does so:

Target appears to be reachable.
64 bytes received from address <IP address specified on the command-line>.

For example:

Target appears to be reachable.
64 bytes received from address 172.16.32.100.

The program then terminates. 

This behaviour differs from the standard Windows 9xNT 4.0/2000 PING.EXE 
utility, in that PING.EXE must be terminated manually if used with the -t 
argument. For example:

PING -t 172.16.32.100

will perform the same function as

LPING 172.16.32.100

However, PING.EXE (part of the standard Windows TCP/IP software environment)
must be terminated manually using a ^C (Ctrl-C) keyboard sequence once a link
has been established (ie: it never terminates), whereas LPING.EXE will 
terminate gracefully once a host has been contacted. LPING.EXE therefore
lends itself more readily to the batch environment than PING.EXE for the 
purpose of waking-up an ISDN link.

Note that LPING.EXE's output may be directed to stdout if required, using
the > redirection character. For example: 

LPING 172.16.32.100 > lping.txt


Example usage
-------------

The following example illustrates the program's use within a batch file:

@echo off

rem Wake-up the ISDN link using LPING.EXE.

lping 172.16.32.100

rem Pause for 15 seconds before terminating the batch script. The assumption
rem here is that LPING.EXE has woken-up the link. The program's exit status 
rem can be checked using the batch 'if errorlevel' construct - see below.

doze 30

rem DOZE.EXE is a simple batch utility which is used to introduce a timed
rem pause into a Windows 9x/NT4.0/2000 batch script. It is available via
rem URL http://www.bastet.com/software/software.html.

exit


Errorlevels
-----------

LPING.EXE returns two possible exit values (errorlevels):

1 - A problem of some sort occurred; the program terminated abnormally.
0 - The program detected no error during execution and terminated normally.


Messages
--------

In addition to the above messages, the following advisory and error messages 
may also be observed during program execution. Error messages are written
to stderr, which may be redirected to a [text] file if required. For example:

LPING 172.16.32.100 > lping.txt 2>&1

or

LPING 172.16.32.100 > lping.txt 2> lping.err

Error messages (fatal; return an errorlevel of 1 (one)). The text 'nn' below
represents a numeric value:

Usage: LPING <host's IP address>
WSAStartup failed. Error: nn.
WSASocket() failed. Error: nn.
Failed to set receive timeout on socket. Error: nn.
Failed to set send timeout on socket. Error: nn.
Failed to set non-blocking option on socket. Error: nn.
Unable to resolve address for target <IP address>.
HeapAlloc failed. Error: nn.
Send-to failed. Error: nn.
Receive-from failed. Error: nn.

Advisory messages:

Timed-out.
Target appears to be currently unreachable.
Too few bytes received from <IP address>.
Non-echo type nn reply received.
Received somebody else's data packet!
Target appears to be reachable.
64 bytes received from <IP address>.


Testing
-------

The program has been tested on a Windows NT4.0 platform with service pack #5
applied. The program should operate within a Windows 9x COMMAND.COM session
and Windows NT 3.x/2000 CMD.EXE session, but this has not been verified due 
to a lack of test equipment.


Known issues/other considerations
---------------------------------

If LPING.EXE is used to contact a host known to be operational (for example,
a lan-based system) the message:

Target appears to be currently unreachable.

may be displayed. Standard PING.EXE reports no problems.

This is due to a bug/feature (call it what you will!) in the code due to the
change of the socket blocking method from blocked to non-blocked. A 
WSAEWOULDBLOCK response is returned when really a time-out should occur. This
is fixable, but doesn't present a problem when used to dial/wake-up an ISDN 
link.

It may be possible to use LPING.EXE to wake-up a standard modem dial-up link. 
This will depend very much on system configuration and has not been verified 
by the author.

Note that the IP address used above (172.16.32.100) is an example only. Users
should use an address appropriate to their environment. A good rule of thumb
seems to be to use the IP address of an ISP's DNS server.


License/disclaimers
-------------------

See file LICENSE.TXT for further information. All registered trademarks etc.
are acknowledged.


Author's contact details.
-------------------------

Clem Dye
clem@bastet.com
