home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rc321.zip / rx.INF (.txt) < prev    next >
OS/2 Help File  |  1995-03-02  |  124KB  |  4,234 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. As an interpreted, high level language, REXX is supposed to be one of the 
  5. easiest languages to use.  This means that a programmer can write useful 
  6. programs with a minimal investment of time and effort.  Unfortunately, REXX has 
  7. one very big drawback; its facilities to get input and output from an enduser 
  8. are positively primitive.  It can do little more than poll the command line 
  9. (ie, the enduser has to type in his input, one line at a time), and display 
  10. text messages to that same command line.  REXX certainly doesn't support any of 
  11. the features that OS/2's Presentation Manager makes possible, such as using the 
  12. mouse and keyboard to manipulate scrolling lists of text, menus, sliders, 
  13. buttons, etc, as well as being able to arrange all of these in multiple windows 
  14. that also can be manipulated with the mouse and keyboard.  With such PM 
  15. controls and dialogs, a programmer can create a much easier to use, and more 
  16. sophisticated, interface.  Wouldn't it be nice to be able to combine PM's 
  17. flexibility with REXX's simplicity?  Sure it would, and that's why there are a 
  18. few products that "extend" REXX to give it a PM interface (ie, add new REXX 
  19. commands that interface to PM, by having the REXX interpreter call C compiled 
  20. code in custom Dynamic Link Libraries which implements those new commands). 
  21. Rexx Dialog is one more such product; except that it's free, and it's small and 
  22. memory efficient because it doesn't try to do too much.  It's sort of my 
  23. version of VREXX and PMREXX, but a lot more flexible in the way that it lets 
  24. you create and manage a PM interface for your REXX script.  Using Rexx Dialog, 
  25. you can quickly create a PM program in REXX. 
  26.  
  27. It is hoped that, by making a tool such as Rexx Dialog freely available (and 
  28. some of the other freebies that I've created such as FILEREXX), other 
  29. programmers will continue that spirit and create even more OS/2 native software 
  30. (which is very much needed right now) and freely distribute such. 
  31.  
  32.  
  33. Some of the words in this manual are highlighted in bold text, such as Group 
  34. Type.  These are words that refer to something that you have to setup in your 
  35. REXX script to use Rexx Dialog to create and manage a PM interface.  Other 
  36. words are in colored text such as RXVAL.  These refer to actual REXX variables 
  37. in your script (ie, the names of variables).  Underlined words, such as RXSAY, 
  38. refer to actual REXX commands created by Rexx Dialog, which your REXX script 
  39. calls to create and manage a PM interface. Some words are in colored text such 
  40. as Read This are meant to be emphasized.  Words in italics refer to aspects of 
  41. OS/2. 
  42.  
  43.  
  44. ΓòÉΓòÉΓòÉ 2. License ΓòÉΓòÉΓòÉ
  45.  
  46. Rexx Dialog (comprised of the files RXDLG.DLL, RX.EXE, RX.INF, RXCAPP.INF and 
  47. all example REXX scripts written by Jeff Glatt) is copyright 1995 by Jeff 
  48. Glatt.  Rexx Dialog is freely redistributable.  It can be used by and 
  49. distributed along with any other program be it a shareware, freeware, or even 
  50. commercial product, as long as this documentation is included with the program. 
  51. There are no pagan user fees, surreptitious financial charges, or other devious 
  52. capitalist trickery associated with the use of these files.  There are also no 
  53. warranties of any kind with this software.  If swallowed, induce vomiting 
  54. immediately (by contemplating the aesthetics of Windows).  You can do anything 
  55. you like with this archive, except reverse engineer or modify RXDLG.DLL, 
  56. RX.EXE, RX.INF, or RXCAPP.INF, nor can you poke it with a sharp stick.  But you 
  57. can print it out on flimsy paper stock, wrap it around your privates, and go to 
  58. work like that as long as you don't blame the author for your actions.  You are 
  59. not allowed to think nasty thoughts about the author, even if the software 
  60. somehow causes the erasure of your collection of smutty picture files.  You may 
  61. have more or less protections in certain states of the union, depending upon 
  62. how far your local politicians bend over for a bribe from some business 
  63. lobbyist.  Just remember that I have no money, so don't bother suing me for any 
  64. damages as a result of using this software.  Tell your greasy lawyer to go 
  65. after IBM, and make sure that you pick 12 really stupid pinheads for the jury. 
  66.  
  67. I can be contacted at: 
  68.  
  69. 6 Sycamore Drive East 
  70. New Hartford, NY 13413 
  71. (315) 735-5350 
  72.  
  73. Report bug fixes, or shut up. 
  74.  
  75. Whose says that writing software licenses is no fun? 
  76.  
  77.  
  78. ΓòÉΓòÉΓòÉ 3. Initial Setup and Requirements ΓòÉΓòÉΓòÉ
  79.  
  80. There are 2 files that comprise the Rexx Dialog facility; RX.EXE and RXDLG.DLL. 
  81. These must be present upon any system that runs scripts which utilize Rexx 
  82. Dialog's new commands to create and manage a PM interface. Of course, the OS/2 
  83. REXX Interpreter must also be installed upon the system (although PMREXX does 
  84. not need to be -- especially now that you have Rexx Dialog). 
  85.  
  86. RX.EXE is an executable that you use to start up your REXX script.  At an OS/2 
  87. command prompt, you type RX, followed by the name of your REXX script (with 
  88. full path if necessary).  For example, to start the REXX script "blort.cmd", 
  89. you would type: 
  90.  
  91. rx blort 
  92.  
  93. and then press ENTER. 
  94.  
  95. Note:  It's not necessary to type the .exe extension on rx.exe, nor the cmd 
  96.        extension on the script name.
  97.  
  98. You must use RX.EXE to start (and run) your REXX script, or the REXX 
  99. interpreter won't understand the special, new commands that Rexx Dialog makes 
  100. available to your script, and you'll get an error message saying that "The name 
  101. specified is not recognized as an internal or external command, operable 
  102. program, or batch file".  RX.EXE takes care of all of the details of telling 
  103. the REXX interpreter what the new commands are (so that your script can use 
  104. them) and also runs your script. 
  105.  
  106. RX.DLL is a Dynamic Link Library used by RX.EXE.  RX.EXE must be able to find 
  107. this DLL, so you should copy it to some place that is specified on the LIBPATH 
  108. statement of your config.sys file.  A good place is C:\OS2\DLL.  Also, it's 
  109. recommended that RX.EXE be copied to some place that is specified by the PATH 
  110. statement.  A good place is C:\OS2. 
  111.  
  112. If you would like to setup your script so that it runs by clicking upon a 
  113. Desktop icon (ie, object), that's easy to do.  Open the Templates folder on the 
  114. Desktop.  Drag the Program object to whichever place you want to put the icon 
  115. for your script, and release the mouse button (ie, drop the icon there).  A 
  116. Notebook should pop up, with the Settings page displayed.  In the Path and 
  117. Filename entry, type RX.EXE.  If you didn't copy RX.EXE to some place specified 
  118. in your config.sys PATH, then you'll need to specify the complete path, for 
  119. example, C:\OS2\RX.EXE.  Make sure that RXDLG.DLL is copied to some place 
  120. specified in your config.sys LIBPATH (or you can usually place it in the same 
  121. directory as the scripts that use Rexx Dialog).  In the Parameters field of the 
  122. Notebook, type the name of your REXX script.  Again, you may need to specify 
  123. the full path.  Now whenever you click upon that icon, your script will run, 
  124. and be able to use Rexx Dialog's new commands. 
  125.  
  126. Repeat the above process with every REXX script for which you'd like to setup a 
  127. Desktop icon, and which will use Rexx Dialog. 
  128.  
  129. Note:  It doesn't matter whether you launch your REXX script from the OS/2 
  130.        command prompt (as described above) or a Desktop icon.  Your script will 
  131.        run as if it were a real PM program regardless. 
  132.  
  133.  
  134. ΓòÉΓòÉΓòÉ 4. Rexx ΓòÉΓòÉΓòÉ
  135.  
  136. REXX is a computer language.  It's interpreted, like BASIC, which means that 
  137. you simply write your program as an ordinary text file, and some interpreter 
  138. runs that text file directly.  There's no need for you to compile and link your 
  139. source code into an executable program.  Your text file *IS* your program (and 
  140. can be created with any text editor such as the OS/2 System Editor, or the 
  141. Enhanced Editor).  So, REXX is a script language.  But, it has lots of 
  142. features, including variables, string processing, looping, etc.  Consult the 
  143. "Rexx User's Guide" on the OS/2 PDK, or the "Rexx Procedures/2" online book for 
  144. a description of fundamental things that can be done with REXX. 
  145.  
  146. The REXX interpreter is built into OS/2.  That's why you can run a REXX script 
  147. (ie, text file containing REXX instructions) just by typing its name from an 
  148. OS/2 Command Prompt window. 
  149.  
  150. OS/2 programs may be written to also start up REXX scripts.  RX.EXE is one such 
  151. program.  It is used to start your REXX script so that your script has 9 
  152. special commands to call in order to create and manage a PM interface. 
  153.  
  154. There's a very important difference between running a REXX script using RX.EXE, 
  155. and running a script from a Command Prompt window.  When you run a REXX script 
  156. using RX.EXE, RX.EXE takes care of all of the details of letting the REXX 
  157. interpreter know what the new commands are.  Your REXX script can immediately 
  158. use those new commands.  RX.EXE also helps your script create and manage the PM 
  159. interface that your script specifies. 
  160.  
  161. RX.EXE does not pass any args to your REXX script. 
  162.  
  163. Note:  It's advisable to first read the OS/2 documentation on REXX, and 
  164.        experiment with the standard commands and features.  The REXX examples 
  165.        here may use some standard features without explaining them.  Mostly, 
  166.        the examples will illustrate the 9, special commands that Rexx Dialog 
  167.        makes available to create and manage a PM interface.
  168.  
  169.  
  170. ΓòÉΓòÉΓòÉ 5. Rexx Dialog Commands ΓòÉΓòÉΓòÉ
  171.  
  172. The 9 special Rexx Dialog commands that your script can call to create and 
  173. manage a PM interface all begin with the 2 letters RX.  Here are the 4 
  174. commands: 
  175.  
  176. RXACTIVE 
  177. RXDLG 
  178. RXERR 
  179. RXFILE 
  180. RXHELP 
  181. RXQUERY 
  182. RXSAY 
  183. RXSET 
  184. RXVERS 
  185.  
  186. You can begin a line in your REXX script with one of these commands.  Then, 
  187. when the script is run, the REXX interpreter executes the command when it gets 
  188. to that line. 
  189.  
  190. Most of the commands will have arguments.  This is just additional text that 
  191. you place after the command, on the same line.  Arguments modify the way that a 
  192. Rexx Dialog command works, or provide necessary additional information for the 
  193. command to use. 
  194.  
  195. Note:  It's OK to put blank spaces before and after commands, and inbetween 
  196.        arguments.  This makes your script easier for you to read.
  197.  
  198. All Rexx Dialog commands return either a string or number (depending upon which 
  199. you specify via RXERR, but some commands always return strings).  The return is 
  200. stored in the special REXX symbol RC.  As each command is issued, RC reflects 
  201. what that command returns.  The return usually tells you whether a command 
  202. worked or failed (although sometimes the return provides other info instead 
  203. such as which button was used to dismiss a RXSAY box).  In the case of a 
  204. command that could fail as a result of something that goes wrong within the 
  205. command, you should always check RC after issuing that command.  Alternately, 
  206. since all Rexx Dialog commands set the REXX FAILURE or ERROR flags for any 
  207. possible errors, you can SIGNAL ON ERROR or SIGNAL ON FAILURE to an appropriate 
  208. place in your REXX script to handle such an error situation. An RC of 0 (for 
  209. error numbers) or an empty string, ie "" (for error strings) is considered to 
  210. be a successful return. 
  211.  
  212. The following descriptions of each command tell what the template for the 
  213. command is (ie, how you notate it in your script), what the command does, what 
  214. the arguments are, what it returns to your REXX script, and examples of using 
  215. the command. 
  216.  
  217.  
  218. ΓòÉΓòÉΓòÉ 5.1. RXACTIVE ΓòÉΓòÉΓòÉ
  219.  
  220. Template       RXACTIVE 
  221.  
  222. Description    This command determines which open window is the active one, and 
  223.                sets the REXX variable RXWIND to that window's title.  It also 
  224.                sets the REXX variables RXID and RXSUBID to the Group # and 
  225.                Control # that have the focus.  For example, if the user 
  226.                happened to be using the first control of the first Group in a 
  227.                window titled "Window 1", then RXWIND is 'Window 1', RXID is 1, 
  228.                and RXSUBID is 1.  If the window itself has the focus (ie, the 
  229.                window is active but the user has not activated any particular 
  230.                control inside of that window), then RXID and RXSUBID are set to 
  231.                0. 
  232.  
  233.                If none of the open windows are active, this indicates that the 
  234.                user has made some other application's window active.  In this 
  235.                case, RXWIND is set to a NULL string (ie, ''). 
  236.  
  237. Args 
  238.  
  239. None. 
  240.  
  241. Returns 
  242.  
  243. Sets RXWIND, RXID, and RXSUBID. 
  244.  
  245. Examples 
  246.  
  247. /* This gets and displays RXWIND, RXID and RXSUBID for the active window */ 
  248.  
  249. RXACTIVE 
  250. RXSAY 'Active Window = "'RXWIND'"' 
  251. RXSAY 'Active Group = 'RXID 
  252. RXSAY 'Active Control = 'RXSUBID 
  253.  
  254.  
  255. ΓòÉΓòÉΓòÉ 5.2. RXDEV ΓòÉΓòÉΓòÉ
  256.  
  257. Template       RXDEV DeviceTitle Operation Value 
  258.  
  259. Description    This command is used to setup for reading from devices or pipes. 
  260.                The input will be returned when your script calls RXDLG. 
  261.  
  262.                Note:  You must have a Main Window open before calling RXDEV. 
  263.                       Closing the Main Window also performs RXDEV's CLOSE 
  264.                       Operation upon any opened and initialized devices.
  265.  
  266.                PM applications (including REXX scripts written for Rexx Dialog) 
  267.                must approach reading from devices differently than non-PM apps 
  268.                (ie, REXX scripts launched like they normally are; without a PM 
  269.                interface).  This is due to 2 design limitations of OS/2.  First 
  270.                of all, PM has a single system queue which requires a PM app's 
  271.                window procedure to complete its work in 1/10 of a second.  If a 
  272.                PM app doesn't do this, it will appear to "lock up" the desktop. 
  273.                The other design limitation of OS/2 is its very awful 16-bit 
  274.                Physical Device Driver model, which is essentially a more 
  275.                convoluted version of MS-DOS 2.0's driver model.  This model 
  276.                lacks standardized approaches to such things as querying if any 
  277.                input is available for reading, or setting a time-out for reads 
  278.                (ie, if no input is received within a certain amount of time, 
  279.                the read is aborted).  As might be expected, communication 
  280.                between an archaic 16-bit driver model and modern 32-bit 
  281.                application software is grotesquely crude and inflexible, and 
  282.                therefore, driver programmers have resorted to all manner of 
  283.                proprietary schemes to implement these features that IBM never 
  284.                wrote into OS/2's PDD model.  Worse, many drivers don't even 
  285.                bother to implement the features at all.  So, a call to DosRead 
  286.                input from a device may result in the app being "blocked" (ie, 
  287.                halted) until input is available for reading, and this may take 
  288.                much longer than 1/10 of a second.  Therefore, a PM app must 
  289.                have a separate thread to read input from a device.  Its main 
  290.                thread must not call any function that ultimately calls DosRead 
  291.                when reading from a device.  (ie, Standard functions such as 
  292.                STREAM, CHARIN, and LINEIN must not be used when reading from a 
  293.                device.  Neither can you use FileRexx's FileRead, FileGets, or 
  294.                FileReadValue, nor any other function library's input routines 
  295.                that call DosRead, such as RXASYNC.  Hey, if you don't like it, 
  296.                tell IBM to fix PM's single system queue, and implement a more 
  297.                modern PDD model, preferably 32-bit).  In lieu of these 
  298.                functions, you'll use RXDEV to setup a device for reading, and 
  299.                then retrieve input from the device via RXDLG.  To make things 
  300.                easier, Rexx Dialog's device reading has such features as being 
  301.                able to read whole blocks of data (ie, more than 1 character at 
  302.                a time), and discard input that doesn't begin or end with 
  303.                certain patterns, parse input into several REXX variables, and 
  304.                perform binary to REXX variable conversion.  So, it's sort of 
  305.                like a combination of FileGets, FileRead, and FileReadValue, 
  306.                which should handle the bulk of your needs. 
  307.  
  308. Args 
  309.  
  310. DeviceTitle    The title (ie, string) of the device, which can be any title of 
  311.                your choosing.  If there are blank spaces in the title, then 
  312.                enclose the string with two pairs of quotes '"' (or "'") if the 
  313.                title is a variable, or '" and "' (or "' and '") if a literal 
  314.                string.  For example, these are legal titles: 
  315.  
  316.                '"'title'"'  /* title would be some variable that you 
  317.                initialized earlier, for example, title='My Device Title' */ 
  318.                '"My Device Title"' 
  319.  
  320.                This is used to identify the device in the same way that the 
  321.                WindowTitle arg to RXDLG identifies a window.  The DeviceTitle 
  322.                should be unique from any other device that you have setup for 
  323.                reading with RXDEV.  If you specify a DeviceTitle of '""', then 
  324.                this refers to the first device that has been initialized (and 
  325.                is not yet closed) with RXDEV. 
  326.  
  327. Value          The meaning of the Value arg depends upon the Operation arg (and 
  328.                may not need to be supplied for some Operations). 
  329.  
  330. Operation      Operation is one of the following: 
  331.  
  332. INIT           This operation must be performed before any other operations. 
  333.                It sets up a device for reading (and will begin the reading 
  334.                unless the PAUSE Flag is set).  Prior to performing this 
  335.                operation, you must setup several REXX variables to desired 
  336.                values.  After the INIT operation, these variables can be 
  337.                discarded. 
  338.  
  339.                First, you must open the device for reading using FILEREXX's 
  340.                (ie, my REXX function library for doing device I/O, available 
  341.                separately) FileOpen.  If you're going to also be doing writes 
  342.                to the device (ie, using FILEREXX's FileWrite, FilePuts, or 
  343.                FileWriteValue), you can open the device for both reading and 
  344.                writing, and use this one handle for both FILEREXX and Rexx 
  345.                Dialog.  You must store the handle returned by FileOpen in the 
  346.                REXX variable RXINFO before doing the INIT operation. 
  347.  
  348.                The REXX variable RXCOUNT contains the size of the input buffer, 
  349.                and a count limit.  Rexx Dialog can return blocks of data (ie, 
  350.                more than 1 character or 8-bit byte) to your script.  For 
  351.                example, you can ask Rexx Dialog to return the next 64 bytes of 
  352.                data read from the device, when you call RXDLG once.  The count 
  353.                limit is how many bytes to input before they are returned to 
  354.                your script.  For example, a count of limit of 64 would mean 
  355.                that after reading 64 bytes, a call to RXDLG returns those 64 
  356.                bytes to your script.  The input buffer must be at least 4 bytes 
  357.                larger than the count limit.  Rexx Dialog implements a circular 
  358.                buffer.  This helps to speed up device reads, but unless your 
  359.                script can receive and process input faster than Rexx Dialog 
  360.                reads it, further device input may overwrite previous input. 
  361.                You can work around this either by using the PAUSE Flag, or by 
  362.                setting the size of the input buffer to be at least twice your 
  363.                count limit (plus 4 bytes that Rexx Dialog uses for 
  364.                bookkeeping).  So, if your count limit is 64, and you want 
  365.                double-buffering, then set the input buffer size to (64+4)*2. 
  366.                If you need triple buffering, set the buffer size to (count 
  367.                limit + 4)*3.  Etc.  If you specify a buffer size of 0, then 
  368.                4096 bytes is used.  This corresponds to a page of memory.  It's 
  369.                best to round up your buffer size to a multiple of 4096 (or use 
  370.                a default of 0 if you don't need more than 4096 bytes), as that 
  371.                won't use any more memory, due to OS/2's paging system.  If you 
  372.                don't specify the count limit, it defaults to a setting 
  373.                appropriate for double buffering.  The buffer size and count 
  374.                limit are restricted to 65,535 or less. 
  375.  
  376.                RXLABEL is set to the name of the REXX stem variable where the 
  377.                device input is returned.  The variable name should be limited 
  378.                to 22 characters.  All of the returned bytes are stored in that 
  379.                variable name with a .0 extension.  For example, if you specify 
  380.                RXLABEL = 'MYINPUT', and a count limit of 3, then a call to 
  381.                RXDLG returns those 3 characters in MYINPUT.0.  If the NUM flag 
  382.                is set, then each byte is expressed as an ascii numeric value 
  383.                (in decimal, a range of 0 to 255), with a space inbetween each 
  384.                value.  For example, if a line feed and carriage return were 
  385.                returned, MYINPUT.0 would be '13 10'.  If the SIGN Flag is set 
  386.                (in addition to NUM), then the ascii numeric values are 
  387.                expressed as signed (instead of unsigned) values (ie, a range of 
  388.                -128 to 127).  The returned string is limited to 255 characters. 
  389.                If the PARSE Flag is set, then each byte is returned in a 
  390.                different stem variable (and the 255 character limit is not 
  391.                applicable).  For example, the first byte is returned in 
  392.                MYINPUT.0, the second byte is returned in MYINPUT.1, and the 
  393.                third byte is returned in MYINPUT.2.  Both the NUM and PARSE 
  394.                flags can be set. 
  395.  
  396.                RXSTARTPAT is set to a string containing various patterns, one 
  397.                of which must be matched before device input is saved.  This 
  398.                makes it possible to discard device input until a certain 
  399.                pattern is spotted, and then start collecting all data at that 
  400.                point.  Each pattern in the start string must be separated by a 
  401.                | character.  If RXSTARTPAT is a null string, then all device 
  402.                input is saved (ie, start pattern match is disabled). 
  403.  
  404.                Each pattern can contain one or more characters or values.  A 
  405.                pattern begins with a "Format" letter.  This is an 'H' if you're 
  406.                expressing the values in hexadecimal, a 'B' if you're expressing 
  407.                the values in binary, a 'D' if you're expressing the values in 
  408.                decimal, or an 'L' if the characters are not to be translated in 
  409.                any way (ie, a literal string).  For 'H', 'B', or 'D', Rexx 
  410.                Dialog translates each value to its binary equivalent when used 
  411.                in a start pattern.  For example, if you want to set a start 
  412.                pattern that looks for a line feed and a carriage return 
  413.                characters, you could express the LF and CR in decimal as so: 
  414.  
  415.                'D 13 10' 
  416.  
  417.                Or, you could express them each in hexidecimal: 
  418.  
  419.                'H D A' 
  420.  
  421.                Or, you could even express them in binary: 
  422.  
  423.                'B 1101 1010' 
  424.  
  425.                If the "Format" is 'L', then the value string is used verbatim 
  426.                without any translation to binary values. For example, to set a 
  427.                start pattern that looks for the string 'hello': 
  428.  
  429.                'L hello' 
  430.  
  431.                The Format can have an extension, which I'll refer to as the 
  432.                "Count".  This will be how many values of that type follow.  If 
  433.                the Count arg is omitted, then the field's size is ultimately 
  434.                determined by however many values follow.  For example, if you 
  435.                had a field that consisted of 32 decimal values, you could 
  436.                define the Format and Count as D.32 and then list the 32 values 
  437.                after that.  If you don't supply as many values as "Count", then 
  438.                null bytes are used to pad out to Count.  There can be an 
  439.                additional extension after the Count, which I'll refer to as an 
  440.                "Initialization".  This will be either a numeric value that it 
  441.                is to be duplicated for Count times, or a (non-numeric) 
  442.                character that it is to be duplicated Count times.  For example, 
  443.                if you wanted to specify 32 decimal values and set them all to 
  444.                the value 16, the Format, Count, and Initialization would be 
  445.                D.32.16 with no need to specify any values after that.  If you 
  446.                wanted to specify 4 'A' chars, the Format, Count, and 
  447.                Initialization would be L.4.A with no need to specify any chars 
  448.                after that. 
  449.  
  450.                It's also permissible to have more than one Format, Count, and 
  451.                values (or Initialization) per field.  But, all of the Formats 
  452.                must also have a Count, except for the last Format (which may or 
  453.                may not have a Count).  For example, say that you want to set a 
  454.                start pattern of 'hello' followed by a line feed and carriage 
  455.                return: 
  456.  
  457.                'L.5 hello D 13 10' 
  458.  
  459.                Here's an example of setting 2 start patterns.  One pattern is 
  460.                'OK', and the other pattern is 'NO'.  So, device input is 
  461.                ignored until either string is detected. 
  462.  
  463.                'L OK | L NO' 
  464.  
  465.                The returned input starts with the matching start pattern (ie, 
  466.                it's part of the returned input) unless the TRIM Flag is set (in 
  467.                which case the start pattern is trimmed from the returned 
  468.                input). 
  469.  
  470.                If the WATCH Flag is set, then the device input is returned as 
  471.                soon as a start pattern is matched (ie, the returned input 
  472.                consists only of the matching start pattern).  This is useful if 
  473.                you need to throw away all device input except for a particular 
  474.                set of patterns. 
  475.  
  476.                RXENDPAT is also set to a string containing various patterns. 
  477.                If one of these patterns is matched, then the device input is 
  478.                returned to the script at that point, regardless of whether the 
  479.                count limit has been met.  This makes it possible to force 
  480.                device input to be returned as soon as a certain pattern is 
  481.                spotted.  Each pattern in the end string must be separated by a 
  482.                | character.  The format of the string is the same as per 
  483.                RXSTARTPAT.  If RXENDPAT is a null string, then device input 
  484.                isn't returned until the count limit is reached (ie, end pattern 
  485.                match is disabled). 
  486.  
  487.                The returned input ends with the matching end pattern (ie, it's 
  488.                part of the returned input) unless the TRIM Flag is set (in 
  489.                which case the end pattern is trimmed from the returned input). 
  490.  
  491.                RXFLAGS is any or all of the following, with each flag separated 
  492.                by a | character. 
  493.  
  494.                TRIM    Trim any matching start and/or end pattern from the 
  495.                returned input. 
  496.                NUM    Translate each returned byte to an ascii numeric value. 
  497.                SIGN    Return ascii numeric values as signed.  The NUM Flag 
  498.                must be also set. 
  499.                PARSE   Return each byte in its own REXX stem variable. 
  500.                PAUSE   Rexx Dialog's device reading pauses after returning each 
  501.                block to the script.  It will not read the next block until the 
  502.                script performs a RESUME operation.  This allows the script to 
  503.                start/stop the device reads at will, thereby preventing Rexx 
  504.                Dialog from reading input faster than the script can handle it. 
  505.                WATCH   Return input as soon as one of the start patterns is 
  506.                matched.  End patterns are ignored (as is all input except for 
  507.                an exact match to one of the start patterns). 
  508.                PARTIAL  Some drivers do not block reads.  That is to say that 
  509.                if there is no more input to be read, the driver indicates that 
  510.                to Rexx Dialog.  For example, COM drivers support setting up 
  511.                reads to have a time-out (via an IOCTL interface), in which case 
  512.                if there is no more data to be read, control is returned to Rexx 
  513.                Dialog.  In this case, setting the PARTIAL Flag will cause Rexx 
  514.                Dialog to return (to your script) whatever data it has collected 
  515.                up to the point when no more data is available, even though an 
  516.                end pattern may not be matched (ie, RXENDPAT=0) or the count 
  517.                limit has not been met.  In other words, Rexx Dialog always ends 
  518.                up returning input data back to your script as soon as that data 
  519.                is available from the device, rather than waiting to fulfill the 
  520.                count limit or finding a matching end pattern before returning a 
  521.                data block. 
  522.  
  523. COUNT          This operation sets a new count limit for the specified device. 
  524.                The input buffer size can't be altered after INIT.  The Value 
  525.                arg is the new count limit (which should be at least 4 bytes 
  526.                less than the input buffer size). 
  527.  
  528. VAR            This operation sets a new REXX stem variable name to return 
  529.                input for the specified device.  The Value arg is the new 
  530.                variable name. 
  531.  
  532. START          This operation sets a new start string for the specified device. 
  533.                The Value arg is the new start string (expressed in the same 
  534.                format as per the INIT operation). 
  535.  
  536. END            This operation sets a new end string for the specified device. 
  537.                The Value arg is the new end string (expressed in the same 
  538.                format as per the INIT operation). 
  539.  
  540. FLAGS          This operation sets the new Flags for the specified device.  The 
  541.                Value arg is the new Flags (expressed in the same manner as per 
  542.                the INIT operation). 
  543.  
  544. RESUME         This operation tells Rexx Dialog to read another block of data 
  545.                for the specified device.  There is no Value arg.  You must do a 
  546.                RESUME Operation each time after RXDLG returns device input if 
  547.                you wish to receive another block of data upon the next RXDLG 
  548.                call.  Otherwise, device reading is paused. 
  549.  
  550. CLOSE          This operation closes the file handle for the specified device, 
  551.                and frees any resources allocated for it.  There is no Value 
  552.                arg.  After a CLOSE operation, you do not need to FILEREXX 
  553.                FileClose any handle that was setup on the INIT operation. 
  554.                Neither can you subsequently use that same handle with other 
  555.                FILEREXX routines.  (You'd have to FileOpen the device again). 
  556.  
  557. Returns 
  558.  
  559. A large variety of error messages or numbers could be returned by RXDLG.  See 
  560. Errors for details. 
  561.  
  562. The actual device input is returned upon a call to RXDLG.  RXDLG will setup the 
  563. REXX stem variable you specified during INIT (or VAR) with the device input. 
  564. RXWIND will be set to the DeviceName of the device whose input is being 
  565. returned.  RXID will be 1000 + the device number (where the first device 
  566. initialized is 0, the second device initialized is 1, etc).  So, you can either 
  567. use RXWIND or RXID to differentiate between RXDLG returning device input, or 
  568. some user input.  RXSUBID will be set to how many input bytes are being 
  569. returned.  RXSTARTPAT will be set to the number of whichever start pattern 
  570. matched the input (where the first start pattern is 1, the second pattern is 2, 
  571. etc).  RXSTARTPAT is 0 if no pattern was matched (ie, there was no start string 
  572. specified).  RXENDPAT will be set to the number of whichever end pattern 
  573. matched the input.  RXENDPAT is 0 if no pattern was matched (ie, there was no 
  574. end string specified or the count limit was reached before a matching end 
  575. pattern could be detected). 
  576.  
  577.  
  578. ΓòÉΓòÉΓòÉ 5.3. RXDLG ΓòÉΓòÉΓòÉ
  579.  
  580. Template       RXDLG NumGroups WindowTitle Dimensions Flags 
  581.                RXDLG WindowTitle Operation 
  582.  
  583. Description    This command is the major function that is used to create and 
  584.                manage the PM Interface.  It creates, manages, and finally 
  585.                destroys a window which can contain many different kinds of PM 
  586.                controls such as push buttons, radio buttons, checkmark buttons, 
  587.                result buttons, list boxes, drop boxes, entry boxes, sliders, 
  588.                menus, etc) that the user manipulates in order to enter data, or 
  589.                which your script uses to display data.  RXDLG has 2 different 
  590.                calling templates.  The first is used when you want to create a 
  591.                window.  The second template is used when you want to perform 
  592.                user input or output with, or perform some other operation such 
  593.                as destroying, a window.  RXDLG also returns device input (if 
  594.                you've opened a device for reading).  RXDLG can be called many 
  595.                times to create multiple windows, each with their own (perhaps 
  596.                unique) Groups of controls; all managed by a collaborative 
  597.                communication between Rexx Dialog and your script (mostly using 
  598.                RXDLG). 
  599.  
  600.                RXDLG requires that you set up various REXX Variables to 
  601.                describe all of the controls/menus/etc that you want within a 
  602.                particular window prior to issuing a RXDLG command to create a 
  603.                window.  Rexx Dialog then queries the state of those REXX 
  604.                variables on its own, and creates your window.  Subsequent calls 
  605.                to RXDLG can perform some other operation upon an open window 
  606.                that your script specifies. 
  607.  
  608.                RXDLG is a very complex command, so the next sections deal with 
  609.                various topics that concern RXDLG.  This page simply gives a 
  610.                brief, reference summary.  You may wish to skip to the next page 
  611.                now, and use this page simply as a reference after becoming 
  612.                familiar with RXDLG. 
  613.  
  614.                Note:  Rexx Dialog assumes that the system font has a point size 
  615.                       of 10 (ie, as does the default System Proportional).
  616.  
  617. Args 
  618.  
  619. NumGroups      How many Groups of controls are described.  For example, if you 
  620.                specify 2 Groups, then you need to set up two sets of variables 
  621.                for 2 Groups (ie, RXVAL.1, RXINFO.1, RXLABEL.1, etc, for the 
  622.                first Group, and RXVAL.2, RXINFO.2, RXLABEL.2, etc, for the 
  623.                second Group) or RXDLG will fail to create the window and return 
  624.                an error message.  Note that if you were to describe two Groups, 
  625.                but only passed a NumGroups of 1 to RXDLG, then a window would 
  626.                be created with only 1 Group in it.  You'd never see that second 
  627.                Group that you specified.  Make sure that NumGroups is set 
  628.                respective to how many sets of variables (ie, Groups of 
  629.                controls) that you've described, and vice versa. 
  630.  
  631.                Only the first 127 Groups in a window can have groupboxes 
  632.                automatically created around them (if desired).  For subsequent 
  633.                Groups, you'll have to use separate GROUP Types to encompass the 
  634.                desired controls. 
  635.  
  636.                Note:  If you don't supply a NumGroups arg, then Rexx Dialog 
  637.                       automatically knows that you're using the second template 
  638.                       of RXDLG (ie, where the WindowTitle comes first).  In 
  639.                       this case, you're not creating a window, but rather, 
  640.                       performing an operation upon an already open Window.
  641.  
  642.                In order to create a window, NumGroups must not be 0 (ie, you 
  643.                always have to specify at least 1 Group of controls).  If you 
  644.                truly want an "empty" window, then specify an empty MENU Group. 
  645.  
  646. WindowTitle    The title (ie, string) of the window.  If there are blank spaces 
  647.                in the title, then enclose the string with two pairs of quotes 
  648.                '"' (or "'") if the title is a variable, or '" and "' (or "' and 
  649.                '") if a literal string.  For example, these are legal titles: 
  650.  
  651.                '"'title'"'  /* title would be some variable that you 
  652.                initialized earlier, for example, title='My Window Title' */ 
  653.                '"My Window Title"' 
  654.  
  655.                Note:  You must not name a window where the first character is a 
  656.                       numeric digit (ie, 0 to 9) although numeric digits can 
  657.                       appear later in the title.
  658.  
  659.                If you're using the first RXDLG template, then a window will be 
  660.                created with this title. 
  661.  
  662.                If you're using the second RXDLG template, then WindowTitle is 
  663.                the title of the window upon which you wish to perform an 
  664.                operation.  In the second template, the WindowTitle can be an 
  665.                empty string, ie '""', in which case, the Main Window is used 
  666.                for Operations 2, 3, and 4, and for Operations 0 and 1, an empty 
  667.                string allows user interaction to resume with the window that 
  668.                was active upon the previous call to RXDLG.  The WindowTitle 
  669.                that you pass must match the title of some open window, or RXDLG 
  670.                will return a "Can't find Rexx Dialog" error message.  (If you 
  671.                pass an empty string, then the Main Window must be open). 
  672.  
  673.                Note:  If you specify a particular window title for Operations 0 
  674.                       or 1, that window will be brought to the front and made active.
  675.  
  676. Operation      This arg is for the second template of RXDLG.  Operation will be 
  677.                one of the following: 
  678.  
  679. 0              Perform user interaction (only upon the specified window if its 
  680.                MODAL flag is set).  Note that if there are multiple windows 
  681.                open and the specified window is not MODAL, then the user may 
  682.                choose to interact with a different window which may cause RXDLG 
  683.                to return.  In such a case, you should always check the RXWIND 
  684.                variable after a call to RXDLG. 
  685.  
  686. 1              Perform user interaction (only upon the specified window if its 
  687.                MODAL flag is set), and also tell Rexx Dialog that it's OK to 
  688.                close that window when RXDLG returns.  Note that if there are 
  689.                multiple windows open and the specified window is not MODAL, 
  690.                then the user may choose to interact with a different window 
  691.                which causes RXDLG to return.  In such a case, the specified 
  692.                window will not be closed, and you should always check the 
  693.                RXWIND variable after a call to RXDLG. 
  694.  
  695. 2              Set up the REXX return values as per the state of the specified 
  696.                window and return immediately without performing any user 
  697.                interaction nor window closing.  This operation does not set up 
  698.                the RXID, RXSUBID, and RXWIND variables. 
  699.  
  700. 3              Set up the REXX return values as per the state of the specified 
  701.                window, close that window, and return immediately without 
  702.                performing any user interaction.  This operation does not set up 
  703.                the RXID, RXSUBID, and RXWIND variables. 
  704.  
  705. 4              Close the specified window, and return immediately without 
  706.                performing any user interaction.  Do not set up the REXX return 
  707.                values as per the state of that window.  If you want to close 
  708.                all open windows, including the Main Window, then pass a 
  709.                WindowTitle arg of '""' (ie, two double quotes inside of two 
  710.                single quotes). 
  711.  
  712. 255            Clear out the PM message queue without performing any user 
  713.                interaction nor closing any windows nor setting up any REXX 
  714.                variables.  This is just to prevent PM lockups if you have 
  715.                windows open, and your script is not "sleeping" (ie, doing some 
  716.                call to RXDLG that performs user interaction). 
  717.  
  718. Dimensions     The name of a REXX variable that is a string containing the 
  719.                desired Width, Height, X Position, and Y Position of the window. 
  720.                These are measured in screen pixels.  X and Y positions are 
  721.                referenced to the bottom left corner of the Desktop if the 
  722.                window is a Main Window (ie, the very first window that you 
  723.                create upon the Desktop).  For example, specifying X and Y of 0 
  724.                means that the Main Window opens at the bottom left corner of 
  725.                the Desktop.  All other windows that you create after the Main 
  726.                Window are Child Dialogs, and their X and Y positions are 
  727.                referenced to the bottom left corner of the Main Window (as 
  728.                opposed to the Desktop itself).  For example, specifying X and Y 
  729.                of 0 means that the Child Dialog opens at the bottom left corner 
  730.                of the Main Window (ie, inside of the Main Window itself). 
  731.                Specifying a Width of 0 means that you want Rexx Dialog to 
  732.                determine a default size and position for the window (and the 
  733.                Height, X, and Y are ignored).  In this case, you also get a 
  734.                window that can be resized and maximized, and so the SIZE flag 
  735.                is redundant.  For example, if you wanted a window with 
  736.                Width=300, Height=200, X=10, and Y=10, then setup a variable 
  737.                with these values enclosed in quotes, and pass the name of that 
  738.                variable as the Dimensions arg: 
  739.  
  740.                Note:  Whenever Rexx Dialog closes a window, it updates the 
  741.                       Dimensions string for that window.  This is handy if you 
  742.                       want to reopen the window later.  If you pass the same 
  743.                       Dimensions string to RXDLG (without reinitializing it), 
  744.                       then the window will open with the same size and position 
  745.                       as it had when it was closed.  Rexx Dialog also updates a 
  746.                       window's Dimensions string if you specify that window in 
  747.                       Operations 2, 3, or 4.
  748.  
  749.                MyWinDimensions = '300 200 10 10' 
  750.                RXDLG 1 '"My Window Title"' 'MyWinDimensions' 
  751.  
  752.                The variable containing the dimensions can be any legal variable 
  753.                name that you wish. 
  754.  
  755. Flags          A string that describes the various display and management 
  756.                options for the window.  You can specify any or all of these 
  757.                Flags, and each one must be separated by a | character, enclosed 
  758.                in quotes.  The various Flags are: 
  759.  
  760. SIZE           You want a window that can be resized by the user (ie, has a 
  761.                border that he can grab with the mouse and move to resize the 
  762.                window).  The window will also have a maximize/restore button in 
  763.                the titlebar. 
  764.  
  765. MIN            You want a window that can be minimized by the user.  Main 
  766.                Windows are always created with a minimize button in the 
  767.                titlebar, and this flag need not be specified.  A Main Window 
  768.                minimizes into an icon on the bottom of the Desktop.  If a Child 
  769.                Dialog has a minimize control, it doesn't minimize to the bottom 
  770.                of the Desktop, but rather, the bottom left of the Main Window. 
  771.                (Be careful to not place controls there in the Main Window, or 
  772.                the child window will fall behind them). 
  773.  
  774. SMALL          When a window is first created, it starts out minimized.  The 
  775.                MIN Flag must also be set. 
  776.  
  777. MODAL          When the window is created or when performing an operation upon 
  778.                it, all other Child Dialogs and controls in the Main Window are 
  779.                disabled. 
  780.  
  781.                Note:  A Main Window cannot be created MODAL.  The MODAL Flag is 
  782.                       ignored in this case.
  783.  
  784. NOCLOSE        When a call to RXDLG returns as a result of the user doing 
  785.                something with this window, Rexx Dialog automatically closes 
  786.                this window.  NOCLOSE simply is a way of telling Rexx Dialog to 
  787.                close a window when it causes RXDLG to return, so that your 
  788.                script doesn't have to perform that extra operation (which would 
  789.                be done if the window was a one-shot type of deal, ie, where you 
  790.                wanted to get a set of data from the user once, and then dismiss 
  791.                the window). 
  792.  
  793.                Whenever the Main Window is closed, either automatically due to 
  794.                not specifying NOCLOSE, or by doing an operation upon the Main 
  795.                Window which causes it to close, all Child Dialogs are also 
  796.                automatically closed. 
  797.  
  798.                Note:  All windows have a CLOSE ICON (ie, on the left side of 
  799.                       the titlebar).  RXDLG always returns when a user clicks 
  800.                       upon a CLOSE ICON (with RXID = -98).  But a window is not 
  801.                       closed if the NOCLOSE Flag is specified.  If you specify 
  802.                       NOCLOSE, your script always has to eventually perform an 
  803.                       END operation upon a particular window in order to close 
  804.                       it (although if your script exits with any windows still 
  805.                       open, those windows are automatically closed).
  806.  
  807. RESULT         When the window has the focus, and the user presses the ESC or 
  808.                ENTER key, RXDLG returns control to your script (ie, your script 
  809.                "wakes up" from a call to RXDLG).  See ESC and ENTER Keys. 
  810.  
  811. KEYS           When the window has the focus, and the user presses some key 
  812.                combination, RXDLG returns control to your script (ie, your 
  813.                script "wakes up" from a call to RXDLG).  The RESULT Flag has 
  814.                precedence over KEYS (for ESC and ENTER), although both Flags 
  815.                can be set.  See Keyboard Input. 
  816.  
  817. ONCE           After the timer for the window times out, the timer is 
  818.                automatically disabled.  See Time-out. 
  819.  
  820. NEWSIZE        After the user resizes a window, the REXX script is notified of 
  821.                the new size.  See Resizing a window. 
  822.  
  823.                Here's an example of a Flags arg that might be passed to RXDLG: 
  824.  
  825.                'SIZE|MODAL|MIN' 
  826.  
  827.                Of course, you could also use a variable: 
  828.  
  829.                myflags = 'SIZE|MODAL|MIN' 
  830.                RXDLG 1 '"My Window Title"' 'DIMENSIONS' myflags 
  831.  
  832.                If you don't specify a Flags arg, then none of the above flags 
  833.                are enabled (ie, you get a window that can't be sized, nor 
  834.                minimized if not a Main Window, nor maximized, is not modal, 
  835.                won't recognize the ESC and ENTER keys when that window is 
  836.                active to return from RXDLG, and when it does cause RXDLG to 
  837.                return, Rexx Dialog automatically closes the window. 
  838.  
  839.                Note:  It doesn't matter in what order you specify the Flags, 
  840.                       but each must be separated from another using a | character.
  841.  
  842. Returns 
  843.  
  844. A large variety of error messages or numbers could be returned by RXDLG.  See 
  845. Errors for details. 
  846.  
  847. Examples 
  848.  
  849. See the following sections. 
  850.  
  851.  
  852. ΓòÉΓòÉΓòÉ 5.3.1. Groups ΓòÉΓòÉΓòÉ
  853.  
  854. A PM control is some graphical object (inside of a window) which the user can 
  855. manipulate with the mouse or keyboard in order to enter data.  Controls can 
  856. also be used to display data to the user. 
  857.  
  858. Rexx Dialog arranges controls into Groups.  A Group is simply one or more 
  859. instances of the same type of PM control.  For example, you can have a Group of 
  860. 3 sliders.  Or you can have a Group of 2 list boxes.  Or you can have a Group 
  861. of 16 push buttons.  Etc.  Arranging similiar controls into Groups makes it 
  862. easier for your script to define many instances of the same type of control. 
  863. That's why I defined a Group.  Of course, you could have only 1 control per 
  864. each Group, but that sort of defeats the purpose of a Group.  How does Rexx 
  865. Dialog make it easier to define a Group of controls rather than 1 control at a 
  866. time?  One thing that Rexx Dialog does is intelligently arrange and space 
  867. controls in the window.  So, if you have a Group of 32 push buttons, you don't 
  868. have to specify the width, height, X and Y positions of each one (as well as 
  869. where to place and size the label of each button).  You simply tell Rexx Dialog 
  870. where the first button is located, how many buttons there are, how many buttons 
  871. should appear upon each line, and what the width of a button is.  Rexx Dialog 
  872. will take care of positioning and spacing the other 31 push buttons, and will 
  873. arrange them symmetrically.  Secondly, if you desire a group box (ie, a 
  874. rectangular border that surrounds all of the controls in the group, and which 
  875. has its own label), Rexx Dialog intelligently figures out how to size and 
  876. position that group box.  You merely have to specify the label for that group 
  877. box.  Also, you typically may want the same kind of behavior for all of the 
  878. same type of controls.  For example, maybe you want 10 list boxes, and you want 
  879. them all to be able to select multiple items in their lists.  You don't have to 
  880. specify that you want multiple select for each list box.  You simply define all 
  881. the list boxes within one group, and say that you want the group to be multiple 
  882. select.  Finally, Rexx Dialog allows you to apply certain types of editing or 
  883. initializing to an entire group.  For example, if you have 32 push buttons and 
  884. you want to clear the checkmarks of all of them, you simply say that you want 
  885. to clear the Group. 
  886.  
  887. Rexx Dialog doesn't limit you to only one Group within a window, nor one Group 
  888. Type within a window.  For example, you can have a Group of 3 sliders, and then 
  889. above them, in the same window, have a Group of list boxes.  As another 
  890. example, you can have a Group of list boxes that are multiple select, and in 
  891. the same window, have another Group of list boxes that are single select. 
  892.  
  893. Defining controls in Groups is an easy way to define lots of similiar controls. 
  894. But, because a Group can be merely 1 control, you can also have plenty of 
  895. flexibility on an individual control basis if need be.  Also, because you only 
  896. need specify the X and Y position of the entire Group (and Rexx Dialog does 
  897. positioning of individual controls), it's easy to change the position of 
  898. Grouped controls. 
  899.  
  900. There are several Types of Groups.  They are: 
  901.  
  902.    Push Button (PUSH) 
  903.    Radio Button (RADIO) 
  904.    Checkmark Button (CHECK) 
  905.    Result Button (RESULT) 
  906.    Entry (ENTRY) 
  907.    List Box (LIST) 
  908.    Drop Box (DROP) 
  909.    Spin Button (SPIN) 
  910.    Slider (SLIDER) 
  911.    Text (TEXT) 
  912.    Group Box (GROUP) 
  913.    Menu (MENU) 
  914.  
  915. Each Type has its own options (ie, Flags) and a particular way in which you 
  916. must setup REXX variables to define that Group. 
  917.  
  918. You must use particular REXX stem variables when you define the Groups in a 
  919. window.  These stem variables are: 
  920.  
  921.    RXTYPE 
  922.    RXX 
  923.    RXY 
  924.    RXFLAGS 
  925.    RXLABEL 
  926.    RXINFO 
  927.    RXVAL 
  928.  
  929. RXTYPE         The Group Type.  If you look at the above list of Types, you'll 
  930.                see the values for Type in parentheses.  So, to define a Spin 
  931.                Button Group, you would set RXTYPE to 'SPIN'. 
  932.  
  933. RXFLAGS        May be interpreted differently for various Types.  It describes 
  934.                particular behavior and display options you want for this Group. 
  935.                For example, a Group of list boxes may have RXFLAGS set to 
  936.                'INDEX|MULTIPLE'.  Each Group Type's Flags will be described 
  937.                further in later sections. 
  938.  
  939. RXLABEL        May also be interpreted a little differently for various Types, 
  940.                but for most Types, it is simply the Text Labels for all of the 
  941.                controls within the Group, and the Label for any group box which 
  942.                surrounds this Group.  It will be set to one string that 
  943.                contains the label for each control, starting with the first 
  944.                control, and each label is separated from the next by a | 
  945.                character.  The group box label will be last (if it is specified 
  946.                at all.  If not specified, then no group box is created around 
  947.                the controls).  For example, if you have 3 list boxes named 
  948.                "Fruits", "Vegetables", and "Meats" respectively, plus a 
  949.                surrounding group box labeled "Food Groups", then RXLABEL would 
  950.                be set to 'Fruits | Vegetables | Meats | Food Groups'. 
  951.  
  952.                Note:  You can omit or add blank spaces between the labels and | 
  953.                       character.  The above example could also be: 
  954.                       'Fruits|Vegetables|Meats|Food Groups' 
  955.                       or 
  956.                       '   Fruits   |  Vegetables  |    Meats   |  Food Groups' 
  957.                       with the same results.  Rexx Dialog trims leading and 
  958.                       trailing spaces off of each label.
  959.  
  960.                If a particular control is not to be labeled, then simply leave 
  961.                a blank space where its label would go.  For example, to create 
  962.                the "Meats" list box unlabeled, set RXLABEL to 'Fruits | 
  963.                Vegetables | | Food Groups".  You can omit the spaces and it 
  964.                becomes 'Fruits|Vegetables||Food Groups'.  If you don't want the 
  965.                group box, simply omit its label, ie, 'Fruits|Vegetable|Meats'. 
  966.                In fact, if you specify less labels than there are controls 
  967.                within a Group, then the remaining controls are unlabeled.  For 
  968.                example, to only label the first 2 list boxes, not label the 
  969.                third one, and omit the group box, set RXINFO to 
  970.                'Fruits|Vegetables'. 
  971.  
  972.                Placing a ~ character before any letter in the label causes that 
  973.                letter to be underlined.  This is handy for identifying 
  974.                "keyboard shortcuts" to the user (which your script will 
  975.                implement using the window's KEYS Flag, and processing Keyboard 
  976.                Input). 
  977.  
  978.                The first control in the group appears closest to the lower left 
  979.                corner of the Desktop or Main Window.  This is how OS/2 defines 
  980.                coordinates.  (I would have preferred a top-down approach). 
  981.  
  982. RXINFO         A string that may be interpreted differently for various Types, 
  983.                but in some way, it describes how many controls are contained in 
  984.                the Group.  It may also describe things like how wide (in 
  985.                pixels) a control should be, how many controls should be placed 
  986.                upon each line, and also any other information particular to a 
  987.                certain Group Type.  For most all Group Types, the first 3 
  988.                components in the RXINFO string are the number of controls in 
  989.                the Group (ie, which I'll refer to as TotalControls), how many 
  990.                controls appear per line (ControlsPerLine), and how wide a 
  991.                control should be (WidthOfControl). (You only have to describe 
  992.                the control height for certain Types. Most Types have a standard 
  993.                height).  For some controls, such as PUSH, RESULT, CHECK, RADIO, 
  994.                and TEXT, a width of 0 tells Rexx Dialog to calculate the best 
  995.                fit.  How each Group Type utilizes RXINFO will be described 
  996.                further in later sections. 
  997.  
  998. RXVAL          A string that may be interpreted differently for various Types, 
  999.                but in some way, it initializes the values of the controls (ie, 
  1000.                it's either a string that contains the value of each control, or 
  1001.                contains the names of stem variables where Rexx Dialog finds the 
  1002.                values for the controls).  Rexx Dialog also uses the same RXVAL 
  1003.                to return the data that the user enters via the controls in that 
  1004.                Group.  How each Group Type utilizes RXVAL  will be described 
  1005.                further in later sections. 
  1006.  
  1007. RXX            The X position of the Group (ie, where along the X axis the 
  1008.                first control within the Group should be positioned in a 
  1009.                window).  This is measured relative to the lower left corner of 
  1010.                the Desktop (if a Main Window) or the Main Window's lower left 
  1011.                corner (if a Child Dialog).  In other words, this is how far 
  1012.                away from the left border of the Desktop or Main Window, you 
  1013.                want the Group of controls to be displayed.  If a group box is 
  1014.                to be included, move the group farther to the right in order to 
  1015.                make room for the box. 
  1016.  
  1017. RXY            The Y position of the Group (ie, where along the Y axis the 
  1018.                first control within the Group should be positioned in a 
  1019.                window).  This is measured relative to the lower left corner of 
  1020.                the Desktop (if a Main Window) or the Main Window's lower left 
  1021.                corner (if a Child Dialog).  In other words, this is how far up, 
  1022.                from the bottom border of the Desktop or Main Window, you want 
  1023.                the Group of controls to be displayed.  If a group box is to be 
  1024.                included, move the group up higher in order to make room for the 
  1025.                box. 
  1026.  
  1027. The stem on these variable names pertains to which Group you're defining. 
  1028. Don't get nervous.  I'm going to explain this.  Haven't I done OK so far? 
  1029.  
  1030. For example, let's say that you want a Group of 3 sliders, a Group of 2 spin 
  1031. buttons, and a Group of 4 push buttons in a window.  That's 3 Groups.  Let's 
  1032. say that you want the sliders to be Group 1, the spin buttons are Group 2, and 
  1033. the push buttons are Group 3. That means that, when you describe the slider 
  1034. group, the variables names that you use are RXTYPE.1, RXX.1, RXY.1, RXFLAGS.1, 
  1035. RXLABEL.1, RXINFO.1, and RXVAL.1.  When you describe the spin button group, the 
  1036. variables names that you use are RXTYPE.2, RXX.2, RXY.2, RXFLAGS.2, RXLABEL.2, 
  1037. RXINFO.2, and RXVAL.2.  When you describe the push button group, the variables 
  1038. names that you use are RXTYPE.3, RXX.3, RXY.3, RXFLAGS.3, RXLABEL.3, RXINFO.3, 
  1039. and RXVAL.3.  What variables would you use to describe a fourth Group of 
  1040. controls in the window?  Yep.  RXVAL.4, etc.  See, that wasn't so bad, was it? 
  1041.  
  1042. OK, now it's time for an example.  Let's implement the above example.  Don't 
  1043. worry about what the particular strings for RXVAL, RXINFO, and RXFLAGS mean for 
  1044. each Type.  Just note how I define the 3 Groups (which can be done in any 
  1045. order, or at any time as long as this is done before the call to RXDLG).  Pay 
  1046. attention to the commented lines. 
  1047.  
  1048. /* First Group (ie, the 3 sliders) */ 
  1049. RXTYPE.1 = 'SLIDER'  /* SLIDER Type */ 
  1050. RXFLAGS.1 = ' ' 
  1051. RXLABEL.1 = '128 255 Slider 1: | 64 0 Slider 2: | 128 0 Slider 3: | Slide Us' 
  1052. RXVAL.1 = '64 32' 
  1053. RXINFO.1 = '3 1 142'   /* TotalControls, ControlsPerLine, WidthOfControl */ 
  1054. RXX.1 = 80          /* X position of first control (ie, the Group) */ 
  1055. RXY.1 = 18          /* X position of first control (ie, the Group) */ 
  1056.  
  1057. /* Second Group (ie, the 2 spin buttons) */ 
  1058. RXTYPE.2 = 'SPIN'    /* SPIN Type */ 
  1059. RXFLAGS.2 = ' ' 
  1060. RXLABEL.2 = '128 0 Spin 1: | 64 0 Spin 2: | Spin Us' 
  1061. RXVAL.2 = '10 20' 
  1062. RXINFO.2 = '2 1 90'   /* TotalControls, ControlsPerLine, WidthOfControl */ 
  1063. RXX.2 = 320          /* X position of first control (ie, the Group) */ 
  1064. RXY.2 = 18          /* X position of first control (ie, the Group) */ 
  1065.  
  1066. /* Third Group (ie, the 4 push buttons) */ 
  1067. RXTYPE.3 = 'PUSH'    /* PUSH Type */ 
  1068. RXFLAGS.3 = ' ' 
  1069. RXLABEL.3 = 'Push 1 | Push 2 | Push 3 | Push Us' 
  1070. RXVAL.3 = '' 
  1071. RXINFO.3 = '3 3 0'    /* TotalControls, ControlsPerLine, WidthOfControl (best 
  1072. fit) */ 
  1073. RXX.3 = 90         /* X position of first control (ie, the Group) */ 
  1074. RXY.3 = 100        /* X position of first control (ie, the Group) */ 
  1075.  
  1076. /* Now that you've defined the 3 Groups, you can create a window containing 
  1077. them.  Let's call it "Main Window" (since it will be the first window that we 
  1078. open, and therefore, the Main Window).  Note that I specify NumGroups arg as 3 
  1079. */ 
  1080.  
  1081. windowSize = ''     /* Default */ 
  1082. RXDLG 3 '"Main Window"' 'windowSize' 'RESULT' 
  1083.  
  1084. /* After the window is created, you can DROP those REXX variables used for such 
  1085. if desired, in order to conserve memory. It's recommended that you leave RXVAL 
  1086. and all windows Dimensions strings. */ 
  1087. DROP RXTYPE. RXFLAGS. RXLABEL. RXINFO. RXX. RXY. 
  1088.  
  1089. /* Perform user interaction, such as wait for him to click the window CLOSE 
  1090. ICON */ 
  1091. RXDLG 
  1092.  
  1093. Copy the above example to a file and run it with RX.EXE. 
  1094.  
  1095. Note:  It doesn't matter in what order you assign the variables.  For example, 
  1096.        you can setup the variable RXINFO.1 before you setup RXTYPE.1.  The only 
  1097.        important consideration is setting up all variables before the call to RXDLG.
  1098.  
  1099.  
  1100. ΓòÉΓòÉΓòÉ 5.3.2. Managing a PM Interface ΓòÉΓòÉΓòÉ
  1101.  
  1102. In order to interact with the user (ie, get input from him and display output 
  1103. to him), your script will need to use one or more PM windows (with PM controls 
  1104. inside of them). 
  1105.  
  1106. To create a window, you use the first template of RXDLG.  Call RXDLG with the 
  1107. NumGroups parameter greater than 0 (ie, you always have to specify at least 1 
  1108. Group of controls).  This tells RXDLG that you wish to create a window with 
  1109. that many Groups of controls inside of it.  RXDLG will query all of the 
  1110. variables that your script setup in order to create, initialize, and display 
  1111. that window and its controls.  If this is the first window to be displayed, it 
  1112. becomes the Main Window and all other windows (ie, Child Dialogs) open inside 
  1113. of this window.  The window is given the title that you specified to RXDLG. 
  1114.  
  1115. Note:  Each window should have a distinct title.
  1116.  
  1117. After RXDLG creates the window, it will return immediately.  Although the 
  1118. window is displayed, the user will not be able to interact with it yet.  At 
  1119. that point, you can do further initialization if desired.  One thing that you 
  1120. can do is call RXDLG again, using its first template, to create another window. 
  1121. You can have as many windows simultaneously open as desired (PM resources 
  1122. permitting), each containing its own (perhaps unique) Groups of controls. 
  1123.  
  1124. Then, you'll make one or more calls to RXDLG using the second template to 
  1125. manage the PM interface.  In the second template of RXDLG, you specify what 
  1126. operation you wish to perform on the PM interface, where such operations 
  1127. include allowing the user to interact with one or all open windows and perhaps 
  1128. return user input to the script, and eventually closing down windows. 
  1129.  
  1130. The following discussion is for RXDLG Operations that perform user interaction 
  1131. (ie, 0 and 1), and may not pertain to other RXDLG Operations. 
  1132.  
  1133. When you perform an RXDLG Operation that allows the user to interact with the 
  1134. windows (and the PM controls within them), RXDLG does not return immediately. 
  1135. Instead, your script "goes to sleep" while Rexx Dialog manages the user's 
  1136. interaction and all of the PM processing associated with that.  In other words, 
  1137. while the user is interacting with the windows\controls, your script is locked 
  1138. inside of that call to RXDLG.  (The exception to this is RXDLG Operations that 
  1139. don't perform user interaction, such as operations 2, 3, 4, and 255).  When 
  1140. RXDLG returns control to your script, then the user can't interact with the 
  1141. windows anymore (until you again call RXDLG to perform an Operation that allows 
  1142. the user to interact with the windows\controls).  So, think of RXDLG as a way 
  1143. for you to pass control to Rexx Dialog (and the user).  When RXDLG returns, it 
  1144. is passing control back to your script (and away from the user). 
  1145.  
  1146. While Rexx Dialog has control, the user is free to manipulate the windows (and 
  1147. controls within them) in any order that he wishes.  (The exception to this is 
  1148. for a window with its MODAL Flag set).  For example, if there are 3 windows 
  1149. open, the user can click upon any one of them to make it the active window, and 
  1150. then activate any control inside of that window.  Therefore, your script can 
  1151. never make any assumptions about which window and control the user has 
  1152. manipulated.  Instead, Rexx Dialog will keep track of that information, and 
  1153. sets some REXX variables in your script which you can then examine (after RXDLG 
  1154. returns) to determine which window and control has been manipulated. 
  1155.  
  1156. There are a number of actions the user could do which would cause RXDLG to 
  1157. return (ie, and therefore return control to your script).  They are: 
  1158.  
  1159.  1. If the script is launched by some application other than RX.EXE, and that 
  1160.     app wants the script to abort (ie, EXIT). 
  1161.  
  1162.  2. He clicks upon the CLOSE ICON of a window. 
  1163.  
  1164.  3. If the window's RESULT Flag is set, and the window itself has the focus 
  1165.     (ie, the window is active, but no control within it is activated), he 
  1166.     presses the ESC key. 
  1167.  
  1168.  4. If the window's RESULT Flag is set, and the window itself has the focus, he 
  1169.     presses the ENTER key. 
  1170.  
  1171.  5. The window's timeout is enabled, and the timeout expires. 
  1172.  
  1173.  6. If the window's KEYS Flag is set, and the window itself has the focus, he 
  1174.     presses some key on the computer's keyboard. 
  1175.  
  1176.  7. He clicks upon some button in a RESULT Group. 
  1177.  
  1178.  8. He finishes using some control that is in a Group with its END Flag set. 
  1179.  
  1180. Before RXDLG returns control to your script, it sets up all returned variables 
  1181. (ie, RXVAL, RXWIND, RXID, RXSUBID, the window's Dimensions string, etc) per the 
  1182. state of this window (and its Groups). (The exception to this is RXDLG 
  1183. Operations that specifically don't want the return values setup, such as 
  1184. operation 4).  RXDLG will also close the window that caused the return unless 
  1185. the window's NOCLOSE Flag is set.  (The exception to this is with KEYS 
  1186. processing.  Although RXDLG returns control to your script when the user 
  1187. presses a key, the window is not closed, and only the variables RXID, RXSUBID, 
  1188. and RXWIND are setup.  Another exception is for action #1, an app indicating to 
  1189. abort.  In this case, only RXWIND, RXID, and RXSUBID are setup). 
  1190.  
  1191. If the user was able to interact with more than one window during the call to 
  1192. RXDLG, then your script needs to examine the RXWIND variable.  This is set to 
  1193. the title of the window which caused RXDLG to return.  Typically, each window 
  1194. would be associated with some operation that your script performs.  You'd do a 
  1195. SELECT on RXWIND, comparing it to the titles of all of your windows, and when 
  1196. you found the match, you'd carry out the operation associated with that window. 
  1197.  
  1198. There are 2 variables that let you determine exactly what the user did to cause 
  1199. RXDLG to return (from the above list).  Those variables are RXID and RXSUBID. 
  1200. First, you examine RXID.  If the user manipulated some control in the window, 
  1201. then RXID is set to the Group number that control is within (where the first 
  1202. Group is number 1).  For example, if the first Group in the window contains 5 
  1203. PUSH buttons, and the user pressed one of those buttons, then RXID will be 1 to 
  1204. indicate that he used a control in Group 1.  (This assumes that the Group has 
  1205. its END Flag set so that it causes RXDLG to return).  RXSUBID is set to the 
  1206. control number that was manipulated in that Group (where the first control is 
  1207. number 1).  Let's say that he pushed the third button in that Group.  RXSUBID 
  1208. will be 3. 
  1209.  
  1210. If RXID is 0 or some negative number, this indicates that what caused RXDLG to 
  1211. return wasn't due to the user manipulating some control within a Group, but 
  1212. rather, one of the first 6 actions listed above occurred.  Both RXID and 
  1213. RXSUBID are 0 if a timeout occurred (ie, the window timer timed out before any 
  1214. of the other 6 actions could occur).  RXID will be -98 if the window's CLOSE 
  1215. ICON was clicked.  RXID will be -12 if the ESC key was pressed. RXID will be 
  1216. -20 if the window was resized (and you specified the NEWSIZE Flag).  If the 
  1217. script is launched by some application other than RX.EXE (the app must be 
  1218. written to specifically use RXDLG.DLL), and that app wants the script to abort 
  1219. (ie, EXIT), then RXID will be -99.  If the user pressed some other key on the 
  1220. keyboard, RXID will be between 0 and -11 (depending upon whether the ALT, 
  1221. SHIFT, and\or CTRL keys were held down too, and whether the key is a printable 
  1222. character such as "s" or unprintable such as the HOME key), and RXSUBID will 
  1223. identify that particular key (as described in Keyboard Input). 
  1224.  
  1225. Based upon RXWIND, RXID, and RXSUBID, your script will decide what operation it 
  1226. wishes to perform (perhaps using the other REXX variables which were setup to 
  1227. the "values" of all of the controls in the window specified by RXWIND).  It's 
  1228. possible that this operation could involve opening more windows and getting 
  1229. even more user input.  After this operation is complete, the script will either 
  1230. terminate, or loop back to calling RXDLG to do some more user interaction (ie, 
  1231. if you want to give the user an opportunity to repeat an operation with a new 
  1232. set of input). 
  1233.  
  1234. If the script does continually loop around, getting new sets of user input, 
  1235. you'll need a method of breaking out of the loop and exiting from your REXX 
  1236. script.  Typical ways include checking if the user has clicked upon the Main 
  1237. Window's CLOSE ICON, checking if the user has selected a "Quit" menu label (if 
  1238. you add such to the window), or checking if the user has pressed the ESC key 
  1239. (or pressed some key combo, or manipulated some control, that you have deemed 
  1240. will be interpreted as a signal to quit the program).  If your script is 
  1241. launched by some app other than RX.EXE, you'll also want to check for a signal 
  1242. to abort. 
  1243.  
  1244. Refer to the RXDLG section for details on the args passed to RXDLG. 
  1245.  
  1246.  
  1247. ΓòÉΓòÉΓòÉ 5.3.3. Group Types ΓòÉΓòÉΓòÉ
  1248.  
  1249. The next sections explain the details about each Group Type (ie, and offer a 
  1250. detailed explanation of some of the variables mentioned in Groups, which can be 
  1251. interpreted differently for each Group). 
  1252.  
  1253.  
  1254. ΓòÉΓòÉΓòÉ 5.3.3.1. Push Button ΓòÉΓòÉΓòÉ
  1255.  
  1256. Type           PUSH 
  1257.  
  1258. Description    A push button is a graphical, square button with the label 
  1259.                inside of the button itself. 
  1260.  
  1261.                A user can move the mouse pointer over the button and press (and 
  1262.                hold down) the mouse button.  The button will visually depress 
  1263.                as if the mouse pointer were a finger pushing down upon the 
  1264.                button.  When the user releases the mouse button, so too does 
  1265.                the mouse release the push button, and that's when it becomes 
  1266.                activated (ie, like a "momentary switch").  Alternately, 
  1267.                pressing the SPACE BAR will activate the button which currently 
  1268.                has the focus (ie, is highlighted). 
  1269.  
  1270.                When the user activates a push button, RXDLG returns if the END 
  1271.                Flag for its Group is specified. 
  1272.  
  1273.                There are a maximum of 32 buttons per Group. 
  1274.  
  1275. Uses           Push buttons are usually used to launch operations, such as to 
  1276.                begin a file save or load, or initiate an action such as to 
  1277.                create another window. 
  1278.  
  1279. REXX Setup 
  1280.  
  1281. RXINFO is a string specifying the TotalControls, ControlsPerLine, and 
  1282. WidthOfControl.  If WidthOfControl is 0, then Rexx Dialog calculates a "best 
  1283. fit".  If you specify a non-zero width, make sure that it is large enough or 
  1284. the button's label will be visually clipped. 
  1285.  
  1286. RXLABEL is as described in Groups.  But, if a Label for a particular button is 
  1287. omitted, then that button is not placed upon the display, and its number is 
  1288. skipped.  In this way, you can determine how you want to number the buttons 
  1289. upon the display.  For example, let's say that you want 3 buttons on the 
  1290. display.  But, you want the first button (which we'll label as "One") to be #1, 
  1291. the second button ("Two") to actually count itself as #3, and the third button 
  1292. ("Three") to count itself as #5 (ie, you want to skip #2 and #4).  You would 
  1293. omit labels for buttons 2 and 4.  Therefore, RXLABEL would be 'One | | Two | | 
  1294. Three'.  In this way, the "values" of the second and third buttons are 3 and 5. 
  1295. Note that if you skip buttons, you still have to count them in RXINFO's 
  1296. TotalControls.  For example, here TotalControls would be 5 (ie, TotalControls 
  1297. reflects how many labels you supply, not how many buttons are displayed). 
  1298.  
  1299. Note:  OS/2 REXX appears to have a bug in it regarding null strings.  A null 
  1300.        string is supposed to simply be quotes without any characters in 
  1301.        between, but OS/2 REXX doesn't like this in assignments (ie, when you 
  1302.        assign a variable to be a null string).  It likes to see at least 1 
  1303.        character between the quotes.  So instead of myvar = '', use myvar = ' ' 
  1304.        whenever assigning a null string to a label variable (or any other 
  1305.        variable that specifies a string rather than a numeric value).
  1306.  
  1307. RXVAL is a string specifying which button is initially selected by default. 
  1308. For example, if the first button is to be selected, then RXVAL = '1'.  If you 
  1309. don't want any default selection, then set RXVAL to a null string (ie, '').  By 
  1310. doing the latter, you can examine the return that Rexx Dialog gives for this 
  1311. Group, and determine whether the user selected any button at all.  Note that 
  1312. you must consider any skipped values when specifying button numbers in the 
  1313. RXVAL string. 
  1314.  
  1315. RXFLAGS can be any, all, or none of the following: 
  1316.  
  1317. 'NUMBERED'     Rexx Dialog automatically labels the buttons with numbers, (ie, 
  1318.                the first button has a label of '1', the second button is '2', 
  1319.                etc).  Therefore, you don't have to specify any of the button 
  1320.                labels in RXLABEL.  RXLABEL will simply be the group box label 
  1321.                (or a null string if no group box is desired). 
  1322.  
  1323. 'END'          Causes RXDLG to return (with all RXVALs set for all Groups in 
  1324.                the active dialog window, including this button group) when the 
  1325.                user selects one of the buttons in this group. 
  1326.  
  1327. REXX Return 
  1328.  
  1329. Rexx Dialog returns this Group's RXVAL variable set to which button was pushed. 
  1330. For example, if the second button was pushed, then RXVAL is set to '2'.  Note 
  1331. that if buttons were skipped, the numbering reflects that.  In the above 
  1332. example, if the user pushed the third button, it really has a value of 5 
  1333. (because 2 and 4 were skipped), and so RXVAL is set to '5'.  If you initially 
  1334. specified no default, and the user never pushed any button before the dialog 
  1335. window containing this group caused RXDLG to return, then RXVAL would be a null 
  1336. string. 
  1337.  
  1338. Examples 
  1339.  
  1340. /* This creates a window called "Push Stuff" containing 1 Group of 3 push 
  1341. buttons labeled "High", "Mid", "Low", with a group box labeled "Tone".  Each 
  1342. button appears upon its own line (ie, they are stacked in a column), ie, 
  1343. ControlsPerLine=1.  Rexx Dialog calculates a best fit for width of each button. 
  1344. Selecting one of the buttons in this Group causes RXDLG to return (and also 
  1345. causes the dialog containing these buttons to be destroyed if the dialog isn't 
  1346. NOCLOSE).  There is no initial default selection.  */ 
  1347.  
  1348. RXTYPE.1 = 'PUSH' 
  1349.  
  1350. /* Cause RXDLG to return */ 
  1351. RXFLAGS.1 = 'END' 
  1352.  
  1353. /* NumOfControls, ControlsPerLine, WidthOfControl */ 
  1354. RXINFO.1 = '3 1 0' 
  1355.  
  1356. /* Labels for buttons, and group box */ 
  1357. RXLABEL.1 = 'High|Mid|Low|Tone' 
  1358.  
  1359. /* No default */ 
  1360. RXVAL.1 = '' 
  1361.  
  1362. /* Position */ 
  1363. RXX.1 = 10 
  1364. RXY.1 = 10 
  1365.  
  1366. /* Create "Push Stuff" window */ 
  1367. RXDIM = '80 160 50 50' 
  1368. RXDLG 1 '"Push Stuff"' 'RXDIM' 'RESULT' 
  1369.  
  1370. /* Display the selection */ 
  1371. RXSAY 'Chose button #'RXVAL.1 
  1372.  
  1373.  
  1374. ΓòÉΓòÉΓòÉ 5.3.3.2. Radio Button ΓòÉΓòÉΓòÉ
  1375.  
  1376. Type           RADIO 
  1377.  
  1378. Description    A radio button is a graphical, round button that is filled in 
  1379.                with a different color depending upon whether the button is "on" 
  1380.                or "off".  The label is immediately to the right of the button. 
  1381.  
  1382.                A radio button's state turns "on", and stays "on", when the user 
  1383.                activates it.  Like the push button, the user activates a radio 
  1384.                button when he clicks the mouse upon it.  Alternately, pressing 
  1385.                the SPACE BAR will activate the button which currently has the 
  1386.                focus (ie, is highlighted). But, only one radio button in a 
  1387.                group can be activated (ie, turned "on") at any given moment. 
  1388.                When a particular radio button is activated, any other button 
  1389.                that was "on" is automatically turned off, and only the newly 
  1390.                activated button is turned "on".  In other words, only one 
  1391.                button is ever "on" at any given moment, and all others in the 
  1392.                Group are "off". 
  1393.  
  1394.                When the user activates a radio button, RXDLG returns if the END 
  1395.                Flag for its Group is specified. 
  1396.  
  1397.                There are a maximum of 32 buttons per Group. 
  1398.  
  1399. Uses           Radio buttons are used to allow the user to choose one (and only 
  1400.                one) item from several available choices. For example, there may 
  1401.                several radio buttons, each offering a different "paper size" 
  1402.                for a printing job, and the user must choose one size. 
  1403.  
  1404. REXX Setup 
  1405.  
  1406. Setup is exactly the same as per the Push Button Group. 
  1407.  
  1408. REXX Return 
  1409.  
  1410. Return is exactly the same as per the Push Button Group. 
  1411.  
  1412. Examples 
  1413.  
  1414. /* This creates a window called "Radio" containing 1 Group of 4 radio buttons. 
  1415. Rexx Dialog labels them with numbers (ie, 'NUMBERED' Flag), so RXLABEL is the 
  1416. group box label only.  There are 2 buttons per line.  We specify a width of 30. 
  1417. Selecting a button in this Group DOESN'T cause RXDLG to return because we 
  1418. didn't specify 'END' Flag.  When the Group first appears, button 3 is selected 
  1419. */ 
  1420.  
  1421. RXTYPE.1 = 'RADIO' 
  1422.  
  1423. /* Let Rexx Dialog label all of the buttons with numbers */ 
  1424. RXFLAGS.1 = 'NUMBERED' 
  1425.  
  1426. /* NumOfControls, ControlsPerLine, WidthOfControl */ 
  1427. RXINFO.1 = '4 2 30' 
  1428.  
  1429. /* Group box label */ 
  1430. RXLABEL.1 = 'Numbers' 
  1431.  
  1432. /* Default is button 3 */ 
  1433. RXVAL.1 = '3' 
  1434.  
  1435. /* Position */ 
  1436. RXX.1 = 10 
  1437. RXY.1 = 7 
  1438.  
  1439. /* Create "Radio" window */ 
  1440. RXDIM = '100 110 50 50' 
  1441. RXDLG 1 '"Radio"' 'RXDIM' 'RESULT' 
  1442.  
  1443. /* Display the selection */ 
  1444. RXSAY 'Chose button #'RXVAL.1 
  1445.  
  1446.  
  1447. ΓòÉΓòÉΓòÉ 5.3.3.3. Checkmark Button ΓòÉΓòÉΓòÉ
  1448.  
  1449. Type           CHECK 
  1450.  
  1451. Description    A checkmark button is a graphical, square button that is filled 
  1452.                in with a graphical checkmark depending upon whether the button 
  1453.                is "on" or "off".  The label is immediately to the right of the 
  1454.                button. 
  1455.  
  1456.                A checkmark button's state toggles between "on" and "off" each 
  1457.                time that the user activates it. (ie, If it's currently "off" 
  1458.                when he activates it, it turns "on" and stays "on", and vice 
  1459.                versa).  Like the push button, the user activates a checkmark 
  1460.                button when he clicks the mouse upon it.  Alternately, pressing 
  1461.                the SPACE BAR will activate the button which currently has the 
  1462.                focus (ie, is highlighted).  But, unlike radio buttons, each 
  1463.                checkmark's state is independent of the others in the Group. 
  1464.                So, all of them can be turned "on", or all of them can be turned 
  1465.                "off", or any combination inbetween. 
  1466.  
  1467.                When the user activates a checkmark button, RXDLG returns if the 
  1468.                END Flag for its Group is specified. 
  1469.  
  1470.                There are a maximum of 32 buttons per Group. 
  1471.  
  1472. Uses           Checkmark buttons are used to allow the user to choose any, all, 
  1473.                or no items from several available choices. For example, there 
  1474.                may several checkmark buttons, each offering a different style 
  1475.                for a font (ie, underlined, italic, boldface), and the user can 
  1476.                choose any/all/none of those choices to be applied to the font 
  1477.                simultaneously. 
  1478.  
  1479. REXX Setup 
  1480.  
  1481. Setup is exactly the same as per the Push Button Group, except that more than 
  1482. one button can be specified for the RXVAL string.  For example, if you want 
  1483. checkmark buttons 1, 4, and 6 checked initially, then set RXVAL to '1 4 6'.  It 
  1484. doesn't matter in which order you specify the selected buttons, so '6 4 1' 
  1485. would be the same as '1 6 4'. 
  1486.  
  1487. Also, RXFLAGS has one more option: 
  1488.  
  1489. ALLNONE        Two push buttons are displayed above all of the checkmark 
  1490.                buttons.  One push button is labeled "All".  If this is pushed, 
  1491.                it automatically forces all of the checkmark buttons to be 
  1492.                selected (ie, checked).  The other button is "None", and forces 
  1493.                all checkmark buttons to be deselected (ie, clears the checks). 
  1494.  
  1495. REXX Return 
  1496.  
  1497. Rexx Dialog returns this Group's RXVAL variable set to only those buttons that 
  1498. are checked (ie, selected).  For example, if the user selected buttons 4 and 5, 
  1499. then RXVAL is '4 5'.  The buttons are always ordered from lowest to highest 
  1500. numbers. 
  1501.  
  1502. Examples 
  1503.  
  1504. /* This creates a window called "Checks" containing a Group of 3 checkmarks 
  1505. labeled "Bold", "Italic", and "Underline", with no group box. There are 3 
  1506. buttons per line (so all 3 are on one line). We let Rexx Dialog calculate a 
  1507. best fit.  Selecting a button in this Group DOESN'T cause RXDLG to return 
  1508. because we didn't specify 'END' Flag.  When the Group first appears, buttons 1 
  1509. and 3 are selected.  There are also "All" and "None" push buttons */ 
  1510.  
  1511. RXTYPE.1 = 'CHECK' 
  1512.  
  1513. /* Add ALL\NONE push buttons */ 
  1514. RXFLAGS.1 = 'ALLNONE' 
  1515.  
  1516. /* NumOfControls, ControlsPerLine, WidthOfControl (best fit) */ 
  1517. RXINFO.1 = '3 3 0' 
  1518.  
  1519. /* Label for checkmarks, and group box */ 
  1520. RXLABEL.1 = 'Bold|Italic|Underline' 
  1521.  
  1522. /* Check buttons 1 and 3 */ 
  1523. RXVAL.1 = '1 3' 
  1524.  
  1525. /* Position */ 
  1526. RXX.1 = 7 
  1527. RXY.1 = 7 
  1528.  
  1529. /* Create "Checks" window */ 
  1530. RXDIM = '260 80 40 40' 
  1531. RXDLG 1 '"Checks"' 'RXDIM' 'RESULT' 
  1532.  
  1533. /* Display the selections (ie, more than 1 button can be selected. We need to 
  1534. parse the RXVAL string to remove each selected button number, and then we 
  1535. simply display its respective label */ 
  1536. DO UNTIL RXVAL.1 <= '' 
  1537.   PARSE VAR RXVAL.1 button RXVAL.1 
  1538.   IF button = 1 THEN RXSAY 'Chose Bold' 
  1539.   IF button = 2 THEN RXSAY 'Chose Italic' 
  1540.   IF button = 3 THEN RXSAY 'Chose Underline' 
  1541. END 
  1542.  
  1543.  
  1544. ΓòÉΓòÉΓòÉ 5.3.3.4. Result Button ΓòÉΓòÉΓòÉ
  1545.  
  1546. Type           RESULT 
  1547.  
  1548. Description    A result button is a special, preset collection of push buttons. 
  1549.                You have a choice of labeled buttons, including OK, CANCEL, YES, 
  1550.                NO, RETRY, IGNORE, ON, OFF, START, or STOP.  Any or all of these 
  1551.                buttons can be specified, and they are created upon one line. 
  1552.                When the user activates a result button, it always causes RXDLG 
  1553.                to return. 
  1554.  
  1555. Uses           Used mostly to end a dialog, after the user has set up all other 
  1556.                controls in the dialog window to desired values.  Depending upon 
  1557.                which one of the result buttons was selected, the script can 
  1558.                then perform an operation using the values of the dialog's 
  1559.                controls, or abort a pending operation. 
  1560.  
  1561. REXX Setup 
  1562.  
  1563. RXINFO is a string containing which preset buttons to display.  Here are the 
  1564. values for the available buttons: 
  1565.  
  1566. CANCEL    1 
  1567. OK       2 
  1568. NO       3 
  1569. YES      4 
  1570. ABORT     5 
  1571. RETRY     6 
  1572. IGNORE    7 
  1573. ENTER     8 
  1574. OFF       9 
  1575. ON       10 
  1576. STOP      11 
  1577. START     12 
  1578.  
  1579. For example, if you want the OK, CANCEL, and ABORT buttons, specify RXINFO is 
  1580. set to '1 2 5'.  It doesn't matter in what order you specify the button 
  1581. numbers. 
  1582.  
  1583. Note:  All of the buttons normally associated with "positive" responses are 
  1584.        even numbers.  All of the buttons normally associated with "negative" 
  1585.        response are odd numbers.  I refer to the positive buttons as SUCCESS 
  1586.        buttons, and the negative buttons as FAILURE buttons.
  1587.  
  1588. RXLABEL is the simply the group box label (or a null string if none). 
  1589.  
  1590. RXVAL need not be initialized. 
  1591.  
  1592. RXFLAGS can be any, all, or none of the following: 
  1593.  
  1594. 'BOOL'         Only return a 0 or 1.  If the user clicks upon one of the 
  1595.                SUCCESS buttons, return a 1.  If the user clicks upon one of the 
  1596.                FAILURE buttons, return a 0. 
  1597.  
  1598. Note:  It's not necessary to specify the 'END' Flag for a RESULT Group.  A 
  1599.        RESULT Group always causes RXDLG to return.
  1600.  
  1601. REXX Return 
  1602.  
  1603. Rexx Dialog returns this Group's RXVAL variable set to which button was pushed. 
  1604. For example, if the NO button was pushed, then RXVAL is set to '3' (unless BOOL 
  1605. Flag is specified, in which case RXVAL would be set to '0'). 
  1606.  
  1607. Note:  If a dialog is created with its RESULT Flag specified, when the user 
  1608.        presses ESC (while the dialog has the focus), any RESULTBUTTON has its 
  1609.        RXVAL return set to the lowest numbered FAILURE button in the Group. 
  1610.        For example, if you have a NO button in the Group, RXVAL is set to '3' 
  1611.        (unless BOOL Flag is specified).  When the user presses ENTER (while the 
  1612.        dialog has the focus), any RESULTBUTTON has its RXVAL return set to the 
  1613.        lowest numbered SUCCESS button in the Group.  For example, if you have 
  1614.        an OK button in the Group, RXVAL is set to '2' (unless BOOL Flag is 
  1615.        specified, in which case RXVAL is 1).
  1616.  
  1617. Examples 
  1618.  
  1619. /* This creates a window called "Result" containing a Result button Group with 
  1620. OK, CANCEL, and ABORT. There is no group box */ 
  1621.  
  1622. RXTYPE.1 = 'RESULT' 
  1623.  
  1624. /* Default */ 
  1625. RXFLAGS.1 = ' ' 
  1626.  
  1627. /* 1=OK, 2=CANCEL, 5=ABORT */ 
  1628. RXINFO.1 = '1 2 5' 
  1629.  
  1630. /* Group box label */ 
  1631. RXLABEL.1 = ' '  /* Leave a space. See note on REXX bug in "Groups" */ 
  1632.  
  1633. /* Position */ 
  1634. RXX.1 = 7 
  1635. RXY.1 = 7 
  1636.  
  1637. /* Create "Result" window */ 
  1638. RXDIM = '226 60 40 40' 
  1639. RXDLG 1 '"Result"' 'RXDIM' 'RESULT' 
  1640.  
  1641. /* Display the selection */ 
  1642. IF RXVAL.1 = 2 THEN RXSAY 'Pressed OK' 
  1643. IF RXVAL.1 = 1 THEN RXSAY 'Pressed CANCEL' 
  1644. IF RXVAL.1 = 5 THEN RXSAY 'Pressed ABORT' 
  1645.  
  1646.  
  1647. ΓòÉΓòÉΓòÉ 5.3.3.5. Entry ΓòÉΓòÉΓòÉ
  1648.  
  1649. Type           ENTRY 
  1650.  
  1651. Description    A box into which the user can type and edit (using the left and 
  1652.                right cursor, Delete, Insert, and Backspace keys) text, or which 
  1653.                can display text for the user to edit. 
  1654.  
  1655.                The user clicks inside of the box, and a cursor appears (ie, the 
  1656.                entry gets the focus).  He can then type keys and text will be 
  1657.                entered into the box.  When he presses the ENTER key, the text 
  1658.                is "accepted", and the entry will cause RXDLG to return if the 
  1659.                END Flag is set for this Group.  He can press the ESC key to 
  1660.                stop entering text into the entry (and return focus to the 
  1661.                dialog window). 
  1662.  
  1663. Uses           To obtain a line of text from the user, or present a line of 
  1664.                text to be edited by the user.  It could be used in the same way 
  1665.                that a REXX PULL statement would be used, except that a dialog 
  1666.                can contain many entries, so that the user can choose which ones 
  1667.                he wants to interact with, and which he doesn't. 
  1668.  
  1669. REXX Setup 
  1670.  
  1671. RXINFO is a string specifying the TotalControls, ControlsPerLine, and 
  1672. WidthOfControl.  WidthOfControl specifies only the size of the entry box (not 
  1673. any label for it too), and therefore will determine how many characters can be 
  1674. displayed in the entry box simultaneously.  If there are more characters in the 
  1675. line than can fit into the box, the user can press the right or left cursor 
  1676. keys to scroll other characters into view. 
  1677.  
  1678. RXLABEL is as described in Groups. 
  1679.  
  1680. RXVAL is a string specifying the name of a REXX stem variable where all of the 
  1681. initial contents of the entries are stored.  The variable name should be 
  1682. limited to 22 characters.  For example, if you set RXVAL to 'STRS', then the 
  1683. first entry in the Group will be initialized to whatever the value of STRS.1 is 
  1684. (ie, the string assigned to STRS.1 will be placed into the entry box when it is 
  1685. created, for the user to edit).  The second entry will be initialized to 
  1686. whatever the value of STRS.2 is.  Etc.  If you don't want any text initially 
  1687. placed into a particular entry (ie, you want it created empty), set its 
  1688. variable to a null string.  For example, if you wanted the second entry to be 
  1689. blank, assign STRS.2 = ' '. 
  1690.  
  1691. Note:  OS/2 REXX appears to have a bug in it regarding null strings.  A null 
  1692.        string is supposed to simply be quotes without any characters in 
  1693.        between, but OS/2 REXX doesn't like this in assignments (ie, when you 
  1694.        assign a variable to be a null string).  It likes to see at least 1 
  1695.        character between the quotes.  So instead of '', use ' ' whenever 
  1696.        assigning a null string to any variable that specifies a string rather 
  1697.        than a numeric value).
  1698.  
  1699. RXFLAGS can be any, all, or none of the following: 
  1700.  
  1701. 'END'          Causes RXDLG to return (with all RXVALs set for all Groups in 
  1702.                the active dialog window, including this entry group) when the 
  1703.                ENTER key is pressed while one of the entries in this group has 
  1704.                the focus. 
  1705.  
  1706. RXX reflects the position of the first entry box, not its label (which needs 
  1707. room to the left of the entry in order to be displayed).  Therefore, set RXX 
  1708. far enough to the left to leave room for the label. 
  1709.  
  1710. REXX Return 
  1711.  
  1712. Rexx Dialog returns each entry's text in the same variable that was used to 
  1713. fetch its text.  In other words, if you specified RXVAL as 'STRS' when the 
  1714. Group was created, then the first entry's text is returned in STRS.1. 
  1715.  
  1716. Note:  Currently, an entry is limited to entering 31 characters maximum.  There 
  1717.        is a limit of 256 entries per Group, or if Labels are specified, 128 
  1718.        entries per Group.
  1719.  
  1720. Examples 
  1721.  
  1722. /* This creates a window called "Enter Stuff" containing a group of 3 entries 
  1723. with labels of "One", "Two", and "Three", and a groupbox of "All".  The first 
  1724. is initialized to contain "Hello", and the second and third are blank */ 
  1725.  
  1726. RXTYPE.1 = 'ENTRY' 
  1727.  
  1728. /* Default */ 
  1729. RXFLAGS.1 = ' ' 
  1730.  
  1731. /* Labels for each entry, and Groupbox */ 
  1732. RXLABEL.1 = 'One:|Two:|Three:|All' 
  1733.  
  1734. /* Variable name where the text "typed into" the entries is stored */ 
  1735. RXVAL.1 = 'TEXT' 
  1736.  
  1737. /* TotalControls, ControlsPerLine, WidthOfControls */ 
  1738. RXINFO.1 = '3 3 45' 
  1739.  
  1740. /* Position of Group */ 
  1741. RXX.1 = 60 
  1742. RXY.1 = 16 
  1743.  
  1744. /* The text for the 3 entries */ 
  1745. TEXT.1 = 'Hello' 
  1746. TEXT.2 = ' ' 
  1747. TEXT.3 = ' ' 
  1748.  
  1749. /* Create "Enter Stuff" window */ 
  1750. RXDIM = '256 106 20 20' 
  1751. RXDLG 1 '"Enter Stuff"' 'RXDIM' 'RESULT' 
  1752.  
  1753. /* Display the selection for each entry */ 
  1754. RXSAY 'Entry One is "'TEXT.1'"' 
  1755. RXSAY 'Entry Two is "'TEXT.2'"' 
  1756. RXSAY 'Entry Three is "'TEXT.3'"' 
  1757.  
  1758.  
  1759. ΓòÉΓòÉΓòÉ 5.3.3.6. List Box ΓòÉΓòÉΓòÉ
  1760.  
  1761. Type           LIST 
  1762.  
  1763. Description    A box containing numerous lines of text.  Each line is an "item" 
  1764.                that the user can select (ie, highlight).  There is a scroll bar 
  1765.                immediately to the right which, if there are more items than can 
  1766.                be simultaneously displayed in the box, can be used to scroll 
  1767.                those other items into view.  (The scroll bar is inoperable if 
  1768.                all of the items in the list can be simultaneously displayed in 
  1769.                the box).  The user can select an item by clicking upon it with 
  1770.                the mouse.  By holding the mouse button down, and moving the 
  1771.                mouse up and down, he can also scroll the list.  Alternately, 
  1772.                the up and down cursor keys can be used to cursor through the 
  1773.                list, and the ENTER key will select an item.  For multiple 
  1774.                select list boxes, more than one item can be selected 
  1775.                simultaneously.  When an item is selected, its state toggles. 
  1776.                (ie, If the item was not selected, selecting it highlights it. 
  1777.                If the item was highlighted, selecting it unhighlights, or 
  1778.                deselects it). 
  1779.  
  1780.                Clicking the mouse twice on an item very fast (ie, 
  1781.                double-clicking) causes RXDLG to return if the END Flag is set 
  1782.                for this control's group.  Alternately, pressing the ENTER key 
  1783.                does the same. 
  1784.  
  1785. Uses           List boxes are used to present items that a user can choose 
  1786.                from, much like checkmark or radio buttons, except that list 
  1787.                boxes use up less area if you have lots of items from which the 
  1788.                user can choose.  Multiple select lists function like 
  1789.                checkmarks, and single select lists function like radio buttons. 
  1790.  
  1791. REXX Setup 
  1792.  
  1793. RXINFO is a string specifying the TotalControls, ControlsPerLine, 
  1794. WidthOfControl, and NumVisibleItems.  WidthOfControl specifies the width of the 
  1795. list box, and therefore will determine how many characters of an item can be 
  1796. displayed in the list box.  NumVisibleItems determines how many items can be 
  1797. displayed simultaneously in the list box, and therefore this determines the 
  1798. height of the box. 
  1799.  
  1800. RXLABEL is as described in Groups. 
  1801.  
  1802. RXVAL is a string specifying the name of the REXX stem variables where all of 
  1803. the initial items of each list box are stored.  Each variable name should be 
  1804. limited to 22 characters.  Each list box has its own stem variable associated 
  1805. with it.  That stem variable contains all of the items that get added to that 
  1806. list box.  RXVAL specifies the REXX variable name for the first list box, then 
  1807. the REXX variable name for the second list box, then the REXX variable name for 
  1808. the third list box, etc.  Each list box's variable name is separated from the 
  1809. next by a | character.  For example, if you set RXVAL to 'ONE|TWO|THREE', then 
  1810. the first list box in the Group will be initialized to contain all of the items 
  1811. starting with ONE.1, the second list box will be initialized to contain all of 
  1812. the items starting with TWO.1, and the third list box will be initialized to 
  1813. contain all of the items starting with THREE.1.  Rexx Dialog reads items until 
  1814. it comes to an item that is a null string.  That marks the end of a list box's 
  1815. item.  For example, if you wanted to put 3 strings into the first list box; 
  1816. "Hello", "Hi", and 'Goodbye", then you would set ONE.1 to 'Hello', ONE.2 to 
  1817. 'Hi', and ONE.3 to to 'Goodbye'.  ONE.4 would be set to ' ' to mark the end of 
  1818. the list. 
  1819.  
  1820. Note:  OS/2 REXX appears to have a bug in it regarding null strings.  A null 
  1821.        string is supposed to simply be quotes without any characters in 
  1822.        between, but OS/2 REXX doesn't like this in assignments (ie, when you 
  1823.        assign a variable to be a null string).  It likes to see at least 1 
  1824.        character between the quotes.  So instead of '', use ' ' whenever 
  1825.        assigning a null string to any variable that specifies a string rather 
  1826.        than a numeric value).
  1827.  
  1828. RXFLAGS can be any, all, or none of the following: 
  1829.  
  1830. 'MULTIPLE'     Allows more than one item to be selected simultaneously (ie, 
  1831.                multiple select), rather than single select. 
  1832.  
  1833. ALLNONE        This is only applicable to a multiple select list box.  Two push 
  1834.                buttons are displayed above the list box.  One push button is 
  1835.                labeled "All".  If this is pushed, it automatically forces all 
  1836.                of the items in the list to be selected (ie, highlighted).  The 
  1837.                other button is "None", and forces all items to be deselected. 
  1838.                If the END Flag is also set for this Group, then RXDLG returns. 
  1839.                There is a limit of 40 list boxes per Group if the ALLNONE Flag 
  1840.                is used. 
  1841.  
  1842. INDEX          Instead of returning the actual text of an item when it is 
  1843.                selected, Rexx Dialog returns its index number (ie, where it 
  1844.                appears in the list).  The first item in the list has an index 
  1845.                of 0. 
  1846.  
  1847. 'END'          Causes RXDLG to return (with all RXVALs set for all Groups in 
  1848.                the active dialog window, including this list box group) when an 
  1849.                item from a list is selected (or also unselected for multiple 
  1850.                select lists). 
  1851.  
  1852. REXX Return 
  1853.  
  1854. For single select list boxes, Rexx Dialog returns each list box's selected item 
  1855. in the same variable that was used to fetch its items, but with a .0 extension. 
  1856. Using the above example, the selected item for the first list box would be 
  1857. returned in ONE.0, the selected item for the second list box would be returned 
  1858. in TWO.0, and the selected item for the third list box would be returned in 
  1859. THREE.0. 
  1860.  
  1861. For multiple select list boxes, Rexx Dialog returns a count of how many items 
  1862. were selected in the list in the same variable that was used to fetch its 
  1863. items, but with a .0 extension.  Using the above example, the count for the 
  1864. first list box would be returned in ONE.0, the count for the second list box 
  1865. would be returned in TWO.0, and the count for the third list box would be 
  1866. returned in THREE.0.  The selections for each list box are then returned in 
  1867. compound variables (ie, a second extension is added to the variable name).  For 
  1868. example, the first selected item in the first list is returned in ONE.0.1, the 
  1869. second selected item in the first list is returned in ONE.0.2, etc.  The first 
  1870. selected item in the second list is returned in TWO.0.1, the second selected 
  1871. item in the second list is returned in TWO.0.2, etc. 
  1872.  
  1873. Note:  Currently, a list box item is limited to 31 characters maximum.  There 
  1874.        is a limit of 256 list boxes per group, or if Labels are specified, 128 
  1875.        list boxes per Group, or if ALL\NONE push buttons are included, 40 list 
  1876.        boxes per Group.
  1877.  
  1878. Examples 
  1879.  
  1880. /* This creates a window called "List Me" containing a Group of 1 single select 
  1881. list box with a label of "One", and a groupbox of "Choices".  The list box's 6 
  1882. items are stored in the ONE variable.  Those 6 items are "This is one", "This 
  1883. is two", "This is three", "This is four", "This is five", and "This is six". */ 
  1884.  
  1885. RXTYPE.1 = 'LIST' 
  1886.  
  1887. /* Default */ 
  1888. RXFLAGS.1 = ' ' 
  1889.  
  1890. /* Labels for each list box, and Groupbox */ 
  1891. RXLABEL.1 = 'One:|Choices' 
  1892.  
  1893. /* Variable names where the items are stored */ 
  1894. RXVAL.1 = 'ONE' 
  1895.  
  1896. /* TotalControls, ControlsPerLine, WidthOfControls, NumVisibleItems */ 
  1897. RXINFO.1 = '1 1 110 4' 
  1898.  
  1899. /* Position of Group */ 
  1900. RXX.1 = 10 
  1901. RXY.1 = 10 
  1902.  
  1903. /* The items for list 1 */ 
  1904. ONE.1 = 'This is one' 
  1905. ONE.2 = 'This is two' 
  1906. ONE.3 = 'This is three' 
  1907. ONE.4 = 'This is four' 
  1908. ONE.5 = 'This is five' 
  1909. ONE.6 = 'This is six' 
  1910. ONE.7 = ' '  /* End of List */ 
  1911.  
  1912. /* Create "List Me" window */ 
  1913. RXDIM = '140 146 30 30' 
  1914. RXDLG 1 '"List Me"' 'RXDIM' 'RESULT' 
  1915.  
  1916. /* Display the selection */ 
  1917. RXSAY 'Selection is "'ONE.0'"' 
  1918.  
  1919.  
  1920. ΓòÉΓòÉΓòÉ 5.3.3.7. Drop Box ΓòÉΓòÉΓòÉ
  1921.  
  1922. Type           DROP 
  1923.  
  1924. Description    A combination of an ENTRY and LIST.  The list is not visible 
  1925.                until you click the mouse upon a small arrow immediately to the 
  1926.                right of the entry.  Then, the list drops down, and the user can 
  1927.                manipulate it like a list.  Otherwise, if he clicks inside of 
  1928.                the entry box, he can then manipulate that part of it just like 
  1929.                an entry.  Whenever an item in the list is selected, it is 
  1930.                automatically copied to the entry. 
  1931.  
  1932.                Clicking the mouse on an item in the list causes RXDLG to return 
  1933.                if the END Flag is set for this control's group.  Also, pressing 
  1934.                the ENTER key does the same. 
  1935.  
  1936. Uses           Like a list box, this displays many choices to the user, but the 
  1937.                entry also gives him the opportunity to type in some text that 
  1938.                isn't currently in the list.  So, it might be used for a 
  1939.                situation where you want to present some default choices to the 
  1940.                user, but then allow him to reject those and specify his own 
  1941.                choice. 
  1942.  
  1943. REXX Setup 
  1944.  
  1945. RXINFO is a string specifying the TotalControls, ControlsPerLine, and 
  1946. WidthOfControl.  WidthOfControl specifies the width of the drop box, and 
  1947. therefore will determine how many characters of an item can be displayed in the 
  1948. drop box. 
  1949.  
  1950. RXVAL is exactly as in a List Box Group. 
  1951.  
  1952. RXLABEL is as described in Groups. 
  1953.  
  1954. RXFLAGS can be any, all, or none of the following: 
  1955.  
  1956. SHOWLIST       Instead of list box that drops down, the list box is always 
  1957.                visible.  In this case, the RXINFO must be setup like a list box 
  1958.                (ie, with a NumVisibleItems parameter too). 
  1959.  
  1960. READONLY       The user cannot type anything into the entry, but must select an 
  1961.                item for the list.  If READONLY is set, then SHOWLIST should not 
  1962.                be set (ie, if you don't want a drop down list and want it 
  1963.                readonly, just use a LIST Group). The real difference between a 
  1964.                READONLY DROP and a LIST is that the former takes up less area 
  1965.                because its list is only displayed when dropped down. 
  1966.  
  1967. INDEX          Instead of returning the actual text of a drop box item when it 
  1968.                is selected, Rexx Dialog returns its index number (ie, where it 
  1969.                appears in the list).  The first item in the list has an index 
  1970.                of 0. 
  1971.  
  1972. 'END'          Causes RXDLG to return (with all RXVALs set for all Groups in 
  1973.                the active dialog window, including this drop box group) when an 
  1974.                item from a list is selected or user types into the entry and 
  1975.                presses ENTER. 
  1976.  
  1977. RXX and RXY reflect the position of the entry box of the first drop box, not 
  1978. its drop down list (which needs room beneath the entry in order to "drop 
  1979. down"), nor the drop box's label (which needs room to the left of the entry in 
  1980. order to be displayed).  Therefore, set RXX far enough to the left to leave 
  1981. room for the label, and set RXY far enough above the bottom border of the 
  1982. window in which the Group is placed in order for the drop boxes to have room to 
  1983. drop down.  The RXY variable should be 30 or more. 
  1984.  
  1985. REXX Return 
  1986.  
  1987. The return is exactly as in a single select List Box Group. 
  1988.  
  1989. Note:  Currently, a drop box is limited to 31 characters maximum.  There is a 
  1990.        limit of 256 drop boxes per Group, or if Labels are specified, 128 drop 
  1991.        boxes per Group.
  1992.  
  1993. Examples 
  1994.  
  1995. /* This creates a window called "Drop Me" containing a Group of 1 drop box with 
  1996. a label of "One" and no groupbox.  The drop box's list items are stored in the 
  1997. ONE variable. Those 3 items are "Hello", "Hi", and "Goodbye" */ 
  1998.  
  1999. RXTYPE.1 = 'DROP' 
  2000.  
  2001. /* Default */ 
  2002. RXFLAGS.1 = ' ' 
  2003.  
  2004. /* Labels for each drop box, and Groupbox */ 
  2005. RXLABEL.1 = 'One:' 
  2006.  
  2007. /* Variable names where the items are stored */ 
  2008. RXVAL.1 = 'ONE' 
  2009.  
  2010. /* TotalControls, ControlsPerLine, WidthOfControls */ 
  2011. RXINFO.1 = '1 1 90' 
  2012.  
  2013. /* Position of Group */ 
  2014. RXX.1 = 40 
  2015. RXY.1 = 60 
  2016.  
  2017. /* The items for list 1 */ 
  2018. ONE.1 = 'Hello' 
  2019. ONE.2 = 'Hi' 
  2020. ONE.3 = 'Goodbye' 
  2021. ONE.4 = ' '  /* End of List */ 
  2022.  
  2023. /* Create "Drop Me" window */ 
  2024. RXDIM = '140 104 30 30' 
  2025. RXDLG 1 '"Drop Me"' 'RXDIM' 'RESULT' 
  2026.  
  2027. /* Display the selection */ 
  2028. RXSAY 'Selection is "'ONE.0'"' 
  2029.  
  2030.  
  2031. ΓòÉΓòÉΓòÉ 5.3.3.8. Spin Button ΓòÉΓòÉΓòÉ
  2032.  
  2033. Type           SPIN 
  2034.  
  2035. Description    A spin button is an entry that deals with numeric values.  It 
  2036.                consists of an entry, plus two up and down arrows immediately to 
  2037.                the right of the entry. The up and down arrows will cycle the 
  2038.                spin through its numeric range (and roll over when a lower or 
  2039.                upper numeric limit is surpassed).  Alternately, the user can 
  2040.                click inside of the entry box, and type a number in just as he 
  2041.                would manipulate an entry.  His input is checked against the 
  2042.                spin's upper and lower limit, and forced to fall within that 
  2043.                range.  When the entry is activated, he can also use the up and 
  2044.                down cursor keys to cycle through the range. 
  2045.  
  2046.                If the user changes the numeric value of a spin (either by using 
  2047.                the arrow buttons, or typing a new value, or using the cursor 
  2048.                keys), RXDLG will return if the END Flag is set for this 
  2049.                control's Group. 
  2050.  
  2051.                There is a limit of 256 spin buttons per Group, or if Labels are 
  2052.                specified, 128 spin buttons per Group. 
  2053.  
  2054. Uses           Useful for allowing the user to specify some numeric parameter 
  2055.                such as how many copies of a document he would like printed. 
  2056.                Because the user can type a specific value into the entry, this 
  2057.                offers an easy way to pick out one particular value (ie, it's 
  2058.                easy to make fine adjustments with a spin). 
  2059.  
  2060. REXX Setup 
  2061.  
  2062. RXINFO is a string specifying the TotalControls, ControlsPerLine, and 
  2063. WidthOfControl. 
  2064.  
  2065. The string for RXLABEL has some extra information in addition to the labels for 
  2066. all of the spin buttons in the Group, as well as the Group box label.  Every 
  2067. spin button has a minimum and maximum value that restricts the numeric range of 
  2068. the spin.  For example, you could have a spin that did not allow numbers 
  2069. greater than 100 nor less than 10. The maximum and minimum limits for a 
  2070. particular spin must be specified, in that order, before the spin's label.  One 
  2071. spin's parameters must be separated from the next spin's parameters by a | 
  2072. character.  So, the order of the parameters in the RXLABEL string is: 
  2073.  
  2074. First spin's maximum limit 
  2075. First spin's minimum limit 
  2076. First spin's label 
  2077. Second spin's maximum limit 
  2078. Second spin's minimum limit 
  2079. Second spin's label 
  2080. etc. 
  2081. Group box label 
  2082.  
  2083. If you desire no groupbox label, simply omit it.  If you desire a spin with no 
  2084. label, then omit that spin's label (although you still must specify a maximum 
  2085. and minimum limit). 
  2086.  
  2087. Note:  The maximum limit of a spin is limited to 255 (ie, it can span 256 
  2088.        different values).  The low limit is 0.  The limits are inclusive.  That 
  2089.        is, if you set the low limit to 10 and the high limit to 20, then the 
  2090.        spin can be set to the value 10 or 20, as well as any number inbetween.
  2091.  
  2092. RXVAL is a string containing the initial values of all the spin buttons in the 
  2093. group starting with the first.  You must specify an initial value for each 
  2094. spin.  For example, if you have 3 spin buttons, and you want to set the first 
  2095. spin initially to 30, the second spin to 5, and the third spin to 0, set RXVAL 
  2096. to '30 5 0'. 
  2097.  
  2098. Note:  Don't forget to put quotes around the numeric values in the RXVAL 
  2099.        string.  You need to specify all of numbers as one string.
  2100.  
  2101. RXFLAGS can be any, all, or none of the following: 
  2102.  
  2103. 'END'          Causes RXDLG to return (with all RXVALs set for all Groups in 
  2104.                the active dialog window, including this drop box group) when an 
  2105.                item from a list is selected or user types into the entry and 
  2106.                presses ENTER. 
  2107.  
  2108. RXX reflects the position of the entry box of the first spin, not its label 
  2109. (which needs room to the left of the entry in order to be displayed). 
  2110. Therefore, set RXX far enough to the left to leave room for the label. 
  2111.  
  2112. REXX Return 
  2113.  
  2114. Rexx Dialog sets the Group's RXVAL string to contain the current values of all 
  2115. the spin buttons in the group, starting with the first. 
  2116.  
  2117. Examples 
  2118.  
  2119. /* This creates a window called "Spin Me" containing a Group of 1 spin button, 
  2120. labeled "Range:"  with a group box labeled "Value".  The spin has a max limit 
  2121. of 20 and a min limit of 10, and is initially set to 19.  */ 
  2122.  
  2123. RXTYPE.1 = 'SPIN' 
  2124.  
  2125. /* Default */ 
  2126. RXFLAGS.1 = ' ' 
  2127.  
  2128. /* Max, Min, Label for each slider, and groupbox */ 
  2129. RXLABEL.1 = '20 10 Range:|Value' 
  2130.  
  2131. /* Values for each spin */ 
  2132. RXVAL.1 = '19' 
  2133.  
  2134. /* TotalControls, ControlsPerLine, WidthOfControls */ 
  2135. RXINFO.1 = '1 1 70' 
  2136.  
  2137. /* Position */ 
  2138. RXX.1 = 80 
  2139. RXY.1 = 18 
  2140.  
  2141. /* Create "Spin Me" window */ 
  2142. RXDIM = '190 86 30 30' 
  2143. RXDLG 1 '"Spin Me"' 'RXDIM' 'RESULT' 
  2144.  
  2145. /* Now display the value the spin.  Since there's only 1 in this Group, we 
  2146. don't need to parse the RXVAL string for the Group to extract the spin's value 
  2147. */ 
  2148. RXSAY 'value =' RXVAL.1 
  2149.  
  2150.  
  2151. ΓòÉΓòÉΓòÉ 5.3.3.9. Slider ΓòÉΓòÉΓòÉ
  2152.  
  2153. Type           SLIDER 
  2154.  
  2155. Description    Like a spin, the slider also deals with numeric values.  A 
  2156.                slider has a shaft, and a knob that can be "grabbed" with the 
  2157.                mouse (ie, place the mouse pointer over the knob, and press and 
  2158.                hold down the mouse button) and moved along the shaft.  The 
  2159.                numeric value of the slider will change as the knob moves, with 
  2160.                the far left position being 0 and the far right position being 
  2161.                the maximum range of the slider.  Alternately, when a slider has 
  2162.                the focus (ie, its knob has a black dot on it), the knob can be 
  2163.                moved with the left and right cursor keys.  There are also two 
  2164.                arrows immediately to the right of the shaft, which can be used 
  2165.                to adjust the value in fine amounts (ie, single steps). 
  2166.                Alternately, if the mouse is clicked to either side of the knob 
  2167.                (but not on the knob itself), the value will increment or 
  2168.                decrement (depending upon which side of the knob the mouse was 
  2169.                clicked).  The slider may also have a "detent", which is a small 
  2170.                black marker above the shaft, which if the user clicks upon, 
  2171.                forces the knob to jump to that position. 
  2172.  
  2173.                If the user changes the value of a slider (either by moving and 
  2174.                releasing the knob, pressing the ENTER key when the knob is 
  2175.                highlighted, clicking upon the arrows, clicking to either side 
  2176.                of the knob, or clicking upon a detent), RXDLG will return if 
  2177.                the END Flag is set for this control's group. 
  2178.  
  2179.                There is a limit of 256 sliders per Group.  If Labels are 
  2180.                specified, there is a limit of 128 sliders per Group.  If values 
  2181.                are printed out, then there is a limit of 64 sliders per Group. 
  2182.  
  2183. Uses           Allows the user to cycle through a wide range of numeric values 
  2184.                very quickly, albeit hard to pinpoint specific settings, and 
  2185.                therefore is more appropriate to use for setting parameters 
  2186.                where very fine adjustments aren't as important as being able to 
  2187.                quickly cycle through a large range. 
  2188.  
  2189. REXX Setup 
  2190.  
  2191. RXINFO is a string specifying the TotalControls, ControlsPerLine, and 
  2192. WidthOfControl.  The WidthOfControl must be wide enough for OS/2 to have enough 
  2193. pixel resolution to display the range of values (ie, steps) that you want the 
  2194. slider to encompass.  If the width is not wide enough to accomodate the range 
  2195. of values, then OS/2 will not display the slider shaft.  Only the knob may be 
  2196. visible, and subsequent updating of the slider display will be bizarre to say 
  2197. the least.  PM's slider needs fixing. 
  2198.  
  2199. The string for RXLABEL has some extra information in addition to the labels for 
  2200. all of the sliders in the Group, as well as the Group box label.  Every slider 
  2201. button has a value that determines how many steps the slider can move (ie, its 
  2202. range of values).  For example, you could have a slider that could be set to 
  2203. one of 20 different steps.  Also, a slider may have a detent.  The NumOfSteps 
  2204. and Detent for a particular slider must be specified, in that order, before the 
  2205. slider's label.  One slider's parameters must be separated from the next 
  2206. slider's parameters by a | character.  So, the order of the parameters in the 
  2207. RXLABEL string is: 
  2208.  
  2209. First slider's NumOfSteps 
  2210. First slider's Detent 
  2211. First slider's label 
  2212. Second slider's NumOfSteps 
  2213. Second slider's Detent 
  2214. Second slider's label 
  2215. etc. 
  2216. Group box label 
  2217.  
  2218. If you desire no groupbox label, simply omit it.  If you desire a slider with 
  2219. no label, then omit that slider's label (although you still must specify 
  2220. NumOfSteps and Detent).  If you desire no Detent, then set Detent to 255. 
  2221.  
  2222. The Detent value is not in terms of steps, but rather pixels from the left of 
  2223. the slider shaft.  Therefore, if the slider WidthOfControl is 128, and you wish 
  2224. to place a Detent halfway across the slider, then set Detent to 64. 
  2225.  
  2226. Note:  The maximum range of a slider is 0 to 254 (ie, 255 steps).  The 
  2227.        NumOfSteps setting is exclusive.  That is, if you set NumOfSteps to 20, 
  2228.        then the slider can be set to a value from 0 to 19 (ie, a total of 20 steps).
  2229.  
  2230. RXVAL is a string containing the initial values of all the sliders in the group 
  2231. starting with the first.  You must specify an initial value for each slider. 
  2232. For example, if you have 3 sliders, and you want to set the first slider 
  2233. initially to 30, the second slider to 5, and the third slider to 0, set RXVAL 
  2234. to '30 5 0'. 
  2235.  
  2236. Note:  Don't forget to put quotes around the numeric values in the RXVAL 
  2237.        string.  You need to specify all of numbers as one string.
  2238.  
  2239. RXFLAGS can be any, all, or none of the following: 
  2240.  
  2241. 'VALUE'        Automatically prints out the current value of the slider to the 
  2242.                right of the shaft. 
  2243.  
  2244. 'END'          Causes RXDLG to return (with all RXVALs set for all Groups in 
  2245.                the active dialog window, including this drop box group) when an 
  2246.                item from a list is selected or user types into the entry and 
  2247.                presses ENTER. 
  2248.  
  2249. RXX reflects the position of the shaft of the first slider, not its label 
  2250. (which needs room to the left of the shaft in order to be displayed). 
  2251. Therefore, set RXX far enough to the left to leave room for the label. 
  2252.  
  2253. REXX Return 
  2254.  
  2255. Rexx Dialog sets the Group's RXVAL string to contain the current values of all 
  2256. the sliders buttons in the group, starting with the first. 
  2257.  
  2258. Examples 
  2259.  
  2260. /* This creates a window called "Slide Me" containing a Group of 1 slide 
  2261. button, labeled "Range:"  with a group box labeled "Value".  The slider has 20 
  2262. steps, a detect at 45 (ie, in the center), and is initially set to 12 */ 
  2263.  
  2264. RXTYPE.1 = 'SLIDER' 
  2265.  
  2266. /* Print value as slider moves */ 
  2267. RXFLAGS.1 = 'VALUE' 
  2268.  
  2269. /* NumOfSteps, Detent, Label for each slider, and groupbox */ 
  2270. RXLABEL.1 = '20 45 Range:|Value' 
  2271.  
  2272. /* Values for each slider */ 
  2273. RXVAL.1 = '12' 
  2274.  
  2275. /* TotalControls, ControlsPerLine, WidthOfControls */ 
  2276. RXINFO.1 = '1 1 90' 
  2277.  
  2278. /* Position */ 
  2279. RXX.1 = 80 
  2280. RXY.1 = 18 
  2281.  
  2282. /* Create "Slide Me" window */ 
  2283. RXDIM = '230 86 30 30' 
  2284. RXDLG 1 '"Slide Me"' 'RXDIM' 'RESULT' 
  2285.  
  2286. /* Now display the value of the slider.  Since there's only 1 in this Group, we 
  2287. don't need to parse the RXVAL string for the Group to extract the slider's 
  2288. value */ 
  2289. RXSAY 'value =' RXVAL.1 
  2290.  
  2291.  
  2292. ΓòÉΓòÉΓòÉ 5.3.3.10. Text ΓòÉΓòÉΓòÉ
  2293.  
  2294. Type           TEXT 
  2295.  
  2296. Description    This merely displays phrases of text.  A phrase is any number of 
  2297.                words and punctuation that is not broken by a line feed.  The 
  2298.                user can't edit nor select the text in any way.  It's simply for 
  2299.                the purpose of displaying text in a window. 
  2300.  
  2301.                There is a limit of 256 phrases per Group. 
  2302.  
  2303.                A TEXT Group can't cause RXDLG to return. 
  2304.  
  2305. Uses           Can be used to display instructions, or label things in a 
  2306.                window, or display some message to the user. 
  2307.  
  2308. REXX Setup 
  2309.  
  2310. RXINFO is a string specifying the TotalPhrases, PhrasesPerLine, and 
  2311. WidthOfPhrase, and SpaceBetweenPhrases.  SpaceBetweenPhrases is only effective 
  2312. if PhrasesPerLine is greater than 1 (ie, you're putting more than one phrase on 
  2313. a line).  In this case, SpaceBetweenPhrases allows you to evenly space out the 
  2314. phrases, which is handy if you need to make columns of data (where 
  2315. SpaceBetweenPhrases would be the space between columns).  If you're going to 
  2316. place more than one phrase upon a line, then SpaceBetweenPhrases should be 8 or 
  2317. more.  If WidthOfPhrase is 0, then Rexx Dialog automatically sets up all of the 
  2318. phrases to be as wide as the longest phrase, which ensures that no phrase will 
  2319. be visually clipped.  Otherwise, if you specify a WidthOfPhrase, make sure that 
  2320. is wide enough to accomodate the widest phrase.  WidthOfPhrase is limited to 
  2321. 255 pels maximum.  (If you need to set a wider default, use RXSET's SIZE 
  2322. command after creating the Group).  If you're going to be changing a phrase 
  2323. later with the RXSET command, then either make sure that you aren't going to 
  2324. change it to some phrase that is wider than the widest original phrase in the 
  2325. group, or specify a WidthOfPhrase to accomodate any changes that will be made 
  2326. to the phrase, or use RXSET's SIZE command to size a particular phrase as 
  2327. desired (the 255 pel limit does not apply to RXSET's SIZE command). 
  2328.  
  2329. The string for RXLABEL contains all of the phrases in the Group, as well as the 
  2330. Group box label.  Each phrase is separated from the next by a | character.  The 
  2331. group box label is last (or omitted if no group box is desired).  If you want a 
  2332. blank area where a phrase would go (this would be a blank line if 
  2333. PhrasesPerLine=0), then simply put a space where that phrase would be 
  2334. specified. 
  2335.  
  2336. RXVAL is not used, and need not be initialized. 
  2337.  
  2338. RXFLAGS can be any, all, or none of the following: 
  2339.  
  2340. 'CENTER'       Each phrase is centered relative to the other phrases on lines 
  2341.                above or below. 
  2342.  
  2343. 'RIGHT'        All phrases are aligned along the right margin. 
  2344.  
  2345.                Note:  If neither RIGHT nor CENTER flags are specified, then all 
  2346.                       phrases are aligned along the left margin.
  2347.  
  2348. REXX Return 
  2349.  
  2350. None.  A TEXT Group doesn't interact with the user in any way, nor does it 
  2351. cause RXDLG to return. 
  2352.  
  2353. Examples 
  2354.  
  2355. /* This creates a window called "Text" containing 1 TEXT Group with 3 lines of 
  2356. centered text with a groupbox */ 
  2357.  
  2358. RXTYPE.1 = 'TEXT' 
  2359.  
  2360. /* Center the text */ 
  2361. RXFLAGS.1 = 'CENTER' 
  2362.  
  2363. /* Text lines */ 
  2364. RXLABEL.1 = 'PLEASE READ!|This is a REXX example of|centered text.|Text Stuff' 
  2365.  
  2366. /* TotalPhrases, PhrasesPerLine, WidthOfPhrase, BetweenPhrases. Note: because 
  2367. we want WidthOfPhrase and BetweenPhrases to be 0, then we can omit both args. 
  2368. Rexx Dialog sets omitted args to 0 */ 
  2369. RXINFO.1 = '3 1' 
  2370.  
  2371. /* Position */ 
  2372. RXX.1 = 10 
  2373. RXY.1 = 10 
  2374.  
  2375. RXDIM = ' ' 
  2376. RXDLG 1 '"Text"' 'RXDIM' 'SIZE|RESULT' 
  2377.  
  2378.  
  2379. ΓòÉΓòÉΓòÉ 5.3.3.11. Group Box ΓòÉΓòÉΓòÉ
  2380.  
  2381. Type           GROUP 
  2382.  
  2383. Description    This is a rectangular box, within which other controls can be 
  2384.                placed.  The box can have its own label, which usually pertains 
  2385.                to whatever is the purpose of the controls within the box. 
  2386.  
  2387.                A group box can't cause RXDLG to return. 
  2388.  
  2389. Uses           Identifies controls that "belong together" usually because they 
  2390.                are all related to one operation. 
  2391.  
  2392. REXX Setup 
  2393.  
  2394. A GROUP Type only describes one group box.  In other words, it isn't a group of 
  2395. group boxes.  You can have more than 1 GROUP in a window, but of course, you'll 
  2396. have to specify each separately. 
  2397.  
  2398. RXINFO is a string specifying the Width and Height of the group box (in 
  2399. pixels). 
  2400.  
  2401. RXLABEL is the label for the group box (or a null string if no label desired, 
  2402. ie, the group box is simply a rectangular box). 
  2403.  
  2404. RXVAL is not used, and need not be initialized. 
  2405.  
  2406. RXFLAGS is not used, and should be set to a null string. 
  2407.  
  2408. Note:  A GROUP must be specified before any of the controls that will be 
  2409.        displayed inside of it, otherwise the group box will draw over those 
  2410.        controls and visually wipe them from the display.
  2411.  
  2412. REXX Return 
  2413.  
  2414. None.  A GROUP doesn't interact with the user in any way, nor does it cause 
  2415. RXDLG to return. 
  2416.  
  2417. Examples 
  2418.  
  2419. /* This creates a window called "Group" that contains a GROUP box */ 
  2420.  
  2421. RXTYPE.1 = 'GROUP' 
  2422.  
  2423. /* Default */ 
  2424. RXFLAGS.1 = ' ' 
  2425.  
  2426. /* Label */ 
  2427. RXLABEL.1 = 'Everything' 
  2428.  
  2429. /* Width, Height */ 
  2430. RXINFO.1 = '240 220' 
  2431.  
  2432. /* Position */ 
  2433. RXX.1 = 6 
  2434. RXY.1 = 6 
  2435.  
  2436. RXDIM = ' ' 
  2437. RXDLG 1 '"Group"' 'RXDIM' 'SIZE|RESULT' 
  2438.  
  2439.  
  2440. ΓòÉΓòÉΓòÉ 5.3.3.12. Menu ΓòÉΓòÉΓòÉ
  2441.  
  2442. Type           MENU 
  2443.  
  2444. Description    A menu attaches to the titlebar of the window, and will drop 
  2445.                down when the user clicks the mouse on a Menu Heading in the 
  2446.                titlebar (ie, the menu attached to that Menu Heading drops 
  2447.                down).  The user can then make selections with the mouse. 
  2448.                Alternately, if the menus have "mnemonic keys", those keys can 
  2449.                be used to open and select menu items. 
  2450.  
  2451.                Note:  There must only be 1 MENU Group per window, and there is 
  2452.                       a limit of 256 Labels in a menu.
  2453.  
  2454. Uses           Operations that can be arranged into groups lend themselves well 
  2455.                to being put into a menu.  For example, all file load and save 
  2456.                operations may be placed into a menu with a heading of "File". 
  2457.  
  2458. REXX Setup 
  2459.  
  2460. RXINFO is a string specifying the TotalMenus (ie, total Menu Headings), and 
  2461. then the REXX stem variable names (where the menu labels are fetched) for all 
  2462. of the menus (headings).  Each variable name is separated from the next by a | 
  2463. character.  If TotalMenus is 0, then an "empty" menu is created, and the 
  2464. variable names do not need to be supplied.  This is more memory efficient if 
  2465. you plan upon using the RXSET ADD Operation to later create a new menu bar. 
  2466.  
  2467. Note:  Placing a ~ character before some letter in a Label, means that, when 
  2468.        the menu is displayed, pressing that letter on the keyboard activates 
  2469.        the menu item\subitem associated with that label.  This is a mnemonic.
  2470.  
  2471. RXLABEL need not be initialized. 
  2472.  
  2473. RXVAL need not be initialized. 
  2474.  
  2475. RXFLAGS can be any, all, or none of the following: 
  2476.  
  2477. 'HELP'         A "Help" menu is automatically added to the end of the menu bar, 
  2478.                containing 4 Help Items labeled "Help index", "General Help", 
  2479.                "Using Help", and "Keys Help".  Whenever the user selects one of 
  2480.                these Items, Rexx Dialog automatically handles this (ie, and 
  2481.                RXDLG doesn't return) by displaying an appropriate panel in any 
  2482.                help file attached to the window.  See RXHELP.  The Help File 
  2483.                that you write should have a panel with the name KEYS that lists 
  2484.                any keyboard commands for the program.  If there are no such 
  2485.                keyboard commands, then do not name any panel KEYS. 
  2486.  
  2487. REXX Return 
  2488.  
  2489. RXID is the Group number for this MENU Group (ie, if the MENU Group is the 
  2490. First Group in the window, then RXID is 1).  RXSUBID is the menu label number. 
  2491. This will depend upon which item or subitem was chosen.  The menu labels are 
  2492. numbered from top to bottom, and left to right.  For example, assume that you 
  2493. have w Menu Headings labeled "File" and "Edit".  "File" has 2 items labeled 
  2494. "Open" and "Save".  The first item ("Open") has 2 subitems labeled "All" and 
  2495. "Excerpt".  Here's how the menu would look displayed: 
  2496.  
  2497. ΓòÆΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòò  ΓòÆΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòò
  2498. Γöé  File  Γöé  Γöé  Edit  Γöé
  2499. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñΓòÆΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòò
  2500. Γöé  Open->ΓöéΓöéAll    Γöé
  2501. Γöé  Save  ΓöéΓöéExcerptΓöé
  2502. ΓòÿΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¢ΓòÿΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¢
  2503.  
  2504. "File" is label 1.  "Open" is label 2.  But, since "Open" has two subitems, we 
  2505. count those before moving on to "Save".  So, "All" is label 3, and "Excerpt" is 
  2506. label 4.  "Save" is label 5.  That's all of the items\subitems in the first 
  2507. menu, so moving on to the next menu, "Edit" is label 6.  The first item in the 
  2508. "Edit" menu would be label 7.  Etc. 
  2509.  
  2510. If you specify the HELP Flag, then the first 5 label numbers correspond to the 
  2511. Help Heading, and the 4 Help Items, "Help index", "General Help", "Using Help", 
  2512. and "Keys Help", even though the Help menu appears last on the menu bar. 
  2513. Therefore, the menu label that actually appears on the left side of the menu 
  2514. bar is label number 6.  So, if we had a HELP menu in the above example, then 
  2515. the label numbering would be changed to be "File" = 6, "Open" = 7, "All" = 8, 
  2516. "Excerpt" = 9, "Save" = 10, and "Edit" = 11. 
  2517.  
  2518. Examples 
  2519.  
  2520. The REXX stem variable for a particular menu is setup such that a stem of 0 is 
  2521. assigned the heading of the menu.  Subsequent stems starting at 1 are the item 
  2522. labels.  A null string must mark the end of the items.  For example, if you 
  2523. have a menu with a heading of "File" and 2 items labeled "Item 1" and "Item 2", 
  2524. and the REXX variable name you supplied in the RXINFO string is 'MENU', then 
  2525. here is the setup: 
  2526.  
  2527. /* Menu Structure */ 
  2528. MENU.0 = 'File'      /* Heading */ 
  2529. MENU.1 = 'Item 1'  /* First Item */ 
  2530. MENU.2 = 'Item 2'    /* Second Item */ 
  2531. MENU.3 = ' '         /* End of Items */ 
  2532.  
  2533. If an item has any subitems, the number of subitems should be placed after that 
  2534. item's label, separated by a | character.  The labels for those subitems are 
  2535. assigned to compound variables where an extra stem is added to the item's 
  2536. variable name.  The extra stem is the subitem number, starting with 1. 
  2537.  
  2538. For example, if "Item 1" had 2 subitems labeled "Sub 1" and "Sub 2": 
  2539.  
  2540. /* Menu Structure */ 
  2541. MENU.0 = 'File'   /* Heading */ 
  2542. MENU.1 = 'Item 1|2' /* First Item, # of subitems */ 
  2543. MENU.2 = 'Item 2'  /* Second Item */ 
  2544. MENU.3 = ' '     /* End of Items */ 
  2545.  
  2546. MENU.1.1 = 'Sub 1' /* First SubItem for Item 1 */ 
  2547. MENU.1.2 = 'Sub 2' /* Second SubItem for Item 1 */ 
  2548.  
  2549. As a further example, assume "Item 2" had 1 subitem labeled "hello": 
  2550.  
  2551. /* Menu Structure */ 
  2552. MENU.0 = 'File'   /* Heading */ 
  2553. MENU.1 = 'Item 1|2'  /* First Item, # of subitems */ 
  2554. MENU.2 = 'Item 2|1' /* Second Item, # of subitems */ 
  2555. MENU.3 = ' '     /* End of Items */ 
  2556.  
  2557. MENU.1.1 = 'Sub 1' /* First SubItem for Item 1 */ 
  2558. MENU.1.2 = 'Sub 2' /* Second SubItem for Item 1 */ 
  2559.  
  2560. MENU.2.1 = 'hello' /* First SubItem for Item 2 */ 
  2561.  
  2562.  
  2563. ΓòÉΓòÉΓòÉ 5.3.4. The TAB key ΓòÉΓòÉΓòÉ
  2564.  
  2565. Pressing the TAB key causes the focus (ie, which control is active) to switch 
  2566. to the next control in the window (regardless of whether the next control is 
  2567. within the same Group as the control that currently has the focus).  This 
  2568. allows using the computer keyboard to select which control is active.  In 
  2569. conjunction with the ENTER and SPACE BAR (for buttons and multiple select 
  2570. lists), any control can be activated, manipulated, and then selected without 
  2571. requiring a mouse. 
  2572.  
  2573. Holding down the CTRL key while pressing TAB causes the focus to jump to the 
  2574. first control of the next Group within a window.  This allows quickly jumping 
  2575. from Group to Group. 
  2576.  
  2577. If no control has the focus (ie, the window itself has the focus), then 
  2578. pressing the TAB key causes the focus to jump to the first control of the first 
  2579. Group. 
  2580.  
  2581. Even if the END flag is set for a Group, when the user switches the focus from 
  2582. a control in that Group, RXDLG does not return.  Therefore, it's possible for 
  2583. the user to select various controls via the TAB key, changing their values, and 
  2584. never having to cause RXDLG to return.  In order to have a control (in a Group 
  2585. with its END Flag set) cause RXDLG to return, the user must explicitly indicate 
  2586. that he is done manipulating the control (for example, he has to press the 
  2587. ENTER key when he's done entering text into an ENTRY.  If he instead presses 
  2588. TAB to switch to another control, RXDLG doesn't return for that ENTRY). 
  2589.  
  2590.  
  2591. ΓòÉΓòÉΓòÉ 5.3.5. NOCLOSE Flag ΓòÉΓòÉΓòÉ
  2592.  
  2593. There are a few reasons why you may want to specify NOCLOSE when creating a 
  2594. window. 
  2595.  
  2596. Let's assume that you want to get input from the user, perform some operation 
  2597. using that input, and then get some more of the same type of input from the 
  2598. user.  You could open a window without NOCLOSE, and when RXDLG returns, it will 
  2599. have returned the user input and closed the window.  You could then perform the 
  2600. operation, and subsequently call RXDLG to reopen the same window.  Here's an 
  2601. example of that approach: 
  2602.  
  2603. /* =============== Create "Main Window" ================= */ 
  2604. /* Just put 1 Group of checkmark buttons in it */ 
  2605. RXTYPE.1 = 'CHECK' 
  2606. RXFLAGS.1 = 'NUMBERED' 
  2607. RXLABEL.1 = 'Pick one' 
  2608. RXINFO.1 = '16 4 0' 
  2609. RXVAL.1 = '1' 
  2610. RXX.1 = 10 
  2611. RXY.1 = 10 
  2612. RXWIN1 = ' ' 
  2613.  
  2614. here: 
  2615.  
  2616. /* Don't specify NOCLOSE */ 
  2617. RXDLG 1 '"Main Window"' 'RXWIN1'  /* No Flags arg needed, as there's nothing to 
  2618. specify */ 
  2619.  
  2620. /* Now we use RXDLG's second template to perform user interaction. No window or 
  2621. operation arg means "Use Main Window" and "Operation 0" (ie, perform user 
  2622. interaction, but don't clear any NOCLOSE Flag -- not applicable here since we 
  2623. never set that flag anyway) */ 
  2624. RXDLG 
  2625.  
  2626. /* The window is now closed */ 
  2627.  
  2628. /* At this point, we examine the REXX return values, and perform some 
  2629. operation. Then we jump back to "here" */ 
  2630. SIGNAL here 
  2631.  
  2632. In the above example, the window would be opening and closing for each 
  2633. iteration.  What if you wanted the window to stay open until you had completed 
  2634. as many iterations as desired?  Well, that's where NOCLOSE comes in.  Here's 
  2635. the revamped version (from the label "here" -- everything up to that point 
  2636. remains the same): 
  2637.  
  2638. here: 
  2639.  
  2640. /* Specify NOCLOSE, so RXDLG doesn't close the window when it returns */ 
  2641. RXDLG 1 '"Main Window"' 'RXWIN1'  'NOCLOSE' 
  2642.  
  2643. more: 
  2644.  
  2645. /* Now we need to use RXDLG's second template to perform user interaction. No 
  2646. window or operation arg means "Use Main Window" and "Operation 0" (ie, perform 
  2647. user interaction, but don't tell Rexx Dialog that it's OK to close the window) 
  2648. */ 
  2649. RXDLG 
  2650.  
  2651. /* The window is still open */ 
  2652.  
  2653. /* At this point, we examine the REXX return values, and perform some 
  2654. operation.  Then, we can jump back to the label "more" to do more user 
  2655. interaction.  We don't jump back to "here" because we don't need to open the 
  2656. window again */ 
  2657. SIGNAL more 
  2658.  
  2659. Another reason to use NOCLOSE is if you have a Group which you want to cause 
  2660. RXDLG to return (ie, you specified the 'END' Flag for the Group), but you don't 
  2661. want that to cause the window to be closed.  For example, maybe each checkmark 
  2662. button in the above group causes the REXX script to turn on/off something, and 
  2663. you want this action to be performed in realtime.  (ie, As soon as the user 
  2664. selects a checkmark, turning it on or off, you want control to return to the 
  2665. REXX script so that you can carry out that operation immediately.  Therefore, 
  2666. you have to specify the END Flag for the Group, because otherwise, RXDLG 
  2667. wouldn't return after each click on a checkmark -- it would only return when 
  2668. the user clicked on the CLOSE ICON for the window).  But, you don't want the 
  2669. window to close down everytime that he clicks on a checkmark in that Group 
  2670. either.  So, you need to specify NOCLOSE too. 
  2671.  
  2672.  
  2673. ΓòÉΓòÉΓòÉ 5.3.6. MODAL Flag ΓòÉΓòÉΓòÉ
  2674.  
  2675. Normally, the WindowTitle arg for the second template of RXDLG will either be 
  2676. omitted (if also doing an Operation of 0), or specified as a pair of double 
  2677. quotes inside of single quotes (ie, '""') meaning that you wish Rexx Dialog to 
  2678. initiate user interaction upon the window that was active during the previous 
  2679. call to RXDLG. 
  2680.  
  2681. There may be times when you have multiple windows open, but you want to force 
  2682. the user to interact with only one of the windows (ie, disable interaction with 
  2683. the other windows).  You do this by specifying the MODAL Flag when you create 
  2684. the window, and then passing that window's title to RXDLG when doing an 
  2685. Operation that performs user interaction (ie, 0 or 1).  Rexx Dialog will 
  2686. disable all other windows (and any controls in the Main Window).  The user must 
  2687. interact with only that window (although he is allowed to minimize or resize 
  2688. the Main Window, and perhaps switch to another app).  Only when that window is 
  2689. destroyed will this "Modal State" also be ended. 
  2690.  
  2691. Note:  The Main Window can't be made MODAL.
  2692.  
  2693. By making Child Dialogs modal, and then passing the title of the specific 
  2694. window that you wish to be the "active" window to RXDLG, you can control the 
  2695. user's interaction with multiple open windows. 
  2696.  
  2697.  
  2698. ΓòÉΓòÉΓòÉ 5.3.7. Opening windows within a message loop ΓòÉΓòÉΓòÉ
  2699.  
  2700. For windows that are going to be open during the life of your script, you 
  2701. normally will make a series of calls to RXDLG, using the first template, to 
  2702. create all of those windows.  Then, after all windows are open, you'll drop 
  2703. into a "message loop" around a call to RXDLG using its second template to do 
  2704. user interaction upon the windows. 
  2705.  
  2706. But, you can call RXDLG, using the first template, to create new windows at any 
  2707. time, including within that message loop.  For example, you could have a button 
  2708. in the Main Window which causes RXDLG to return.  When your message loop 
  2709. detects that this button in Main Window has been pressed, you could call RXDLG 
  2710. to create a new window.  But, your message loop should also contain 
  2711. instructions to specifically handle any situation where RXWIND is returned as 
  2712. the name of that new window.  After all, that will be one more open window that 
  2713. the user can choose to interact with. 
  2714.  
  2715.  
  2716. ΓòÉΓòÉΓòÉ 5.3.8. A message loop within a message loop ΓòÉΓòÉΓòÉ
  2717.  
  2718. Let's assume that you have a button in the Main Window labeled "Players names" 
  2719. which causes RXDLG to return.  When your message loop detects that this button 
  2720. in Main Window has been pressed, you want to call RXDLG to create a new window 
  2721. with an ENTRY for the user to type in some person's name.  Each time that the 
  2722. person types in a name, you want to add this to a stem variable, clear the 
  2723. ENTRY, and let him type in another player's name.  During this entire process, 
  2724. you want to prevent him from interacting with other windows.  When he finally 
  2725. enters a blank name, or clicks upon the window's CLOSE ICON, then you'll close 
  2726. the window, and return to allowing the user to interact with whatever other 
  2727. windows are open at his discretion.  For that ENTRY window, you'll make it 
  2728. MODAL, and then do what appears to be a message loop (on that MODAL window) 
  2729. inside of the larger message loop. 
  2730.  
  2731. /* =============== Create "Main Window" ================= */ 
  2732. /* Just put 1 Push button in it */ 
  2733. RXTYPE.1 = 'PUSH' 
  2734. RXFLAGS.1 = 'END' 
  2735. RXLABEL.1 = 'Players names' 
  2736. RXINFO.1 = '1 1 0' 
  2737. RXVAL.1 = '1' 
  2738. RXX.1 = 10 
  2739. RXY.1 = 10 
  2740. RXWIN1 = ' ' 
  2741. RXDLG 1 '"Main Window"' 'RXWIN1' 'NOCLOSE' 
  2742.  
  2743. /* Perhaps open more windows now... */ 
  2744.  
  2745. /* Put any window's Dimensions strings outside of the message loop so it only 
  2746. gets initialized once */ 
  2747. RXWIN2 = '150 70 50 50' 
  2748.  
  2749. more: 
  2750.  
  2751. /* Do user interaction upon main (and any other open) windows */ 
  2752. RXDLG 
  2753.  
  2754. /* Did the user click on the Main Window's CLOSE ICON? If so, end the program 
  2755. */ 
  2756. IF RXID < 0 THEN DO 
  2757.   IF RXWIND = 'Main Window' THEN EXIT 
  2758. END 
  2759.  
  2760. ELSE SELECT 
  2761.   WHEN RXWIND = 'Main Window' THEN DO 
  2762.   /* There's only 1 button in Main, so don't bother checking RXID and RXSUBID 
  2763. */ 
  2764.  
  2765.     /* Open that Child Dialog with the ENTRY. NOCLOSE and MODAL */ 
  2766.     RXTYPE.1 = 'ENTRY' 
  2767.     RXFLAGS.1 = 'END' 
  2768.     RXLABEL.1 = 'Name:' 
  2769.     RXINFO.1 = '1 1 60' 
  2770.     RXVAL.1 = 'TEXT' 
  2771.     RXX.1 = 50 
  2772.     RXY.1 = 10 
  2773.     TEXT.1 = ' ' 
  2774.     RXDLG 1 '"Player Name"' 'RXWIN2' 'NOCLOSE|MODAL' 
  2775.  
  2776.     /* Get the next name */ 
  2777.     name = 1 
  2778.     DO WHILE name > 0 
  2779.       RXDLG '"Player Name"' 
  2780.  
  2781.       /* Did the user click on window's CLOSE ICON? If so, return to main loop 
  2782. */ 
  2783.       IF RXID < 0 | TEXT.1 = 0 THEN DO 
  2784.         RXDLG '"Player Name"' 4 
  2785.         name = 0 
  2786.       END 
  2787.  
  2788.       ELSE DO 
  2789.         NAMES.name = TEXT.1 
  2790.         name = name + 1 
  2791.          RXSET '"Player Name"' 1 1 'VAL' 
  2792.       END 
  2793.     END 
  2794.   END 
  2795. END 
  2796.  
  2797. /* Go back to the "main" message loop */ 
  2798. SIGNAL more 
  2799.  
  2800.  
  2801. ΓòÉΓòÉΓòÉ 5.4. RXERR ΓòÉΓòÉΓòÉ
  2802.  
  2803. Template       RXERR Flags 
  2804.  
  2805. Description    This command controls whether Rexx Dialog automatically displays 
  2806.                error message boxes when an error occurs (as a result of calling 
  2807.                some Rexx Dialog command).  It also controls whether error 
  2808.                messages or error numbers are returned to a script.  Sometimes, 
  2809.                it's easier for a script to deal with error numbers rather than 
  2810.                messages when trying to recover from some error situation.  If 
  2811.                Rexx Dialog is allowed to automatically display, this also 
  2812.                controls whether just the error message is displayed, or whether 
  2813.                the line number and REXX source where the error occurred is also 
  2814.                displayed in a message box. 
  2815.  
  2816.                RXERR can be called at any time.  (ie, You can change the error 
  2817.                behavior at any time via a call to RXERR). 
  2818.  
  2819. Args 
  2820.  
  2821. Flags          A string that describes the various display and control options 
  2822.                for error returns.  You can specify any or all of these Flags, 
  2823.                and each one must be separated by a | character, enclosed in 
  2824.                quotes. The various Flags are: 
  2825.  
  2826. NUM            Return error numbers instead of error messages.  For example, if 
  2827.                you pass the title of a window that isn't open to RXDLG (ie, 
  2828.                using its second template), then RXDLG will return, setting the 
  2829.                special variable RC to error number 10011 rather than the 
  2830.                message "Can't find Rexx Dialog.". 
  2831.  
  2832. FULL           If Rexx Dialog is automatically displaying error messages for a 
  2833.                particular error number, then you want the line number and REXX 
  2834.                source where the error occurred to also be displayed.  (Without 
  2835.                this flag, Rexx Dialog displays only the error message). 
  2836.  
  2837. A display level (ie, numeric arg) can also be specified.  Rexx Dialog displays 
  2838. error messages for all errors that have a display level less than or equal the 
  2839. specified level.  If display level is 0, then Rexx Dialog never displays error 
  2840. messages (having to do with calls to Rexx Dialog functions -- the REXX 
  2841. Interpreter may still present message boxes for such things as syntax errors, 
  2842. etc).  If display level is not specified, then Rexx Dialog will display any 
  2843. error message having to do with a Rexx Dialog function. 
  2844.  
  2845. Note:  A particular error's display level is simply the rightmost two digits of 
  2846.        the error number.  For example, the "Can't find Rexx Dialog" error has 
  2847.        an error number of 10011.  It's display level is therefore 11.  If you 
  2848.        specify a display level of 10 to RXERR, then Rexx Dialog will not 
  2849.        automatically display the "Can't find Rexx Dialog" error message (nor 
  2850.        any error messages with higher display levels).  See Errors for details 
  2851.        on the error number for all Rexx Dialog error messages.
  2852.  
  2853. It doesn't matter in which order flags are specified. 
  2854.  
  2855. When you specify FULL, any Rexx Dialog errors that are to be automatically 
  2856. displayed generate a REXX FAILURE condition.  Otherwise, Rexx Dialog errors 
  2857. generate a REXX ERROR condition. 
  2858.  
  2859. Returns 
  2860.  
  2861. None 
  2862.  
  2863. Examples 
  2864.  
  2865. /* This specifies that Rexx Dialog is not to display any error messages (ie, 
  2866. display level is 0), and is to return error numbers for RC */ 
  2867.  
  2868. RXERR 'NUM|0' 
  2869.  
  2870.  
  2871. ΓòÉΓòÉΓòÉ 5.5. RXFILE ΓòÉΓòÉΓòÉ
  2872.  
  2873. Template       RXFILE Type FilenameVar ButtonLabel '|' Title 
  2874.  
  2875. Description    This command presents the OS/2 File Dialog, whereby the user can 
  2876.                pick out a filename (complete with path), which is returned to 
  2877.                the script. 
  2878.  
  2879.                The File Dialog will open on the Desktop if there are no windows 
  2880.                open.  Otherwise, it will open in the Main Window, and will be a 
  2881.                modal dialog (ie, user can't interact with any windows until the 
  2882.                File Dialog is dismissed). 
  2883.  
  2884. Args 
  2885.  
  2886. Type is either 'LOAD' or 'SAVE'.  If 'LOAD', then the user is allowed to click 
  2887. upon a filename in the list of files in the displayed directory, and that 
  2888. selection is copied to the filename entry.  If 'SAVE', the user can't click 
  2889. upon a filename in the list.  The list is just for reference, and the user must 
  2890. manually type in the desired name.  The latter scheme makes it more difficult 
  2891. to accidentally click on an existing file, which would be dangerous for a save 
  2892. operation. 
  2893.  
  2894. FilenameVar is the name of the REXX variable where the filename will be 
  2895. returned.  Before the call to RXFILE, this must be initialized with a file or 
  2896. path name in order to bring up the File Dialog displaying the contents of that 
  2897. directory.  For example, assume that FilenameVar will be RXNAME.  Setting 
  2898. RXNAME to 'C:\OS2\*.exe' will display all of the files in the 'C:\OS2' 
  2899. directory that end in an '.exe' extension.  If you want to display all files in 
  2900. a directory then use '*.*', for example 'C:\OS2\*.*'.  If you want to display 
  2901. the current directory, with no filtering, then set the variable to a null 
  2902. string (ie, ' '). 
  2903.  
  2904. ButtonLabel is a string that you want displayed in the "OK" button of the File 
  2905. Dialog.  If omitted, the default string is "OK". 
  2906.  
  2907. Title is the string that you want displayed in the titlebar of the File Dialog. 
  2908. If omitted, then the titlebar is blank.  If this is specified, you must place a 
  2909. | character in quotes inbetween the ButtonLabel and Title.  (It's ok to omit 
  2910. any ButtonLabel before the | character, if desired). 
  2911.  
  2912. Returns 
  2913.  
  2914. If Rexx Dialog is returning strings (ie, the NUM flag has not been specified to 
  2915. RXERR), then a null string '' is returned if the user clicked upon the "OK" 
  2916. button to end the dialog.  "Cancel" is returned if the user clicked upon the 
  2917. CANCEL button to end the dialog.  (The CANCEL button does not raise a REXX 
  2918. FAILURE or ERROR, nor does it automatically display an error message, so you 
  2919. must explicitly check the RC return of RXFILE in order to determine if the user 
  2920. cancelled the filename selection.  If Rexx Dialog is returning numbers, then 0 
  2921. is OK, and 350 is CANCEL. 
  2922.  
  2923. This may return other errors as described in Errors, which raise a REXX FAILURE 
  2924. or ERROR. 
  2925.  
  2926. If an OK selection, the filename is returned in the REXX variable specified by 
  2927. the FilenameVar arg.  This will be a fully qualified filename (ie, with the 
  2928. drive and directory too). 
  2929.  
  2930. Examples 
  2931.  
  2932. /* This gets a filename selection and checks for 'OK' selection */ 
  2933.  
  2934. /* Store the filename in the variable FN. Initialize it to '*.cmd' in order to 
  2935. initially display all filenames in the current directory that end in '.cmd' */ 
  2936. FN = '*.cmd' 
  2937. RXFILE 'LOAD' 'FN' 'Load Me|' 'This is the title' 
  2938. IF RC = '' THEN DO  /* check for 0 if Rexx Dialog returning numbers */ 
  2939.   /* Do some operation with the filename in FN */ 
  2940. END 
  2941.  
  2942.  
  2943. ΓòÉΓòÉΓòÉ 5.6. RXHELP ΓòÉΓòÉΓòÉ
  2944.  
  2945. Template       RXHELP 'CREATE' WindowTitle HelpFilename 
  2946.                RXHELP 'FREE' WindowTitle 
  2947.                RXHELP Panel WindowTitle 
  2948.  
  2949. Description    This command attaches or detaches an OS/2 Help file to a window, 
  2950.                and then can to be used to display a help "panel" from that help 
  2951.                file (ie, page within the book).  It has 3 templates depending 
  2952.                upon whether you want to attach a help file, detach a help file, 
  2953.                or display a panel within a help file. 
  2954.  
  2955.                RXHELP uses OS/2's Information Presentation Manager Facility. 
  2956.                For example, this book that you're reading is an example of IPF. 
  2957.                You use OS/2's Information Presentation Facility Compiler, 
  2958.                IPFC.EXE, to create a .HLP file (ie, write a script with the 
  2959.                imbedded IPF "tags" and compile it into a HLP file).  Then, you 
  2960.                can attach such a file to a window using RXHELP. 
  2961.  
  2962.                Each window can have a different HLP file attached to it.  Only 
  2963.                one help file can be attached to a given window. 
  2964.  
  2965.                Note:  You can attach a help file to a window, and then later 
  2966.                       attach a different help file to that same window.  But, 
  2967.                       if there are any Child Dialogs that share the same help 
  2968.                       file as the Main Window (ie, you didn't supply the 
  2969.                       HelpFilename arg when attaching a help file to the Child 
  2970.                       Dialog), then you should do a 'FREE' upon those Child 
  2971.                       Dialogs before ever changing the Main Window's help file.
  2972.  
  2973. Args 
  2974.  
  2975. If the first template is being used (ie, first arg is 'CREATE'), then this 
  2976. attaches a Help file to a window.  If HelpFilename is omitted, then it doesn't 
  2977. attach a new file, but instead shares the same help file that is attached to 
  2978. the Main Window.  Otherwise, this attaches the specified HelpFilename (ie, the 
  2979. name of some OS/2 Help file) to the window whose title matches WindowTitle. 
  2980. WindowTitle must be enclosed in quotes if there are spaces within the window 
  2981. title.  If WindowTitle is a null string (ie, use '""'), then the Main Window 
  2982. will be the one to which the help file is being attached.  You can call 
  2983. 'CREATE' at any time to change the help file attached to a window.  You do not 
  2984. need to 'FREE' a previous help file, except as noted above for Child Dialogs 
  2985. that share the Main Window, when you wish to subsequently change the Main 
  2986. Window's help file. 
  2987.  
  2988. If the second template is being used (ie, first arg is 'FREE'), then this 
  2989. detaches a Help file from the window whose title matches WindowTitle. 
  2990. WindowTitle must be enclosed in quotes if there are spaces within the window 
  2991. title.  If WindowTitle is a null string (ie, use '""'), then any help file is 
  2992. detached from the Main Window.  'FREE' only ever needs to be done as noted 
  2993. above. 
  2994.  
  2995. If the third template is being used, Panel is the panel number or name within 
  2996. the help file that you want displayed.  Panel must be enclosed in quotes if 
  2997. there are spaces within the panel name.  WindowTitle is the window whose help 
  2998. file is to be used to find the panel.  WindowTitle must be enclosed in quotes 
  2999. if there are spaces within the window title.  If WindowTitle is omitted, the 
  3000. Main Window is used. 
  3001.  
  3002. Note:  The name of a panel should not start with a numeric character, although 
  3003.        these may appear later in the name.  Also, you must not name a panel 
  3004.        such that the first 4 letters are CREA or FREE.
  3005.  
  3006. Returns 
  3007.  
  3008. This may return some errors as described in Errors. 
  3009.  
  3010. Examples 
  3011.  
  3012. /* This attaches the file "test.hlp" (in the current dir, or along the help 
  3013. path) to a window named "Main", and brings up a panel named "INFO" */ 
  3014.  
  3015. RXHELP 'CREATE' 'Main' 'test.hlp' 
  3016.  
  3017. RXHELP 'INFO' 'Main' 
  3018.  
  3019.  
  3020. ΓòÉΓòÉΓòÉ 5.7. RXQUERY ΓòÉΓòÉΓòÉ
  3021.  
  3022. Template       RXQUERY WindowTitle 
  3023.  
  3024. Description    This command returns (in the special REXX variable RC) a 0 if 
  3025.                the passed WindowTitle does not match an open window, or 1 if a 
  3026.                window with that title is open.  This can be used to check 
  3027.                whether a particular window is open. 
  3028.  
  3029. Args 
  3030.  
  3031. WindowTitle is a string to match with the title of any open window.  This must 
  3032. be enclosed in quotes if there are spaces within the window title. 
  3033.  
  3034. Returns 
  3035.  
  3036. 0 if the specified window is not open, or 1 if that window is open. 
  3037.  
  3038. Examples 
  3039.  
  3040. /* This gets the version and revision numbers and displays each separately */ 
  3041.  
  3042. RXVERS 
  3043. rev = RC 
  3044. PARSE rev ver rev 
  3045. RXSAY 'Version = 'ver 
  3046. RXSAY 'Revision = 'rev 
  3047.  
  3048.  
  3049. ΓòÉΓòÉΓòÉ 5.8. RXSAY ΓòÉΓòÉΓòÉ
  3050.  
  3051. Template       RXSAY Message '|' Type Heading 
  3052.  
  3053. Description    This command pops up a message box on the Desktop, displaying 
  3054.                the text that you specified after the RXSAY command keyword. 
  3055.                There will be one or more push buttons that the user can click 
  3056.                the mouse upon in order to manually dismiss the message box. 
  3057.                The box remains displayed, and your script is suspended, until 
  3058.                the user dismisses that box, at which time your script resumes 
  3059.                its processing (on the next REXX line after the call to RXSAY). 
  3060.  
  3061.                Use this instead of the REXX standard SAY command.  The SAY 
  3062.                command won't display anything because the REXX script isn't 
  3063.                being run from an OS/2 Command Prompt window, (and that's where 
  3064.                the standard SAY command tries to send its output, with the net 
  3065.                result that the output gets discarded).  In fact, you can't use 
  3066.                the PULL nor PARSE PULL commands either, or any other REXX 
  3067.                standard command that tries to get input or output from a 
  3068.                command line.  But then, that's why Rexx Dialog exists -- 
  3069.                because the former method is a lousy way to get user input and 
  3070.                display output, and you're going to want to use Rexx Dialog's PM 
  3071.                Interface instead.  Since Rexx Dialog offers other facilities to 
  3072.                open windows and display text, there are other ways of 
  3073.                displaying such, but RXSAY is the easiest and is a direct 
  3074.                replacement for the standard SAY command (mostly).  Just change 
  3075.                any reference from SAY to RXSAY, and you've changed a REXX 
  3076.                script to output via Desktop message boxes.  RXSAY doesn't 
  3077.                recognize any ANSI sequences to change color or move the cursor. 
  3078.                And sometimes programmers use the fact that SAY outputs to only 
  3079.                1 window in order to spread output of one "statement" across 
  3080.                several calls to SAY.  On the other hand, each call to RXSAY 
  3081.                produces a distinct message box.  So, the translation isn't 
  3082.                exact, but it's close enough.  Generally, what RXSAY is used for 
  3083.                is to display error messages, or to offer the user a simple 
  3084.                prompt, such as to ask him if he wants to overwrite an existing 
  3085.                file. 
  3086.  
  3087.                If you have a Main Window open (via the RXDLG command), then the 
  3088.                message box is attached to that window.  In this case, it won't 
  3089.                suspend other OS/2 applications, nor lockup the Desktop until 
  3090.                the message box is dismissed.  If no Main Window is open, the 
  3091.                message box pops up directly upon the Desktop, and the user must 
  3092.                dismiss it before he can do anything else from the Desktop. 
  3093.  
  3094.                RXSAY offers a choice of various pushbuttons that can be created 
  3095.                at the bottom of the message box, which the user can click upon 
  3096.                to dismiss the message box.  RXSAY will then return different 
  3097.                values depending upon which button the user clicked.  For 
  3098.                example, you can use RXSAY to present a box that displays a 
  3099.                question and offers the user a YES or NO button, and write your 
  3100.                REXX script to do different things based upon the returned RC. 
  3101.  
  3102. Args 
  3103.  
  3104. Message        The string that you want displayed.  Just like with the standard 
  3105.                SAY command, it can be a literal string, or a variable.  If you 
  3106.                intend to supply the Type arg, then you must put a | character 
  3107.                after the Message.  This character must be enclosed in quotes in 
  3108.                order to prevent the REXX Interpreter from misinterpreting it as 
  3109.                a mathematical OR symbol.  It's OK to omit blank spaces 
  3110.                inbetween the | and the Message and Type args, or even to 
  3111.                enclose all 3 in one set of quotes if you're supplying a literal 
  3112.                string for Message.  For example, all of the following are the 
  3113.                same: 
  3114.  
  3115.                RXSAY 'hello' '|' 1 
  3116.                RXSAY 'hello''|'1 
  3117.                RXSAY 'hello|' 1 
  3118.                RXSAY 'hello|1' 
  3119.  
  3120. Type           What Buttons (ie, OK, CANCEL, YES, NO, etc) to place at the 
  3121.                bottom of the message box, and also what graphic symbol to 
  3122.                display next to the message (ie, Question Mark, Stop Sign, 
  3123.                Warning Sign, etc).  If Type is omitted, then there are only an 
  3124.                OK button and a Stop Sign. 
  3125.  
  3126.                For the Type arg, pick any 1 of the following button groups, and 
  3127.                then pick out 1 of the graphic symbols, and add the two values 
  3128.                together. 
  3129.  
  3130.                BUTTONS 
  3131.                OK               0 
  3132.                OK and CANCEL        1 
  3133.                RETRY and CANCEL      2 
  3134.                ABORT, RETRY and IGNORE  3 
  3135.                YES and NO          4 
  3136.                YES, NO, and CANCEL     5 
  3137.                CANCEL            6 
  3138.                ENTER             7 
  3139.                ENTER and CANCEL      8 
  3140.  
  3141.                GRAPHIC SYMBOLS 
  3142.                None          0 
  3143.                Question Mark     16 
  3144.                Exclamation Mark   32 
  3145.                Asterisk        48 
  3146.                Stop Symbol      64 
  3147.  
  3148.                For example, set Type as 4+16 if you want YES and NO buttons 
  3149.                with a Question Mark symbol. 
  3150.  
  3151. Heading        The Heading that appears above the message.  If you don't supply 
  3152.                any Heading text, then a default heading is used which consists 
  3153.                of "Rexx Dialog x.x" where x.x is the version and revision 
  3154.                number of the Rexx Dialog release. 
  3155.  
  3156. Returns 
  3157.  
  3158. A number which represents which button the user pressed to dismiss the message 
  3159. box.  Each of the different buttons that you can include in the box not only 
  3160. dismisses the box, but also returns a different value, so your script knows 
  3161. which one the user selected.  Here are the values that each button returns. 
  3162.  
  3163. OK       1 
  3164. CANCEL    2 
  3165. ABORT     3 
  3166. RETRY     4 
  3167. IGNORE    5 
  3168. YES      6 
  3169. NO       7 
  3170. ENTER     9 
  3171.  
  3172. Examples 
  3173.  
  3174. /* Pop up a dialog with the question "Is your name Marvin"? Note that we stored 
  3175. the name 
  3176.   in a variable.  We also include YES and NO buttons, and a Question Mark 
  3177. symbol. */ 
  3178. txt='Marvin' 
  3179. RXSAY 'Is your name 'txt'?|' 20 
  3180. IF RC = 6 THEN RXSAY 'Yes, your name is 'txt'.' 
  3181.  
  3182. Note:  Don't forget the | character, somewhere within quotes, inbetween the 
  3183.        Message and the Type args.  Otherwise, the Type will be misinterpreted 
  3184.        as part of the message and displayed in the message box after the Message.
  3185.  
  3186.  
  3187. ΓòÉΓòÉΓòÉ 5.9. RXSET ΓòÉΓòÉΓòÉ
  3188.  
  3189. Template       RXSET WindowTitle GroupNum ControlNum Operation Value 
  3190.                RXSET WindowTitle WindowOperation Value 
  3191.  
  3192. Description    This command sets the specified control within the specified 
  3193.                Group and Window to a particular value.  In other words, it can 
  3194.                be used to set a currently displayed control to a new value. 
  3195.                The second template is used to change a window's 
  3196.                characteristics. 
  3197.  
  3198. Args 
  3199.  
  3200. WindowTitle is a string to match with the title of any open window.  This must 
  3201. be enclosed in quotes if there are spaces within the window title.  WindowTitle 
  3202. can be an empty string, ie '""', in which case, the Main Window is used for the 
  3203. operation. 
  3204.  
  3205. GroupNum is the Group containing the desired control, where the first Group in 
  3206. the window is 1. 
  3207.  
  3208. ControlNum is the desired control, where the first control in the Group is 1. 
  3209. If you want the Operation to be performed upon all controls within the Group, 
  3210. then pass a ControlNum of 0. 
  3211.  
  3212. Operation is the operation that you desire as so: 
  3213.  
  3214. VAL            Change the value of the control to the Value string. 
  3215.  
  3216. HIDE           Hide the control (ie, visually remove it from the display).  The 
  3217.                Value string is a 1 if you want to hide the Label for the 
  3218.                control (as well as the Value printout for a slider, and 
  3219.                ALL\NONE buttons with multiple select lists and checkmark 
  3220.                Groups), or 0 if you only want to hide the control itself.  If 
  3221.                ControlNum is 0, then all controls in the Group are hidden, as 
  3222.                well as any surrounding groupbox.  For a MENU group, the whole 
  3223.                menu is always hidden. 
  3224.  
  3225. SHOW           Show the control (if it was hidden).  The Value string is a 1 if 
  3226.                you want to show the Label for the control (as well as the Value 
  3227.                printout for a slider, and ALL\NONE buttons with multiple select 
  3228.                lists and checkmark Groups), or 0 if you only want to show the 
  3229.                control itself.  If ControlNum is 0, then all controls in the 
  3230.                Group are shown, as well as any surrounding groupbox.  For a 
  3231.                MENU group, the whole menu is always shown. 
  3232.  
  3233. SIZE           Size a control (ie, visually change its width and/or height). 
  3234.                The Value string specifies the new width and height (in pels) 
  3235.                for the control.  If the width is set to 0, then the width is 
  3236.                not changed (ie, the original width is retained).  If the height 
  3237.                is set to 0 (or omitted), then the height is not changed.  If 
  3238.                ControlNum is 0, then all controls in the Group are sized to the 
  3239.                specified width and height, as well as any surrounding groupbox. 
  3240.                A MENU group can't be sized. 
  3241.  
  3242.                Note:  The SIZE command doesn't properly relocate labels and 
  3243.                       groupboxes for ENTRY nor SLIDER controls.  Furthermore, a 
  3244.                       LIST box's Height should be set to some multiple of 16. 
  3245.                       The SIZE command is provided primarily for sizing the 
  3246.                       width of TEXT or DROPBOX controls, or the width and 
  3247.                       height of LISTBOX controls.
  3248.  
  3249. MOVE           Move a control (ie, visually change its position).  The Value 
  3250.                string specifies the X and Y offsets (in pels from the current 
  3251.                position) to move the control.  If X is set to 0, then the 
  3252.                vertical position is not changed.  If Y is set to 0 (or 
  3253.                omitted), then the horizontal position is not changed.  If 
  3254.                ControlNum is 0, then all controls in the Group are moved the 
  3255.                specified amount, as well as any surrounding groupbox.  A MENU 
  3256.                group can't be moved. 
  3257.  
  3258.                Note:  If you're using the SIZE or MOVE commands upon only 1 
  3259.                       control within a group, and that control is encircled by 
  3260.                       a groupbox, then you should HIDE the control before 
  3261.                       issuing the SIZE or MOVE commands, and then SHOW the 
  3262.                       control afterwards.  This is necessary due a peculiarity 
  3263.                       in the way that OS/2 GroupBoxes handle repainting. 
  3264.                       Failure to follow this guideline may result in seeing 
  3265.                       remnants of the original control's graphic not properly 
  3266.                       erased inside of the groupbox.  If the encircling 
  3267.                       groupbox is a separate GROUP from the control, then 
  3268.                       HIDE/SHOW the groupbox instead of the control.  If you're 
  3269.                       issuing several SIZE and/or MOVE commands, upon several 
  3270.                       controls within a group, but one control at a time, you 
  3271.                       only need to HIDE those controls (or the groupbox) once 
  3272.                       before the MOVE/SIZE commands, and SHOW them afterwards.
  3273.  
  3274. ADD            Add the value string (ie, text for an item) to a LIST or DROP 
  3275.                box, or add a new MENU bar.  When adding a new menu bar, the old 
  3276.                menu bar is deleted. 
  3277.  
  3278. DEL            Delete a particular item (or all items) from a LIST or DROP box, 
  3279.                or a MENU label.  When deleting a menu label, if it happens to 
  3280.                be a Menu Heading, all of the drop down items\subitems for that 
  3281.                heading are also deleted.  If the label happens to be an Item 
  3282.                with SubItems, all of the SubItems are deleted.  Note that the 
  3283.                numbering of the labels doesn't change simply because you 
  3284.                deleted items, subitems, or headings.  You still must count 
  3285.                those deleted labels when counting the menu labels (unless you 
  3286.                create an entirely new menubar -- then the numbering of the 
  3287.                labels is reset). 
  3288.  
  3289. FLAG           Set Flags for the Group.  In this case, the Value string will be 
  3290.                the Flags arg as you would specify it for RXFLAGS.  But, the 
  3291.                only Flags you may set via RXSET are END, INDEX, and BOOL.  The 
  3292.                ControlNum arg is irrelevant. 
  3293.  
  3294. For the second template of RXSET, WindowOperation can be one of the following: 
  3295.  
  3296. HIDE           Hide the window and all of its controls (ie, visually remove it 
  3297.                from the display).  If the Main Window, then all of the child 
  3298.                dialogs get hidden too. 
  3299.  
  3300. SHOW           Show the window (if it was hidden). 
  3301.  
  3302. MOVE           Move the window.  In this case, the Value string will be the X 
  3303.                position and Y position. 
  3304.  
  3305. SIZE           Resize the window.  In this case, the Value string will be the 
  3306.                Width and Height. 
  3307.  
  3308. STATE          Change the window's state.  In this case, the Value string will 
  3309.                be a 0 to minimize the window, 1 to maximize the window, or 2 to 
  3310.                restore the window.  If Value arg is omitted, the window is 
  3311.                minimized. 
  3312.  
  3313. ACTIVE         Brings the window to the front of the screen, and makes it 
  3314.                active. 
  3315.  
  3316. FLAG           Set Flags for the window.  In this case, the Value string will 
  3317.                be the Flags arg as you would specify it to RXDLG.  But, the 
  3318.                only Flags you may set via RXSET are NOCLOSE, MODAL, KEYS, ONCE, 
  3319.                and RESULT. 
  3320.  
  3321. TIME           Sets the time-out for the window.  In this case, the Value 
  3322.                string will be the desired time-out in milliseconds.  (1000 
  3323.                milliseconds = 1 second, 1000*60 milliseconds = 1 minute, etc). 
  3324.                If you pass a Value of 0 (or omit the Value arg), then the 
  3325.                time-out function for the window is turned off, and the timer is 
  3326.                stopped.  A non-zero time-out will start the timer.  See Time 
  3327.                out. 
  3328.  
  3329. Value is the value for the Operation.  Note that you do not need to place any 
  3330. Value string inside of 2 sets of quotes, even if it is a literal string with 
  3331. imbedded spaces. 
  3332.  
  3333. Here is what Value string specifies for each Group Type when the Operation is 
  3334. VAL: 
  3335.  
  3336. PUSH           Value is a 1 if the button is to be chosen as the default, or a 
  3337.                0 if the button is to be unselected.  Note that if a button is 
  3338.                selected for default, all other buttons in the Group are 
  3339.                automatically unselected. 
  3340.  
  3341. RADIO          Value is a 1 if the button is to be selected, or a 0 if the 
  3342.                button is to be unselected.  Note that if a button is selected, 
  3343.                all other buttons in the Group are automatically unselected. 
  3344.  
  3345. CHECK          Value is a 1 if the button is to be checked, or a 0 if the 
  3346.                button is to be unchecked. 
  3347.  
  3348. ENTRY          Value is the text to set into the entry box.  The text should 
  3349.                not contain a | character.  Omitting the text will blank the 
  3350.                box. 
  3351.  
  3352. DROP           Value is the text to set into the entry box.  The text should 
  3353.                not contain a | character.  Omitting the text will blank the 
  3354.                box. 
  3355.  
  3356. LIST           Value is the text of the item to select or deselect.  This text 
  3357.                should be followed by a | character, and then either a 1 or 0 to 
  3358.                select or deselect any item that matches the text.  If you omit 
  3359.                the text before the | character, then all items are selected if 
  3360.                a 1 follows the |, or all items are deselected if a 0 follows 
  3361.                the |. 
  3362.  
  3363.                Note:  For single-select list boxes, only 1 item can be selected 
  3364.                       at a time, and all other items will be automatically deselected.
  3365.  
  3366. SPIN           Value is the numeric value to which the spin will be set. 
  3367.  
  3368. SLIDER         Value is the numeric value to which the slider (knob) will be 
  3369.                set. 
  3370.  
  3371. TEXT           Value is the phrase to display, and ControlNum is the phrase 
  3372.                number to replace.  If the new phrase isn't as wide as the 
  3373.                original WidthOfPhrase (ie, when the TEXT Group was created), 
  3374.                text may be visually clipped. 
  3375.  
  3376. MENU           Value is the text to set into the menu label.  The text should 
  3377.                not contain a | character.  The ControlNum arg to RXSET is the 
  3378.                menu label number.  See Menu Group for how to count the labels. 
  3379.  
  3380. GROUP          Value is the text to set for the groupbox label.  The text 
  3381.                should not contain a | character. 
  3382.  
  3383. Note:  RESULT Type can't be used with a VAL Operation.
  3384.  
  3385. Here is what Value string specifies for each Group Type when the Operation is 
  3386. DEL: 
  3387.  
  3388. LIST or DROP   Value is the text of the item (in the list) to delete.  If you 
  3389.                omit the Value arg (ie, don't supply a string to match), then 
  3390.                all items in the list are deleted (ie, the list is "emptied"). 
  3391.  
  3392. MENU           There is no Value arg.  The ControlNum arg specifies the menu 
  3393.                label to delete.  Note that you can delete the entire menu bar 
  3394.                by passing ControlNum of 0 (ie, specify that you want the delete 
  3395.                action applied to all menus in the Group). 
  3396.  
  3397. Note:  Other Types can't be used with a DEL Operation.
  3398.  
  3399. Here is what Value string specifies for each Group Type when the Operation is 
  3400. ADD: 
  3401.  
  3402. LIST or DROP   Value is the text of the item to add to the list.  This text 
  3403.                should be followed by a | character, and then a number that 
  3404.                specifies how you want the item added to the list.  If you want 
  3405.                the item added to the end of the list, specify -1.  If you want 
  3406.                the item added in ascending alphabetical order, specify -2.  If 
  3407.                you want the item added in descending alphabetical order, 
  3408.                specify -3.  All positive numbers represent the offset in the 
  3409.                list where you want the item placed, with 0 being at the 
  3410.                beginning of the list.  For example, if you want to add the item 
  3411.                as the tenth item in the list, specify 9 (because 0 is the 
  3412.                first). 
  3413.  
  3414.                Note:  Put quotes around any negative numbers that you pass, for 
  3415.                       example '-1'.  OS/2 REXX appears to have another bug 
  3416.                       related to recognizing the minus sign for negative numbers.
  3417.  
  3418. MENU           The Value arg are the HELP Flag, followed by the REXX variable 
  3419.                names where each dropdown menu is defined.  In other words, the 
  3420.                Value arg is just like how you would specify the RXINFO string 
  3421.                for a MENU Group, except that instead of the TotalMenus count in 
  3422.                front of the variable names, you specify the 'HELP' flag 
  3423.                followed by a | character (or just omit the 'HELP' before the | 
  3424.                character if you don't desire a help menu).  Note that you must 
  3425.                set up all of the stem variables as you would if you were 
  3426.                creating a MENU Group in a window. 
  3427.  
  3428. Note:  Other Types can't be used with a ADD Operation.
  3429.  
  3430. Returns 
  3431.  
  3432. This could return an error.  See Errors for details. 
  3433.  
  3434. Examples 
  3435.  
  3436. /* Assume that the first Group in a window called "Window 1" is an ENTRY Group, 
  3437. and we want to change the contents of the 3rd entry to the string "hello there" 
  3438. */ 
  3439.  
  3440. RXSET '"Window 1"' 1 3 'VAL' 'hello there' 
  3441.  
  3442.  
  3443. ΓòÉΓòÉΓòÉ 5.10. RXVERS ΓòÉΓòÉΓòÉ
  3444.  
  3445. Template       RXVERS 
  3446.  
  3447. Description    This command returns a string (in the special REXX variable RC) 
  3448.                that identifies the version and revision numbers (separated by a 
  3449.                space) of RXDLG.DLL.  For example, if the version/revision 
  3450.                number of Rexx Dialog is 1.0, then the returned string is '1 0'. 
  3451.  
  3452. Args 
  3453.  
  3454. None. 
  3455.  
  3456. Returns 
  3457.  
  3458. The version and revision numbers as one string. 
  3459.  
  3460. Examples 
  3461.  
  3462. /* This gets the version and revision numbers and displays each separately */ 
  3463.  
  3464. RXVERS 
  3465. rev = RC 
  3466. PARSE rev ver rev 
  3467. RXSAY 'Version = 'ver 
  3468. RXSAY 'Revision = 'rev 
  3469.  
  3470.  
  3471. ΓòÉΓòÉΓòÉ 6. PM Lockups ΓòÉΓòÉΓòÉ
  3472.  
  3473. While your script is not "sleeping" within a call to RXDLG, and the script has 
  3474. (NOCLOSE) windows open, it may be preventing other PM apps from multitasking 
  3475. (due to OS/2 2.X PM having a single-threaded message queue).  Only when RXDLG 
  3476. is allowed to perform user interaction (ie, when you call RXDLG to perform some 
  3477. operation that allows user interaction with those open windows) can you be 
  3478. assured that your script isn't locking up PM. 
  3479.  
  3480. So, if your script opens NOCLOSE windows, then whenever RXDLG returns, your 
  3481. script should either close all open windows (so that the user can't interact 
  3482. with them and perhaps cause a PM lockup while your script is busy doing 
  3483. something), or finish its work quickly and get back to calling RXDLG with some 
  3484. operation that allows user interaction. 
  3485.  
  3486. But, what if your script doesn't want to close all windows, and yet, needs to 
  3487. do some processing that may take a long time?  In order to avoid any lockup 
  3488. situation, you should periodically call RXDLG with the following call: 
  3489.  
  3490. RXDLG '""' 255 
  3491.  
  3492. Note that the WindowTitle arg is 2 double-quotes inside of single quotes.  An 
  3493. operation of 255 cleans out the PM message queue so that no PM lockup will 
  3494. occur.  The user will not be allowed to interact with any open windows in this 
  3495. call to RXDLG (other than to resize/maximize/minimize the main window), so it 
  3496. doesn't effect REXX variables or the window states at all. 
  3497.  
  3498. For example, assume that you have some open windows, but you need to read in 
  3499. the lines of a text file.  Here's an example where RXDLG is called after 
  3500. reading in every 10 lines in order to clean out the PM message queue.  This 
  3501. will allow the user to switch to and use other PM apps while your script is 
  3502. reading in the lines of the text file. 
  3503.  
  3504. IF ''\=STREAM(FileName,'c','query exists') THEN DO 
  3505.   code=LINEIN(FileName,1,0) 
  3506.   nLines=0 
  3507.   DO WHILE LINES(FileName) 
  3508.    Lin.nLines=LINEIN(FileName) 
  3509.    nLines=nLines+1 
  3510.    IF (nLines%10) = 0 THEN RXDLG '""' 255 
  3511.   END 
  3512.   code=STREAM(FName,'c','close') 
  3513. END 
  3514.  
  3515. Note:  Never use any REXX function library "sleep" function that makes a call 
  3516.        to OS/2's DosSleep() routine.  PM programs are not allowed to use 
  3517.        DosSleep() and doing so will lockup the Desktop.  Calling RXDLG 
  3518.        automatically puts your program to sleep when the user is not 
  3519.        interacting with it, so there is no need to use any sleep function to 
  3520.        halt your script at any point.  Simply call RXDLG with an operation that 
  3521.        does user interaction.  If you need to wakeup at a certain time in order 
  3522.        to check upon some condition, then setup a time-out on a window (perhaps 
  3523.        making it MODAL so that the user won't be able to change to another 
  3524.        window).  Then check the return RXID and RXSUBID both for 0 in order to 
  3525.        detect a time-out.  If you need to ensure that the user can't interfere 
  3526.        with the time-out, then I suggest creating a window with something 
  3527.        simple, like a TEXT group, making the window MODAL, and hiding that 
  3528.        window.  Then, when you need to do a time-out, use RXSET to set the 
  3529.        time-out, and then call RXDLG with an operation of 0 and specify that 
  3530.        window.  After the time-out, you can use RXSET to disable further 
  3531.        time-outs for that window.
  3532.  
  3533.  
  3534. ΓòÉΓòÉΓòÉ 7. Time-out ΓòÉΓòÉΓòÉ
  3535.  
  3536. A time-out can be set for a window which, when your script is sleeping in RXDLG 
  3537. (ie, you performed some operation that does user interaction) and the user has 
  3538. not done anything with that window that would case RXDLG to return during that 
  3539. specified time-out, then RXDLG automatically returns to your script.  In this 
  3540. case, RXID is set to 0 (ie, just like with the ENTER key if the RESULT Flag is 
  3541. set, or other keys if the KEYS Flag is set), and RXSUBID is set to 0. 
  3542.  
  3543. If you wish to change the time-out value, you can do so by calling RXSET with a 
  3544. WindowOperation of 'TIME' and the desired time-out value.  If you set a 
  3545. time-out value of 0, then the time-out function for that window is disabled 
  3546. (and any time-out that may have already occurred is cleared).  Setting a 
  3547. time-out value of anything but 0 causes a time-out for that window to be 
  3548. enabled (and if the time-out was previously enabled, any time-out that may have 
  3549. already occurred is cleared). 
  3550.  
  3551. While your script is not sleeping in RXDLG, the timer will still be counting 
  3552. down for the next time-out.  So, if another time-out occurs while your script 
  3553. is doing some processing, then upon the next call to RXDLG, your script will 
  3554. immediately return with another time-out.  Even if more than 1 time-out occurs 
  3555. while your script is doing some processing (ie, you have a time-out of 10 
  3556. milliseconds, but your script takes 50 milliseconds to do some processing 
  3557. before calling RXDLG again), you'll only be notified of a single time-out.  So, 
  3558. the time-out should not be used as an accurate clock of elapsed time. 
  3559.  
  3560. Setting a time-out value of anything but 0 clears out any time-out that may 
  3561. have occurred while your script was doing some processing.  So, if you wish to 
  3562. "rearm" the time-out before calling RXDLG, simply set the time-out value with 
  3563. RXSET before calling RXDLG. 
  3564.  
  3565. If you want a countdown timer (ie, the timer counts down once, and then is 
  3566. automatically disabled), then set the ONCE Flag for the Window.  This ensures 
  3567. that each time you set a time-out with RXSET, you'll receive one time-out at 
  3568. most. 
  3569.  
  3570. The time-out value is specified in milliseconds. 
  3571.  
  3572.  
  3573. ΓòÉΓòÉΓòÉ 8. Keyboard Input ΓòÉΓòÉΓòÉ
  3574.  
  3575. If you set the KEYS Flag for a window, whenever that window has the focus (ie, 
  3576. the window itself and not some control within it) and the user presses some key 
  3577. combo upon the computer's keyboard, RXDLG will return.  RXWIND will be set to 
  3578. the title of the window which was active when the user pressed the key combo. 
  3579. RXID will be 0 or a negative number depending upon whether the user held down 
  3580. the ALT, SHIFT, and/or CTRL keys when he pressed another key, and whether the 
  3581. key is a printable key (such as "s") or an unprintable key (such as the HOME 
  3582. key). 
  3583.  
  3584. Note:  The ALT, SHIFT, or CTRL keys, pressed by themselves, do not cause RXDLG 
  3585.        to return.  These are "modifier" keys, and only effect the value of RXID 
  3586.        returned when the user presses another key in combination with these modifiers.
  3587.  
  3588. When RXDLG returns, it does NOT close the window, even if that window did not 
  3589. specify the NOCLOSE flag.  The exception to this is pressing the ESC or ENTER 
  3590. keys if the window's RESULT Flag is set. 
  3591.  
  3592. When the user presses a printable key, without the CTRL or ALT keys held down, 
  3593. then RXID is 0, and RXSUBID is that character.  For example, if he presses the 
  3594. 'd' key alone, then RXSUBID is 'd'.  If he holds down the shift key, then the 
  3595. shifted character printed on the key is returned.  For example, if he holds 
  3596. down the SHIFT while pressing 'd', then RXSUBID is 'D'.  If he holds the SHIFT 
  3597. while pressing the '1' key, then RXSUBID is '!'. 
  3598.  
  3599. If the user holds the ALT key while pressing a printable character, then RXID 
  3600. is -1, and RXSUBID is that character.  If he also holds the SHIFT key, that 
  3601. will cause RXSUBID to be the shifted character as above. 
  3602.  
  3603. If the user holds the CTRL key while pressing a printable character, then RXID 
  3604. is -2, and RXSUBID is that character.  If he also holds the SHIFT key, that 
  3605. will cause RXSUBID to be the shifted character as above. 
  3606.  
  3607. If the user holds both the ALT and CTRL keys while pressing a printable 
  3608. character, then RXID is -3, and RXSUBID is that character.  If he also holds 
  3609. the SHIFT key, that will cause RXSUBID to be the shifted character as above. 
  3610.  
  3611. If the user presses an unprintable character without the CTRL, ALT, or SHIFT 
  3612. keys held down, then RXID is -4, and RXSUBID is a "virtual key number".  Here 
  3613. are the virtual key numbers for the following unprintable characters: 
  3614.  
  3615. Break               4 
  3616.  
  3617. BackSpace           5 
  3618.  
  3619. TAB                 6 
  3620.  
  3621. BackTAB             7 
  3622.  
  3623. Pause               13 
  3624.  
  3625. Caps Lock           14 
  3626.  
  3627. Page Up             17 
  3628.  
  3629. Page Down           18 
  3630.  
  3631. End                 19 
  3632.  
  3633. Home                20 
  3634.  
  3635. Left                21 
  3636.  
  3637. Up                  22 
  3638.  
  3639. Right               23 
  3640.  
  3641. Down                24 
  3642.  
  3643. Print Screen        25 
  3644.  
  3645. Insert              26 
  3646.  
  3647. Delete              27 
  3648.  
  3649. Scroll Lock         28 
  3650.  
  3651. Num Lock            29 
  3652.  
  3653. SysRq               31 
  3654.  
  3655. F1                  32 
  3656.  
  3657. F2                  33 
  3658.  
  3659. F3                  34 
  3660.  
  3661. F4                  35 
  3662.  
  3663. F5                  36 
  3664.  
  3665. F6                  37 
  3666.  
  3667. F7                  38 
  3668.  
  3669. F8                  39 
  3670.  
  3671. F9                  40 
  3672.  
  3673. F10                 41 
  3674.  
  3675. F11                 42 
  3676.  
  3677. F12                 43 
  3678.  
  3679. F13                 44 
  3680.  
  3681. F14                 45 
  3682.  
  3683. F15                 46 
  3684.  
  3685. F16                 47 
  3686.  
  3687. F17                 48 
  3688.  
  3689. F18                 49 
  3690.  
  3691. F19                 50 
  3692.  
  3693. F20                 51 
  3694.  
  3695. F21                 52 
  3696.  
  3697. F22                 53 
  3698.  
  3699. F23                 54 
  3700.  
  3701. F24                 55 
  3702.  
  3703. If the user holds the ALT key while pressing an unprintable character, then 
  3704. RXID is -5, and RXSUBID is the virtual key number as described above. 
  3705.  
  3706. If the user holds the CTRL key while pressing an unprintable character, then 
  3707. RXID is -6, and RXSUBID is the virtual key number as described above. 
  3708.  
  3709. If the user holds both the ALT and CTRL keys while pressing an unprintable 
  3710. character, then RXID is -7, and RXSUBID is the virtual key number as described 
  3711. above. 
  3712.  
  3713. If the user holds the SHIFT key while pressing an unprintable character, then 
  3714. RXID is -8, and RXSUBID is the virtual key number as described above. 
  3715.  
  3716. If the user holds both the ALT and SHIFT keys while pressing an unprintable 
  3717. character, then RXID is -9, and RXSUBID is the virtual key number as described 
  3718. above. 
  3719.  
  3720. If the user holds both the CTRL and SHIFT keys while pressing an unprintable 
  3721. character, then RXID is -10, and RXSUBID is the virtual key number as described 
  3722. above. 
  3723.  
  3724. If the user holds the ALT, CTRL, and SHIFT keys while pressing an unprintable 
  3725. character, then RXID is -11, and RXSUBID is the virtual key number as described 
  3726. above. 
  3727.  
  3728. If the user presses the ESC key, RXID is -12, and RXSUBID is 0. 
  3729.  
  3730. If the user presses the ENTER key, RXID is 0, and RXSUBID is 10. 
  3731.  
  3732. Note:  If the user clicks upon the window's CLOSE ICON, RXID is -98, and 
  3733.        RXSUBID is 0.  If the window's NEWSIZE flag is set, and the window is 
  3734.        resized, RXID is -20 and RXSUBID is 0.  If the script is launched by an 
  3735.        app other than RX.EXE, and the app wants the script to abort, RXID is - 
  3736.        99, and RXSUBID is 0.
  3737.  
  3738. PM siphons off some key combos for operation of windows.  For example, pressing 
  3739. the ALT key usually activates a window's menu bar.  And CTRL + ESC switches 
  3740. between sessions.  F1 activates any Help file attached to a window.  Etc. 
  3741. These key combos are never seen by your script. 
  3742.  
  3743. Normally, you'll use ENTRY, DROP, and other PM controls to get strings of user 
  3744. input.  Use of KEYS flag is meant to be used for "keyboard commands".  For 
  3745. example, you can set KEYS for your Main Window, and when the user presses the 
  3746. ALT and "f" keys, you can bring up the File Dialog (ie, via RXFILE) as part of 
  3747. some sort of file operation.  Each key combo will initiate a different 
  3748. operation in your script.  By using mnuemonic symbols (ie, ~ placed before the 
  3749. letter that you wish underlined in any label for a control), and setting the 
  3750. KEYS Flag, you can identity and implement keyboard shortcuts that will 
  3751. implement the same operations as the controls in that window. 
  3752.  
  3753. Rexx Dialog ignores key releases.  Only key down is detected. 
  3754.  
  3755.  
  3756. ΓòÉΓòÉΓòÉ 8.1. ESC and ENTER Keys ΓòÉΓòÉΓòÉ
  3757.  
  3758. If the RESULT Flag is set for a window, then when the window has the focus and 
  3759. the user presses the ESC or ENTER key, RXDLG returns.  RXID and RXSUBID are set 
  3760. as described in Keyboard Input.  But, all of the other variables are set per 
  3761. this window's Groups as well, and if the window doesn't have its NOCLOSE Flag 
  3762. set, the window is closed.  Also, the first RESULT Group (if present) in that 
  3763. window is setup in a FAILURE state if ESC was pressed, or SUCCESS state if the 
  3764. ENTER key was pressed. 
  3765.  
  3766. Note:  When a control within the window has the focus, the ESC and ENTER keys 
  3767.        instead work with that control (regardless of whether you specified the 
  3768.        RESULT Flag).  The dialog window itself must have the focus (ie, which 
  3769.        happens automatically after the user has finished manipulating a control 
  3770.        by pressing the ENTER or ESC keys.  The ESC and ENTER keys can always be 
  3771.        used to deactivate a control and return the focus back to the window 
  3772.        itself.  The ENTER key will usually cause a Group with its END Flag to 
  3773.        force RXDLG to return, whereas the ESC key will not).
  3774.  
  3775.  
  3776. ΓòÉΓòÉΓòÉ 9. Positioning a window ΓòÉΓòÉΓòÉ
  3777.  
  3778. If you double-click the mouse 2 button anywhere in a window, this pushs the 
  3779. window down to the lower left corner of the Main Window (if a Child Dialog) or 
  3780. the Desktop (if a Main Window).  Since Child Dialogs open inside of the Main 
  3781. Window, sometimes a situation may happen where the titlebar of the Child Dialog 
  3782. is beyond the border of the Main Window (and therefore inaccessible by the 
  3783. mouse unless you can resize the Main Window to get to that titlebar).  Clicking 
  3784. the mouse 2 button twice is an easy way to drop the window down to the lower 
  3785. left corner, where the Child Dialog's controls will usually be more accessible. 
  3786.  
  3787.  
  3788. ΓòÉΓòÉΓòÉ 10. Resizing a window ΓòÉΓòÉΓòÉ
  3789.  
  3790. If the window's NEWSIZE flag is set, then after the user resizes that window, 
  3791. RXDLG returns with RXWIND set to the name of the window that was resized, RXID 
  3792. = -20 (and RXSUBID = 0), and the window's Dimensions string is updated with the 
  3793. width and height (as well as X and Y position of the lower left corner relative 
  3794. to the Desktop).  A use for this might be to issue a RXSET SIZE command to 
  3795. resize any LISTBOX height, or TEXT or DROPBOX width in accordance with the size 
  3796. of the window.  Here's an example of detecting that a window has been resized, 
  3797. and parsing the new width and height. 
  3798.  
  3799. /* Creates a window called "Text" containing 1 TEXT Group with 1 line of 
  3800. centered text */ 
  3801.  
  3802. RXTYPE.1 = 'TEXT' 
  3803.  
  3804. /* Center the text */ 
  3805. RXFLAGS.1 = 'CENTER' 
  3806.  
  3807. /* Text lines */ 
  3808. RXLABEL.1 = 'Hello' 
  3809.  
  3810. /* TotalPhrases, PhrasesPerLine, WidthOfPhrase, BetweenPhrases */ 
  3811. RXINFO.1 = '1 1' 
  3812.  
  3813. /* Position */ 
  3814. RXX.1 = 10 
  3815. RXY.1 = 10 
  3816.  
  3817. RXDIM = ' ' 
  3818. RXDLG 1 '"Text"' 'RXDIM' 'SIZE|NEWSIZE' 
  3819.  
  3820. /* Do user interaction */ 
  3821. RXDLG 
  3822.  
  3823. /* Is this a resize? */ 
  3824. IF RXID = -14 THEN DO 
  3825.  
  3826.   /* We only have 1 window, but if we had several open, we'd need to check 
  3827. which one was resized so that we'd know which one's Dimensions string to parse 
  3828. */ 
  3829.   IF RXWIND = 'Text' THEN DO 
  3830.    PARSE VAR RXDIM width height x y 
  3831.    /* Now width, height, x, and y hold the window dimensions */ 
  3832.   END 
  3833. END 
  3834.  
  3835.  
  3836. ΓòÉΓòÉΓòÉ 11. Aborting a script ΓòÉΓòÉΓòÉ
  3837.  
  3838. If a script is going to be launched by an app other than RX.EXE (the app must 
  3839. be written to specifically use RXDLG.DLL), then upon return from an RXDLG 
  3840. Operation 0 or 1, you should check if RXID = -99, and immediately EXIT if so. 
  3841. This is the app's way of indicating that it would like your script to 
  3842. prematurely abort. 
  3843.  
  3844.  
  3845. ΓòÉΓòÉΓòÉ 12. Errors ΓòÉΓòÉΓòÉ
  3846.  
  3847. All Rexx Dialog commands return either a string or number (depending upon which 
  3848. you specify via RXERR, but some commands always return strings).  The return is 
  3849. stored in the special REXX symbol RC.  As each command is issued, RC reflects 
  3850. what that command returns.  The return usually tells you whether a command 
  3851. worked or failed (although sometimes the return provides other info instead 
  3852. such as which button was used to dismiss a RXSAY box).  An RC of 0 (for error 
  3853. numbers) or an empty string, ie "" (for error strings) is considered to be a 
  3854. successful return.  In the case of a command that could fail as a result of 
  3855. something that goes wrong within the command, you should always check RC after 
  3856. issuing that command.  Alternately, since all Rexx Dialog commands set the REXX 
  3857. FAILURE or ERROR flags for any possible errors, you can SIGNAL ON ERROR or 
  3858. SIGNAL ON FAILURE to an appropriate place in your REXX script to handle such an 
  3859. error situation. 
  3860.  
  3861. Some Rexx Dialog commands always work if they make it past the REXX interpreter 
  3862. to RX.EXE.  But of course, any command can fail as a result of some syntax 
  3863. error (ie, you typed it in incorrectly) or other errors that occur before the 
  3864. REXX interpreter ships the command off to RX.EXE.  In this case, the ERROR or 
  3865. FAILURE flag is usually raised by the REXX interpreter itself, and it will 
  3866. return an RC value (usually a number that is not 0, instead of an empty 
  3867. string).  Or, the interpreter may abort the script and return an error number 
  3868. to RX.EXE.  In the case of these errors, RX.EXE displays a PM message box 
  3869. containing the error.  The heading of the dialog will be "REXX INTERPRETER 
  3870. ERROR".  (When you use RXSAY, the PM message box default heading is "Rexx 
  3871. Dialog x.x" where x.x is the version and revision number of the Rexx Dialog 
  3872. release).  The error message provided by the interpreter usually identifies the 
  3873. line number in your script where the error occurred, and may also display the 
  3874. text upon that line. 
  3875.  
  3876. Note:  The interpreter doesn't count blank lines, or lines that only contain 
  3877.        comments.  So when it reports that an error occurred upon line 5, that 
  3878.        doesn't mean that it actually is line 5 in your text file.  You need to 
  3879.        count the lines, skipping any blank lines or lines that contain only 
  3880.        comments in order to find the "real" line 5.
  3881.  
  3882. If REXX aborts the script (ie, perhaps REXX detected an error with it before 
  3883. even starting the script running), then RX.EXE will display an error message in 
  3884. a PM message box.  Once again, the message box will have a heading that says 
  3885. "REXX INTERPRETER ERROR:".  If the problem was with RX.EXE being unable to set 
  3886. itself up or find the script that you specified to run, then the message box 
  3887. heading will be "Rexx Dialog x.x".  The 2 different headings allow you to 
  3888. visually differentiate between errors with the REXX interpreter (ie, usually 
  3889. with the standard REXX commands, or syntax problems, etc), and errors with 
  3890. processing the 9 special Rexx Dialog commands (errors that occur in creating 
  3891. and managing the PM interface).  For the meaning of REXX INTERPRETER ERROR 
  3892. messages, consult your REXX documentation. 
  3893.  
  3894. When developing a script, it may be advantageous to include this line at the 
  3895. top: 
  3896.  
  3897. RXERR 'FULL' 
  3898.  
  3899. This will force the REXX interpreter to supply the line number and REXX source 
  3900. where the error occurred. 
  3901.  
  3902. Here are the error messages (and corresponding error numbers) that each Rexx 
  3903. Dialog command may return.  The bottom two (highlighted) digits of the error 
  3904. number indicate the "display level" for that message (to be used as a reference 
  3905. when you set the display level with RXERR). 
  3906.  
  3907. RXDLG 
  3908.  
  3909. When you use the first template of RXDLG, it could return any of the following 
  3910. errors: 
  3911.  
  3912. 211       "Can't create dialog." 
  3913.  
  3914.           Rexx Dialog couldn't create the window (into which all of the Groups 
  3915.           of controls are placed).  Possible problems are: you have too many 
  3916.           windows open and OS/2 has run out of certain PM resources, or you may 
  3917.           have specified a window size that is too big for the display or X and 
  3918.           Y positions that cause problems (ie, try setting the windows 
  3919.           Dimensions string to a null string for default size and position). 
  3920.  
  3921. 212       "Can't create control: Group XXX, Control XXX." 
  3922.  
  3923.           Rexx Dialog couldn't create a particular control within a Group.  The 
  3924.           XXX after "Group" will indicate which Group number the control 
  3925.           belonged to.  For example, if the control was in the first Group that 
  3926.           you defined for the window, then XXX would be 1.  The XXX after 
  3927.           "Control" will indicate which control within the group couldn't be 
  3928.           created.  For example, if the control was in the first in the group, 
  3929.           then XXX would be 1.  Possible problems are: you have too many 
  3930.           windows/controls open and OS/2 has run out of certain PM resources, 
  3931.           or you specified some incorrect width for the control, or you 
  3932.           specified some strange X and Y position for the group, or made some 
  3933.           other error in the setup of REXX variables particularly for that one 
  3934.           control within the Group. 
  3935.  
  3936. 213       "Bad Group Type: Group XXX, Control 1.." 
  3937.  
  3938.           An unknown Group Type was encountered.  The XXX after "Group" will 
  3939.           indicate which Group number had an unknown Type.  For example, if the 
  3940.           first Group that you defined for the window had a bad Type, then XXX 
  3941.           would be 1.  Possible problems are: you specified some incorrect Type 
  3942.           for this Group (ie, check its RXTYPE variable), or you're using an 
  3943.           old version of RXDLG.DLL that doesn't support this Group Type (ie, 
  3944.           use the RXVERS command to discover whether the DLL's version and 
  3945.           revision is equal or greater than the version/revision in the title 
  3946.           of this book). 
  3947.  
  3948. 214       "Can't create control Label: Group XXX, Control XXX." 
  3949.  
  3950.           Rexx Dialog couldn't create a label for a particular control within a 
  3951.           Group.  The XXX after "Group" will indicate which Group number the 
  3952.           control belonged to.  For example, if the control was in the first 
  3953.           group that you defined for the window, then XXX would be 1.  The XXX 
  3954.           after "Control" will indicate for which control within the Group the 
  3955.           label couldn't be created.  For example, if the control was the first 
  3956.           in the Group, then XXX would be 1.  Possible problems are: you have 
  3957.           too many windows/controls open and OS/2 has run out of certain PM 
  3958.           resources, or you specified some strange X position for the Group 
  3959.           which maybe didn't leave room for a label to the left of the control, 
  3960.           or you didn't properly specify the label for the control (ie, check 
  3961.           the RXLABEL string for the Group to make sure that you have enough 
  3962.           labels for all controls). 
  3963.  
  3964. 215       "Can't create Groupbox: Group XXX, Control XXX." 
  3965.  
  3966.           Rexx Dialog couldn't create a particular Groupbox around a Group (or 
  3967.           if the Type for a group is GROUP, then it couldn't create that 
  3968.           Groupbox).  The XXX after "Group" will indicate the Group number for 
  3969.           which the Groupbox couldn't be created.  For example, if the Groupbox 
  3970.           was to encircle the first group that you defined for the window, then 
  3971.           XXX would be 1.  Possible problems are: you have too many 
  3972.           windows/controls open and OS/2 has run out of certain PM resources, 
  3973.           or you specified some incorrect width for the control, or you 
  3974.           specified some strange X and Y position for the group, or you didn't 
  3975.           properly specify the label for the Groupbox (ie, check the RXLABEL 
  3976.           string for the Group to make sure that you have enough labels for all 
  3977.           controls as well as the Groupbox).  If the indicated "Control" number 
  3978.           is not equal to the TotalControls parameter in the Group's RXLABEL 
  3979.           string (with the exception of RESULT Group, or button Groups where 
  3980.           there are "skipped" buttons), then this indicates a potential problem 
  3981.           with not enough or too many labels in the RXLABEL string. 
  3982.  
  3983. ???       "Failed to create/set REXX variable XXX." 
  3984.  
  3985.           Rexx Dialog couldn't setup some REXX return variable (for example, 
  3986.           the RXVAL return for a Group, or RXWIND, etc).  The error number can 
  3987.           be one of several different values depending upon what the REXX 
  3988.           Interpreter returns.  This error indicates an internal problem with 
  3989.           the REXX Interpreter, and could be anything from a memory problem to 
  3990.           what-have-you.  But, when receiving any such error, your script 
  3991.           should assume that RXDLG has not returned a good set of values.  The 
  3992.           XXX tells which REXX variable in particular couldn't be setup. 
  3993.           Although this message is associated with a range of error numbers, 
  3994.           its display level is 16. 
  3995.  
  3996. ???       "Can't fetch REXX variable XXX." 
  3997.  
  3998.           Rexx Dialog couldn't find some REXX variable that your script was 
  3999.           supposed to setup prior to a call to RXDLG.  (for example, the RXTYPE 
  4000.           for a Group, etc).  The error number can be one of several different 
  4001.           values depending upon what the REXX Interpreter returns.  The XXX 
  4002.           tells which REXX variable in particular couldn't be fetched.  Check 
  4003.           to make sure that you have either defined that REXX variable in your 
  4004.           script (ie, sometimes, with copying and pasting source code, it's 
  4005.           easy to forget to change the extension on a stem variable to reflect 
  4006.           the Group number), or that the NumGroups arg to RXDLG reflects how 
  4007.           many Groups you have defined.  This error message cannot be 
  4008.           surpressed, and the REXX Interpreter forces a message box display. 
  4009.  
  4010. 10008     "Not enough memory." 
  4011.  
  4012.           There is not enough free RAM in your system to setup some structures 
  4013.           needed to create window/controls.  You'll have to close down other 
  4014.           running programs. 
  4015.  
  4016. When you use the second template of RXDLG, it could return any of the following 
  4017. errors: 
  4018.  
  4019. 10017     "Can't find REXX dialog." 
  4020.  
  4021.           RXDLG couldn't find the specified window to perform an operation 
  4022.           upon.  Possible problems are: you've passed a WindowTitle arg to 
  4023.           RXDLG that doesn't match any of the open windows (or perhaps omitted 
  4024.           the WindowTitle arg, but included the Operation arg -- you must 
  4025.           supply both, or neither).  If the passed WindowTitle arg is '""' (or 
  4026.           not supplied), then you must have at least a Main Window open.  The 
  4027.           exception to this is an operation of 255, which will never return 
  4028.           this (or any other Rexx Dialog) error. 
  4029.  
  4030. 10007     "Too much device input to return: XXX." 
  4031.  
  4032.           The string to be returned is larger than 256 characters.  You might 
  4033.           try trimming the start or end patterns, or parsing each value into 
  4034.           its own variable. 
  4035.  
  4036. Also, the "Failed to create/set REXX variable XXX" error message\number may be 
  4037. encountered for Operations of 0, 1, 2, 3, and 4 (although it's a trivial 
  4038. problem with Operation 4 -- this just means that the Window's Dimensions string 
  4039. hasn't been updated). 
  4040.  
  4041. RXDEV 
  4042.  
  4043. 10005     "Can't find/setup device: XXX." 
  4044.  
  4045.           RXDEV couldn't find the specified device to perform an operation 
  4046.           upon.  Possible problems are: you've passed a DevTitle arg to RXDEV 
  4047.           that doesn't match any of the open devices (or perhaps omitted the 
  4048.           DevTitle arg, but included the Operation arg -- you must supply both, 
  4049.           or neither).  If the passed DevTitle arg is '""' (or not supplied), 
  4050.           then you must have at least 1 device open.  Also, you must have a 
  4051.           Main Window open in order to open a device, and the device must be 
  4052.           opened for reading using FILEREXX's FileOpen.  XXX will be the device 
  4053.           name passed to RXDEV. 
  4054.  
  4055. 10006     "Can't start REXX device thread." 
  4056.  
  4057.           Can't start a thread to read data from the device.  Try closing down 
  4058.           other OS/2 apps. 
  4059.  
  4060. 10020     "XXX Operation not supported." 
  4061.  
  4062.           The operation that you specified is not recognized by this version of 
  4063.           Rexx Dialog.  XXX will be the operation that Rexx Dialog doesn't 
  4064.           understand.  Make sure that you spelled it correctly, and have a 
  4065.           current version of RXDLG.DLL.  Also, you will see this error if you 
  4066.           forget to do an OPEN Operation on the specified DevName before 
  4067.           attempting to do some other operation. 
  4068.  
  4069. 10009     "Bad read NNN, Device: XXX." 
  4070.  
  4071.           There was an error reading the next byte from a device.  XXX will be 
  4072.           the device name (as you specified during the OPEN Operation).  This 
  4073.           error may happen when accessing a device that returns immediately 
  4074.           when it has no bytes to return to Rexx Dialog (ie, it doesn't "block" 
  4075.           reads).  In this case, you'll have to find some way of querying the 
  4076.           device to determine if it has any input bytes queued (ie, usually via 
  4077.           some IOCTL vector that you'll access using FILEREXX), and read only 
  4078.           that many bytes (using FILEREXX's reading functions).  This error may 
  4079.           also happen if CTRL-C or CTRL-BREAK is pressed, or some other 
  4080.           operation causes the device to abort a read (if the device supports 
  4081.           that).  NNN is the error number returned from OS/2, and can be: 
  4082.  
  4083.           5     Access denied 
  4084.           6     Invalid handle 
  4085.           26     Not a DOS disk 
  4086.           33     Lock violation 
  4087.           109    Broken pipe connection 
  4088.           234    More data 
  4089.           -1     Can't get a semaphore for the device thread.  Try closing down 
  4090.           other OS/2 apps. 
  4091.  
  4092. RXFILE 
  4093.  
  4094. 311       "Can't create dialog." 
  4095.  
  4096.           Rexx Dialog couldn't open the File Dialog.  Possible problems are: 
  4097.           you have too many windows open and OS/2 has run out of certain PM 
  4098.           resources, or you may have specified a bizarre filename (ie, try 
  4099.           setting to a null string). 
  4100.  
  4101. The "Failed to create/set REXX variable XXX" error message\number may be 
  4102. returned if Rexx Dialog couldn't return the filename. 
  4103.  
  4104. The "Can't fetch REXX variable XXX" error message\number may be returned if 
  4105. Rexx Dialog couldn't fetch the initial filename.  Make sure that you initialize 
  4106. the FilenameVar arg to RXFILE, even if you set it to a null string. 
  4107.  
  4108. RXHELP 
  4109.  
  4110. 10022     "Can't attach help file." 
  4111.  
  4112.           Rexx Dialog couldn't attach the help file to the window.  Possible 
  4113.           problems are: OS/2 has run out of certain PM resources, or you didn't 
  4114.           properly specify the help filename (ie, make sure that you spelled it 
  4115.           correctly, and supplied a complete path if that is needed). 
  4116.  
  4117. 10021     "Can't find help panel XXX." 
  4118.  
  4119.           Rexx Dialog couldn't find the specified panel number or name within 
  4120.           the help file for the window.  Possible problems are: OS/2 has run 
  4121.           out of certain PM resources, or you didn't properly specify the panel 
  4122.           name or number (ie, make sure that you spelled it correctly), or no 
  4123.           such panel name or number exists within the help file that is 
  4124.           attached to the Window specified to RXHELP (ie, make sure that you 
  4125.           have the correct window and help file). 
  4126.  
  4127. The "Can't find REXX dialog." error message\number may be returned if the 
  4128. WindowTitle you specified doesn't match any open window. 
  4129.  
  4130. RXSAY 
  4131.  
  4132. RXSAY never causes a REXX FAILURE or ERROR, but always returns a number 
  4133. (regardless of RXERR's NUM flag) as described in RXSAY. 
  4134.  
  4135. RXSET 
  4136.  
  4137. 10018     "Can't find group XXX" 
  4138.  
  4139.           The window that you specified doesn't contain the GroupNum that you 
  4140.           specified.  Make sure that you haven't asked for a Group number 
  4141.           larger than the number of Groups in the window, nor a Group number of 
  4142.           0. 
  4143.  
  4144. 10019     "Can't find control XXX" 
  4145.  
  4146.           The Group that you specified doesn't contain the control that you 
  4147.           specified.  Make sure that you haven't asked for a control number 
  4148.           larger than the number of controls in the Group, nor a control number 
  4149.           of 0. 
  4150.  
  4151. 10010     "Can't start timer." 
  4152.  
  4153.           If you do a TIME operation to setup a timer for a window, and the 
  4154.           timer can't be setup, this error may be returned.  OS/2 has a limited 
  4155.           number of timers available, so shut down other apps that may be using 
  4156.           timers. 
  4157.  
  4158. The "Operation not supported." error message\number may be returned if the 
  4159. operation that you specified is not recognized by this version of Rexx Dialog. 
  4160.  
  4161. The "Can't find REXX dialog." error message\number may be returned if the 
  4162. WindowTitle you specified doesn't match any open window. 
  4163.  
  4164. RXVERS 
  4165.  
  4166. RXVERS never causes a REXX FAILURE or ERROR, but always returns a string 
  4167. (regardless of RXERR's NUM flag) as described in RXVERS. 
  4168.  
  4169. Other Rexx Dialog commands 
  4170.  
  4171. All other Rexx dialog commands do not return anything except successful returns 
  4172. (ie, 0 error numbers, or null strings). 
  4173.  
  4174. There are a few error messages that you may see that aren't related to specific 
  4175. Rexx Dialog commands.  Unless otherwise mentioned, these will happen before 
  4176. your script starts executing, and usually reflect a problem in RX.EXE's setup. 
  4177. These error messages are always displayed unless otherwise mentioned. 
  4178.  
  4179. 20001     "Can't find REXX script to run." 
  4180.  
  4181.           The script name that you specified for RX.EXE to run can't be found. 
  4182.           Check that you spelled the script name correctly and/or supplied the 
  4183.           correct path.  If you didn't supply a path, then the script must be 
  4184.           in the same directory as RX.EXE, or must be in the directory 
  4185.           specified in the Working Directory or specified in the Parameters 
  4186.           field of the Program Object for the script (if launched from a 
  4187.           Desktop object). 
  4188.  
  4189. 20003     "Window registration failed." 
  4190.  
  4191.           RXDLG.DLL couldn't properly register its special window class. 
  4192.           Perhaps there is another running app that happens to have a 
  4193.           similiarly named public window class.  (Unlikely, but try closing 
  4194.           down other running apps). 
  4195.  
  4196. 20004     "Can't install REXX." 
  4197.  
  4198.           RXDLG.DLL couldn't properly register its REXX handler.  Perhaps there 
  4199.           is another running app that happens to have a similiarly named 
  4200.           handler.  (Unlikely, but try closing down other running apps). 
  4201.  
  4202. 10002     "REXX dialog unknown command: XXX" 
  4203.  
  4204.           This error may occur while your script is running.  It indicates that 
  4205.           your script contains a command that isn't some built-in REXX command, 
  4206.           but also isn't a Rexx Dialog command.  It may be that you're trying 
  4207.           to run some executable, for example, OS/2's DIR command.  So, you 
  4208.           have this line in your script: 
  4209.  
  4210.           'dir' 
  4211.  
  4212.           The problem is that REXX is passing this command to Rexx Dialog, and 
  4213.           Rexx Dialog doesn't have a DIR command.  Normally, REXX scripts are 
  4214.           run from the OS/2 command line, and so REXX would pass this command 
  4215.           to the OS/2 command line, which does have a DIR command.  But, when 
  4216.           running a script with RX.EXE, REXX passes everything that it doesn't 
  4217.           recognize as a built-in command to Rexx Dialog.  In this case, you 
  4218.           need to specifically direct that command to the OS/2 shell.  You do 
  4219.           so by putting ADDRESS CMD before the line that you want to send to 
  4220.           the OS/2 shell (ie, CMD is the REXX environment name for the OS/2 
  4221.           shell, and ADDRESS tells REXX to send the following line to that 
  4222.           environment instead of letting Rexx Dialog try to implement that 
  4223.           line).  So the line would be: 
  4224.  
  4225.           ADDRESS CMD 'dir' 
  4226.  
  4227.           This error message has a display level of 2. 
  4228.  
  4229.           Rexx Dialog's environment name is RXDLG. 
  4230.