home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / vrexx_2.zip / VREXX.INF (.txt) < prev    next >
OS/2 Help File  |  1993-10-28  |  43KB  |  1,888 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. VREXX ΓòÉΓòÉΓòÉ
  3.  
  4.         VREXX - Version 1.1
  5. (C) Copyright IBM Corp.  1992, 1993
  6.  
  7.  
  8. Written by:
  9.  
  10.  
  11. Richard B. Lam
  12.  
  13. IBM T.J. Watson Research Center
  14. Route 134  POB 218
  15. Yorktown Heights, NY  10598
  16.  
  17. VREXX is Visual REXX - a new way for OS/2 users to create their own 
  18. Presentation Manager (PM) programs using REXX!  VREXX provides users with a set 
  19. of functions that can be called from REXX procedures.  These functions open and 
  20. close standard PM windows, providing programmable control over the appearance 
  21. and positioning of the windows.  Dialog box functions allow file selection, 
  22. display of messages, entering numbers or text strings, and making single or 
  23. multiple selections through radiobutton, checkbox or listbox controls.  Table, 
  24. Color and font selection dialogs are also available.  And, graphics functions 
  25. for setting pixels, drawing markers, lines, polygons, splines, arcs, circles 
  26. and text (in multiple fonts) are included. 
  27.  
  28. With VREXX, OS/2 REXX procedures can use all of the standard features of REXX 
  29. under OS/2, except that the old text window input and output procedures are 
  30. replaced with PM windows and dialogs.  No prior experience with PM programming 
  31. is necessary.  The OS/2 Programming toolkit is NOT required.  All you need to 
  32. do is write a REXX program that makes function calls to the VREXX functions. 
  33.  
  34. VREXX features: 
  35.  
  36. o Creation and manipulation of standard PM windows 
  37.  
  38. o Powerful dialog functions, including: 
  39.  
  40.    - Positioning control over the dialogs 
  41.  
  42.    - Dialog button selections 
  43.  
  44.    - Standard filename selection dialog 
  45.  
  46.    - Data Table, Color selection and Font selection dialogs 
  47.  
  48.    - 10 line message box 
  49.  
  50.    - Input boxes for entering text or numbers 
  51.  
  52.    - Radiobutton, checkbox and listbox controls for selecting item(s) from a 
  53.      list 
  54.  
  55. o Graphics support, with functions for: 
  56.  
  57.    - Setting window foreground and background colors 
  58.  
  59.    - Setting individual pixels 
  60.  
  61.    - Drawing markers, with 10 different marker types 
  62.  
  63.    - Polylines, with 7 different line types 
  64.  
  65.    - Filled polygons, with 6 different fill types 
  66.  
  67.    - Splines 
  68.  
  69.    - Arcs and circles 
  70.  
  71. o On-line help facility 
  72.  
  73.  
  74. ΓòÉΓòÉΓòÉ 2. SYSTEM REQUIREMENTS ΓòÉΓòÉΓòÉ
  75.  
  76. VREXX runs under OS/2 version 2.0 or 2.1 on IBM PS/2 or PC-compatible systems. 
  77.  
  78. Copy VREXX.INF to a BOOKSHELF help file directory specified in your CONFIG.SYS 
  79. file.  Copy VREXX.EXE and the sample command files to a utility directory 
  80. included in your PATH statement.  Copy VREXX.DLL and DEVBASE.DLL to a directory 
  81. specified in your LIBPATH in CONFIG.SYS. 
  82.  
  83.  
  84. ΓòÉΓòÉΓòÉ 3. USING VREXX ΓòÉΓòÉΓòÉ
  85.  
  86. REXX procedures that call VREXX functions are started normally, by either 
  87. typing the CMD filename on an OS/2 command line, or by using the OS/2 START 
  88. command. 
  89.  
  90. To run a REXX procedure named EXAMPLE.CMD which calls VREXX functions, simply 
  91. type: 
  92.  
  93. example
  94. or 
  95.  
  96. start example.cmd
  97. from an OS/2 command line prompt.  The EXAMPLE.CMD procedure will then execute 
  98. normally, in addition to providing access to the VREXX functions. To access 
  99. on-line help for VREXX, use the OS/2 VIEW command by typing: 
  100.  
  101. view vrexx.inf
  102. or 
  103.  
  104. vrexx
  105. from an OS/2 command line prompt. 
  106.  
  107. Before calling VREXX functions in your REXX procedures, you must load and 
  108. initialize the external functions by calling VInit.  Also, the VExit function 
  109. must be called at the end of your REXX procedure to clean up the system 
  110. resources allocated in the initialization.  The recommended approach for this 
  111. is to structure your REXX procedure as follows: 
  112.  
  113. /* EXAMPLE.CMD - structure for initializing and */
  114. /*               terminating VREXX procedures   */
  115.  
  116. /* initialize VREXX */
  117.  
  118. '@echo off'
  119. call RxFuncAdd 'VInit', 'VREXX', 'VINIT'
  120. initcode = VInit()
  121. if initcode = 'ERROR' then signal CLEANUP
  122.  
  123. signal on failure name CLEANUP
  124. signal on halt name CLEANUP
  125. signal on syntax name CLEANUP
  126.  
  127. /* REXX statements and VREXX function calls go here */
  128. /* ...                                              */
  129. /* end of REXX statements                           */
  130.  
  131. /* terminate VREXX - add any other clean-up */
  132. /* for your REXX procedure here also        */
  133.  
  134. CLEANUP:
  135.    call VExit
  136.  
  137. exit
  138.  
  139. The SIGNAL statements ensure that VExit is called if your REXX procedure 
  140. contains an error.  You may optionally add a SIGNAL ON ERROR NAME CLEANUP 
  141. statement also, depending on whether you provide another error handler for 
  142. non-fatal ERROR return codes. 
  143.  
  144. After initialization, VREXX lets you create multiple windows, with each window 
  145. returning a specific id that you use to refer to the window for later 
  146. operations.  Note for PM programmers:  the REXX command files are procedural, 
  147. not event-driven.  Therefore, your REXX procedure executes from top to bottom 
  148. as a normal REXX program.  But, at any time, especially when dialogs are 
  149. displayed, the windows created with VREXX calls can be manipulated just like 
  150. other PM windows - they may be iconized, resized, moved, etc.  Also, the 
  151. contents of the window are maintained internally - you don't need to redraw the 
  152. window every time it is moved or sized.  The windows are destroyed by calling a 
  153. window close function, passing it the id of the window to close. 
  154.  
  155. Although multiple windows may be created, only 1 dialog box at a time may be 
  156. processed by the running REXX procedure. 
  157.  
  158. Graphics coordinates for the windows are always set from 0 to 1000 in both the 
  159. x and y directions, with the origin at the lower left corner of the window. The 
  160. current color and line type apply to all graphics operations. 
  161.  
  162. The window and dialog positioning functions always operate with numbers 
  163. representing a percentage of the screen.  Thus, to center a window on the 
  164. screen with the window filling half of the screen area, the left and bottom 
  165. corners of the window are set to 25, while the right and top corners of the 
  166. window are set to 75.  See the COMMAND REFERENCE section for more examples on 
  167. graphics and window positioning. 
  168.  
  169. There are three sample REXX programs that come with the package, called 
  170. TESTWIN.CMD, TESTDLGS.CMD, and TESTDRAW.CMD, which demonstrate the syntax of 
  171. the VREXX functions.  See the EXAMPLES section for more details. 
  172.  
  173.  
  174. ΓòÉΓòÉΓòÉ 4. COMMAND REFERENCE ΓòÉΓòÉΓòÉ
  175.  
  176. This section provides a summary of the functions which can be called from a 
  177. REXX procedure running under VREXX.  See the EXAMPLES section for some REXX 
  178. procedures which implement the VREXX commands. 
  179.  
  180. The following functions are provided: 
  181.  
  182. o Startup, Termination and Version Functions 
  183.  
  184.    VExit               Cleans up the current VREXX system resources 
  185.  
  186.    VGetVersion         Returns the current VREXX program version number 
  187.  
  188.    VInit               Initializes the VREXX functions and system resources 
  189.  
  190. o Window Functions 
  191.  
  192.    VBackColor          Sets the background color of a window 
  193.  
  194.    VClearWindow        Clears the contents of a window 
  195.  
  196.    VCloseWindow        Closes a window 
  197.  
  198.    VForeColor          Sets the foreground color of a window 
  199.  
  200.    VOpenWindow         Opens a new window 
  201.  
  202.    VResize             Resizes and repositions a window on the screen 
  203.  
  204.    VSetTitle           Sets the titlebar of a window to a specified string 
  205.  
  206. o Dialog Functions 
  207.  
  208.    VCheckBox           Creates a checkbox dialog for selecting multiple items 
  209.                        from a list 
  210.  
  211.    VColorBox           Allows selection of foreground and background colors 
  212.                        from a dialog 
  213.  
  214.    VDialogPos          Controls the positioning of dialog windows on the screen 
  215.  
  216.    VFileBox            Allows selection of a full pathname of a file from a 
  217.                        dialog 
  218.  
  219.    VFontBox            Allows selection of the typeface and point size to use 
  220.                        for text output 
  221.  
  222.    VInputBox           Creates an entryfield dialog with prompt strings for 
  223.                        entering numbers or strings 
  224.  
  225.    VListBox            Creates a listbox dialog for selecting 1 item from a 
  226.                        large list 
  227.  
  228.    VMsgBox             Creates a message box for displaying from 1 to 10 
  229.                        message strings 
  230.  
  231.    VMultBox            Creates a multiple entryfield dialog, with 1 to 10 
  232.                        entryfields and a prompt string for each field, with 
  233.                        optional echoing of input characters (e.g. for entering 
  234.                        passwords). 
  235.  
  236.    VRadioBox           Creates a radiobox dialog for selecting 1 item from a 
  237.                        list 
  238.  
  239.    VTableBox           Constructs a table dialog as a listbox, with 
  240.                        programmable column widths 
  241.  
  242. o Graphics Functions 
  243.  
  244.    VArc                Draws an arc or complete circle, optionally filled with 
  245.                        the current fill style 
  246.  
  247.    VDraw               Draws pixels, markers, lines, polygons or splines using 
  248.                        the current marker type, line attribute and fill style 
  249.  
  250.    VDrawParms          Sets the current marker type, line attribute and fill 
  251.                        style to use for subsequent graphics operations 
  252.  
  253.    VSay                Draws a text string in the current font on a window 
  254.  
  255.    VSetFont            Sets the current font to use for drawing text 
  256.  
  257. For the dialog functions, several of them take a [stem] variable name as an 
  258. argument.  For example, the VMsgBox function is called as follows: 
  259.  
  260. msg.0 = 2
  261. msg.1 = 'This is the first line'
  262. msg.2 = 'This is the second line'
  263.  
  264. buttons = 1
  265.  
  266. call VMsgBox 'Dialog title', msg, buttons
  267. where msg is the variable name of a stem variable.  This variable uses the same 
  268. format for all dialog functions, where the stem.0 variable holds the number of 
  269. items, and stem.1 through stem.n hold the actual items.  In the example above, 
  270. there are 2 message lines to be displayed, so msg.0 is set to 2, and msg.1 and 
  271. msg.2 hold the actual lines that will be displayed by the function. 
  272.  
  273. The dialogs also take a standard [buttons] argument, which is defined as a 
  274. number between 1 and 6, denoting that the following buttons be created on the 
  275. dialog: 
  276.  
  277.  [buttons] value     Buttons created     Return value
  278.  _______________     _______________     ____________
  279.  
  280.         1            OK                  'OK'
  281.         2            Cancel              'CANCEL'
  282.         3            OK and Cancel       'OK' or 'CANCEL'
  283.         4            Yes                 'YES'
  284.         5            No                  'NO'
  285.         6            Yes and No          'YES' or 'NO'
  286.  
  287. In the example above, the [buttons] argument to the VMsgBox function was 1, so 
  288. the message box dialog would be created with a single pushbutton labelled "OK". 
  289. The VMsgBox function could also be called with the syntax: 
  290.  
  291. return_button = VMsgBox('Dialog title', msg, buttons)
  292. where the return_button variable would be set to the return value corresponding 
  293. to the pushbutton selected by the user (return_value = 'OK' in this example). 
  294.  
  295. Those dialogs which need to return a selected string will place the selected 
  296. string in a [stem].vstring variable.  For example, to access the string typed 
  297. into an entryfield with the VInputBox function, use the following code: 
  298.  
  299. str.0 = 1
  300. str.1 = 'Type a string'
  301. call VInputBox 'Example', str, 1
  302.  
  303. answer = str.vstring
  304.  
  305. /* answer now contains the user input */
  306.  
  307.  
  308. ΓòÉΓòÉΓòÉ 4.1. VArc ΓòÉΓòÉΓòÉ
  309.  
  310. Purpose             Draws an arc or complete circle, optionally filled with the 
  311.                     current fill style 
  312.  
  313. Definition 
  314.  
  315.                                         VArc [id] [x] [y] [radius] [angle1] [angle2]
  316.  
  317. Parameters          [id] is the window id.  [x] and [y] are the center point of 
  318.                     the arc, and [radius] is the radius of the arc, in units of 
  319.                     0 to 1000.  [angle1] and [angle2] are the angles to draw 
  320.                     the arc between, starting with angle 0 at 3 o'clock, 
  321.                     increasing in a counter-clockwise direction. 
  322.  
  323. Comments            [angle1] should be less than [angle2] and both angles 
  324.                     should be between 0 and 360 degrees.  The angles may be 
  325.                     specified in floating point format. 
  326.  
  327. Function Result     none 
  328.  
  329. Example: 
  330.  
  331. /* draw an arc in the center of a window, going
  332.    from 12 o'clock to 6 o'clock, with a radius of
  333.    100 */
  334.  
  335. a1 = 90
  336. a1 = 270.0
  337. call VArc id, 500, 500, 100, a1, a2
  338.  
  339.  
  340. ΓòÉΓòÉΓòÉ 4.2. VBackColor ΓòÉΓòÉΓòÉ
  341.  
  342. Purpose             Sets the background color of a window 
  343.  
  344. Definition 
  345.  
  346.                                         VBackColor [id] [color]
  347.  
  348. Parameters          [id] is the window id and [color] is the new background 
  349.                     color to use for the window. 
  350.  
  351. Comments            [color] must be specified as a string, in either upper, 
  352.                     lower or mixed case, and must equal one of 'BLACK', 
  353.                     'WHITE', 'RED', 'GREEN', 'BLUE', 'CYAN', 'YELLOW' or 
  354.                     'PINK'. 
  355.  
  356. Function Result     none 
  357.  
  358. Example: 
  359.  
  360. /* change a window background color to 'RED' */
  361.  
  362. call VBackColor id, 'RED'
  363.  
  364.  
  365. ΓòÉΓòÉΓòÉ 4.3. VCheckBox ΓòÉΓòÉΓòÉ
  366.  
  367. Purpose             Creates a checkbox dialog for selecting multiple items from 
  368.                     a list 
  369.  
  370. Definition 
  371.  
  372.                                         VCheckBox [title] [stem] [output] [buttons]
  373.  
  374. Parameters          [title] is the string to use for the dialog titlebar, and 
  375.                     [stem] is the variable name of the stem variable containing 
  376.                     the items that will be used in constructing the dialog. 
  377.                     [output] is the variable name of the stem variable where 
  378.                     the selected items will be placed, and [buttons] denotes 
  379.                     the desired button types to be placed on the dialog. 
  380.  
  381. Comments            A maximum of 10 items may be passed to this function. The 
  382.                     [output] stem variable need not exist when this function is 
  383.                     called. The number of items selected is given by the 
  384.                     [output].0 variable name (e.g. if [output] = 
  385.                     user_selection, then the REXX variable user_selection.0 
  386.                     holds the number of items checked in the dialog, and 
  387.                     user_selection.1 through user_selection.n hold the actual 
  388.                     selections).  The [output] variable can be initialized 
  389.                     before calling this function with the default strings to be 
  390.                     checked when the dialog is created. 
  391.  
  392. Function Result     'OK', 'CANCEL', 'YES' or 'NO', depending on the [buttons] 
  393.                     argument 
  394.  
  395. Example: 
  396.  
  397. /* let user select movies */
  398.  
  399. movie.0 = 5
  400. movie.1 = 'Silence of the Lambs'
  401. movie.2 = 'Dr. Strangelove'
  402. movie.3 = 'Terminator 2'
  403. movie.4 = 'Goldfinger'
  404. movie.5 = 'Basic Instinct'
  405.  
  406. button = VCheckBox('Select movies', movie, selection, 3)
  407. if button = 'OK' then do
  408.    call VMsgBox('Your selections', selection, 1)
  409. end
  410.  
  411.  
  412. ΓòÉΓòÉΓòÉ 4.4. VClearWindow ΓòÉΓòÉΓòÉ
  413.  
  414. Purpose             Clears the contents of a window 
  415.  
  416. Definition 
  417.  
  418.                                         VClearWindow [id]
  419.  
  420. Parameters          [id] is the id of the window to clear. 
  421.  
  422. Comments            This function erases all graphics from a window, enabling 
  423.                     you to start over with a new set of graphics commands. 
  424.  
  425. Function Result     none 
  426.  
  427. Example: 
  428.  
  429. /* clear a window of all graphics */
  430.  
  431. call VClearWindow id
  432.  
  433.  
  434. ΓòÉΓòÉΓòÉ 4.5. VCloseWindow ΓòÉΓòÉΓòÉ
  435.  
  436. Purpose             Closes a window 
  437.  
  438. Definition 
  439.  
  440.                                         VCloseWindow [id]
  441.  
  442. Parameters          [id] is the id of the window you wish to close. 
  443.  
  444. Comments            The window must have been opened with a call to 
  445.                     VOpenWindow. 
  446.  
  447. Function Result     none 
  448.  
  449. Example: 
  450.  
  451. /* close a window */
  452.  
  453. call VCloseWindow id
  454.  
  455.  
  456. ΓòÉΓòÉΓòÉ 4.6. VColorBox ΓòÉΓòÉΓòÉ
  457.  
  458. Purpose             Allows selection of foreground and background colors from a 
  459.                     dialog 
  460.  
  461. Definition 
  462.  
  463.                                         VColorBox [stem]
  464.  
  465. Parameters          [stem] is the name of a stem variable which holds the .fore 
  466.                     and .back color values for the foreground and background 
  467.                     colors. 
  468.  
  469. Comments            The colors should be specified as one of 'BLACK', 'WHITE', 
  470.                     'RED', 'GREEN', 'BLUE', 'CYAN', 'YELLOW' or 'PINK'. 
  471.  
  472. Function Result     'OK' or 'CANCEL' 
  473.  
  474. Example: 
  475.  
  476. /* get new foreground and background colors for a
  477.    window and set them */
  478.  
  479. color.fore = 'BLACK'
  480. color.back = 'WHITE'
  481. button = VColorBox color
  482.  
  483. if button = 'OK' then do
  484.    call VForeColor color.fore
  485.    call VBackColor color.back
  486. end
  487.  
  488.  
  489. ΓòÉΓòÉΓòÉ 4.7. VDialogPos ΓòÉΓòÉΓòÉ
  490.  
  491. Purpose             Controls the positioning of dialog windows on the screen 
  492.  
  493. Definition 
  494.  
  495.                                         VDialogPos [x] [y]
  496.  
  497. Parameters          [x] and [y] are the center position to use for positioning 
  498.                     subsequent dialog boxes on the screen. 
  499.  
  500. Comments            [x] and [y] should be integers between 0 and 100, specified 
  501.                     in percentage of the screen. 
  502.  
  503. Function Result     none 
  504.  
  505. Example: 
  506.  
  507. /* position a message box in the center of the screen */
  508.  
  509. call VDialogPos 50, 50
  510.  
  511. msg.0 = 1
  512. msg.1 = 'This box is in the center of the screen'
  513. call VMsgBox 'TEST', msg, 1
  514.  
  515.  
  516. ΓòÉΓòÉΓòÉ 4.8. VDraw ΓòÉΓòÉΓòÉ
  517.  
  518. Purpose             Draws pixels, markers, lines, polygons or splines using the 
  519.                     current marker type, line attribute and fill style 
  520.  
  521. Definition 
  522.  
  523.                                         VDraw [id] [drawtype] [xstem] [ystem] [num]
  524.  
  525. Parameters          [id] is the id of the window to use for drawing the 
  526.                     graphics.  [drawtype] is a string, which must be one of 
  527.                     'PIXEL', 'MARKER', 'LINE', 'POLYGON' or 'SPLINE', depending 
  528.                     on the graphic to be drawn.  [xstem] and [ystem] are 
  529.                     variable names for stem variables, which contain the 
  530.                     coordinates to be used for drawing the graphics (ranging 
  531.                     from .1 to .n).  [num] is the number of data points 
  532.                     specified in the [xstem] and [ystem] variables. 
  533.  
  534. Comments            The coordinates should range between 0 and 1000.  The 
  535.                     drawtypes and their effects are: 
  536.  
  537.    o 'PIXEL' sets a pixel in the foreground color for each point 
  538.  
  539.    o 'MARKER' draws a marker at each point using the current marker type 
  540.  
  541.    o 'LINE' draws a polyline connecting all of the points using the current 
  542.      line attribute 
  543.  
  544.    o 'POLYGON' draws a closed figure using the coordinates as vertices, filling 
  545.      the figure with the current fill type 
  546.  
  547.    o 'SPLINE' requires 4 data points, and draws a B╨Æzier cubic spline that 
  548.      passes through points 1 and 4, using points 2 and 3 as control points. 
  549.  
  550. Function Result     none 
  551.  
  552. Example:  See the TESTDRAW.CMD procedure for some sample function calls using 
  553. the VDraw function. 
  554.  
  555.  
  556. ΓòÉΓòÉΓòÉ 4.9. VDrawParms ΓòÉΓòÉΓòÉ
  557.  
  558. Purpose             Sets the current marker type, line attribute and fill style 
  559.                     to use for subsequent graphics operations 
  560.  
  561. Definition 
  562.  
  563.                                         VDrawParms [id] [markertype] [linetype] [filltype]
  564.  
  565. Parameters          [id] is the window id.  [markertype] is the marker type to 
  566.                     draw, [linetype] is the line attribute to use, and 
  567.                     [filltype] is the fill style to use in subsequent VDraw 
  568.                     operations. 
  569.  
  570. Comments            0 is the default for all 3 attributes, equal to a cross 
  571.                     marker, a solid line, or an empty fill style.  The other 
  572.                     values and their corresponding meanings are shown in the 
  573.                     example. 
  574.  
  575. Function Result     none 
  576.  
  577. Example: 
  578.  
  579. /* VDrawParms marker, line and fill values */
  580.  
  581. default = 0
  582.  
  583. /* marker types */
  584.  
  585. cross        = 1     /* X */
  586. plus         = 2     /* + */
  587. diamond      = 3     /* diamond */
  588. square       = 4     /* box */
  589. star6        = 5     /* 6 point star */
  590. star8        = 6     /* 8 point star */
  591. soliddiamond = 7     /* solid diamond */
  592. solidsquare  = 8     /* Γûá */
  593. soliddot     = 9     /* . */
  594. circle       = 10    /* O */
  595.  
  596. /* line types */
  597.  
  598. solid      = 0       /* ____  */
  599. dot        = 1       /* ....  */
  600. dash       = 2       /* ----  */
  601. dashdot    = 3       /* -.-.  */
  602. dotdot     = 4       /* .. .. */
  603. longdash   = 5       /* __ __ */
  604. dashdotdot = 6       /* -..-  */
  605.  
  606. /* set up fill types */
  607.  
  608. nofill    = 0        /*       */
  609. solidfill = 1        /* Γûê */
  610. horz      = 2        /* ===== */
  611. vert      = 3        /* ||||| */
  612. leftdiag  = 4        /* \\\\\ */
  613. rightdiag = 5        /* ///// */
  614.  
  615. /* sample function call */
  616.  
  617. call VDrawParms diamond, dotdot, leftdiag
  618.  
  619.  
  620. ΓòÉΓòÉΓòÉ 4.10. VExit ΓòÉΓòÉΓòÉ
  621.  
  622. Purpose             Cleans up the current VREXX system resources 
  623.  
  624. Definition 
  625.  
  626.                                         VExit
  627.  
  628. Parameters          none 
  629.  
  630. Comments            This function should be called after all VREXX function 
  631.                     calls in the current REXX procedure are made. 
  632.  
  633. Function Result     none 
  634.  
  635. Example: 
  636.  
  637. /* terminate VREXX */
  638.  
  639. call VExit
  640.  
  641.  
  642. ΓòÉΓòÉΓòÉ 4.11. VFileBox ΓòÉΓòÉΓòÉ
  643.  
  644. Purpose             Allows selection of a full pathname of a file from a dialog 
  645.  
  646. Definition 
  647.  
  648.                                         VFileBox [title] [template] [stem]
  649.  
  650. Parameters          [title] is the string to use for the dialog titlebar. 
  651.                     [template] is the pathname template that specifies the file 
  652.                     types to display.  [stem] is the name of a stem variable 
  653.                     that contains the full pathname of the selected file. 
  654.  
  655. Comments            If the name of the [stem] variable is fname, the full 
  656.                     pathname is returned in the REXX variable fname.vstring. 
  657.  
  658. Function Result     'OK' or 'CANCEL' 
  659.  
  660. Example: 
  661.  
  662. /* get a filename */
  663.  
  664. button = VFileBox('Pick a file', '*.dat', name)
  665. if button = 'OK' then do
  666.    filename = name.vstring
  667.  
  668.    /* get size of file */
  669.  
  670.    bytes = stream(filename, C, 'query size')
  671. end
  672.  
  673.  
  674. ΓòÉΓòÉΓòÉ 4.12. VFontBox ΓòÉΓòÉΓòÉ
  675.  
  676. Purpose             Allows selection of the typeface and point size to use for 
  677.                     text output 
  678.  
  679. Definition 
  680.  
  681.                                         VFontBox [stem]
  682.  
  683. Parameters          [stem] is the name of a stem variable, with [stem].type and 
  684.                     [stem].size containing the selected font type and font 
  685.                     point size returned from the dialog box. 
  686.  
  687. Comments            The point size must be a positive integer greater than 
  688.                     zero.  The font type must be one of the following strings: 
  689.  
  690.    o 'SYSTEM' - standard system font 
  691.  
  692.    o 'SYMBOL' - greek/math symbols 
  693.  
  694.    o 'COUR' - Courier, Courier Bold, Courier Italic, Courier Bold Italic 
  695.  
  696.    o 'COURB' 
  697.  
  698.    o 'COURI' 
  699.  
  700.    o 'COURBI' 
  701.  
  702.    o 'HELV' - Helvetica, Helvetica Bold, Helvetica Italic, Helvetica Bold 
  703.      Italic 
  704.  
  705.    o 'HELVB' 
  706.  
  707.    o 'HELVI' 
  708.  
  709.    o 'HELVBI' 
  710.  
  711.    o 'TIME' - Times Roman, TR Bold, TR Italic, TR Bold Italic 
  712.  
  713.    o 'TIMEB' 
  714.  
  715.    o 'TIMEI' 
  716.  
  717.    o 'TIMEBI' 
  718.  
  719. Function Result     'OK' or 'CANCEL' 
  720.  
  721. Example: 
  722.  
  723. /* let user pick a new font */
  724.  
  725. cur_font.type = 'SYSTEM'
  726. cur_font.size = 10
  727.  
  728. button = VFontBox(cur_font)
  729.  
  730. if button = 'OK' then do
  731.    call VSetFont id, cur_font.type, cur_font.size
  732. end
  733.  
  734.  
  735. ΓòÉΓòÉΓòÉ 4.13. VForeColor ΓòÉΓòÉΓòÉ
  736.  
  737. Purpose 
  738.  
  739. Definition          Sets the foreground color of a window 
  740.  
  741.                                         VForeColor [id] [color]
  742.  
  743. Parameters          [id] is the window id and [color] is the new foreground 
  744.                     color to use for the window. 
  745.  
  746. Comments            [color] must be specified as a string, in either upper, 
  747.                     lower or mixed case, and must equal one of 'BLACK', 
  748.                     'WHITE', 'RED', 'GREEN', 'BLUE', 'CYAN', 'YELLOW' or 
  749.                     'PINK'. 
  750.  
  751. Function Result     none 
  752.  
  753. Example: 
  754.  
  755. /* change a window foreground color to 'PINK' */
  756.  
  757. call VForeColor id, 'PINK'
  758.  
  759.  
  760. ΓòÉΓòÉΓòÉ 4.14. VGetVersion ΓòÉΓòÉΓòÉ
  761.  
  762. Purpose             Returns the current VREXX program version number 
  763.  
  764. Definition 
  765.  
  766.                                         VGetVersion
  767.  
  768. Parameters          none 
  769.  
  770. Comments            none 
  771.  
  772. Function Result     Returns the version number as major.minor 
  773.  
  774. Example: 
  775.  
  776. /* test version of VREXX */
  777.  
  778. ver = VGetVersion()
  779.  
  780. if ver <> '1.1' then do
  781.    msg.0 = 1
  782.    msg.1 = 'Wrong version of VREXX'
  783.  
  784.    call VMsgBox('Initialization Error', msg, 2)
  785.    exit
  786. end
  787.  
  788.  
  789. ΓòÉΓòÉΓòÉ 4.15. VInit ΓòÉΓòÉΓòÉ
  790.  
  791. Purpose             Initializes the VREXX functions and system resources 
  792.  
  793. Definition 
  794.  
  795.                                         VInit
  796.  
  797. Parameters          none 
  798.  
  799. Comments            This function must be called before calling any other VREXX 
  800.                     functions.  The VExit routine should be called at the end 
  801.                     of the REXX procedure if VInit was called. 
  802.  
  803. Function Result     Returns 'ERROR' if initialization was unsuccessful. 
  804.  
  805. Example: 
  806.  
  807. /* load and initialize VREXX (use the */
  808. /* RxUtils function RxFuncAdd)        */
  809.  
  810. call RxFuncAdd 'VInit', 'VREXX', 'VINIT'
  811. call VInit
  812.  
  813. /* or */
  814.  
  815. call RxFuncAdd 'VInit', 'VREXX', 'VINIT'
  816. initcode = VInit()
  817.  
  818.  
  819. ΓòÉΓòÉΓòÉ 4.16. VInputBox ΓòÉΓòÉΓòÉ
  820.  
  821. Purpose             Creates an entryfield dialog with prompt strings for 
  822.                     entering numbers or strings 
  823.  
  824. Definition 
  825.  
  826.                                         VInputBox [title] [stem] [width] [buttons]
  827.  
  828. Parameters          [title] is the string to use for the dialog titlebar. 
  829.                     [stem] is the name of the stem variable containing the 
  830.                     prompt strings to display in the dialog, and [width] if the 
  831.                     width (in character units) of the entryfield. [buttons] is 
  832.                     a number between 1 and 6 denoting the pushbuttons to 
  833.                     display on the dialog. 
  834.  
  835. Comments            Up to 10 strings can be specified for a prompt, and all 
  836.                     strings should be 80 characters or less in length.  The 
  837.                     [stem].vstring field may contain a default value for the 
  838.                     entryfield on input, and holds the contents of the 
  839.                     entryfield when the dialog is finished. 
  840.  
  841. Function Result     'OK', 'CANCEL', 'YES' or 'NO', depending on the value of 
  842.                     [buttons] 
  843.  
  844. Example: 
  845.  
  846. /* get the user's name */
  847.  
  848. prompt.0 = 4
  849. prompt.1 = 'Please enter your name'
  850. prompt.2 = 'Enter it first name last, last name first'
  851. prompt.3 = ''
  852. prompt.4 = 'Leave out your middle initial'
  853.  
  854. prompt.vstring = 'Doe John'
  855.  
  856. button = VInputBox('Verify info', prompt, 25, 2)
  857.  
  858. if button = 'OK' then do
  859.    name = prompt.vstring
  860. end
  861.  
  862.  
  863. ΓòÉΓòÉΓòÉ 4.17. VListBox ΓòÉΓòÉΓòÉ
  864.  
  865. Purpose             Creates a listbox dialog for selecting 1 item from a large 
  866.                     list 
  867.  
  868. Definition 
  869.  
  870.                                         VListBox [title] [stem] [width] [height] [buttons]
  871.  
  872. Parameters          [title] is the string to use for the dialog titlebar. 
  873.                     [stem] is the name of the stem variable which contains the 
  874.                     number of items and text of each item to be placed in the 
  875.                     listbox.  [width] and [height] are the dimensions of the 
  876.                     listbox in character units, and [buttons] is a number 
  877.                     between 1 and 6 denoting the type of pushbuttons to display 
  878.                     on the dialog. 
  879.  
  880. Comments            Any number of strings may be passed to this function.  On 
  881.                     input, [stem].vstring may contain the default list item to 
  882.                     be selected when the dialog is created.  If a default is 
  883.                     not specified, the first item becomes the default 
  884.                     selection. On output, [stem].vstring contains the listbox 
  885.                     item selected by the user. 
  886.  
  887. Function Result     'OK', 'CANCEL', 'YES' or 'NO', depending on the value of 
  888.                     [buttons] 
  889.  
  890. Example: 
  891.  
  892. /* select 1 item from a listbox */
  893.  
  894. clone.0 = 8
  895. clone.1 = 'Northgate'
  896. clone.2 = 'Everex'
  897. clone.3 = 'Gateway'
  898. clone.4 = 'PC Brand'
  899. clone.5 = 'AST Research'
  900. clone.6 = 'Tandy'
  901. clone.7 = 'Swan'
  902. clone.8 = 'Commodore'
  903.  
  904. call VListBox 'Pick an IBM PC clone', clone, 10, 5, 1
  905. selection = clone.vstring
  906.  
  907.  
  908. ΓòÉΓòÉΓòÉ 4.18. VMsgBox ΓòÉΓòÉΓòÉ
  909.  
  910. Purpose             Creates a message box for displaying from 1 to 10 message 
  911.                     strings 
  912.  
  913. Definition 
  914.  
  915.                                         VMsgBox [title] [stem] [buttons]
  916.  
  917. Parameters          [title] is the string to use for the dialog titlebar. 
  918.                     [stem] is the name of the stem variable which contains the 
  919.                     number of message lines text of each line to be displayed. 
  920.                     [buttons] is a number between 1 and 6 denoting the type of 
  921.                     pushbuttons to display on the dialog. 
  922.  
  923. Comments            Up to 10 lines of 80 characters each may be displayed. 
  924.  
  925. Function Result     'OK', 'CANCEL', 'YES' or 'NO', depending on the value of 
  926.                     [buttons] 
  927.  
  928. Example: 
  929.  
  930. /* display a message box */
  931.  
  932. mbox.0 = 5
  933. mbox.1 = 'VREXX Version 1.1'
  934. mbox.2 = ''
  935. mbox.3 = 'Written by R.B. Lam'
  936. mbox.4 = '(C) Copyright IBM Corp.  1992, 1993'
  937.  
  938. call VMsgBox 'VREXX Info', mbox, 1
  939.  
  940.  
  941. ΓòÉΓòÉΓòÉ 4.19. VMultBox ΓòÉΓòÉΓòÉ
  942.  
  943. Purpose             Creates a multiple entryfield dialog, with 1 to 10 
  944.                     entryfields and a prompt string for each field, with 
  945.                     optional echoing of input characters (e.g. for entering 
  946.                     passwords). 
  947.  
  948. Definition 
  949.  
  950.                                         VMultBox [title] [prompt] [width] [hide] [return] [buttons]
  951.  
  952. Parameters          [title] is the string to use for the dialog titlebar. 
  953.                     [prompt] is the name of the stem variable containing the 
  954.                     prompt strings to display (1 for each entryfield) in the 
  955.                     dialog, where [prompt].0 is the number of entryfields. 
  956.                     [width] is an array of widths (in character units) to use, 
  957.                     one for each entryfield.  [hide] is an array where the 
  958.                     elements are 0 or 1, depending on whether or not you wish 
  959.                     to echo (0) or not echo (1) the characters as they are 
  960.                     typed into the entryfield.  This is useful for entering 
  961.                     passwords (see the example below).  [return] is the array 
  962.                     of return strings, which represent what was typed into each 
  963.                     entryfield.  [return] may be initialized with default 
  964.                     strings for each entryfield before this function is called. 
  965.                     [buttons] is a number between 1 and 6 denoting the 
  966.                     pushbuttons to display on the dialog. 
  967.  
  968. Comments            Up to 10 strings can be specified for a prompt, and all 
  969.                     strings should be 80 characters or less in length. 
  970.  
  971. Function Result     'OK', 'CANCEL', 'YES' or 'NO', depending on the value of 
  972.                     [buttons] 
  973.  
  974. Example: 
  975.  
  976. /* get system, userid, and password */
  977.  
  978. /* here are the prompts */
  979.  
  980. p.0 = 3
  981. p.1 = 'System name'
  982. p.2 = 'User ID'
  983. p.3 = 'Password'
  984.  
  985. /* here are the widths for each entryfield */
  986.  
  987. w.0 = p.0
  988. w.1 = 20
  989. w.2 = 10
  990. w.3 = 8
  991.  
  992. /* don't echo the password field */
  993.  
  994. h.0 = p.0
  995. h.1 = 0
  996. h.2 = 0
  997. h.3 = 1
  998.  
  999. /* default strings */
  1000.  
  1001. r.0 = p.0
  1002. r.1 = 'IBMVM'
  1003. r.2 = 'johndoe'
  1004. r.3 = ''
  1005.  
  1006. button = VMultBox('Logon Panel', p, w, h, r, 2)
  1007.  
  1008. if button = 'OK' then do
  1009.    call VMsgBox 'Logon Info', r, 1
  1010. end
  1011.  
  1012.  
  1013. ΓòÉΓòÉΓòÉ 4.20. VOpenWindow ΓòÉΓòÉΓòÉ
  1014.  
  1015. Purpose             Opens a new window 
  1016.  
  1017. Definition 
  1018.  
  1019.                                         VOpenWindow [title] [color] [stem]
  1020.  
  1021. Parameters          [title] is the string to use for the window titlebar. 
  1022.                     [color] is the background color to use for the window. 
  1023.                     [stem] is the name of a stem variable which contains the 
  1024.                     position and size of the window when it it created.  There 
  1025.                     are 4 fields, [stem].left, [stem].right, [stem].bottom and 
  1026.                     [stem].top, which must be specified. 
  1027.  
  1028. Comments            The left, right, top and bottom fields should be integer 
  1029.                     numbers representing a percentage of the screen, ranging 
  1030.                     between 0 and 100. 
  1031.  
  1032. Function Result     Returns an integer id number used to refer to the new 
  1033.                     window in subsequent function calls 
  1034.  
  1035. Example: 
  1036.  
  1037. /* put up a new window in the upper left quadrant of
  1038.    the screen, with a background of white */
  1039.  
  1040. pos.left   = 0
  1041. pos.bottom = 0
  1042. pos.right  = 50
  1043. pos.top    = 100
  1044.  
  1045. color = 'WHITE'
  1046.  
  1047. new_id = VOpenWindow('An example window', color, pos)
  1048.  
  1049.  
  1050. ΓòÉΓòÉΓòÉ 4.21. VRadioBox ΓòÉΓòÉΓòÉ
  1051.  
  1052. Purpose             Creates a radiobox dialog for selecting 1 item from a list 
  1053.  
  1054. Definition 
  1055.  
  1056.                                         VRadioBox [title] [stem] [buttons]
  1057.  
  1058. Parameters          [title] is the string to use for the dialog titlebar. 
  1059.                     [stem] is the name of the stem variable which contains the 
  1060.                     number of items and text of each item to be placed in the 
  1061.                     dialog.  [buttons] is a number between 1 and 6 denoting the 
  1062.                     type of pushbuttons to display on the dialog. 
  1063.  
  1064. Comments            A maximum of 10 items may be passed to this function.  On 
  1065.                     input, [stem].vstring can specify the default radio button 
  1066.                     to be pressed when the dialog is created.  If none is 
  1067.                     specified, the first item becomes the default. On output, 
  1068.                     [stem].vstring contains the item selected by the user. 
  1069.  
  1070. Function Result     'OK', 'CANCEL', 'YES' or 'NO', depending on the value of 
  1071.                     [buttons] 
  1072.  
  1073. Example: 
  1074.  
  1075. /* have user select a font by pushing a radiobutton */
  1076.  
  1077. font.0 = 7
  1078. font.1 = 'Garamond'
  1079. font.2 = 'Helvetica'
  1080. font.3 = 'Times Italic'
  1081. font.4 = 'Weather'
  1082. font.5 = 'Math'
  1083. font.6 = 'Orator'
  1084. font.7 = 'Default'
  1085.  
  1086. call VRadioBox 'Select a font', font, 1
  1087.  
  1088. msg.0 = 1
  1089. msg.1 = 'You selected' font.vstring
  1090.  
  1091. call VMsgBox 'Selection', msg, 1
  1092.  
  1093.  
  1094. ΓòÉΓòÉΓòÉ 4.22. VResize ΓòÉΓòÉΓòÉ
  1095.  
  1096. Purpose             Resizes and repositions a window on the screen 
  1097.  
  1098. Definition 
  1099.  
  1100.                                         VResize [id] [stem]
  1101.  
  1102. Parameters          [id] is the id of the window to move and size.  [stem] is 
  1103.                     the name of a stem variable containing the new coordinates 
  1104.                     of the window in percentage of screen units.  The size and 
  1105.                     position are given in [stem].left, [stem].right, 
  1106.                     [stem].bottom and [stem].top. 
  1107.  
  1108. Comments            The left, bottom, right and top coordinates should be 
  1109.                     integers between 0 and 100. 
  1110.  
  1111. Function Result     none 
  1112.  
  1113. Example: 
  1114.  
  1115. /* create a small window in the center of the screen,
  1116.    then move it to the lower right quadrant and
  1117.    increase its size */
  1118.  
  1119. pos.left   = 40
  1120. pos.bottom = 40
  1121. pos.right  = 60
  1122. pos.top    = 60
  1123. id = VOpenWindow('Small window', 'WHITE', pos)
  1124.  
  1125. pos.left   = 50
  1126. pos.bottom = 0
  1127. pos.right  = 100
  1128. pos.top    = 50
  1129. call VResize id, pos
  1130.  
  1131.  
  1132. ΓòÉΓòÉΓòÉ 4.23. VSay ΓòÉΓòÉΓòÉ
  1133.  
  1134. Purpose             Draws a text string in the current font on a window 
  1135.  
  1136. Definition 
  1137.  
  1138.                                         VSay [id] [x] [y] [text]
  1139.  
  1140. Parameters          [id] is the id of the window where the text will be drawn. 
  1141.                     [x] and [y] are the starting coordinates for the text, 
  1142.                     expressed as integers between 0 and 1000.  [text] is the 
  1143.                     text string to draw. 
  1144.  
  1145. Comments            The text will be drawn in the current font and the current 
  1146.                     color. 
  1147.  
  1148. Function Result     none 
  1149.  
  1150. Example: 
  1151.  
  1152. /* draw a set of text strings */
  1153.  
  1154. str.1 = 'You will need:
  1155. str.2 = '*  C Compiler'
  1156. str.3 = '*  OS/2 Programmer's Reference'
  1157.  
  1158. x = 50
  1159. y = 900
  1160. do i = 1 to 3
  1161.    call VSay id, x, y, str.i
  1162.    y = y - 100
  1163. end
  1164.  
  1165.  
  1166. ΓòÉΓòÉΓòÉ 4.24. VSetFont ΓòÉΓòÉΓòÉ
  1167.  
  1168. Purpose             Sets the current font to use for drawing text 
  1169.  
  1170. Definition 
  1171.  
  1172.                                         VSetFont [id] [type] [size]
  1173.  
  1174. Parameters          [id] is the id of the window.  [type] is a string 
  1175.                     representing the typeface requested, and [size] is the 
  1176.                     point size for the requested font. 
  1177.  
  1178. Comments            The point size must be a positive integer greater than 
  1179.                     zero.  The typeface must be one of the following strings: 
  1180.  
  1181.    o 'SYSTEM' - standard system font 
  1182.  
  1183.    o 'SYMBOL' - greek/math symbols 
  1184.  
  1185.    o 'COUR' - Courier, Courier Bold, Courier Italic, Courier Bold Italic 
  1186.  
  1187.    o 'COURB' 
  1188.  
  1189.    o 'COURI' 
  1190.  
  1191.    o 'COURBI' 
  1192.  
  1193.    o 'HELV' - Helvetica, Helvetica Bold, Helvetica Italic, Helvetica Bold 
  1194.      Italic 
  1195.  
  1196.    o 'HELVB' 
  1197.  
  1198.    o 'HELVI' 
  1199.  
  1200.    o 'HELVBI' 
  1201.  
  1202.    o 'TIME' - Times Roman, TR Bold, TR Italic, TR Bold Italic 
  1203.  
  1204.    o 'TIMEB' 
  1205.  
  1206.    o 'TIMEI' 
  1207.  
  1208.    o 'TIMEBI' 
  1209.  
  1210. Function Result     none 
  1211.  
  1212. Example: 
  1213.  
  1214. /* set the font to 20 point Helvetica Bold */
  1215.  
  1216. call VSetFont id, 'HELVB', 20
  1217.  
  1218.  
  1219. ΓòÉΓòÉΓòÉ 4.25. VSetTitle ΓòÉΓòÉΓòÉ
  1220.  
  1221. Purpose             Sets the titlebar of a window to a specified string 
  1222.  
  1223. Definition 
  1224.  
  1225.                                         VSetTitle [id] [title]
  1226.  
  1227. Parameters          [id] is the id of the window, and [title] is the new string 
  1228.                     to use for the window's titlebar. 
  1229.  
  1230. Comments 
  1231.  
  1232. Function Result     none 
  1233.  
  1234. Example: 
  1235.  
  1236. /* open a window with one title, then change it */
  1237.  
  1238. pos.left   = 25
  1239. pos.bottom = 25
  1240. pos.right  = 75
  1241. pos.top    = 75
  1242.  
  1243. id = VOpenWindow('Old Window Title', 'WHITE', pos)
  1244.  
  1245. call VSetTitle id, 'New Window Title'
  1246.  
  1247.  
  1248. ΓòÉΓòÉΓòÉ 4.26. VTableBox ΓòÉΓòÉΓòÉ
  1249.  
  1250. Purpose             Constructs a table dialog as a listbox, with programmable 
  1251.                     column widths 
  1252.  
  1253. Definition 
  1254.  
  1255.                                         VTableBox [title] [stem] [selection] [width] [height] [buttons]
  1256.  
  1257. Parameters          [title] is the string to use for the dialog titlebar. 
  1258.                     [stem] is the name of the stem variable which contains the 
  1259.                     number of rows and columns, column widths, column labels 
  1260.                     and text of each item to be placed in a table-style 
  1261.                     listbox. [selection] contains the number of the table row 
  1262.                     to be selected when the dialog is created.  [width] and 
  1263.                     [height] are the dimensions of the table in character 
  1264.                     units, and [buttons] is a number between 1 and 6 denoting 
  1265.                     the type of pushbuttons to display on the dialog. 
  1266.  
  1267. Comments            Any number of strings may be passed to this function, all 
  1268.                     with a maximum length of 80.  The number of columns in the 
  1269.                     table is limited to 10.  The number of rows and columns in 
  1270.                     the table are specified with the [stem].rows and 
  1271.                     [stem].cols variables.  The column widths are specified in 
  1272.                     [stem].width.1, [stem].width.2, etc. The column labels are 
  1273.                     specified in [stem].label.1, [stem].label.2, etc. Finally, 
  1274.                     the entries for the table are stored in row-column order, 
  1275.                     with [stem].1.1 being the entry for row 1, column 1, 
  1276.                     [stem].1.2 being the entry for row 1, column 2, etc. On 
  1277.                     output, [stem].vstring contains the table row number 
  1278.                     selected by the user. 
  1279.  
  1280. Function Result     'OK', 'CANCEL', 'YES' or 'NO', depending on the value of 
  1281.                     [buttons] 
  1282.  
  1283. Example: 
  1284.  
  1285. /* display a table of data */
  1286.  
  1287. table.rows = 50
  1288. table.cols = 3
  1289.  
  1290. table.label.1 = 'Name'
  1291. table.label.2 = 'Division'
  1292. table.label.3 = 'Serial Number'
  1293.  
  1294. table.width.1 = 20
  1295. table.width.2 = 10
  1296. table.width.3 = 15
  1297.  
  1298. table.1.1 = 'John Doe'
  1299. table.1.2 = 10
  1300. table.1.3 = 'CR1034'
  1301.  
  1302. table.2.1 = 'Mary Jane'
  1303. table.2.2 = 44
  1304. table.2.3 = 'TX1143'
  1305.  
  1306. /* etc. */
  1307.  
  1308. table.50.1 = 'Joe Programmer'
  1309. table.50.2 = 11
  1310. table.50.3 = '001101'
  1311.  
  1312. call VTableBox 'Pick a row from the table', table, 1, 50, 15, 1
  1313. selection_number = table.vstring
  1314.  
  1315.  
  1316. ΓòÉΓòÉΓòÉ 5. EXAMPLE VREXX PROCEDURES ΓòÉΓòÉΓòÉ
  1317.  
  1318. This section provides several example REXX procedures which give you some ideas 
  1319. about how to incorporate the VREXX functions in your own REXX programs.  The 
  1320. following examples are presented: 
  1321.  
  1322. TESTWIN.CMD         Shows creation and manipulation of PM windows, text 
  1323.                     display, etc. 
  1324.  
  1325. TESTDLGS.CMD        Demonstrates the use of the standard dialog functions, 
  1326.                     including filename and list item selections. 
  1327.  
  1328. TESTDRAW.CMD        Draws some arbitrary graphics to PM windows. 
  1329.  
  1330.  
  1331. ΓòÉΓòÉΓòÉ 5.1. TESTWIN.CMD ΓòÉΓòÉΓòÉ
  1332.  
  1333. /* TESTWIN.CMD */
  1334.  
  1335. '@echo off'
  1336. call RxFuncAdd 'VInit', 'VREXX', 'VINIT'
  1337. initcode = VInit()
  1338. if initcode = 'ERROR' then signal CLEANUP
  1339.  
  1340. signal on failure name CLEANUP
  1341. signal on halt name CLEANUP
  1342. signal on syntax name CLEANUP
  1343.  
  1344. /* display the version number of VREXX */
  1345.  
  1346. ver = VGetVersion()
  1347. msg.0 = 1
  1348. msg.1 = 'VREXX version # ' ver
  1349. call VMsgBox 'TESTWIN.CMD', msg, 1
  1350.  
  1351. /* open a window and draw some text */
  1352.  
  1353. win.left   = 20
  1354. win.right  = 70
  1355. win.top    = 80
  1356. win.bottom = 40
  1357. id = VOpenWindow('My VREXX Window', 'RED', win)
  1358.  
  1359. text.1 = 'This is a VREXX window, created with a call to VOpenWindow.'
  1360. text.2 = 'The window currently has a title = My VREXX Window, and it'
  1361. text.3 = 'has a red background, which can be changed by a call to the'
  1362. text.4 = 'VBackColor function.  The font is 12 point Times Roman.'
  1363.  
  1364. call VForeColor id, 'WHITE'
  1365. call VSetFont id, 'TIME', 12
  1366.  
  1367. x = 10
  1368. y = 900
  1369. do i = 1 to 4
  1370.    call VSay id, x, y, text.i
  1371.    y = y - 50
  1372. end
  1373.  
  1374. /* now display a message box */
  1375.  
  1376. msg.0 = 2
  1377. msg.1 = 'Press OK to change the window title, the'
  1378. msg.2 = 'window background color, and the font...'
  1379. call VMsgBox 'TESTWIN.CMD', msg, 1
  1380.  
  1381. /* change the title and background color */
  1382.  
  1383. call VSetTitle id, 'A New Title!'
  1384. text.2 = 'The new window title = A New Title!, and it'
  1385.  
  1386. call VClearWindow id
  1387. call VBackColor id, 'BLUE'
  1388. text.3 = 'has a blue background, which can be changed by a call to the'
  1389. call VForeColor id, 'WHITE'
  1390.  
  1391. /* change the font */
  1392.  
  1393. call VSetFont id, 'HELVB', 15
  1394. text.4 = 'VBackColor function.  The font is now 15 point Helvetica Bold.'
  1395.  
  1396. /* redraw the text in the window */
  1397.  
  1398. x = 10
  1399. y = 900
  1400. do i = 1 to 4
  1401.    call VSay id, x, y, text.i
  1402.    y = y - 60
  1403. end
  1404.  
  1405. /* now move and resize the window */
  1406.  
  1407. msg.0 = 3
  1408. msg.1 = 'Now the window will be cleared and moved around'
  1409. msg.2 = 'and resized using the VResize function.  Press'
  1410. msg.3 = 'OK to continue...'
  1411. call VMsgBox 'TESTWIN.CMD', msg, 1
  1412.  
  1413. call VClearWindow id
  1414.  
  1415. win.left   = 5
  1416. win.right  = 15
  1417. win.bottom = 80
  1418. win.top    = 95
  1419. call VResize id, win
  1420.  
  1421. do 8
  1422.    win.left   = win.left   + 5
  1423.    win.right  = win.right  + 10
  1424.    win.top    = win.top    - 5
  1425.    win.bottom = win.bottom - 10
  1426.    call VResize id, win
  1427. end
  1428.  
  1429. /* put up a message box */
  1430.  
  1431. msg.0 = 1
  1432. msg.1 = 'Press Cancel to end...'
  1433. call VMsgBox 'TESTWIN.CMD', msg, 2
  1434.  
  1435. call VCloseWindow id
  1436.  
  1437. /* end of CMD file */
  1438.  
  1439. CLEANUP:
  1440.    call VExit
  1441.  
  1442. exit
  1443.  
  1444.  
  1445. ΓòÉΓòÉΓòÉ 5.2. TESTDLGS.CMD ΓòÉΓòÉΓòÉ
  1446.  
  1447. /* TESTDLGS.CMD */
  1448.  
  1449. '@echo off'
  1450. call RxFuncAdd 'VInit', 'VREXX', 'VINIT'
  1451. initcode = VInit()
  1452. if initcode = 'ERROR' then signal CLEANUP
  1453.  
  1454. signal on failure name CLEANUP
  1455. signal on halt name CLEANUP
  1456. signal on syntax name CLEANUP
  1457.  
  1458. /* example VMsgBox call */
  1459.  
  1460. msg.0 = 4
  1461. msg.1 = 'This is a 4 line message box dialog.'
  1462. msg.2 = 'This is the line 2.  Line 3 is blank.'
  1463. msg.3 = ''
  1464. msg.4 = 'Press YES or NO to continue...'
  1465.  
  1466. call VDialogPos 50, 50
  1467. rb = VMsgBox('TESTDLGS.CMD', msg, 6)
  1468. if rb = 'YES' then do
  1469.    msg.0 = 1
  1470.    msg.1 = 'You pressed YES'
  1471. end
  1472. else do
  1473.    msg.0 = 1
  1474.    msg.1 = 'You pressed NO'
  1475. end
  1476. call VMsgBox 'VMsgBox Result', msg, 1
  1477.  
  1478. /* VInputBox example */
  1479.  
  1480. prompt.0 = 2
  1481. prompt.1 = 'Enter your name'
  1482. prompt.2 = '(Last name first, First name last)'
  1483. prompt.vstring = 'Doe John'
  1484. button = VInputBox('VInputBox example', prompt, 20, 3)
  1485.  
  1486. if button = 'OK' then do
  1487.    msg.0 = 3
  1488.    msg.1 = 'You entered the name'
  1489.    msg.2 = prompt.vstring
  1490.    msg.3 = 'and you pressed OK'
  1491. end
  1492. else do
  1493.    msg.0 = 1
  1494.    msg.1 = 'You pressed CANCEL'
  1495. end
  1496. call VMsgBox 'VInputBox Result', msg, 1
  1497.  
  1498. /* VMultBox example */
  1499.  
  1500. prompt.0 = 2   /* 2 prompt lines */
  1501. prompt.1 = 'User ID'
  1502. prompt.2 = 'Password'
  1503.  
  1504. width.0 = 2
  1505. width.1 = 10   /* widths in character units */
  1506. width.2 = 8    /* for both entryfields */
  1507.  
  1508. hide.0 = 2
  1509. hide.1 = 0     /* echo the User ID input */
  1510. hide.2 = 1     /* don't echo the Password */
  1511.  
  1512. answer.0 = 2
  1513. answer.1 = ''  /* these are the default strings */
  1514. answer.2 = ''  /* which will contain the input */
  1515.  
  1516. button = VMultBox('VMultBox example', prompt, width, hide, answer, 3)
  1517.  
  1518. if button = 'OK' then do
  1519.    call VMsgBox 'VMultBox Result', answer, 1
  1520. end
  1521. else do
  1522.    msg.0 = 1
  1523.    msg.1 = 'You pressed CANCEL'
  1524.    call VMsgBox 'VMultBox Result', msg, 1
  1525. end
  1526.  
  1527. /* VListBox example */
  1528.  
  1529. list.0 = 17
  1530. list.1  = 'OS/2 2.0 Standard Edition'
  1531. list.2  = 'OS/2 2.0 Extended Edition'
  1532. list.3  = 'MMPM/2 Multimedia Extensions'
  1533. list.4  = 'Windows 3.0 Multimedia Extensions'
  1534. list.5  = 'Adobe Type Manager'
  1535. list.6  = 'C-Set/2 Compiler'
  1536. list.7  = 'OS/2 2.0 Programmer Toolkit'
  1537. list.8  = 'WorkFrame/2'
  1538. list.9  = 'Lan Server'
  1539. list.10 = 'Lan Requester'
  1540. list.11 = 'TCP/IP'
  1541. list.12 = 'PMGlobe Demo Program'
  1542. list.13 = 'ASYNC Terminal Emulator'
  1543. list.14 = 'IPFC Preprocessor'
  1544. list.15 = 'VREXX'
  1545. list.16 = 'OS/2 2.0 Corrective Service'
  1546. list.17 = 'IBM SAA CUA Controls Library'
  1547. list.vstring = list.15          /* default selection */
  1548.  
  1549. call VDialogPos 25, 25
  1550. call VListBox 'Select a Product and Press YES', list, 35, 8, 4
  1551. msg.0 = 1
  1552. msg.1 = list.vstring
  1553. call VMsgBox 'VListBox Selection', msg, 1
  1554.  
  1555. /* test of VTableBox */
  1556.  
  1557. table.rows = 5
  1558. table.cols = 3
  1559.  
  1560. table.label.1 = 'Name'
  1561. table.label.2 = 'Division'
  1562. table.label.3 = 'Serial Number'
  1563.  
  1564. table.width.1 = 25
  1565. table.width.2 = 10
  1566. table.width.3 = 15
  1567.  
  1568. table.1.1 = 'Mary Jacobs'
  1569. table.1.2 = 20
  1570. table.1.3 = '243611'
  1571.  
  1572. table.2.1 = 'Joe Johnson'
  1573. table.2.2 = 19
  1574. table.2.3 = '837462'
  1575.  
  1576. table.3.1 = 'Henry Hill'
  1577. table.3.2 = 79
  1578. table.3.3 = '832628'
  1579.  
  1580. table.4.1 = 'Ruby Potts'
  1581. table.4.2 = 11
  1582. table.4.3 = '937567'
  1583.  
  1584. table.5.1 = 'Gary Williams'
  1585. table.5.2 = 22
  1586. table.5.3 = '086203'
  1587.  
  1588. button = VTableBox('Employee List', table, 1, 40, 10, 1)
  1589.  
  1590. msg.0 = 2
  1591. msg.1 = 'Button pressed was' button
  1592. msg.2 = 'Selection number =' table.vstring
  1593. call VMsgBox 'VTableBox Result', msg, 1
  1594.  
  1595. /* VRadioBox example */
  1596.  
  1597. list.0 = 10
  1598. call VRadioBox 'Select 1 item', list, 1
  1599. msg.0 = 1
  1600. msg.1 = list.vstring
  1601. call VMsgBox 'Selected item', msg, 1
  1602.  
  1603. /* test of VCheckBox */
  1604.  
  1605. list.0 = 10
  1606. sel.0 = 2
  1607. sel.1 = list.2
  1608. sel.2 = list.3
  1609. call VCheckBox 'Select items', list, sel, 1
  1610. if sel.0 > 0 then do
  1611.    call VMsgBox 'Selected items', sel, 1
  1612. end
  1613.  
  1614. /* VColorBox example */
  1615.  
  1616. call VDialogPos 75, 75
  1617. color.fore = 'YELLOW'
  1618. color.back = 'BLUE'
  1619. call VColorBox color
  1620. msg.0 = 2
  1621. msg.1 = 'Foreground color is' color.fore
  1622. msg.2 = 'Background color is' color.back
  1623. call VMsgBox 'Color selections', msg, 1
  1624.  
  1625. /* VFontBox example */
  1626.  
  1627. font.type = 'HELVB'
  1628. font.size = 25
  1629. call VFontBox font
  1630. msg.0 = 2
  1631. msg.1 = 'Font type is' font.type
  1632. msg.2 = 'Font size is' font.size
  1633. call VMsgBox 'Font selection', msg, 1
  1634.  
  1635. /* test of VFileBox */
  1636.  
  1637. call VDialogPos 10, 50
  1638. button = VFileBox('Pick a file...', 'c:\os2\*.exe', 'file')
  1639. msg.0 = 3
  1640. msg.1 = 'File name picked was'
  1641. msg.2 = file.vstring
  1642. msg.3 = 'Button pressed was' button
  1643. call VMsgBox 'VFileBox Result', msg, 1
  1644.  
  1645. /* end of CMD file */
  1646.  
  1647. CLEANUP:
  1648.    call VExit
  1649.  
  1650. exit
  1651.  
  1652.  
  1653. ΓòÉΓòÉΓòÉ 5.3. TESTDRAW.CMD ΓòÉΓòÉΓòÉ
  1654.  
  1655. /* TESTDRAW.CMD */
  1656.  
  1657. '@echo off'
  1658. call RxFuncAdd 'VInit', 'VREXX', 'VINIT'
  1659. initcode = VInit()
  1660. if initcode = 'ERROR' then signal CLEANUP
  1661.  
  1662. signal on failure name CLEANUP
  1663. signal on halt name CLEANUP
  1664. signal on syntax name CLEANUP
  1665.  
  1666. /* set up marker types */
  1667.  
  1668. default      = 0
  1669. cross        = 1
  1670. plus         = 2
  1671. diamond      = 3
  1672. square       = 4
  1673. star6        = 5
  1674. star8        = 6
  1675. soliddiamond = 7
  1676. solidsquare  = 8
  1677. soliddot     = 9
  1678. circle       = 10
  1679.  
  1680. /* set up line types */
  1681.  
  1682. solid      = 0
  1683. dot        = 1
  1684. dash       = 2
  1685. dashdot    = 3
  1686. dotdot     = 4
  1687. longdash   = 5
  1688. dashdotdot = 6
  1689.  
  1690. /* set up fill types */
  1691.  
  1692. nofill    = 0
  1693. solidfill = 1
  1694. horz      = 2
  1695. vert      = 3
  1696. leftdiag  = 4
  1697. rightdiag = 5
  1698.  
  1699. /* create 2 windows for drawing some graphics */
  1700.  
  1701. win1.left   = 15
  1702. win1.bottom = 30
  1703. win1.right  = 55
  1704. win1.top    = 70
  1705. id1 = VOpenWindow('TESTDRAW.CMD Graphics Window 1', 'WHITE', win1)
  1706.  
  1707. win2.left   = 60
  1708. win2.bottom = 10
  1709. win2.right  = 95
  1710. win2.top    = 40
  1711. id2 = VOpenWindow('TESTDRAW.CMD Graphics Window 2', 'BLACK', win2)
  1712.  
  1713. /* draw a line graph in window 1 */
  1714.  
  1715. call VForeColor id1, 'BLACK'
  1716.  
  1717. x.1 = 100
  1718. y.1 = 600
  1719. x.2 = 400
  1720. y.2 = 600
  1721. call VDraw id1, 'LINE', x, y, 2         /* x axis */
  1722. x.1 = 100
  1723. y.1 = 600
  1724. x.2 = 100
  1725. y.2 = 900
  1726. call VDraw id1, 'LINE', x, y, 2         /* y axis */
  1727.  
  1728. a = -0.000222   /* construct a quadratic polynomial */
  1729. b = 0.861       /* Y = a*X*X + b*X + c */
  1730. c = 566
  1731.  
  1732. x.1 = 100
  1733. y.1 = a*100*100 + b*100 + c
  1734. do i = 2 to 5
  1735.    j = i - 1
  1736.    x.i = x.j + 75
  1737.    y.i = a * x.i * x.i + b * x.i + c
  1738. end
  1739.  
  1740. call VDrawParms id1, soliddiamond, dashdot, default
  1741. call VDraw id1, 'MARKER', x, y, 5
  1742. call VDraw id1, 'LINE', x, y, 5
  1743.  
  1744. /* draw a set of arcs in window 2 */
  1745.  
  1746. call VForeColor id2, 'YELLOW'
  1747.  
  1748. cx = 100
  1749. cy = 200
  1750. radius = 20
  1751. angle1 = 0
  1752. angle2 = 60
  1753.  
  1754. do i = 1 to 6
  1755.    call VArc id2, cx, cy, radius, angle1, angle2
  1756.    radius = radius + 20
  1757.    cx = cx + 150
  1758.    angle2 = angle2 + 60
  1759. end
  1760.  
  1761. /* draw a bar graph in window 1 */
  1762.  
  1763. call VDrawParms id1, default, default, default
  1764. x.1 = 550
  1765. y.1 = 600
  1766. x.2 = 950
  1767. y.2 = 600
  1768. call VDraw id1, 'LINE', x, y, 2         /* x axis */
  1769. x.1 = 550
  1770. y.1 = 600
  1771. x.2 = 550
  1772. y.2 = 900
  1773. call VDraw id1, 'LINE', x, y, 2         /* y axis */
  1774.  
  1775. px.1 = 600
  1776. py.1 = 600
  1777. px.2 = 600
  1778. py.2 = 650
  1779. px.3 = 650
  1780. py.3 = 650
  1781. px.4 = 650
  1782. py.4 = 600
  1783.  
  1784. call VForeColor id1, 'RED'
  1785. do i = 1 to 6
  1786.    /* draw bar with a new fill type */
  1787.  
  1788.    call VDrawParms id1, default, solid, i-1
  1789.    call VDraw id1, 'POLYGON', px, py, 4
  1790.    call VDraw id1, 'LINE', px, py, 4
  1791.  
  1792.    px.1 = px.1 + 50
  1793.    px.2 = px.1
  1794.    px.3 = px.3 + 50
  1795.    px.4 = px.3
  1796.  
  1797.    py.2 = py.2 + 45
  1798.    py.3 = py.2
  1799. end
  1800.  
  1801. /* draw some lines of different types in window 2 */
  1802.  
  1803. color.1 = 'WHITE'               /* set up color array */
  1804. color.2 = 'RED'
  1805. color.3 = 'GREEN'
  1806. color.4 = 'BLUE'
  1807. color.5 = 'CYAN'
  1808. color.6 = 'YELLOW'
  1809. color.7 = 'PINK'
  1810.  
  1811. x.1 = 200
  1812. y.1 = 950
  1813. x.2 = 800
  1814. y.2 = 950
  1815.  
  1816. do i = 1 to 7
  1817.    call VForeColor id2, color.i
  1818.    call VDrawParms id2, default, i-1, default
  1819.    call VDraw id2, 'LINE', x, y, 2
  1820.  
  1821.    y.1 = y.1 - 100
  1822.    y.2 = y.1
  1823. end
  1824.  
  1825. /* set up a spline in window 1, drawing the control points */
  1826. /* of the spline as markers, and labelling them with text  */
  1827.  
  1828. sx.1 = 350
  1829. sy.1 = 450
  1830. sx.2 = 700
  1831. sy.2 = 200
  1832. sx.3 = 200
  1833. sy.3 = 125
  1834. sx.4 = 650
  1835. sy.4 = 425
  1836.  
  1837. call VForeColor id1, 'BLUE'
  1838. call VDrawParms id1, soliddot, default, default
  1839. call VDraw id1, 'MARKER', sx, sy, 4
  1840. call VDraw id1, 'SPLINE', sx, sy, 4
  1841.  
  1842. call VForeColor id1, 'GREEN'
  1843. call VSetFont id1, 'HELVB', 12
  1844. call VSay id1, 300, 75, 'Spline Control Points'
  1845.  
  1846. /* put up a message box */
  1847.  
  1848. msg.0 = 1
  1849. msg.1 = 'Press OK to close the windows'
  1850. call VMsgBox 'TESTDRAW.CMD', msg, 1
  1851.  
  1852. call VCloseWindow id1
  1853. call VCloseWindow id2
  1854.  
  1855. /* end of CMD file */
  1856.  
  1857. CLEANUP:
  1858.    call VExit
  1859.  
  1860. exit
  1861.  
  1862.  
  1863. ΓòÉΓòÉΓòÉ 6. TECHNICAL DATA ΓòÉΓòÉΓòÉ
  1864.  
  1865. VREXX packages its external functions in the dynamic link library VREXX.DLL. 
  1866. Thus, REXX procedures can load and call the VInit function, which sets up 
  1867. system resources and initializes the other VREXX external functions for access 
  1868. by REXX.  The VExit function then frees up these system resources before the 
  1869. REXX procedure exits. 
  1870.  
  1871. When VInit is called, it starts a copy of the new VREXX.EXE program and sets up 
  1872. a shared memory block to pass variables between the DLL and the program. The 
  1873. program creates an invisible control window, and waits for the VREXX external 
  1874. functions to post messages to the window.  The control window then creates the 
  1875. windows, draws graphics, processes dialogs, etc. 
  1876.  
  1877. Variables are shared between the DLL and the REXX environment through the 
  1878. shared variable pool. Stem variables are used to facilitate the use of REXX 
  1879. arrays by the user. Shared memory blocks and semaphores are used to pass data 
  1880. and synchronize between the DLL and the control window. 
  1881.  
  1882.  
  1883. ΓòÉΓòÉΓòÉ 7. RELEASE NOTES AND COMMENTS ΓòÉΓòÉΓòÉ
  1884.  
  1885. Version 1.1 (10/29/93) fixes a bug which prevented more than one VREXX routine 
  1886. at a time from being started from a single CMD window. 
  1887.  
  1888. Version 1.0 (09/09/92) is the initial release.