home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / UTILITY / WATDG121.ZIP / WATCHDOG.DOC < prev   
Text File  |  1992-10-31  |  19KB  |  506 lines
  1.                               WatchDog v.1.21
  2.                      (c) 1992 Ernest Vogelsinger (ASP)
  3.  
  4. Index
  5. -----
  6.    Package Contents . . . . . . . . . . . . . . . . . 1
  7.    General Description  . . . . . . . . . . . . . . . 1
  8.    Main Features of WatchDog  . . . . . . . . . . . . 2
  9.    How to use WatchDog  . . . . . . . . . . . . . . . 2
  10.    WatchDog Command Line  . . . . . . . . . . . . . . 4
  11.    Built-In Default Values  . . . . . . . . . . . . . 6
  12.    The Multiplexer Interface  . . . . . . . . . . . . 6
  13.    Booting The Machine  . . . . . . . . . . . . . . . 6
  14.    Modem Hang Up  . . . . . . . . . . . . . . . . . . 7
  15.    Delayed Boot . . . . . . . . . . . . . . . . . . . 7 
  16.    The Legal Department . . . . . . . . . . . . . . . 7 
  17.    Zero-Registration Shareware, Distribution Policy . 8
  18.    WatchDog Source Code . . . . . . . . . . . . . . . 8 
  19.    Contacting The Author  . . . . . . . . . . . . . . 8
  20.    ASP Ombudsman Statement  . . . . . . . . . . . . . 8
  21.  
  22.  
  23. Package Contents
  24. ----------------
  25.  
  26. The WTCHDG.ZIP archive contains the following files:
  27.    o WATCHDOG.COM    the WatchDog program
  28.    o READ.ME         you're currently reading this file, thank you!
  29.    o FILE_ID.DIZ     description for automatic extraction by BBS'es
  30.    o DESC.SDI        description for automatic extraction by BBS'es
  31.    o ASP.DOC         ASP Ombudsman Statement
  32.  
  33.  
  34. General Description
  35. -------------------
  36.  
  37.    WatchDog is a resident utility program monitoring the activity status of
  38.    a COM port (carrier) and DOS (Dos and Kbd calls).
  39.  
  40.    Its main use is with remote BBS software that hands control to e.g. a
  41.    shell program. When the shell program hangs (Dos watch) or carrier loss
  42.    is detected (COM watch) the serial port DTR is dropped (hangup) and the
  43.    machine is rebooted.
  44.  
  45. VERSION 1.20
  46.    By popular demand, a ring count watch has been added. This is to allow
  47.    reboot when the BBS program fails to go off-hook, by what reason ever.
  48.    The ring watch can be customized to any needed ring count and can also
  49.    be disabled.
  50.    After a certain time without a ring indicated by the modem, WatchDog will
  51.    assume ringing has stopped, and reset the ring counter. This no-ring time
  52.    can also be customized.
  53.  
  54. VERSION 1.21
  55.    The ability to specify a custom COM port address has been added to
  56.    support non-DOS serial ports.
  57.    The /NORing default value (see below) has been set to 8 seconds.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64. ----- WatchDog ---------------------------------------------- Page 1 of 8 ---
  65.  
  66.  
  67. Main Features of WatchDog
  68. -------------------------
  69.  
  70.    o Needs only 800 bytes of memory.
  71.    o Can be activated, deactivated, and reconfigured as often as needed,
  72.      and it can also be unloaded.
  73.    o Monitoring is lightning fast so no data loss should occur with
  74.      high speed serial communications.
  75.    o Detects carrier loss by monitoring COM 1, 2, 3 or 4, or on a
  76.      user-defined port address.
  77.      The COM port can be selected from the command line, or carrier monitor
  78.      can be completely switched off.
  79.    o Built-in ring counter to reboot when the BBS fails to go off-hook.
  80.      Reboot counter can freely be specified or disabled.
  81.    o Detects a hanging program by monitoring "DOS" activity.
  82.      WatchDog accepts Int16 (keyboard), Int21 (DOS), and Int28 (DOS Idle)
  83.      as "DOS" activity. The "DOS" timeout seconds can be selected from the
  84.      command line, or "DOS" monitoring can be completely switched off.
  85.    o The reboot method can be selected from "Bios" (the usual jump to
  86.      bios location FFFF:0), and "Hardware", where the CPU is rebooted
  87.      via a command to the keyboard controller. This is often necessary with
  88.      protected mode DOS extenders.
  89.    o Reboot can be delayed to allow lazy write cache programs write their
  90.      data back. The delay time can be selected from the command line.
  91.  
  92.    WatchDog can be tailored to meet individual requirements with command
  93.    line arguments. It may be executed multiple times, without being
  94.    reloaded. A secondary copy always modifies the settings of the resident
  95.    watchdog.
  96.  
  97.  
  98. How to use WatchDog
  99. -------------------
  100.  
  101.    Most BBS software is started through a batch file. Assume the following
  102.    batch file (used to start the WildCat! BBS):
  103.  
  104.    REM ----- WILDCAT BBS BATCH FILE -----
  105.       @echo off
  106.  
  107.       :reload
  108.       cd \wildcat
  109.       wildcat
  110.  
  111.       if errorlevel 50 goto door
  112.       if errorlevel 41 goto reload
  113.       if errorlevel 40 goto dropdos
  114.       if errorlevel  2 goto event_a
  115.       if errorlevel  1 goto reload
  116.       goto end
  117.  
  118.       :door
  119.       call door
  120.       goto reload
  121.  
  122.       :dropdos
  123.       call dropdos
  124.       goto reload
  125.  
  126.  
  127. ----- WatchDog ---------------------------------------------- Page 2 of 8 ---
  128.  
  129.  
  130.       :event_a
  131.       call online_game
  132.       goto reload
  133.  
  134.       :end
  135.    REM ----- END WILDCAT BBS BATCH FILE -----
  136.  
  137.    While the BBS software is monitoring for carrier loss, doors, DOS shell,
  138.    and other miscellaneous programs (e.g. the game batch as above) can't.
  139.    Thus, if the caller hangs up while in a DOS shell, a door not supporting
  140.    carrier monitor, or in another program (e.g. online games), the BBS
  141.    software would never get control again, and couldn't service the next
  142.    caller.
  143.  
  144.    This is where WatchDog comes in. In all cases mentioned above you would
  145.    want to reboot the BBS computer, since your AUTOEXEC batch will reload
  146.    the BBS software. On the other hand, it should NOT reboot if the BBS
  147.    program is active, or when no carrier is to be expected (e.g. when
  148.    starting or leaving the BBS batch file).
  149.  
  150.    Here comes the same batch file again. WatchDog commands are added to
  151.    explain how to use it.
  152.  
  153.    REM ----- WILDCAT BBS BATCH FILE -----
  154.       @echo off
  155.  
  156.       REM First time execution will load WatchDog resident
  157.       REM Parameters:
  158.       REM   COM=2          The modem is connected to COM2
  159.       REM
  160.       REM Keep the defaults for all other settings
  161.       REM (see below for default values)
  162.       watchdog /com=2
  163.  
  164.       :reload
  165.  
  166.       REM Since the batch file loop will enter here again, we need to
  167.       REM switch carrier monitoring off before (re)entering the BBS
  168.       REM Parameters
  169.       REM   CARRIER=OFF    Switch off carrier monitor
  170.       REM   QUIET          Suppress copyright message
  171.       watchdog /carrier=off /quiet
  172.  
  173.       cd \wildcat
  174.       wildcat
  175.  
  176.       if errorlevel 50 goto door
  177.       if errorlevel 41 goto reload
  178.       if errorlevel 40 goto dropdos
  179.       if errorlevel  2 goto event_a
  180.       if errorlevel  1 goto reload
  181.       goto end
  182.  
  183.       :door
  184.       REM Let's assume the door program can't handle carrier detection
  185.       REM so we need to activate the carrier monitoring feature of WatchDog
  186.       REM before calling the door batch file
  187.       watchdog /carrier=on /quiet
  188.       call door
  189.  
  190. ----- WatchDog ---------------------------------------------- Page 3 of 8 ---
  191.  
  192.  
  193.       goto reload
  194.  
  195.       :dropdos
  196.       REM before dropping to DOS we need to activate carrier monitor
  197.       watchdog /carrier=on /quiet
  198.       call dropdos
  199.       goto reload
  200.  
  201.       :event_a
  202.       REM before entering the online game activate carrier monitor
  203.       watchdog /carrier=on /quiet
  204.       call online_game
  205.       goto reload
  206.  
  207.       :end
  208.       REM WildCat exits normally, so we unload the WatchDog TSR
  209.       watchdog /unload
  210.  
  211.    REM ----- END WILDCAT BBS BATCH FILE -----
  212.  
  213.  
  214. WatchDog Command Line
  215. ---------------------
  216.  
  217. You load (and reconfigure) WatchDog by specifying
  218.  
  219.    WATCHDOG [/option=value] ...
  220.  
  221. on the command line, or in a batch file.
  222.  
  223. WatchDog recognizes the following parameters:
  224.  
  225.    /COM=n
  226.       n  - A value between 0 and 4, specifying the COM port to monitor.
  227.            Specifying 0, or a non-existent port, will disable
  228.            carrier monitoring and ring counting.
  229.            NOTE: different to version 1.11, the /COM parameter doesn't
  230.                  enable or disable carrier watch, since the ring count
  231.                  feature has been added. To enable or disable carrier
  232.                  monitoring, use the following parameter.
  233.  
  234. ** 1.21 NEW **
  235.    /PORT=hhhh
  236.       hhhh - A hexadecimal value specifying the COM port address.
  237.            If the COM port is on a nonstandard address (and therefore not
  238.            available as COM1-COM4) you can define the actual port address
  239.            to use.
  240.  
  241.    /CARRIER=ss
  242.       ss - A string specifying carrier monitoring activity. You may specify
  243.            ON  - enable carrier monitor
  244.            OFF - disable arrier monitor
  245.  
  246.    /DOS=nn
  247.       nn - A value between 0 and 65535, specifying the number of seconds
  248.            that DOS may be inactive before WatchDog reboots.
  249.            Specifying 0 will disable DOS monitoring.
  250.  
  251.  
  252.  
  253. ----- WatchDog ---------------------------------------------- Page 4 of 8 ---
  254.  
  255.  
  256.    /RING=nn
  257.       nn - A value between 0 and 65535, specifying the number of rings that
  258.            will be allowed for rebooting.
  259.            Specifying 0 will disable the ring monitor.
  260.            NOTE: if the modem is online (carrier active), the ring monitor
  261.                  is automatically disabled, regardless of the carrier
  262.                  monitor status.
  263.  
  264.    /NORING=nn
  265.       nn - A value between 0 and 65535. After this time is elapsed without
  266.            a ring to occur, WatchDog determines that ringing has stopped,
  267.            and resets the ring counter.
  268.  
  269.    /MPX=xx
  270.       xx - A (hexadecimal) value between C0 and FF, specifying the ID byte
  271.            for the Multiplexer communication (see note on MPX below).
  272.            The default value is C0, or the first free ID byte found.
  273.  
  274.    /BOOT=ss
  275.       ss - A string specifying the boot method. You may specify
  276.            BIOS     - boot by passing control to the bios location FFFF:0
  277.            HARDWARE - boot by resetting the CPU via keyboard controller
  278.         or HW         (see note on booting below).
  279.  
  280.    /WAIT=nn
  281.       nn - A value between 0 and 65535, specifying the number of seconds
  282.            that WatchDog will wait for DOS to become idle before rebooting
  283.            (see note on delayed boot below).
  284.  
  285.    /DELAY=nn
  286.       nn - A value between 0 and 65535, specifying the number of seconds
  287.            that WatchDog will delay before rebooting (see note on delayed
  288.            boot below).
  289.  
  290.    /WATCH=ss
  291.       ss - A string specifying WatchDog activity. You may specify
  292.            ON  - enable WatchDog
  293.            OFF - disable WatchDog
  294.            This en- and disables the overall WatchDog activity. If either
  295.            carrier detect or DOS monitor is disabled, specifying ON will
  296.            not change these values.
  297.  
  298.    /UNLOAD
  299.            Unloads the resident WatchDog if possible. If another program
  300.            has hooked one of the interrupts WatchDog uses, it will display
  301.            a message and disable itself.
  302.  
  303.    /STATUS
  304.            Displays the current WatchDog status.
  305.  
  306.    /?, /HELP
  307.            Displays a descriptive help text.
  308.  
  309.    /DEFAULT
  310.            Displays the built-in default values.
  311.  
  312.    /QUIET
  313.            Suppresses all output messages.
  314.  
  315.  
  316. ----- WatchDog ---------------------------------------------- Page 5 of 8 ---
  317.  
  318.  
  319. Built-In Default Values
  320. -----------------------
  321.     COM      = COM1
  322.     PORT     = Dos value for COM1 (usually 3F8h)
  323.     DOS      = 60     1 minute allowed for DOS inactivity
  324.     CARRIER  = OFF    initially disabled since carrier is usually off
  325.                      at loading time
  326.     RING     = 6      reboot after 6 rings without going offhook
  327.     NORING   = 8      after 8 seconds without incoming ring it is assumed
  328.                      that ringing has stopped
  329.     MPX      = C0     see "Multiplexer Interface" below
  330.     BOOT     = BIOS   see "Booting the Machine" below
  331.     WAIT     = 5      Wait 5 seconds for DOS to become available
  332.     DELAY    = 5      Delay 5 seconds before booting
  333.     WATCH    = ON     Activate watchdog
  334.  
  335.  
  336. The Multiplexer Interface
  337. -------------------------
  338.  
  339. The Multiplexer interrupt (Int2F) is a mechanism for programs to communicate.
  340. WatchDog uses this mechanism to communicate between the transient program
  341. (the loader) and the (smaller) part that stays resident in memory.
  342.  
  343. The defined interface protocol is very simple. An ID byte is specified in
  344. the AH register, and the function code is put in the AL register. Then the
  345. interrupt is called. The ID bytes C0 .. FF are reserved for "user programs".
  346.  
  347. WatchDog tries to find a free ID value between C0 and FF and will use this.
  348. Sometimes it is necessary to avoid certain ID values to allow other programs
  349. that do not scan for a free byte to run. This is the reason why the Mpx ID
  350. can be specified on the command line. Usually you will not need to change
  351. this.
  352.  
  353.  
  354. Booting The Machine
  355. -------------------
  356.  
  357. Generally, there are two ways to reboot a (DOS) computer via software. The
  358. method used most is to pass control to the code at FFFF:0. While this works
  359. in most cases where "DOS only" is loaded, it might cause problems with
  360. certain types of protected mode DOS extender software. The machine might
  361. endlessly hang, and not reboot. One example I personally know is Soft-ICE,
  362. a protected mode debugger software. I have heard rumours that QEMM or EMM386
  363. might react similar in some cases.
  364.  
  365. If you encounter that problem, add /BOOT=HW to the command line to enable
  366. hardware CPU reset.
  367.  
  368. WatchDog resets the CPU by sending a special command to the keyboard
  369. controller. The keyboard controller (port 64h) understands a lot of commands.
  370. The command we need here is Fx, that pulses bits of the output port low
  371. for 6 µs. Bits 0-3 of command indicate which bits should be pulsed:
  372. 0=pulse, 1=don't pulse. Pulsing bit 0 (command FE) results in CPU reset
  373. since it is connected to system reset line.
  374.  
  375. There are some PS/2 computers where this method will not work (I believe
  376. it's PS/2 model 80).
  377.  
  378.  
  379. ----- WatchDog ---------------------------------------------- Page 6 of 8 ---
  380.  
  381.  
  382. Modem Hang Up
  383. -------------
  384.  
  385. If a COM port is specified, and WatchDog is about to reboot, it drops
  386. the DTR (Data Terminal Ready) and RTS (Ready To Send) lines on the modem,
  387. causing the modem to hang up and the serial port to be reset.
  388. While this might not be necessary with carrier loss, it is a must if reboot
  389. is caused by DOS timeout.
  390.  
  391.  
  392. Delayed Boot
  393. ------------
  394.  
  395. A very special feature is WatchDogs Delayed Boot opportunity.
  396. Whenever you're using a lazy-write cache program (like SMARTDRV etc) you'll
  397. loose data when rebooting, if the cache software couldn't finish writing
  398. your data back.
  399.  
  400. The first thing WatchDog does after resetting the modem is to wait for DOS
  401. to become available. Since the cache software needs DOS to write the data
  402. to disk, it will not do disk writes if DOS is busy. The time how long
  403. WatchDog should wait for DOS to become available is specified with the
  404. /WAIT=nn command line parameter.
  405.  
  406. After DOS is available, WatchDog waits for the time specified in the
  407. /DELAY=nn parameter. While waiting, it repeatedly issues Int28, thus
  408. pretending that DOS is idle on the command line.
  409.  
  410. Both actions together (wait for DOS to become available, and then loop for
  411. a couple of seconds) allows lazy write caches to finish their write activity.
  412.  
  413. However, if DOS will not become available (e.g. if some DOS structure has
  414. been corrupted, and DOS itself is hanging), WatchDog will reboot the machine
  415. without being able to give time to background programs. In these cases,
  416. data loss will occur and cannot be avoided.
  417.  
  418.  
  419. The Legal Department
  420. --------------------
  421.  
  422. Users of WatchDog must accept the following disclaimer of warranty:
  423.  
  424. THIS COPYRIGHTED SOFTWARE AND ITS DOCUMENTATION IS PROVIDED ON AN "AS IS"
  425. BASIS. THE AUTHOR MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED,
  426. INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY AND/OR
  427. FITNESS FOR A PARTICULAR PURPOSE.
  428.  
  429. THE USER ASSUMES ALL RISKS OF THE USE OF THIS SOFTWARE. THE AUTHOR ASSUMES
  430. NO LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE
  431. USE OR MISUSE OF WATCHDOG.
  432.  
  433. As it cannot be guaranteed that loss of data will not occur, WatchDog should
  434. be tested with non-critical data. As always, judicious backups are a wise
  435. and necessary continuing precaution.
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442. ----- WatchDog ---------------------------------------------- Page 7 of 8 ---
  443.  
  444.  
  445. Zero-Registration Shareware, Distribution Policy
  446. ------------------------------------------------
  447.  
  448. Now that the necessary legal issues are out of the way:
  449.  
  450. WatchDog is a program I wrote because I was missing a lot of features in
  451. the watchdog program I have got (it was written in '84, and therefore
  452. heavily aged out).
  453.  
  454. WatchDog v.1.21 is "zero-registration" shareware. that means, you may use it
  455. freely, without notifying me or anyone else, and without paying one cent. I
  456. sincerely hope it will satisfy you.
  457.  
  458. You may freely distribute WatchDog, as long as the archive file remains
  459. unmodified. I expressly forbid to add any files, or any comments to the
  460. archive.
  461.  
  462.  
  463. WatchDog Source Code
  464. --------------------
  465.  
  466. The source code for WatchDog can be obtained by contacting me at the
  467. CompuServe address mentioned below. The fee for the source code is
  468. US$ 150.--. For more information, please contact me.
  469.  
  470.  
  471. Contacting The Author
  472. ---------------------
  473.  
  474. If you have questions or ideas for future enhancements of WatchDog, I'd be
  475. glad if you would contact me via CompuServe. Of course, I'll be happy if you
  476. just want to tell me the program works well.
  477.  
  478.    Ernest Vogelsinger
  479.    CIS 100015,551
  480.  
  481.  
  482. ASP Ombudsman Statement
  483. -----------------------
  484.  
  485.        This program  is produced by  a member of the Association
  486.        of Shareware Professionals (ASP).  ASP wants to make sure
  487.        that  the shareware principle  works for you.  If you are
  488.        unable to resolve a shareware-related problem with an ASP
  489.        member by contacting the member directly, ASP may be able
  490.        to help. The ASP Ombudsman can help you resolve a dispute
  491.        or problem  with an  ASP  member,  but  does not  provide
  492.        technical support for members' products.  Please write to
  493.  
  494.                        The ASP Ombudsman
  495.                        545 Grover Road, Muskegon
  496.                        MI 49442-9427
  497.                        
  498.        or send a Compuserve message via CompuServe Mail to
  499.  
  500.                        ASP Ombudsman 70007,3536
  501.  
  502.  
  503.  
  504.  
  505. ----- WatchDog ---------------------------------------------- Page 8 of 8 ---
  506.