home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast.iso / batutil / ask.doc < prev    next >
Text File  |  1994-03-04  |  8KB  |  299 lines
  1.                                        ASK
  2.  
  3.  
  4.       ASK - allows batch file to prompt user interactively
  5.  
  6.  
  7.       Syntax
  8.  
  9.       ASK [Options] [Prompt] [Expected response]
  10.  
  11.  
  12.       Parameters
  13.  
  14.       [Prompt] is the question to be displayed; it is a "quoted string"
  15.       (double quotes only).
  16.  
  17.       [Expected response] is a string of all the different characters
  18.       that the user may press in response to your question. If the user
  19.       press the first character in the [Expected response], the
  20.       errorlevel will be set to 1; if the user press the n-th character
  21.       in the [Expected response], the errorlevel will be set to n. If
  22.       the user pressed an invalid response, ASK will prompt him/her
  23.       again until she/he gets it right.
  24.  
  25.       By default, letters in the [Expected response] will match either
  26.       UPPER or lower case (i.e. case insensitive).
  27.  
  28.       If the [Expected response] string is not present, the errorlevel
  29.       will be set to the character code of whatever key the user
  30.       pressed. Normally lower case letters will be mapped to the upper
  31.       case counterpart, i.e. 'a' and 'A' will both return 65.
  32.  
  33.  
  34.       Options
  35.  
  36.       There are two options:
  37.  
  38.           /Q - be quiet, don't yell at the user for unexpected
  39.            response; but return 0 as the errorlevel. This option is
  40.            meaningless if there is no [Expected response].
  41.  
  42.           /C - make [Expected response] case sensitive. This means
  43.            letters typed by the user will match letters only in the
  44.            same case in [Expected response]. If there is no
  45.            [Expected response], then UPPER case letters will return
  46.            errorlevel 65-90, and lower case letters will return 97-
  47.            122.
  48.  
  49.       More than one option letter can share a common switch, like this:
  50.  
  51.           ask /QC "Blah Blah? "     or     ask/qc "Blah Blah? "
  52.  
  53.       You can also do this:
  54.  
  55.  
  56.                   - 1 -
  57.  
  58.  
  59.  
  60.  
  61.                                        ASK
  62.  
  63.  
  64.  
  65.           ask /c/q "Blah Blah ?"
  66.  
  67.       Option letters can be either upper or lower case.
  68.  
  69.  
  70.       Special Characters
  71.  
  72.       Characters that you normally cannot put on a command line (e.g.
  73.       carriage return, escape, backspace, ...) can be included in
  74.       either the [Prompt] or the [Expected response] by using either
  75.       one of the following conventions:
  76.  
  77.           ^nnn - translates to ASCII nnn where nnn is a 3-digit decimal
  78.              number. If this is not followed by another digit (that
  79.              you happen to want to appear in the prompt) then you
  80.              don't need to put all three digits down.  If it is
  81.              followed by a digit, then you have to put down all
  82.              three digits (add leading zeros if necessary).
  83.  
  84.           ^a  -  where a is anything except 0-9, ", and ^. This will
  85.              translates into the corresponding control character.
  86.  
  87.           ^^  -  the ^ (caret) character itself
  88.  
  89.           ^"  -  the double quote character. Without the caret it will
  90.              be interpreted as the beginning or the end of a quoted
  91.              string.
  92.  
  93.       Here are some examples:
  94.  
  95.           ask "How are ^"U^"?"
  96.  
  97.         - will produce    How are "U"?
  98.  
  99.  
  100.           ask "Hi?^7"    or
  101.           ask "Hi?^g"    or
  102.           ask "Hi?^G"    or
  103.           ask "Hi?^007"        (this has nothing to do with spies)
  104.  
  105.         - will produce    Hi?*BEEP*
  106.  
  107.  
  108.           ask "press Enter key when ready " ^m
  109.  
  110.         - will wait for the user to press the enter key
  111.  
  112.  
  113.           ask "1=egg  2=apple  3=orange^m^jSelect one? " 123
  114.  
  115.  
  116.                   - 2 -
  117.  
  118.  
  119.  
  120.  
  121.                                        ASK
  122.  
  123.  
  124.  
  125.         - will print "1=egg  2=apple  3=orange" on one line and
  126.           "Select one? " on another one because of ^m^j
  127.           (carriage return plus line feed).
  128.  
  129.  
  130.       Detailed Description
  131.  
  132.       ASK is a program to let batch files accept a one-character
  133.       response from a user.  This allows you to make simple yes-or-no
  134.       questions or menu-driven type questions.
  135.  
  136.       When testing errorlevel, be sure to test for the highest number
  137.       first because
  138.  
  139.           if errorlevel 5
  140.  
  141.       means
  142.  
  143.           if errorlevel equal to or greater than 5.
  144.  
  145.       For example, you can put the following in AUTOEXEC.BAT:
  146.  
  147.           echo off
  148.           ASK "Load ForKicks (Y/N)? " yn
  149.           if errorlevel 2 goto no
  150.           forkicks
  151.           :no
  152.           echo on
  153.  
  154.       When you boot the computer, you will see the following (minus the
  155.       frame):
  156.  
  157.           +-----------------------------------------+
  158.           | Load ForKicks (Y/N)? _            |
  159.           +-----------------------------------------+
  160.  
  161.       If you press 'y' or 'Y', the batch file will then execute the
  162.       program forkicks; if you press 'n' or 'N', you will return to DOS
  163.       without executing forkicks.
  164.  
  165.       Another use of ASK is to give the user a choice between different
  166.       versions of the same program. Let's say a new version of EDLIN
  167.       just arrived, you can name the old one EDLIN1 and name the new
  168.       one EDLIN2, and put the following in EDLIN.BAT:
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.                   - 3 -
  177.  
  178.  
  179.  
  180.  
  181.                                        ASK
  182.  
  183.  
  184.           echo off
  185.           echo 1) EDLIN old version
  186.           echo 2) EDLIN new version
  187.           echo   rem ** there's an Alt-255 character after the echo
  188.           ask "Choose one (press 1 or 2)? " 12
  189.           if errorlevel 2 goto two
  190.           echo on
  191.           edlin1 %1
  192.           goto end
  193.           :two
  194.           echo on
  195.           edlin2 %1
  196.           :end
  197.  
  198.       Now when a user type EDLIN, she/he will get this menu:
  199.  
  200.           +-----------------------------------------+
  201.           | 1) EDLIN old version            |
  202.           | 2) EDLIN new version            |
  203.           |                     |
  204.           | Choose one (press 1 or 2)? _        |
  205.           +-----------------------------------------+
  206.  
  207.       This way you wouldn't have to tell everybody that a new version
  208.       of EDLIN had been installed, and after a while people will learn
  209.       to type EDLIN1 or EDLIN2 to get to their favorite editor.
  210.  
  211.       The return key can be used as a valid response by including ^m in
  212.       [Expected response].    This can be used to provide default
  213.       response. For example
  214.  
  215.           echo off
  216.           ask "Should I do it or not (Y/N) [default Y]? " ^myn
  217.           rem ** errorlevel = 3 means n key
  218.           rem ** errorlevel = 2 means y key
  219.           rem ** errorlevel = 1 means return key
  220.           if errorlevel 3 goto no
  221.           DoIt
  222.           :no
  223.           echo on
  224.  
  225.       Now if the user press either 'y' or the enter key, the computer
  226.       will DoIt.
  227.  
  228.       Here is a trival use for ASK:
  229.  
  230.           ask "press any key when ready"
  231.  
  232.       This will emulate the 'pause' command in DOS.
  233.  
  234.  
  235.  
  236.                   - 4 -
  237.  
  238.  
  239.  
  240.  
  241.                                        ASK
  242.  
  243.  
  244.       If you supply the [Expected response] characters and the user
  245.       press something unexpected, ASK will automatically address the
  246.       user
  247.  
  248.           *BEEP* Unexpected response - try again
  249.  
  250.       and prompt the user again until he/she press a key that is in the
  251.       [Expected response].
  252.  
  253.       If you don't like this, you can set the /Q (quiet) option and
  254.       trap the unexpected response yourself (it will be errorlevel 0).
  255.       For example:
  256.  
  257.           echo off
  258.           :again
  259.           echo 1 - run hack
  260.           echo 2 - run baby
  261.           ask/q "Select one (1 or 2)? " 12
  262.           if errorlevel 2 goto baby
  263.           if errorlevel 1 goto hack
  264.           rem *** this must be errorlevel 0 ***
  265.           echo No, you must press either 1 or 2. Please try again.
  266.           goto again
  267.           :baby
  268.           baby
  269.           goto end
  270.           :hack
  271.           hack
  272.           :end
  273.           echo on
  274.  
  275.       Normally ASK will consider upper case and lower case letters
  276.       equivalent.  In some cases you might want to know whether the
  277.       user press a lower case letter or an upper case letter. You can
  278.       use the /C (case sensitive) option, like this:
  279.  
  280.           echo off
  281.           echo a - run apl
  282.           echo A - run APE
  283.           ask/c "Select one (a or A)? " aA
  284.           if errorlevel 2 goto ape
  285.           apl
  286.           goto end
  287.           :ape
  288.           APE
  289.           :end
  290.  
  291.  
  292.       Author
  293.  
  294.       Peter Wu
  295.  
  296.       UUCP: {akgua|allegra|harvard|ihnp4|seismo|topaz|ucbvax}
  297.                               !uwvax!uwmacc!pwu
  298.       ARPA: pwu@unix.macc.uwisc.edu or peter@gumby.uwisc.edu
  299.