home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / GETKO1.ZIP / GETKEY.DOC next >
Text File  |  1990-02-25  |  9KB  |  191 lines
  1.                            ████████████████████████
  2.                            ██                    ██
  3.                            ██   GETKEY for OS/2  ██                   
  4.                            ██                    ██
  5.                            ██    Version 1.00    ██
  6.                            ██                    ██
  7.                            ████████████████████████
  8.  
  9. ┌─────────────────────────────────────────────────────────────────────────────┐
  10. │ GENERAL                                                                     │
  11. └─────────────────────────────────────────────────────────────────────────────┘
  12.  
  13.     This program reports a user's keystroke as an ERRORLEVEL for use in batch 
  14. file programming.  The ERRORLEVEL equals the keystroke's ASCII code.  Syntax: 
  15.  
  16.  
  17.     GETKEY lh[..] [B] [C] [D] [E] [F] [H] [R] 
  18.  
  19.  
  20. where 'l' is the lowest valid keystroke & 'h' is the highest.  This string of 
  21. low and high values is called the 'mask.'  It may have as many character pairs 
  22. as needed, in a continuous string without spaces.  It must have an even number 
  23. of characters.  Optional arguments (separated with tabs or spaces) are: 
  24.  
  25.     B   Beep if the keystroke is invalid.
  26.  
  27.     C   Capitalize the keystroke before checking it against the mask.  This 
  28.         option also affects the ERRORLEVEL returned.  For example, if the 
  29.         operator presses 'a' with the C argument in effect, the ERRORLEVEL is 
  30.         65 (A) instead of 97 (a).
  31.  
  32.     D   Ignore ^Break and ^C (the default is to terminate the program)
  33.  
  34.     E   Echo the keystroke to the screen.  Not needed if you use R.  The
  35.         default is not to display the key pressed.
  36.  
  37.     F   Flush keyboard buffer before getting the keystroke.
  38.  
  39.     H   Hide cursor while waiting.
  40.  
  41.     R   Make the user press Return to enter the keystroke.   Always echoes the
  42.         keystroke to the screen.
  43.  
  44.     The program detects only keystrokes reported by OS/2.  For example, it 
  45. does not recognize Alt-Esc or Ctrl-Esc. 
  46.  
  47.    When writing batch files, remember to test for the HIGHEST possible 
  48. ERRORLEVEL first.  If you test for the lowest possible ERRORLEVEL first, ANY 
  49. keystroke will qualify, and the results are unpredictable. 
  50.  
  51. ┌─────────────────────────────────────────────────────────────────────────────┐
  52. │ EXAMPLES                                                                    │
  53. └─────────────────────────────────────────────────────────────────────────────┘
  54.  
  55. Example 1
  56.  
  57.     To have the user answer a yes-no question, use a sequence like: 
  58.  
  59.     GETKEY NNYY C E
  60.     IF ERRORLEVEL 89 GOTO YES
  61.     :Else answer was NO
  62.  
  63. These commands let the operator press only a N or Y.  The C option capitalizes 
  64. the keystroke in case a lower case letter is pressed; thus, a lower case 'y' 
  65. would be accepted.   If you want alphabetic input (i.e, a letter), we 
  66. recommend you always use an upper case mask and the 'C ' option.  In this 
  67. example, the ERRORLEVEL is set to the ASCII code of the upper case letter (65-
  68. 90). 
  69. ______________________________________________________________________________ 
  70.  
  71. Example 2
  72.  
  73.     To have the operator make a numeric menu selection using the Return key 
  74. (Enter), use something like this: 
  75.  
  76.     GETKEY 04 E B R
  77.  
  78. This lets the operator press a digit 0 through 4, echoes the keystroke to the 
  79. screen, and beeps if any other key was pressed. 
  80. ______________________________________________________________________________
  81.  
  82. Example 3
  83.  
  84.     To have the operator make a menu selection with a letter, use something 
  85. like: 
  86.  
  87.    GETKEY DF C H
  88.  
  89. lets the operator press a D, E, or F, but doesn't echo it to the screen, and 
  90. hides the cursor while waiting.  This command will also accept the keystrokes 
  91. d, e, or f, since the C argument capitalizes them before checking them against 
  92. the "DF" mask.  
  93. ______________________________________________________________________________ 
  94.  
  95. Example 4
  96.  
  97. Be careful using the C argument.  The following does NOT work:
  98.  
  99.     GETKEY ab C
  100.  
  101.  
  102. This example would fail because ANY input would be capitalized before checking 
  103. against the mask, and no capital letter is going to be valid with a mask of 
  104. only lower case letters. 
  105.  
  106. ┌─────────────────────────────────────────────────────────────────────────────┐
  107. │ SYSTEM REQUIREMENTS                                                         │
  108. └─────────────────────────────────────────────────────────────────────────────┘
  109.  
  110.     This program requires the OS/2 operating system, version 1.0 or later.  It 
  111. does not require the OS/2 Presentation Manager (PM), though you can run it in 
  112. a PM text window.
  113.  
  114. ┌─────────────────────────────────────────────────────────────────────────────┐
  115. │ EXIT CODES                                                                  │
  116. └─────────────────────────────────────────────────────────────────────────────┘
  117.  
  118.    As stated above, the program's exit code is normally the ASCII code of the 
  119. key pressed.  However, if an error occurs or the user presses ^C or ^Break (if 
  120. they haven't been disabled), the exit code is 255.
  121.  
  122. ┌─────────────────────────────────────────────────────────────────────────────┐
  123. │ REVISION HISTORY                                                            │
  124. └─────────────────────────────────────────────────────────────────────────────┘
  125.  
  126. 1.00   Original version
  127.  
  128. ┌─────────────────────────────────────────────────────────────────────────────┐
  129. │ MESSAGES                                                                    │
  130. └─────────────────────────────────────────────────────────────────────────────┘
  131.  
  132. This program cannot be run in DOS mode.  Either you're in OS/2's DOS 
  133. compatibility box, or you're using the MS-DOS or PC-DOS operating system. You 
  134. must run this version of GETKEY under the OS/2 operating system, and you 
  135. cannot be in the DOS compatibility box. 
  136.  
  137. If the program shows its instructions unexpectedly, there's a syntax error on 
  138. the command line.  The most common error is a mask with an odd number of 
  139. characters, or forgetting to include the mask.
  140.  
  141. ┌─────────────────────────────────────────────────────────────────────────────┐
  142. │ REGISTRATION                                                                │
  143. └─────────────────────────────────────────────────────────────────────────────┘
  144.  
  145.    GETKEY was written in C by Richard W. Adams.  It is copyright 1990 by the 
  146. author, all rights reserved.  Portions of the program are copyright Microsoft 
  147. Corporation, 1988. 
  148.  
  149.     The author provides this copy of the program for evaluation purposes under 
  150. the "shareware" concept.  You may copy and distribute GETKEY freely if you 
  151. meet the following requirements: 
  152.  
  153.     ■  You include this documentation file with the program
  154.     ■  You do not modify the program or documentation in any way
  155.     ■  You charge no fee other than a nominal one to cover distribution costs
  156.     ■  You do not distribute the program for commercial purposes without the 
  157.        written permission of the author
  158.  
  159.     You may post GETKEY on an electronic bulletin board or other computer 
  160. system for downloading, even if you charge a fee for using the system, as long 
  161. as you do not charge a fee specifically for downloading GETKEY.  However, you 
  162. must include both the executable and documentation files--GETKEY.EXE and 
  163. GETKEY.DOC--in a single downloadable file (e.g., a compressed format). 
  164.  
  165.     If you use GETKEY for more than 30 days, you must register your copy, 
  166. which gives you a perpetual license to use the product.  (Bulletin board 
  167. operators may leave GETKEY posted on their boards indefinitely, without paying 
  168. a registration fee, as long as they comply with the conditions listed above).  
  169. To register, send $10.00 to the author at the address below.  Not only is 
  170. registration a legal requirement under federal copyright law, but registration 
  171. fees give shareware authors the incentive to develop new programs and improve 
  172. old ones.  If you wish to receive a disk with the latest version of GETKEY, 
  173. include an additional $5.00 (total of $15.00) with your registration, to cover 
  174. shipping and handling.  State the version of GETKEY you currently have and 
  175. what disk format you need.  Site licenses are available for commercial, 
  176. government, and other organizations 
  177.  
  178.     Finally, this software is provided "as is."  There is no warranty, 
  179. implicit or otherwise.  The author does not guarantee compatibility with your 
  180. system, and is not responsible for any damages incurred by use of this 
  181. software. 
  182.  
  183.     By using this software, you agree to the above terms.  Please send any 
  184. payments or comments on GETKEY to: 
  185.  
  186.  
  187.                            Richard W. Adams
  188.                            104 Willow Oaks Boulevard
  189.                            Hampton, VA  23669-1528
  190.  
  191.