
   The program contained in this archive and described further down in
   this text was written from scratch by Jrgen Hoffmann using BORLAND
   C++ Version 3.1 some time during the year 2010.  It is licensed un-
   der the EUPL V.1.1  and offered  to the public free of charge.  The
   english text  of this european  public licence  is included in this
   archive.  Other, equally valid versions,  together with some useful
   explanations for non-lawers are available in all official languages
   of the european union and can be downloaded from here:
   http://ec.europa.eu/idabc/eupl.

   As the program is free, the author doesn't accept any responsibili-
   ty beyond what can reasonably  be expected  from any other  kind of
   gift as well. Even though the program was thoroughly tested it can-
   not be excluded,  that undiscoverd  errors still arise.  Should you
   find such a one, feel free to inform the author about it, using the
   e-mail address shown at the end of this document.

   


LANSTAT     (LAN STATus) 

   is a LAN supervisor,  a program that regularly polls the nodes of a
   local area network to check their accessability and constantly dis-
   plays the status of the LAN in a clearly arranged tabular manner.

   Of course there are other programs around doing a similar job.  But
   many of them are commercial products,  only a few of them run under
   DOS  and very few will be  as compact in size  as about 30 kB.  The
   trick is, that LANSTAT doesn't do any network access by itself, ra-
   ther it invokes external programs (like e.g. ping) for that purpose.
   The precize syntax to call these programs  is defined in a configu-
   ration file.

   This approach does not only  keep the program small,  it also makes
   it independent of the underlaying network software. LANSTAT can run
   under virtually any  TCP/IP software,  at least any one  that comes
   with a ping routine. And it can do even more that that.  By calling
   other  external programs,  like e.g. lpq, some flavor of natcat  or
   some port scanner,  it can not only check  the net-accessability of
   computer, but also the availability of certain services. Using pro-
   grams like ipx_ping even allow to use it with networks which aren't
   based on TCP/IP at all.  Any program or command (internal or exter-
   nal) can be defined as test-agent,  provided it meets the following
   three requirements:

   1. It must be entirely command-line controled  and complete it's
      operation without any further user intervention.
   2. It must write it's output to stdout,  must not write directly
      onto the screen and should not write anything to stderr.
   3. It must produce  some unique string  that reliably  allows to
      clearly ditinguish between success and failure.

   LANSTAT's screen layout is composed of five sections. In the upper-
   most position the title line is shown in inverse video.  The header
   section, directly below, may or may not be present.  If present, it
   shows, in normal video, user-defined general information. The acti-
   vity  display,  below the header  section shows,  again in  inverse
   video and in two lines, the current polling activity. Below the up-
   per status display follows the actual LAN status display area.  The
   bottom line of the screen shows, again in inverse video,  the lower
   status line giving the user some general infomation  about the pro-
   gram's status.  The layout of  the LAN status  display area  can be
   configured to a large extend.  In addition,  LANSTAT can optionally
   be caused to produce an HTML file which can be displayed by any WEB
   browser which is capable to properly display tables and colors.

   LANSTAT polls the hosts  in the sequence defined  in its configura-
   tionfile by calling the corresponding external program and determi-
   ning, whether the poll was successful or not.  If a host was polled
   successfully during at least three successive polling cycles, it is
   considered as "good".  If it was unsuccessfully polled during three
   successive polling cycles, it is regarded as "bad". All other cases
   are considered "unclear". A polling cycle is completed when all de-
   fined hosts were polled once.

   Before LANSTAT can do anything useful, its configuration file which
   by default is named LANSTAT.INI  and is expected to be found in the
   same directory as the program itself, must be properly set-up.  The
   configuration file is an ordinary text file holding a number of en-
   tries,  each of which on a line of its own and consisting of a key-
   word which is in most cases followed by some arguments. If an argu-
   ment, especially a string argument,  contains a space character, it
   must be enclosed in quotes (""). Otherwise the quotes are optional.
   Blank lines  are acceptable  and a line beginning  with a semicolon
   (';') marks a comment which is not further iterpreted.  The entries
   may appear in any order,  but forward references are not supported.
   Therefore LABELs, ALIASes, HOSTs and DEPENDS ON clauses may not re-
   fer to TESTs, ICONs or other HOSTs  that are not yet defined.  Fur-
   thermore a DEPENDS ON clause  should appear  right after the depen-
   ding host  and a PAGE entry affects only  the items following it in
   the file.  Last but not least, the order in which LABELs, HOSTs and
   ALIASes are defined determines their position on the display.  Case
   is generally not relevant  (except when referencing hostnames)  and
   the following entry types are accepted:

PTEST  <command> <test-string> [ <status-string> ]
NTEST  <command> <test-string> [ <status-string> ]

   These  two entry types  define  an ordinary test-agent.  Up to nine
   PTEST/NTEST entries may be defined.  They will be numberd from 1..9
   in the sequence of their definition and the HOST entries will refer
   to them by that number.

   <command> is a string argument defining the command line  necessary
   to invoke the program,  just as it would be entered manually at the
   command prompt. The output of the command is searched for the <test-
   string> to decide whether it was successful or not. If the optional
   <status-string> is also present,  then the output will  be searched
   again for a line  containing this string.  The last such line found
   will be stored as status message  for the respective host.  If this
   argument is missing, the last non-empty line will be used instead.

   PTEST and NTEST differ in the way how <test-string> is interpreted.
   PTEST (Positive Test)  expects <test-string>  to be present  in the
   output  to regard a test as successful.  A typical example would be
   "Responded in".  NTEST (Negative TEST) expects <test-string> NOT to
   be present in the output to consider the test as successful.  A ty-
   pical example would be  "did not respond".  In any case  the string
   has to be chosen carefully to ensure meaningful results.

   The special sequence "\a" in any of the strings  will automatically
   be replaced by the <argument> string of the corresponding host.  As
   a consequence of that, literal backslashes ('\') have to be duplica-
   ted like this: "c:\\wattcp\\ping \a". As the double quote (") is in-
   terpreted by LANSTAT as a string delimiter  and automatically remo-
   ved from the text,  it cannot be used  in an argument.  To overcome
   this limitation the sequence "\q" may be used, it is silently repla-
   ced by a double quote.

BTEST  <command> <test-string> [ <status-string> ]

   Some commands, like e.g. "net slist" of Novell Netware lite or "net
   view" of Microsoft, do not test for a single host, rather they pro-
   duce a whole list. Of cource it would be possible to define a PTEST
   to invoke this command  again for each  individual host  and search
   the result  for the  occurance of  its <argument> string  to decide
   whether "good" or "bad". But this isn't very efficient.

   This is  where BTEST  (Bulk TEST) entries  come in handy.  They are
   executed only once per polling cycle  and their result is stored in
   a separate place. Whenever a host refers to such a test (by specify-
   ing a "B<n>", n=1..9) this previously stored result is searched for
   the occurence of the <test-string> and possibly the <status-string>
   (which in-turn may include a "\a") without re-executing the command.
   This way the extra network traffic caused by LANSTAT may be reduced.
   Note that BTEST doesn't have a negative form,  so it can only test,
   whether a specific host (string) is found in the list or not. Up to
   nine BTEST entries may be defined.

GTEST  <command> <test-string>

   As LANSTAT's correct operation  depends heavily on external resour-
   ces/programs it is important to ensure that they are available when
   LANSTAT starts.  This is the purpose of GTEST entries.  They define
   tests which will be performed only once on program start-up. If any
   of them fails,  LANSTAT will terminate immediately and tell as much
   as it can about the reason.  An example for such a test  could be a
   ping  to the computers  own IP-address.  Such a ping  should always
   succeed,  unless some very basic problem arises  like e.g. protocol
   stack not loaded or so.  Defining such a GTEST in the configuration
   file  could prevent LANSTAT  from attempting to run  in a situation
   where  it would be  completely pointless.  Up to nine GTEST entries
   may be defined.

HEAD   <text> [ <env-var> | <command> [ <search-string> ] ]

    A HEAD entry defines a line of the above mentioned header section.
    If no HEAD entries are specified, then the header section will not
    be present. A HEAD entry without arguments defines a blank line in
    the header section,  any other  <text>  will simply be  displayed.
    However there are a few exeptions.  A "\t" will be replaced by the
    current time,  a "\d" by the current date  and a "\q" by  a double
    quote. A "\e" is replaced by the content of an environment variab-
    le,  whichs name must be specified as second argument (<env-var>).
    A "\c" will be replaced by a line of the output of a program which
    must equally well  be defined  as second argument (<command>),  in
    much  the same way  as with the *TEST entries.  Which line  of the
    output will be chosen depends on the opional third argument. If it
    is specified,  then it defines the line  containig the string  for
    which the output is searched.  If it is absent, then the last non-
    empty line of the program's output  will be taken.  "\c" \and "\e"
    may not both appear  in same HEAD entry,  as they are mutually ex-
    clusive,  but "\t", "\d" and "\q" can be combined freely.  Again a
    literal backslash ('\') in <text> must be duplicated.

COLS   <columns> <linespacing> <mode> [BOX]  (mode=COLOR,MONO,CHAR)

    The COLS entry defines the layout  of the LAN status display area.
    <columns> is a number in the range 1..10. It defines the number of
    columns which form the atual display. <linespacing> is a number in
    the range 0..5 which defines the number  of additional blank lines
    btween two rows of the table. <mode> can be one of three allowable
    keywords. If set to COLOR (the default) then "good" hosts are dis-
    played in green color, "bad" ones in red and the "unclear" ones in
    yellow. In mode MONO "good" hosts are diplayed in intensive (high-
    lighted) video,  "bad" ones in normal video and "unclear" ones are
    shown blinking.  In CHAR mode all hosts are shown in normal video,
    but the names of "good" ones are preceeded by a '+' sign the "bad"
    ones are marked with a '-' and the "unclear" ones with '?'. Labels
    are always shown in normal video.

    LAN status display data will be displayed as a rectangular pattern
    on the screen.  The defined HOSTs and LABELs  (see below)  will be
    shown in the order they appear in the inifile, from left to right,
    row by row,  until the defined display area is filled  or the list
    is exhausted.  If there are more data items  than can be displayed
    on the screen, then the excessive ones are simply ignored.  Recent
    program versions  allow to scroll the display area vertically  but
    to avoid  the need for such scrolling  it is recommended to adjust
    the layout (more <columns>,  less <linespacing>,  fewer headlines,
    smaller <top margin> and/or smaller <bottom margin>).

    If <columns> is 1,  then the display area shows  for each host the
    counter,  telling for how many successive polling cycles  the cur-
    rent result already persisted,  followed by the  name of the host,
    shown according to the current  <mode>  and the status message for
    that host. In multi-column tables only the names are shown and, if
    the available  screen space permits it,  also the counter for each
    host.

    The optional keyword  BOX  causes  rectangular  boxes to  be drawn
    around the hostnames  on the display,  provided that the available
    space on the screen permits it.  This will be the case if the fol-
    lowing four conditions are met: <columns>  and  <linespacing> must
    both be greater than one and <top margin> and <bottom margin> (see
    below) must both be  at least one.  If one  of these conditions is
    not met then BOX will be silently ignored.

MARGIN <top margin> <left margin> <bottom margin> [ <wallpaper> ]

    The <top margin> (range 0..5) is the number of blank lines between
    the activity display and the first line of the LAN status display.
    The  <left margin> (range 0..30)  is the number  of spaces  to the
    left of the LAN status and the <bottom margin> (range 0..5) is the
    minimal number  of blank lines  between the last  line of  the LAN
    status display area and the lower status line.

    The optional <wallpaper> is a simple textfile which is expected to
    be found in the same diretory as the inifile itself  and it serves
    as a background for the LAN status display area. It can be used to
    display texts  which are to long  to fit  into a label  or to draw
    character  (line-) graphics,  e.g. to visualize relations  between
    the different  items on  the screen.  If it is omitted,  the back-
    ground will simply be left black.

DELAY  <cycle delay> <inter-test delay> [FASTINI]

    The <cycle delay> (range 0..180) defines a time in seconds LANSTAT
    waits after a polling cycle is completed before it begins the next
    one.  The <inter-test delay> (range 0..10) defines a delay in sec-
    onds between each individual test within a polling cycle. Both va-
    lues can be used to adjust the polling frequency which in-turn in-
    fluences the rate by which status changes are detected  as well as
    the extra network traffic  caused ba LANSTAT.  In addition LANSTAT
    automaticly reduces  the polling  frequency of  those hosts,  that
    haven't changed their status for more than five polling cycles.

    If the optional keyword FASTINI is specified, then the delays will
    not be effective  during the first four polling cycles  after pro-
    gram start-up.  LANSTAT will rather poll as fast as it can  during
    this initial phase. Once this phase is over, it will switch to the
    polling frequencies given by <cycle delay> and <inter-test delay>.
    This is intended to get a quick overview soon after program start-
    up and reduce the average network load during long-time operation.

HOST   <name> [B]<test-num> <argument> [ <icon-num> ]

    A HOST entry defines a test instance. In many cases, especially if
    the test-agent ist some flavour of ping, it will be an actual host
    but it can also be a printer queue,  a TCP-port  or something else
    that is tested  by a test-agent.  The <name> will be  displayed on
    the screen.  It may be up to 31 characters long, but will be trun-
    cated by LANSTAT if space on the LAN status dispaly is tight.  The
    <test-num> (range 1..9 or B1..B9) refers to a PTEST/NTEST or BTEST
    entry.  As these entries are numbered  according to their sequence
    in the inifile  <test-num>  may not be larger  than the number  of
    tests specified so far. The <argument> string is the one that will
    replace any occurence of "\a" within the  <command>, <test-string>
    or <status-string> of the respective test.  Typically this will be
    something like an ip-address or a computer name, but it can be any-
    thing suitable.

    The optional <icon-num> (range 1..9)  refers to an icon file  (see
    below) and defines which icon should be used to denote the host in
    the (also optional) html file.  The number of HOST entries is only
    limited by the availabe memory.

DEPENDS ON <host-name>

    Sometimes one test depends on  the result of another one.  Testing
    for the accessability of a remote web server is probably pointless
    if the ping test for the gateway computer (aka router) was already
    not successfull. The DEPENDS ON entry states that the most recent-
    ly defined HOST  depends on the one  specified by <host-name>.  If
    the test for <host-name> fails  (returns "bad")  then the test for
    the depending host will be skipped in the test sequence,  to avoid
    unnecessary  network  traffic.  Preferably  the  DEPENDS ON  entry
    should be placed  in the inifile  right after the HOST entry  that
    depends on another one.  As LANSTAT doesn't enforce unique hostna-
    mes a possible ambiguity of <host-name> is resolved in such a way,
    that always the most recently defined host  of that name is taken.
    If this is a problem,  then names  should be chosen  to be unique.
    Unlike most other aspects of the inifile, <host-name> is case sen-
    sitive and the host it refers to must already be defined previous-
    ly. Example:
                 . . .
                 PTEST "ping \a" responded
                 . . .
                 HOST ROUTER 1 192.168.0.254
                 HOST WEB    1 www.google.com
                 DEPENDS ON  ROUTER
                 . . .

ALIAS <name> IS <host-name> [ <icon-num> ]

    This entry defines a node  which is displayed  just as a real host
    but instead of performing any tests on it,  the results of the ac-
    tual host  will just be copied.  This is  particularly  usefull in
    multi-page layouts  where the same host should appear on more than
    one page  but the network overhead  caused by multiple polling  of
    the same host should be avoided.  The alias has a name of its own,
    specified by <name>, which may or may not be identical to the name
    of the actual host, which in-turn is specified by <host-name>.  As
    in the case of DEPENDS ON, <host-name> must match exactly with re-
    spect of case and spelling and the last matching one will be taken
    in case of an ambiguity. An alias can also have an icon of its own.
    Example:
                 . . .
                 HOST ROUTER 1 192.168.0.254
                 . . .
                 PAGE
                 . . .
                 ALIAS GATEWAY IS ROUTER
                 . . .

LABEL  [ <name> [ <icon-num> ] ]

    A LABEL defines some text that will be displayed at the correspon-
    ding spot of the LAN status display array. It will always be shown
    in normal video and has neither a counter nor a status message. It
    need not have a text.  In this case the corresponding spot will be
    blank. This can be used to create non-rectangular display patterns
    on the screen.  The optional <icon-num> (range 1..9)  refers to an
    icon file (see below) and allows to assign an icon to the label in
    the (also optional) html file.

PAGE  [ HIDE | <columns> <linespacing> [BOX] [ <wallpaper> ] ]

    The LAN status  display data  can be  separated  into a maximum of
    four pages.  By default all HOSTs  and/or  LABELs go into  display
    page one.  Each occurence of the PAGE keyword switches to the next
    page.  All HOSTs and/or LABELs definded after such a PAGE entry go
    to the next display page. LANSTAT regards it as an error if a page
    is empty.  Therefore at least one HOST, ALIAS and/or LABEL must be
    defined before and after each PAGE entry.

    Optionally it is possible to define a new number of columns, and a
    new linespacing for that page.  The optional Keyword BOX allows to
    draw "boxes" around  the hostnames on the display  and a different
    wallpaper can be chosen.  If these arguments are absent,  then the
    default values  as defined by the COLS entry  remain in force.  If
    at least <columns> and <linespacing> are specified, then the absen-
    se of "BOX" swithes box-drawing off and the absense of <wallpaper>
    disables the background for that page.

    The keyword "HIDE", which must be the only argument,  is a special
    case.  It does not switch to the next page,  rather it causes page
    number one not to be displayed, leaving only three displayable pa-
    ges. This hidden page, which is always the first one,  may be used
    to place HOST entries which are not ment to be displayed but refe-
    renced by other ALIASes or depending hosts. To understand why this
    can sometimes be useful, one has to be aware that LANSTAT does not
    support forward references and that the items are displayed on the
    screen  from left to right  and from top to bottom strictly in the
    order they appear in the inifile.  Therefore it is not possible to
    place host on the display  to the right of one that depends on it.
    To overcome this inconvenient limitation,  this host can be repla-
    ced by an ALIAS  refering to a real host  which is defined further
    up in the file on the invisible page. Example:

                 HOST       host_2 . . .
                 DEPENDS ON host_1
                 HOST       host_1

    is an illegal forward reference, rather use:

                 PAGE HIDE
                 HOST       real_1 . . .
                 PAGE
                 HOST       host_2 . . .
                 DEPENDS ON real_1
                 ALIAS      host_1 IS real_1

ICON   <filename>

    This optional entry type  allows to define  up to nine image files
    to be used  as icons which can be  assigned to HOSTs and/or LABELs
    if an html file is generated. <filename> must not contain any path
    or drive specification, LANSTAT rather expects to find these icon-
    files in the same directory where it found the inifile itself. The
    use of icons is completely optional.  If no htmlfile is generated,
    they are not needed anyway, but even if such a file is produced it
    is possible to write a completely text-based html file by not spe-
    cifying any icons and not referencing them by HOSTs and/or LABELs.

HTML   <path\filename> [ <page> [ <refresh-delay> ] ]

    This optional entry  causes LANSTAT  to generate  an htmlfile  and
    tells it where to write that file. This can be on a local drive or
    a mapped network drive and can be further distributed by some http
    server  or directly displayed by a web browser.  The file is (re-)
    written once per polling cycle  so the data is  regularly updated.

    If more than one display page is defined the optional <page> para-
    meter (range 0..4) can specify which page (1..4) should be conver-
    ted to html. If it is zero or completely missing, the current dis-
    play page will be taken,  unless the filename contains the charac-
    ter "0" like e.g. "lanstat0.htm".  In that case  up to four diffe-
    rent htmlfiles will be written, one for each display page.  All of
    them have  the specified filename, but the "0"  is replaced by the
    page number.  In addition they will have apropriate links to allow
    easy switching between the different pages.

    LANSTAT includes a <META> tag  in the html file  which causes most
    browsers to reload the file after a certain period of time  to en-
    sure a regular update. By default this period is 30 seconds but it
    can be changed by the optional <refresh-delay> parameter (range 0,
    10..300). If set to zero, the generation of the <META> tag is com-
    pletely suppressed.  Note that in <path\filename> backslashes must
    NOT be duplicated, as no argument evaluation is done here.

LOGFILE <path\filename> [ <size limit> [ <info string> ] ]

    This optional entry causes LANSTAT  to write a  log message to the 
    file defined by <path\filename> whenever a host changes to a stab-
    le state (good or bad) or vice versa. In other words, whenever the
    display color changes,  a log entry is made.  If the file  already
    existed, new entries will be appended.  This way a constant log is
    is maintained  even across multiple  runs of LANSTAT. The downside
    is a  constantly growing logfile  which may  fill-up the disk.  To
    prevent this, a size limit (in kilobytes) can be defined. Whenever
    the logfile exceeds this limit,  the least recent entries  will be
    removed  to cut the size down below the limit,  before new entries
    are added.  As this check is performed only once per polling cycle
    there is a theoretical chance that the file may temporarily exceed
    the defined limit if the rate of logging events is extremely high.
    The optional <info-string>  will be written to the file at program
    start-up.  If it is omitted, the name and path of the inifile will
    be  written instead.  Several different  inifiles  may specify the
    same logfile. Note that in <path\filename> backslashes must NOT be
    duplicated, as no argument evaluation is done here.


Program operation

    Once the inifile is set-up  the hardest part is done.  If the ini-
    file has its default name "LANSTAT.INI" and is located in the same
    directory as the program,  all there is to do is enter the command
    LANSTAT  and there you go.  Nevertheless  there are  a few options
    that can be specified on the command line:

LANSTAT [ options ]

valid options are:

    /H /?   print this helptext
    /V      operate in VGA (EGA) mode with 50 (43) lines
    /I<fil> define alternate ini-file (default: LANSTAT.INI)
    /D<num> set debug value

    The /h or /? options show the first page of the help screen. Pres-
    sing any key, except <ESC> which immediately terminates,  advances
    to the second page.  The help screen  cannot replace  the carefull
    reading of this text  but it can be a useful help  to memorize the
    details.

    By default LANSTAT will expect  a screen size of 80*25 characters.
    The /V switch causes LANSTAT to swith to VGA/EGA mode, allowing up
    to 50/43 screen lines and providing more display space.

    The /i<fil> option  can be used  if the inifile is  not located in
    the same directory as the program or has a different name. The ar-
    gument <fil> is the drive/path/name of the alternat file.  It must
    immediately follow the "/i", without any intermediate spaces.

    An alternative is  to set the environment  variable LANSTAT_INI to
    the the drive/path/name  of the inifile.  If this variable  is set
    and the /i<fil> option is also given, the latter one overrides the
    environment variable.

    Another environment variable that can be set, is LANSTAT_TMP.  The
    program uses  a number of temporary files to perform its task.  If
    an environment variable TEMP exists, LANSTAT assumes that it holds
    the name of a directory  where it is safe to write those temporary
    files. It TEMP doesn't exist, it looks for a variable TMP, if this
    one doesn't exist either  then the directory where the program it-
    self is located will be used instead.  This default behaviour  can
    be overriden by an environment variable named LANSTAT_TMP.  If set
    LANSTAT assumes  that it points  to the proper directory  to write
    its temporary files.

    The /D<num> option should not be necessary for ordinary operation.
    Its purpose is to help in the case  of problems.  <num> is the sum
    of the  following  values,  which all  enable some  kind of  debug
    option:

         1   show ini-file while reading  -  This value causes LANSTAT
             to echo each line of the inifile on the screen while rea-
             ding it.  This can be helpful  to find the offending line
             if LANSTAT aborts due an error in the inifile.

         2   keep temp-files on exit  - Normally LANSTAT will clean-up
             on termination  and delete  all its temporary files.  For
             debugging it may sometimes be helpful to keep them.

         4   show ini-data after reading (and exit) - This debug opti-
             on causes LANSTAT  to write the contents  of its internal
             tables after processing of the inifile is complete. Some-
             times  it may be helpful to see,  how LANSTAT interpreted
             the data in the inifile. It uses a format which is compa-
             tible with the syntax of the inifile itself.  Actually it
             is even possible to re-direct this output into a file and
             use that file as new re-formatted inifile.

         8   single-step mode   -  This debug option causes LANSTAT to
             operate in single-step mode. During the attempt to execu-
             te an external command,  it will stop  at three  distinct
             points and wait each time until a key is pressed. If this
             key happens to be the <ESC> key, single-step mode will be
             left and normal operation  is resumed.  As a consequence,
             pressing <ESC> a second time will terminate the program.

             LANSTAT shows  the fact that it stopped  and waits for  a
             key by the indicators "Stp1".."Stp3" at the rightmost end
             of the lower status line.  "Stp1" indicates the stop just
             before  the external  program is  executed but  after the
             command line  was compiled  and possible  arguments  were
             evaluated. "Stp2" is right after the external command re-
             turned to LANSTAT  and "Stp3" stops after the status mes-
             sage has been extracted from the result data. This can be
             a useful tool  if some external program doesn't behave as
             expected.

        16   clear temp-file before each test  -  Normally LANSTAT re-
             uses its temporary files over and over again.  In certain
             situations  the writing of  such a file  may fail and the
             results  of a previous  command  are erroniously  re-read
             which can be very confusing. This debug code prevents the
             problem by clearing the temporary file before each execu-
             tion of an external command but at the expense of additi-
             nal I/O activity.

        32   disable html character translation  - When generating the
             htmlfile LANSTAT  has to translate ASCII  codes above 127
             into their  HTML counterparts.  This debug  code disables
             this translation.

        64   If html output with icons is specified  then LANSTAT will
             ensure that current versions of the iconfiles are present
             in the target directory of the htmlfile  and if necessary
             the required iconfiles are copied to that directory. This
             debug option helps tracking the copy process.

    While LANSTAT is running, no user interaction is required. The pur-
    pose of the program is to watch the status of the LAN which is con-
    stantly displayed. Yet some keystrokes do have a special meaning:

    <ESC> terminates the program and <CTRL/C> does the same.

    Pressing the cursor keys will highlight some item  (host or label)
    on the display grid.  By hitting the cursor keys successively this
    highlighted mark  can be moved around.  If it sits on a host,  the
    individual argument string  and the status message for that parti-
    cular host will be shown in the activity display area,  instead of
    the current activity.  If more HOSTs are defined than would fit on
    the display area,  then moving the highlighted mark over the lower
    limit will scoll the display down.  Moving it over the upper limit
    will scroll up again, unless the uppermost (basic) position is al-
    ready reached.  In this case moving up  will return to  the normal
    activity display in the same way as hitting the <HOME> key.

    If more than one display page is defined then the leftmost part of
    the lower status line indicates which page is currently displayed.
    The <PgUP> and <PgDown> keys allow to switch between the different
    pages. 

    If the screen gets messed-up,  which may happen  if one of the ex-
    ternal programs does not completely fulfill  requirement number 2,
    then pressing the 'R' key (for re-draw) may be helpful.

    While LANSTAT is pausing in a delay-loop, hitting the <RETURN> key
    will manually trigger another polling-cycle.

    While LANSTAT executes an external program it is suspended and can
    not process any keystrokes.  This state is indicated by the "busy"
    message  on the rightmost end  of the lower  status line.  Next to
    that indicator  is a small field  with two spinning hyphens.  They
    are intended to show the program's activity even in phases without
    LAN status changes.  The right one  of these two  is advanced each
    time the display  is updated  while the left one  is advanced once
    for each completed polling cycle.

    Even though LANSTAT was developed and is intended to run under DOS
    it  was also tested and ran  successfully  under Windows 3.X/98/ME
    and even Windows NT4.0.  This is especially interesting when using
    the html feature  as these operating environments are multitasking
    and can run an http server at the same time.

Example #1 (bare bones)

                 PTEST   "ping \a /T1" responded
                 HOST    "PC 1" 1 192.168.1.1
                 HOST    "PC 2" 1 192.168.1.9
                 HOST    "PC 3" 1 192.168.1.13

    This is a very minimalistic inifile. It just defines a single test
    agent (in this case the ping utility that comes with NOVELL's  LAN
    workplace for DOS) and three hosts.  No header section and all the
    other parameters left at their default values. This is the absolu-
    te minimum it takes  to get LANSTAT running  and the layout of the
    display may not be considered fully satisfactory by everyone.

Example #2 (LAN monitoring)

    1:           ; The linenumbers at the leftmost margin are only for
    2:           ; reference they are not part of the actual inifile
    3:           ;
    4:           HEAD
    5:           HEAD    "    LANSTAT is running at: \t   under: \c" "ver"
    6:           HEAD
    7:          
    8:           ICON    "DESKTOP.GIF"
    9:           ICON    "ROUTER.GIF"
    10:          HTML    "C:\BORLANDC\PROJECTS\LANSTAT\LANSTAT.HTM"  0  30
    11:          LOGFILE "C:\BORLANDC\PROJECTS\LANSTAT\LANSTAT.LOG"
    12:         
    13:          COLS    4  2  COLOR  BOX
    14:          MARGIN  3  5  1 
    15:          DELAY   0  2 
    16:         
    17:          GTEST   "ping -n 1 192.168.1.2" "Reply from"
    18:          BTEST   "net view"              "\a"
    19:          PTEST   "ping -n 1 \a"          "Reply from"
    20:          PTEST   "type \a"               "available"
    21:         
    22:          LABEL   "PC 1" 1
    23:          HOST    "ping" 1 "192.168.1.2"
    24:          HOST    "net" B1 "\\PC_1"
    25:          DEPENDS ON "ping"
    26:          HOST    "file" 2 "\\PC_1\Drive_C\TEST.TXT"
    27:          DEPENDS ON "net"
    28:         
    29:          LABEL   "PC 2" 1
    30:          HOST    "ping" 1 "192.168.1.9"
    31:          HOST    "net" B1 "\\PC_2"
    32:          DEPENDS ON "ping"
    33:          HOST    "file" 2 "\\PC_2\Drive_C\TEST.TXT"
    34:          DEPENDS ON "net"
    35:         
    36:          LABEL   "PC 3" 1
    37:          HOST    "ping" 1 "192.168.1.13"
    38:          HOST    "net" B1 "\\PC_3"
    39:          DEPENDS ON "ping"
    40:          HOST    "file" 2 "\\PC_3\Drive_C\TEST.TXT"
    41:          DEPENDS ON "net"
    42:         
    43:          LABEL   "PC 4" 1
    44:          HOST    "ping" 1 "192.168.1.16"
    45:          HOST    "net" B1 "\\PC_4"
    46:          DEPENDS ON "ping"
    47:          HOST    "file" 2 "\\PC_4\Drive_C\TEST.TXT"
    48:          DEPENDS ON "net"
    49:         
    50:          LABEL   ""       2
    51:          HOST    "ROUTER" 1 "192.168.1.254"
    52:          HOST    "WEB"    1 "145.253.2.11"
    53:          DEPENDS ON "ROUTER"

    This more sophisticated set-up which actually ran under WfW3.11 on
    top of MS-DOS 6.22 would run equally well (possibly requiring some
    minor adaptions)  under Microsoft  DOS TCP/IP  (aka network client
    for DOS) or Windows98. It only monitors four hosts and an internet
    gateway  but it applies a number of options  that can be specified
    in such an inifile.  Blank lines  are used to group the file  into
    logical blocks and semicolons indicate comments.
  
    Lines four to six define the header section.  Two of the lines are
    just empty  but line five shows the current time and invokes "ver"
    to indicate the operating system under which LANSTAT is running.

    Lines eight and nine  specify two iconfiles  which are  refered to
    further down  and line ten specifies  the location where the html-
    file should be written.  Line eleven specifies  a logfile of unli-
    mited size.

    Line 13 specifies a display matrix of four columns with a linespa-
    cing of two lines,  using colors to indicate the status  (which is
    the default anyway) and "boxes" drawn around each host entry. Line
    14 specifies the top-, left- and bottom margins and line 15 speci-
    fies  a delay of two seconds  between succeding test  and no delay
    between two succeding polling cycles.

    Line 17 specifies a ping to host 192.168.1.2 as global test (GTEST)
    Assuming that this is the mashine LANSTAT is running on, that ping
    should  always succeed,  unless something  very basic  went wrong,
    like e.g. the network stack is not loaded.  Therefore LANSTAT will
    abort if this test failes.

    Line 18 defines the command "net view" as bulk test (BTEST).  This
    test is performed  only once per polling cycle  and hosts refering
    to that test (by "B1") just try to find their argument in the sto-
    red results to determine whether the test was successful or not.

    Line 19 defines an ordinary ping to the respective host as test a-
    gent expecting the string "Reply from" in the result to regard the
    test as successful.  Line 20 is an example showing, that more than
    one test agent may be specified and it shows that every (suitable)
    command and/or program can be used as test agent.  In this case it
    an ordinary "type".  It assumes that a  text file containig a line
    like "Drive \\PC_1\Drive_C is available"  was previously deposited
    in the root directory of the respective drive. If the string "avai-
    lable"  can be found in the response,  then the file could be read
    and the drive  was successfully accessed  otherwise something went
    wrong.

    Each of the groups of lines  22..27,  29..34,  36..41,  43..48 and
    50..53 define one line of the display matrix. The first entries of
    the first  four groups  are labels  which are used  to display the
    name of the computer.  They refer to icon number one (desktop.gif)
    but icons are only visible in the html file. The label of the last
    group is blank  (note the empty string "",  which is necessary for
    syntactic reasons),  followed by a number  refering to icon number
    two (router.gif).  On the local screen the correspondig place will
    be blank but in the html view the icon will be shown.

    The second entry in each group  (shown in the second column of the
    display matrix) refers to PTEST 1, the ping test.  The third entry
    of the first four groups refer to BTEST 1, the "net view". Each of
    them depend on a host entry named "ping".  As these references are
    resolved in such a way, that always the most recently defined HOST
    of that name is taken,  they all refer to  their respective hosts.
    Depending means,  that the "net view" test will not be carried out
    if the previous ping test was not successfull. The last entries of
    the first four groups refer to PTEST 2, the "type" test.  They de-
    pend in-turn on the respective "net view" tests.

    The third entry of the last group (in line 52) is an ordinary ping
    but to some known address in the internet.  It depends on the rou-
    ter, assuming a dial-in router.  If the ping from line 52 succeeds
    the conection to the internet is established.

    Replacing the ping in line 19 of example #2  by a program that ad-
    dresses the IPX-diagnostic responder (aka ipx-ping) and "net view"
    in line 18  by "net slist"  would allow  to use  the set-up  under
    Novell's netware light running on-top of IPX.  It is even possible
    to define both test-agents in the same set-up  (up to nine are al-
    lowed)  to use LANSTAT in a heterogenious network  running IPX and
    TCP/IP in parallel.

Example #3 (WEB monitoring)

    1:           ; The linenumbers at the leftmost margin are only for
    2:           ; reference they are not part of the actual inifile
    3:           ;
    4:           HEAD
    5:           HEAD    "                       Last update:  \t \d "
    6:           HEAD
    7:          
    8:           LOGFILE ".\LANSTAT.LOG" 2
    9:           COLS    3  3  COLOR  BOX
    10:          MARGIN  2  5  1  "WEBTEST.WPR"
    11:          DELAY   60 3  FASTINI
    12:         
    13:          GTEST   "\\wattcp\\ping 0.0.0.0"  "Unable to resolve"
    14:          PTEST   "\\wattcp\\ping \a"       "Average RTT"
    15:          PTEST   "ntool -s \qHEAD / HTTP/1.0\\r\\n\\r\\n\q \a:80"
    15 (cont):                                              "HTTP" "Server"
    16:         
    17:          PAGE    HIDE
    18:          HOST    "router" 1 "192.168.0.254"
    19:          
    20:          PAGE
    21:          LABEL   " "
    22:          HOST    "DNS" 1 "192.76.144.66"
    23:          DEPENDS ON "router"
    24:          ALIAS   "ROUTER" IS "router"
    25:         
    26:          LABEL   "Google"
    27:          HOST    "Ping" 1 "www.google.de"
    28:          DEPENDS ON "DNS"
    29:          HOST    "Http" 2 "www.google.de"
    30:          DEPENDS ON "Ping"
    31:         
    32:          LABEL   "Wikipedia"
    33:          HOST    "Ping" 1 "www.wikipedia.de"
    34:          DEPENDS ON "DNS"
    35:          HOST    "Http" 2 "www.wikipedia.de"
    36:          DEPENDS ON "Ping"
    37:         
    38:          LABEL   "Bttr-Soft"
    39:          HOST    "Ping" 1 "www.bttr-software.de"
    40:          DEPENDS ON "DNS"
    41:          HOST    "Http" 2 "www.bttr-software.de"
    42:          DEPENDS ON "Ping"

    This set-up monitors the accessability of three http servers some-
    where out there in the WEB by invoking utilities which in-turn use
    the WATTCP library. It is an example of what LANSTAT can do beyond
    pinging some host  in a LAN.  Lines one to nine  don't differ much
    from  the previous example.  Line ten  specifies a  wallpaper file
    which is not shown here. It only has some graphic characters draw-
    ing lines and arrows between the different boxes on the display to
    visualize the dependencies.  Line elven specifies a relativly long
    cycle delay of 60 seconds,  but the keyword FASTINI  disables this
    delay during the first four polling cycles.

    Line 13 specifies a ping to address 0.0.0.0 as global test (GTEST)
    and expects to find the text "Unable to resolve"  in the response.
    Even though this message seems to be "bad news",  it actually is a
    success  at this point,  as it means  that no other error occured,
    especially it did not complain about a missing packet driver or an
    unaccessable configuration file (WATTCP.CFG). If the expected mes-
    sage cannot be found  LANSTAT will abort.  Note that literal back-
    slashes must be duplicated in *TEST statements.

    Line 14 defines the ping utility  (in this case the one that comes
    with the wattcp package)  as test agent  and line 15 defines a se-
    cond test agent  it is broken into two lines to fit into this text
    but it must actually be written in one line.  The program ntool is
    a netcat clone and it can be downloaded from the same server where
    LANSTAT can be found.  It is configured  to issue an http HEAD re-
    quest to port 80 of an address which is passed as individual argu-
    ment. This way LANSTAT can not only check, whether a specific host
    is pingable but also verify the availability of a certain service.
    It may appear a bit confusing that some of the backslashes follow-
    ing the "-s" are duplicated while others are not,  but this is due
    to the fact that some of thoses seqences  are to be interpreted by
    LANSTAT itself  while others  are passed to  ntool and interpreted
    only there. The "\q" is turned into a double quote  while "\\n" is
    actually  a "\\"  followed by a plain "n".  Effectively ntool will
    see something like: -s "HEAD / HTTP/1.0\r\n\r\n".

    Line 17 defines the first page as hidden and line 18 places a sin-
    gle host "router" (in small letters) in that page. 

    Lines 20..24 define a blank label,  a host "DNS"  and a third ele-
    ment, an alias ROUTER (in capital letters) which references router
    (in small letters).  These three items  will all be placed  on one
    line of the three-columns display grid. The problem is, that "DNS"
    depends on the router,  which is placed for  graphical  reasons to
    the right of it.  This in-turn requires  the router  to be defined
    further below in the inifile, which conflicts with the dependency.
    To resolve this conflict,  the "real" router is placed in the hid-
    den first page,  allowing to resolve  the dependency of "DNS"  but
    the display of the router is implemted by an ALIAS  which also re-
    ferences the real router.

    The remaining lines are rather straight forward  just the chain of
    dependencies may be worth noting. The host "DNS" depends on router
    therefore its test  will only be carried out,  if the test for the
    router was successful  as it appears pointless to try to access an
    address on the internet  if the gateway is not operational.  Assu-
    ming that DNS  points to the defined nameserver,  all three "ping"
    hosts depend in-turn on DNS. This was done as WATTCP's ping utili-
    ty is unable to reslve names like "www.google.de" if the name ser-
    ver is not availabel.  The http hosts  in-turn depend  on the ping
    hosts,  as it doesn't make sense  to connect to a  tcp-port if the
    server isn't even pingable. 

    With a few modifications the same set-up can be used  with Michael
    Brutman's MTCP programs.  Just replace lines 13..15  of example #3
    by the following lines:

    13:          gtest "\\mtcp\\ping -count 1 0.0.0.0"  "imeout"
    14:          ptest "\\mtcp\\ping -count 1 \a"       "Average" 
    15:          ptest "invoke /D \\mtcp\\nc -target \a 80 -w 3
    15 (cont):                             < head.req" "HTTP" "Server"

    The file head.req  which is piped into nc is a simple text file of
    one line:   "HEAD / HTTP1.0"   followed by a blank line.  In other
    words it ends with two pairs of <CR><LF> characters. Unfortunately
    Mike's incarnation of netcat  does not at all fullfill requirement
    number 2 (see above), rather it writes loads of messages to stderr
    totally messing-up LANSTATs display area. The little helper utili-
    ty "invoke /D" cures that problem.



    Version history: Version 1.2 was the first published version.

    The keywords ALIAS, BOX and FASTINI were only introduced in versi-
    on 1.3  and were not available  in prior versions  as well as  the
    ability to manually trigger  a polling cycle  by hitting <RETURN>.
    The activity display was extended from one to two lines.

    Version 1.6 added the logging feature, the ability to define indi-
    vidual column layouts for different display pages,  the ability to
    define a display background ("wallpapaer") and a number of improv-
    ments for various details.

    Version 1.7  added the possibility  to produce several html files,
    one for  each display page  and the ability  to switch to  VGA/EGA
    mode.

    Version 1.8 fixed a bug in the generation of html files.

    Version 1.9   introduced the vertical scrolling  of the LAN status
    display area, which was not available in prior versions.



    Jrgen Hoffmann   (2010)   j_hoff@hrz1.hrz.tu-darmstadt.de


