* C:\DOC\WHATNOW.DOC ***** 9 FEB 94 *** 9:21 **************; G W Robinson


                   R A L   I B M   P C   U S E R   G U I D E
                   -----------------------------------------

                       WHATNOW BAT file decision router
                       --------------------------------



      1. Introduction
      ===============

      WHATNOW is a program that can be used to display a message,
      analyse the one character response and then terminate with an
      appropriate ERRORLEVEL setting. It can thus be used in a BAT file
      to ask a question and by testing the ERRORLEVEL after the reply can
      take the appropriate action.

      2. Program Specification
      ========================

      Whatnow v1.0 format is:

        whatnow /options wait_secs legal_reply_chars default_reply message

      Whatnow displays the message and waits wait_secs for a reply which
      must be one from legal_reply_chars or an Enter which implies the
      default_reply.  After wait_secs the default reply is also assumed.
      Whatnow then exits with an ERRORLEVEL dependent on the position of
      the reply in the legal_reply_chars list starting at 1.  If the
      whatnow call is illegal an ERRORLEVEL of 0 is returned.  If the
      user presses Ctrl C or Break and replies N to the "Terminate batch
      job (Y/N)?" message put out by DOS then the ERRORLEVEL is 0.  If
      insufficient parameters are given then the values shown in the
      first example below are used by default.

      Possible options are:
        ?  Give this help information
        h  Give this help information
        t  Display seconds remaining on count down


      3. Testing ERRORLEVEL
      =====================

      The Environment variable ERRORLEVEL is optionally set by a program
      when it terminates.  It is an eight bit unsigned integer so has a
      range of 0 to 255.  Most software returns a value of 0 for success
      and 1 for a failure of some form.  Some software is documented as
      exiting with a negative value (eg.  -1) and this simply maps to the
      unsigned eight bit equivalent.  Thus -1 is actually 255, -2 is 254
      etc.

      It should be noted that the IF ERRORLEVEL command in a BAT file
      obeys the command if ERRORLEVEL is >= to the number given.  Thus
      the command:

        IF ERRORLEVEL 2 GOTO END

      would goto label :END for ERRORLEVEL values of 2 upwards.

      Similarily IF NOT ERRORLEVEL obeys the command if ERRORLEVEL is <
      the number given.  Thus:

        IF NOT ERRORLEVEL 2 GOTO END

      would goto label :END for ERRORLEVEL values of 0 and 1.

      In general fewer logic errors are likely to be made if ERRORLEVEL
      values are tested in descending order.


      4. Examples
      ===========

        whatnow 30 yn y Do you wish to continue?
        IF ERRORLEVEL 2 GOTO END
        IF ERRORLEVEL 1 GOTO DOIT
        GOTO END
        :DOIT
        ... next actions to do ....
        :END

      This would be used to get a y/n decision as to whether the next
      course of action was to be done.  A reply of y gives ERRORLEVEL 1,
      n gives 2, the default is y and this is assumed after 30 seconds or
      Enter being pressed.  The reply n causes the next part of the BAT
      file to be jumped round as does pressing the Break key and
      continuing with the BAT file (ERRORLEVEL 0).  Only a reply of y
      causes the next actions to be done.  A call of whatnow without some
      or all of its parameters defaults to the values of this example.


        whatnow /t 20 1234 2 Please select a menu entry:
        IF ERRORLEVEL 4 GOTO 4MENU
        IF ERRORLEVEL 3 GOTO 3MENU
        IF ERRORLEVEL 2 GOTO 2MENU
        IF ERRORLEVEL 1 GOTO 1MENU
        GOTO END
        :1MENU
        .. do menu 1 action ..
        GOTO END
        :2MENU
        .. do menu 2 action ..
        GOTO END
        :3MENU
        .. etc

      This example assumes the BAT file displayed some form of numbered
      menu containing four choices.  The whatnow call gives 20 seconds to
      respond and the time remaining is displayed because of the /t
      option.  A reply of 1 gives ERRORLEVEL 1, 2 gives 2 etc, and the
      default is 2.  The ERRORLEVEL checking jumps to the correct
      actions or label END if an error occurs or the users presses Break
      and does not terminate the batch job.


      5. Support
      ==========

      WHATNOW is supplied free and is supported for all users at RAL
      registered with CISD PC Support.

      Users outside RAL are requested in the first instance to obtain
      copies and help from their normal support sources.

      Academic user support organisations may seek help from RAL but the
      latter will only be given on a 'best endeavours' basis.

      There is no support for other organisations other than by private
      arrangement with the author.

      Updates of the software may be obtained by anonymous FTP from
      FTP.CC.RL.AC.UK (currently 130.246.12.16).  It is held in a self
      extracting binary file WHATNxx.EXE (xx being version number without
      a point - currently 10) in directory /pub/pcsupp/dos/whatnow.
      Executing the file will produce the program and documentation.

      Bug reports or problems should be reported, ideally by email, to
      Graham Robinson:

      E-mail: Graham.Robinson@rl.ac.uk   G W Robinson
      Tel UK: 01235 44 5636              Rutherford Appleton Laboratory
      Int'l : +44 1235 44 5636           Chilton, Didcot
      Fax   : 01235 44 5281              Oxon, OX11 0QX, UK

