
                                   Yukon Ho!

                               -=* Y I N F *=-

                                  Version 1.0

                       Copyright (C) 1994-8 Mark Kerr
                        Documentation by Edward Hobson
                              All rights reserved

                           THIS SOFTWARE IS FREEWARE

       Please read the licensing agreement before running this software!

 ==============================================================================
 SOFTWARE PURPOSE
 ==============================================================================

 When running a multi-line FrontDoor system it is important, when
 planning maintenance events, to ensure that all lines are frozen from
 accepting incoming calls, during critical system updates. Using
 conventional methods this requires a reasonable amount of editing and
 updating each time you add a new line to the system, or change the line
 which actually performs the maintenance. It also means that if, for
 some reason, a task is closed down either accidentally or due to a
 problem, your maintenance routines may hang indefinitely.

 YINF changes all this. It takes care of freezing all active tasks,
 and only returns with a success code once all lines have frozen. If it
 is unable to force the lines to freeze during a given period, it
 returns a failure code. The 'active' lines are denoted by creating
 semaphore files in the format <task>.FRZ in your semaphore directory.
 For example, if you run FrontDoor on tasks 1, 2 and 3, your maintenance
 can only occur when all three lines are frozen. (Note that the line
 from which YINF is run may be one of these, or may be totally
 separate.) For each 'active' line, you create a semaphore, so files
 1.FRZ, 2.FRZ and 3.FRZ should be present in your semaphore directory.
 When run, YINF waits until FrontDoor acknowledges that all three are
 frozen before reporting a success. '.FRZ' files should not be created
 for tasks on which only FrontDoor's editor is used (ie tasks on which
 the Mailer part of FrontDoor is not active under normal circumstances).
 In addition YINF also checks for other relevant activities such as FM
 and FDNC before reporting a success.

 Once YINF has reported a successful freeze, your maintenance can
 progress as normal. Once complete, YINF's '/H' command should be used
 to thaw the frozen lines, in order to allow them accept calls, process
 mail etc. If for some reason YINF is unable to freeze the selected
 lines after the given time (a line may have crashed or hung for some
 reason), it will automatically re-thaw all lines. YINF also optionally
 throws users off associated RemoteAccess lines if it is trying to freeze.

 YINF also has a graphical front end that allows monitoring of all
 tasks 0-255, and individual tasks in detail. Some degree of control
 and extra functions are also available whilst in this mode ALT-H will
 show a help screen listing all available functions many of which
 emulate those found in FD itself.

 For instance fully supports FD mailer function key syntax re error level 
 exits, ie ?190;2 generates an FDXIT2.190 in the semaphore directory etc.

 NOTE! It is vital that all active lines have their TASK environment
 variable set to the respective node number, such that RemoteAccess and
 FrontDoor generate and respond to their individual semaphore files. In
 order to operate, YINF checks that the TASK and FD environment
 variables have been set.

 YINF detects various multi-taskers and releases idle time accordingly.
 During operation, YINF displays an activity screen and can log activity
 to a FrontDoor format text-file. The period of time to wait, and the
 remaining time are displayed on the screen whilst YINF is active in
 'freeze'mode.

 On termination, YINF exits with one of the following errorlevels:

 Value  Description of fault
 -----  ------------------------------------------------------------
 40     Failure to freeze all lines.
 20     Semaphores removed succesfully after /H 'thaw' option.
 10     All lines frozen after /F commandline.
  3     Fatal Error
  2     Normal exit due to keypress.
  1     File not found.
  0     Help screen displayed.


 YINF recognises the following semaphores:

 *.FRZ
 FDALIVE.*
 FDFROZEN.*
 FDINSESS.*
 FMALIVE.*
 FMFROZEN.*
 FDNODE*.*
 BATCH.*
 MAIL.*
 FILES.*
 RAREADY.*
 RABUSY.*
 YFREEZE.*
 YINF.nnn
 FMNEWCNF.*

 Where * represents the task number of the program generating the semaphore and
 nnn is an errorlevel to exit with to process mail.

 Three special cases are BATCH.*, MAIL.*, and FILES.*. If you
 wish to use these YINF will report the task as being in:

 BATCH.* In batch process
 MAIL.*  Mail processing
 FILES.* File processing

 It is up to you to create and destroy these at the appropriate points in the
 batchfile. WARNING failure to remove these could cause YFREEZE to refuse to
 accept a node as being frozen.

 The basic premise of YINF is that the newest semaphore reflects the current
 status of a task. Where this doesn't apply is in the case of FDALIVE.*.
 The current behaviour of FD is that no matter what other semaphores FD has
 created FDALIVE.* is continually touched. However FDINSESS.* and FDFROZEN.*
 should be displayed correctly.

 YINF defaults to displating any FDALIVE.* more than 90 seconds old in RED as
 opposed to yellow. This can be overridden by the /T= commandline switch.

 Information on the display can found by pressing Alt-H whilst running YINF.
 ESC will exit from this help screen.


 ==============================================================================
 COMMAND-LINE OPERATION
 ==============================================================================

 YINF supports the following command-line parameters:

 /A=<path to alternate SETUP.FD> {optional}

        This allows the user to overide the use of the environment variable
        FD for details on the setup and paths in FD by specifying an
        alternate location. The path should NOT finish with \SETUP.FD
        this will be appended internally.

 /B {optional}

        Produces a textfile called YINFSTAT.TXT in the current
        directory giving details of all relevant? semafores found.

 /C=<Age in seconds of fmnewCnf.* before exit>

       /C=nnn Sets the age required in FMNEWCNF.* before exiting with an
       errorlevel specified in /S=. Defaults to 15 minutes.
       /X= and /S= must also both be specified..

 /E=(task to exit for mail)


 /F {optional}

        Creates FD & FM FREEZE.ALL plus FDNLFREZ.ALL

 /F=<timeout period in seconds or 0 for no timeout> {optional}

        This defines the length of time which YINF waits for the
        selected lines to freeze. If set to zero, YINF waits
        indefinitely. The zero setting should be used with care! If this
        option is not specified, a default timeout period of 600 seconds
        is used. If YINF is unable to freeze the selected lines after
        the given timeout period, it will exit with an errorlevel of 98.
        If it is successful, YINF will exit with an errorlevel of 0.

 /H {optional}

        Removes the semaphores created by /F.

 /R=nnn {optional}

        Where nnn is the errorlevel to tell RA to exit with.

 /S=<errorlevel when exiting to scan> {requires /X}

       /S=nnn Sets the errorlevel to exit with if an FMNEWCNF.* older than
       15 mins is found in the semafore directory. As below nnn must be
       between 100 and 255 inclusive, will only work in conjunction with /X.
       This may be overridden with the /C= commandline option below..

 /T=<warning timeout period in seconds> {optional}

       This defines the length of time which YINF waits for the for the
       FDALIVE.TASKno semaphore to be upated before changing the flag
       from yellow to red. Default is 90 seconds
      
 /L=<path to and name of ASCII log file> {optional}

        This defines the location and name of the FrontDoor-style
        activity log which YINF maintains when using /F or /H.
        If this option is not specified, logging is disabled.
        See also the '/F' parameter.

 /X {optional}

        enables exit with errorlevel to process mail.

 /? {on its own}

        Display list of command-line switches.

 ==============================================================================
 EXAMPLE COMMAND-LINE USAGE
 ==============================================================================

 YINF  /L=C:\LOGS\YFRZ%TASK%.LOG /F=120

        This example would tell YINF to look in the defined semaphore
        directory for its .FRZ files, and to create FDFREEZE.ALL
        there too. For TASK 1 the activity log would be written to a file
        called YFRZ1.LOG in the C:\LOGS directory. The timeout period
        is 120 seconds.

 YINF  /H

        This example might be used after a maintenance procedure, in
        order to thaw all previously frozen lines.


 Example batch-file:

        :START
        REM>C:\SEMAFORE\%TASK%.FRZ

        ... BBS routines etc.

        :MAINTENANCE
        YINF /F /L=C:\LOGS\YFRZ%TASK%.LOG
        IF ERRORLEVEL 40 GOTO START
        CD\FD
        FDNC /F
        CD\RA
        RANODE
        YINF /L=C:\LOGS\YFRZ%TASK%.LOG /H
        GOTO START

        ... Other labels and procedures

        :END
        DEL C:\SEMAFORE\%TASK%.FRZ

 ==============================================================================
 SOFTWARE SUPPORT
 ==============================================================================

 Please address any problems or suggestions to Mark Kerr via NetMail to
 Yukon Ho! BBS, FidoNet 2:443/59 and 2:443/60.

 ==============================================================================
 RELATED SOFTWARE
 ==============================================================================

 FrontDoor is Copyright (C) Joaquim Homrighausen and Definite Solutions HB
 RemoteAccess is Copyright (C) Bruce Morse

 "This product uses the SPAWNO routines by Ralf Brown
  to minimize memory use while shelling to DOS and
  running other programs."

 Also using routines developed by Colin Turner and Chris McCandless (thanks
 guys).

 ==============================================================================
 DEVELOPMENT HISTORY
 ==============================================================================

 Version 1.0:  First version.

 ==============================================================================
 TO DO LIST
 ==============================================================================

 Mail signal (improve)
 Logging (improve)
 Netmail support (add)
 Static Queue support (add)
 Activity Monitor (add)

