home *** CD-ROM | disk | FTP | other *** search
/ Mega Top 1 / os2_top1.zip / os2_top1 / APPS / PROG / REXX / CMD / CMDLINE1.ZIP / CMDLINE.DOC < prev    next >
Encoding:
Text File  |  1994-02-09  |  7.9 KB  |  218 lines
  1. INTRODUCTION
  2. ============
  3.  
  4. CmdLine is a pair of REXX library function that I wrote to implement the 
  5. OS/2 command line features in REXX.
  6.  
  7. It's features are almost identical to the OS/2 command line when KEYS ON
  8. is in effect.  It has additional functions that many OS/2 REXX programers
  9. may find useful.  In fact, it has most of the features needed to create a
  10. complete full screen data entry application.
  11.  
  12. CmdLine is not a small, tight program.  It's intended to be a full
  13. featured implementation of the OS/2 command line.  It is over 400 lines
  14. of REXX code.
  15.  
  16. If there are features that are missing, or are substantially different
  17. than the OS/2 command line, please notify me and I will attemp to
  18. implement them.
  19.  
  20. All suggestions, complaints, contributions, etc. are welcome.  Direct 
  21. them to: acrosby@comp.uark.edu.  You are free to use this code in your
  22. programs.  Please give credit where credit is due.
  23.  
  24. OVERVIEW
  25. --------
  26.  
  27. CmdLine may be included in your source file or as called as an external
  28. procedure.  Some of it's features are not available as an external
  29. procedure.
  30.  
  31. CmdLine provides an input parser for REXX that supplies the same features
  32. as the OS/2 command line.  This includes allowing you to use the left and
  33. right arrow keys, up and down arrows for accessing the history list, and
  34. F1 to match commands in the history list.  Additionally, CmdLine allows
  35. hidden input for passwords, calls that don't update the history list,
  36. calls that don't access the history list, and combinations of the above.
  37.  
  38. SYNTAX
  39. ------
  40.  
  41. value=CmdLine([option [,option]...])
  42.  
  43. where options are zero or more of:
  44.  
  45.    Hidden    : Characters are displayed as "*", no history, not kept.
  46.    Forget    : Do not add the result of this call to the history list.
  47.    Nohistory : Do not allow access to the history list.
  48.    Clear     : Reset the history list with this call (no input action
  49.                made.) Also clears any predefined keys!
  50.    Insert    : Set insert mode ON.
  51.    Overwrite : Set overwrite mode OFF.
  52.    Required  : Makes null responses invalid for this request.
  53.    Valid     : Next parameter specifies the valid charachters. (No
  54.                translation is done), no history, not kept.
  55.    Upper     : Translate input to upper case, no history, not kept.
  56.    Lower     : Translate input to lower case, no history, not kept.
  57.                (If both upper and lower are selected, whichever is 
  58.                selected LAST is performed.)
  59.    Width     : Next parameter specifies the maximum width of input, no
  60.                history, not kept.
  61.    Autoskip  : If input has a width, do not wait for enter when field is
  62.                full.
  63.    X         : Initial X (row) position for field
  64.    Y         : Initial Y (column) position for field
  65.    Tag       : Tag value to be displayed in front of field.
  66.  
  67. CmdLine returns either a null string or the value entered by the user.  If
  68. the field is REQUIRED, a valid value must be entered.
  69.  
  70. Only the first letter of the string is necessary, and case is ignored.
  71. Options may be specified in any combination, though _reset_ will always
  72. return without obtaining any user input.
  73.  
  74. If CmdLine is an INTERNAL function (included within your sourcefile), it
  75. will maintain a command line history in the stem variable history.  This
  76. stem variable is also used to store the current INSERT state and the
  77. default mapping for any extended keys.
  78.  
  79. Valid, upper, lower, and hidden all also set FORGET and NOHISTORY.
  80.  
  81. Options that require a parameter can either be seperated by periods or by
  82. an equal sign.
  83.  
  84. Keys used by CmdLine:
  85.  
  86.        [Up]     Cycle to the previous entry in the history list
  87.        [Down]   Cycle to the next entry in the history list
  88.        [Left]   Move the cursor to the left
  89.        [Right]  Move the cursor to the right
  90.        [ESC]    Clear the input line
  91.        [Home]   Moves the cursor to the beginning of the input line
  92.        [End]    Moves the cursor to the end of the input line
  93.        [^Home]  Erases from the cursor to the beginning of the input line
  94.        [^End]   Erases from the cursor to the end of the input line
  95.        [Ins]    Toggles Insert/Typeover mode
  96.        [Del]    Deletes character under the cursor
  97.        [Bkspc]  Deletes the charcter in front of the cursor
  98.        [^Left]  Moves to the beginning of the previous word
  99.        [^Right] Moves to the beginning of the next word
  100.  
  101. DEFINING EXTENDED KEYS
  102. ----------------------
  103.  
  104. This feature only works if CmdLine is an INTERNAL function.
  105.  
  106. Extended keys may be defined by obtaining the code returned as the second
  107. key by SysGetKey when that key is pressed.  The program SHOWCODE.CMD is
  108. included to demonstrate how to obtain these codes.  Place commands such
  109. as:
  110.  
  111. history.key.60="go" /* Definition for F2 */
  112.  
  113. in your program.  You cannot redefine keys that are already used by
  114. CmdLine.
  115.  
  116. Extended keys definitions are only available when history is available.
  117.  
  118. COMMAND HISTORY
  119. ---------------
  120.  
  121. CmdLine keeps a history of the input it has processed similiar to that
  122. at the OS/2 prompt when KEYS=ON is in effect.  A minor difference is that
  123. CmdLine will not add a command to the history if it is the same as the 
  124. last command issued.
  125.  
  126. Input identified as "hidden", "upper", "lower", or with a "verify" string
  127. will not be added to the history list, and will not have access to the
  128. input entered previously.
  129.  
  130. SAMPLE PROGRAMS:
  131. ================
  132.  
  133. There are several sample programs in this archive that use CmdLine.
  134. They are:
  135.  
  136. EXAMPLE1.CMD   An OS/2 style command line
  137. EXAMPLE2.CMD   An OS/2 command line with a Unix-style prompt
  138. DATA.CMD       A sample Data Entry screen written with CmdLine that shows
  139.                some of it's more powerful features.
  140.  
  141. USING CmdLine IN YOUR PROGRAMS:
  142. ===============================
  143.  
  144. You can use CmdLine in your programs as either an internal or external
  145. procedure.  I strongly reccomend including the procedure in your source
  146. as an internal procedure, so that you can have access to command history.
  147. You are free to use and modify the code, all I ask is that you give 
  148. credit where credit is due.
  149.  
  150. You can use CmdLine in your programs simply by including the
  151.  
  152. CmdLine is intended as a generic method for obtaining input from the
  153. keyboard in an OS/2 REXX program.  CmdLine provides input prompts in
  154. your programs all the features of having KEYS=ON at the OS/2 prompt.
  155. Additionally, it can be used to have hidden or validated input.
  156.  
  157. CmdLine uses an exposed stem variable "!history" to keep the history
  158. list and various settings, such as insert mode.  You can assign initial
  159. values to this variable.
  160.  
  161. The values used are:
  162.  
  163.        !history.0      The number of inputs stored
  164.        !history.1...n  The text of the inputs stored, chronologically
  165.        !history.insert The current insert state (1=on, 0=off)
  166.        !history.key.nn The text to be substituted when an extended key is
  167.                        pressed.
  168.  
  169. It isn't necessary to initialize any of these values. 
  170.  
  171. CmdLine() accepts input at the current cursor location.  If you desire to
  172. have a prompt on the same line as the input field, use 
  173. Call Charout, "prompt" as the line just before the call.
  174.  
  175. EXAMPLE 1:  Uses CmdLine to make a simple command processor:
  176.  
  177. /* EXAMPLE1
  178.  
  179.    Uses CmdLine() to make a simple OS/2 command line emulator. 
  180. */
  181. "@echo off"
  182.  
  183. do forever
  184.    Call Charout, "["directory()"]"
  185.    CmdLine()
  186. end
  187. return
  188.  
  189. EXAMPLE 2: A simple command processor with a Unix style prompt.
  190.  
  191. /* EXAMPLE2
  192.  
  193.    A Unix-ish prompt with CmdLine()
  194. */
  195. "@echo off"
  196.  
  197. !history.0=0
  198. do forever
  199.    Call Charout, "%"!history.0+1" "
  200.    CmdLine()
  201. end
  202. return
  203.  
  204. EXAMPLE 3: Uses CmdLine to request value up to 4 char wide.
  205.  
  206. /* EXAMPLE3
  207.  
  208. */
  209.  
  210. word=CmdLine("Width",4)
  211.  
  212. /* Request a password of uppercase letters and numbers up to 8 chars long.
  213.        Entering a value is required. */
  214.  
  215. password=CmdLine("H","R","U","W",8,"V",xrange("A","Z")||"0123456789")
  216.  
  217.  
  218.