home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / lsmt213c.zip / rxutils.inf (.txt) < prev    next >
OS/2 Help File  |  1993-02-19  |  76KB  |  2,939 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Abstract ΓòÉΓòÉΓòÉ
  3.  
  4. Acknowledgements 
  5.  
  6. The author would like to thank everyone that participated in the development 
  7. and testing of RxUtils. 
  8.  
  9. Persons that were and are especially helpful are listed below: 
  10.  
  11. o Tom Bridgman 
  12.  
  13. o Rick McGuire 
  14.  
  15.  
  16. ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ
  17.  
  18. RxUtils is a Dynamic Link Library (DLL) which provides the OS/2 REXX programmer 
  19. with many versatile functions. 
  20.  
  21. RxUtils was created so that many of the REXX execs which our group has written 
  22. could be optimized.  Prior to RxUtils, our execs were forced to shell out to 
  23. OS/2 and run an executable or internal command.  This was very slow and often 
  24. caused many lines of code to be written. 
  25.  
  26. (C) IBM Corporation 1989, 1993 
  27.  
  28.  
  29. ΓòÉΓòÉΓòÉ 3. RxUtils Documentation ΓòÉΓòÉΓòÉ
  30.  
  31. The RXUTILS SCRIPT is written in Bookmaster.  You may script this document to 
  32. any host printer which supports Bookmaster via the following command: 
  33.  
  34.    SCRIPT RXUTILS SCRIPT ( ON printer BOOKIE
  35.  
  36. The RXUTILS INFBIN file may be downloaded in binary to your OS/2 workstation as 
  37. RXUTILS.INF.  This file contains on-line documentation which may be browsed via 
  38. the OS/2 VIEW program.  To view the documentation, execute the following from 
  39. any OS/2 command prompt: 
  40.  
  41.    VIEW RXUTILS.INF
  42.  
  43.  
  44. ΓòÉΓòÉΓòÉ 4. Requirements ΓòÉΓòÉΓòÉ
  45.  
  46. RxUtils requires that you are already running under one of the following 
  47. environments: 
  48.  
  49. o OS/2 1.20 SE running the latest REXXSAA available from OS2TOOLS. 
  50.  
  51. o OS/2 EE 1.20 with OS/2 Procedures Language 2/REXX installed or OS/2 1.30 or 
  52.   1.30.1 (SE or EE) with OS/2 Procedures Language 2/REXX installed. 
  53.  
  54. o OS/2 2.0 with OS/2 Procedures Language 2/REXX installed. 
  55.  
  56.  
  57. ΓòÉΓòÉΓòÉ 5. Contents ΓòÉΓòÉΓòÉ
  58.  
  59. The RXUTILS PACKAGE contains the following files: 
  60.  
  61. RXTEST  CMDBIN   - Test exec that uses all RXUTILS functions
  62. RXUTILS ANNOUNCE - Announcement file containing version information
  63. RXUTI32 DLLBIN   - OS/2 2.0 specific 32-bit version of RXUTILS.DLL
  64. RXUTI16 DLLBIN   - 16-bit version of RXUTILS.DLL. Works for OS/2 1.2+
  65. RXUTILS INFBIN   - Online VIEW documentation
  66. RXUTILS SCRIPT   - BookManager script file source
  67.  
  68. Note:  Those files whose filetype ends in BIN should be downloaded in binary. 
  69.  
  70.  
  71. ΓòÉΓòÉΓòÉ 6. Installation ΓòÉΓòÉΓòÉ
  72.  
  73. For OS/2 1.20, 1.30, 1.30.1 and 2.0 you may use the 16-bit version RXUTILS.DLL. 
  74. The 16-bit version is named RXUTI16.DLL and should be renamed RXUTILS.DLL 
  75. before use. 
  76.  
  77. For OS/2 2.0 you may use the 32-bit version RXUTILS.DLL.  The 32-bit version is 
  78. named RXUTI32.DLL and should be renamed RXUTILS.DLL before use. 
  79.  
  80. To use RXUTILS.DLL, you must first copy it to a subdirectory specified in the 
  81. LIBPATH statement of your CONFIG.SYS. 
  82.  
  83. Example of installing 16-bit version: 
  84.  
  85. COPY RXUTI16.DLL C:\OS2\DLL\RXUTILS.DLL
  86.  
  87. Example of installing 32-bit version: 
  88.  
  89. COPY RXUTI32.DLL C:\OS2\APPS\DLL\RXUTILS.DLL
  90.  
  91.  
  92. ΓòÉΓòÉΓòÉ 7. Usage ΓòÉΓòÉΓòÉ
  93.  
  94. To be able to use an RxUtils function in a REXX exec, you must first add the 
  95. function via the command RxFuncAdd. 
  96.  
  97.    Example:    call RxFuncAdd 'RxGrep', 'RXUTILS', 'RXGREP'
  98.  
  99. The above example would add the RxGrep function so that it can be used. 
  100.  
  101. Note:  RxFuncAdd is an internal REXXSAA command.  It is not part of RxUtils. 
  102. Consult the Procedure Language 2/REXX Reference for further information 
  103. regarding RxFuncAdd if needed.  If an RXUTILS function is not available after 
  104. an RxFuncAdd, you will receive a REXX code 43, Routine not found error.  This 
  105. is NOT RXUTILS fault.  If you receive this error, it is probably due to the 
  106. fact that you are incorrectly using the RxFuncAdd function or that RXUTILS.DLL 
  107. is not along the LIBPATH. If the Routine not found errors persist, append to 
  108. REXXOS2 FORUM on IBMPC as a last resort. 
  109.  
  110. The RxUtils function, RxLoadFuncs, will automatically load all RxUtils 
  111. functions.  To do this from within an exec, add the following commands: 
  112.  
  113.    call RxFuncAdd 'RxLoadFuncs', 'RXUTILS', 'RXLOADFUNCS'
  114.    version = RxLoadFuncs()
  115.  
  116. Note:  If the version of the RxUtils functions which were loaded by RxLoadFuncs 
  117. is not of interest you may call RxLoadFuncs instead. 
  118.  
  119. RxUtils is also compatible with the RxFncLdr package on OS2TOOLS. RxFncLdr is 
  120. an executable which registers all REXX functions within a specified REXX DLL 
  121. (such as RXUTILS.DLL and RXSEM.DLL).  To use RxFncLdr to register all RxUtils 
  122. functions, you could add the following to your STARTUP.CMD: 
  123.  
  124.    RXFNCLDR RXUTILS
  125.  
  126. Note:  Special thanks to Patrick J. Mueller for writing RxFncLdr. 
  127.  
  128. Note:  The 32-bit version of RXUTILS.DLL does not work with RXFNCLDR.  Use the 
  129. RxLoadFuncs technique described above instead. 
  130.  
  131.  
  132. ΓòÉΓòÉΓòÉ 8. RxUtils Definition of a Stem Variable ΓòÉΓòÉΓòÉ
  133.  
  134. Many of RxUtils functions work with stem variables.  These functions are 
  135. limited in that they only work with stem variables having the following 
  136. characteristics: 
  137.  
  138. o STEM.0 specifies the number of elements in the stem (not counting STEM.0). 
  139.  
  140. o STEM.1 through STEM.x (where x is the value specified by STEM.0) are the only 
  141.   accessible values. 
  142.  
  143. The RxGrep and RxRead functions read from files and create stem variables of 
  144. this type. 
  145.  
  146. The RxStemDelete, RxStemInsert, and RxWrite functions all require stem 
  147. variables of this type as input. 
  148.  
  149. The following is sample code which displays the concepts of a stem variable as 
  150. it is described above: 
  151.  
  152. /* Sample code */
  153.  
  154. /* Set the stem variable */
  155. list.0=5
  156. list.1='went to market'
  157. list.2='stayed home'
  158. list.3='had roast beef'
  159. list.4='had none'
  160. list.5='went wee wee wee wee all the way home'
  161.  
  162. /* Print out a story */
  163. do i=1 to list.0
  164.  say 'This little piggy 'list.i
  165. end
  166.  
  167. /* Output */
  168.  
  169. This little piggy went to market
  170. This little piggy stayed home
  171. This little piggy had roast beef
  172. This little piggy had none
  173. This little piggy went wee wee wee wee all the way home
  174.  
  175.  
  176. ΓòÉΓòÉΓòÉ 9. Miscellaneous Functions Overview ΓòÉΓòÉΓòÉ
  177.  
  178.  
  179. ΓòÉΓòÉΓòÉ 9.1. RxAddGroup ΓòÉΓòÉΓòÉ
  180.  
  181. Function: RxAddGroup 
  182.  
  183. Syntax:   rc = RxAddGroup([inifile], group) 
  184.  
  185.    inifile   The name of the INI file which you would like to work with.  This 
  186.              parameter should be a file specification, or one of the following: 
  187.  
  188.       'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the 
  189.                 default. 
  190.  
  191.       'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI). 
  192.  
  193.    group     The name of the group to be added (ie 'Main'). 
  194.  
  195. Purpose:  Add a group to the Start Programs/Desktop Manager window. 
  196.  
  197. RC        Return Codes 
  198.  
  199.    0         Group addition was successful. 
  200.  
  201.    2         Error.  Error adding group; It may already exist. 
  202.  
  203.    9         Invalid INI file entry.  You may have specified the current user 
  204.              or system INI file via a 'relative' filespec.  Make sure to use 
  205.              the full filespec, specifying drive, path, and file name. 
  206.  
  207. Note: 
  208.  
  209. Groups that "Open when system is started" 
  210.  
  211. OS/2 1.30 supports the concept of groups which automatically open when the 
  212. system starts. The RxAddGroup() procedure calls the system function 
  213. PrfAddGroup(), which does not support this type of group attribute. 
  214.  
  215. However, one may use the RxOS2Ini() function to make Autoopen groups. For 
  216. example; to make the Main group open automatically, the following RxOS2Ini call 
  217. should be used: 
  218.  
  219. call RxOS2Ini , 'PM_Autoopen', 'Main', '1'||d2c(0)
  220.  
  221.  
  222. ΓòÉΓòÉΓòÉ 9.2. RxAddProgram ΓòÉΓòÉΓòÉ
  223.  
  224. Function: RxAddProgram 
  225.  
  226. Syntax:   rc = RxAddProgram([inifile], group, stem) 
  227.  
  228.    inifile   The name of the INI file which you would like to work with.  This 
  229.              parameter should be a file specification, or one of the following: 
  230.  
  231.       'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the 
  232.                 default. 
  233.  
  234.       'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI). 
  235.  
  236.    group     The group in which the program should be added (ie 'Main'). 
  237.  
  238.    stem      A stem variable which describes the program to be added.  Stem.0 
  239.              should be set to the number of stem elements.  A stem element may 
  240.              be any one of the following: 
  241.  
  242.       'TITLE=...' The title of the program. 
  243.  
  244.                 Note:  The 'TITLE=...' statement is required. 
  245.  
  246.       'TYPE=...' The program type, any one of the following: 
  247.  
  248.          'DEFAULT' If used, the system will decide how to run the program. 
  249.  
  250.          'FULLSCREEN' The program will be run in a Full Screen OS/2 Window. 
  251.  
  252.          'VIOWINDOW' The program will be run in a VIO OS/2 Window. 
  253.  
  254.          'PM'      The program is a PM application and will be started from the 
  255.                    PM shell. 
  256.  
  257.          'REAL'    'The program is a DOS application and will be run from the 
  258.                    DOS box. 
  259.  
  260.       'VISIBILITY=...' Either one of the following: 
  261.  
  262.          'VISIBLE' The program entry will be displayed in the Desktop Manager 
  263.                    group. 
  264.  
  265.          'INVISIBLE' The program entry will not be displayed in the Desktop 
  266.                    Manager group. 
  267.  
  268.       'EXE=...' The complete path and filename of the program to be run. 
  269.  
  270.       'PARAMS=...' The parameters to be used when running the program. 
  271.  
  272.       'WORKDIR=...' The working directory of the program to be run. 
  273.  
  274.       'ICONFILE=...' The full path and filename of the icon to be associated 
  275.                 with the program. This is not required if the program to be run 
  276.                 contains an icon resource within it (such as most PM programs 
  277.                 do). 
  278.  
  279.       'XYSIZE=x, y, cx, cy' The position and size of the running program.  The 
  280.                 values of x and y denote the position of the lower left of the 
  281.                 program's presentation space.  While the values of cx and cy 
  282.                 denote the width and height of the presentation space, 
  283.                 respectively.  If all values are 0 (the default) the system 
  284.                 will decide the best values for the application. 
  285.  
  286.                 Note:  XYSIZE is really only useful for VIOWINDOW sessions.  It 
  287.                 does not affect FULLSCREEN sessions and PM programs have a 
  288.                 tendency to move and size themselves as they desire. 
  289.  
  290.       'XYSTYLE=...' Any logical combination of the following: 
  291.  
  292.          NORMAL    Session will be normal and have none of the styles or 
  293.                    attributes listed below. 
  294.  
  295.          NOAUTOCLOSE Upon termination of the running program, the session will 
  296.                    not close automatocally. For VIOWINDOW sessions, the session 
  297.                    is terminated by selecting the System Menu Close menu item 
  298.                    (or by pressing ALT-F4 or by double clicking on the System 
  299.                    Menu). 
  300.  
  301.          MINIMIZED The session will start in the minimized state.  This only 
  302.                    works for VIOWINDOW sessions. 
  303.  
  304.          MAXIMIZED The session will start in the maximized state.  This only 
  305.                    works for VIOWINDOW sessions. 
  306.  
  307.          INVISIBLE The session will not be seen while executing (but will show 
  308.                    up in the Task List). This only works for VIOWINDOW 
  309.                    sessions. 
  310.  
  311.                 Note: 
  312.  
  313.                 Multiple XYSTYLE attributes should be specified with one stem 
  314.                 entry. 
  315.  
  316.                 For example: 
  317.  
  318.                                 'XYSTYLE=NOAUTOCLOSE, MINIMIZED'
  319.  
  320.    Purpose:  Add a program to a particular group in the Start Programs/Desktop 
  321.              Manager window. 
  322.  
  323.    RC        Return Codes 
  324.  
  325.       0         Program addition was successful. 
  326.  
  327.       1         Error.  Illegal stem variable item. 
  328.  
  329.       2         Error.  Not enough memory. 
  330.  
  331.       3         Error.  Title not specified. 
  332.  
  333.       4         Error.  Error adding program; It may already exist. 
  334.  
  335.       9         Invalid INI file entry.  You may have specified the current 
  336.                 user or system INI file via a 'relative' filespec.  Make sure 
  337.                 to use the full filespec, specifying drive, path, and file 
  338.                 name. 
  339.  
  340. Note: 
  341.  
  342. Programs that "Open when system is started" 
  343.  
  344. OS/2 1.30 supports the concept of programs which automatically open when the 
  345. system starts. The RxAddProgram() procedure calls the system function 
  346. PrfAddProgram(), which does not support this type of program attribute. 
  347.  
  348. However, one may use the RxOS2Ini() function to make Autostart programs. For 
  349. example; to make the Communications Manager program of the Main group open 
  350. automatically, the following RxOS2Ini call should be used: 
  351.  
  352. call RxOS2Ini , 'PM_Autostart', 'Main\Communications Manager', '1'||d2c(0)
  353.  
  354.  
  355. ΓòÉΓòÉΓòÉ 9.3. RxAnsi ΓòÉΓòÉΓòÉ
  356.  
  357. Function: RxAnsi 
  358.  
  359. Syntax:   state = RxAnsi([newstate]) 
  360.  
  361.    state     Either 'ON' or 'OFF' depending on the current ANSI state. 
  362.  
  363.    newstate  The desired ANSI state to be set, either 'ON' or 'OFF'.  When 
  364.              setting the ANSI state the current state prior to the setting is 
  365.              returned. 
  366.  
  367. Purpose:  This function may be used to determine if ANSI is ON or OFF and to 
  368.           reset the ANSI state to ON or OFF. 
  369.  
  370.  
  371. ΓòÉΓòÉΓòÉ 9.4. RxBootDrive ΓòÉΓòÉΓòÉ
  372.  
  373. Function: RxBootDrive 
  374.  
  375. Syntax:   drive = RxBootDrive() 
  376.  
  377.    drive     The drive that OS/2 was booted from (ie C:). 
  378.  
  379. Purpose:  With the introduction of OS/2 2.0 and MOST, OS/2 can be installed and 
  380.           booted from drives other than C:.  It is often required that the boot 
  381.           drive is known.  RxBootDrive returns the drive from which OS/2 was 
  382.           booted. 
  383.  
  384.  
  385. ΓòÉΓòÉΓòÉ 9.5. RxCls ΓòÉΓòÉΓòÉ
  386.  
  387. Function: RxCls 
  388.  
  389. Syntax:   call RxCls 
  390.  
  391. Purpose:  Clears the screen quickly. 
  392.  
  393.  
  394. ΓòÉΓòÉΓòÉ 9.6. RxCurPos ΓòÉΓòÉΓòÉ
  395.  
  396. Function: RxCurPos 
  397.  
  398. Syntax:   pos = RxCurPos([row, col]) 
  399.  
  400.    pos       The position of the cursor upon the calling of RxCurPos in the 
  401.              form 'row, col'. 
  402.  
  403.    row       The row on the screen to move to. 
  404.  
  405.    col       The column on the screen to move to. 
  406.  
  407.              Note:  Position (0,0) is at the upper left.  You may call RxCurPos 
  408.              without parameters to check the current cursor position without 
  409.              changing it. 
  410.  
  411. Purpose:  Move the cursor to the specified row and column and/or query the 
  412.           current/previous cursor position. 
  413.  
  414. Example:
  415.  
  416.  /* Code */
  417.  call RxCls
  418.  parse value RxCurPos() with row', 'col
  419.  say 'Cursor position is 'row', 'col
  420.  
  421.  /* Output */
  422.  Cursor position is 0, 0
  423.  
  424.  
  425. ΓòÉΓòÉΓòÉ 9.7. RxCurState ΓòÉΓòÉΓòÉ
  426.  
  427. Function: RxCurState 
  428.  
  429. Syntax:   state = RxCurState([newstate]) 
  430.  
  431.    state     The current state of the cursor, either 'ON' or 'OFF'. 
  432.  
  433.    newstate  The desired state which to set the cursor.  Should be one of the 
  434.              following: 
  435.  
  436.       'ON'      Display the cursor. 
  437.  
  438.       'OFF'     Hide the cursor. When setting the cursor state, the current 
  439.              state prior to the setting is returned. 
  440.  
  441. Purpose:  Use this function to hide or display the cursor or to query the 
  442.           current cursor setting. 
  443.  
  444.  
  445. ΓòÉΓòÉΓòÉ 9.8. RxDCName ΓòÉΓòÉΓòÉ
  446.  
  447. Function: RxDCName 
  448.  
  449. Syntax:   server = RxDCName(domain) 
  450.  
  451.    server    The name of the server residing on the domain specified (if any). 
  452.  
  453.              Note:  If valid, the returned server name will start with '\\'. 
  454.  
  455.    domain    The domain of interest. 
  456.  
  457. Purpose:  Given a domain name, this function returns the name of the domain 
  458.           controller's server if there is one. 
  459.  
  460.           Note:  If the domain specified does not exist than the function will 
  461.           return the string '$RXERROR'. 
  462.  
  463. /* Example */
  464.  server = RxDCName('YKCOD02')
  465.  say server   /* Expect something like '\\YKCOD02S' */
  466.  
  467.  
  468. ΓòÉΓòÉΓòÉ 9.9. RxDelete ΓòÉΓòÉΓòÉ
  469.  
  470. Function: RxDelete 
  471.  
  472. Syntax:   rc = RxDelete(file) 
  473.  
  474. Purpose:  Deletes the specified file. 
  475.  
  476. RC:       Return Codes 
  477.  
  478.    0         File deleted successfully. 
  479.  
  480.    2         Error.  File not found. 
  481.  
  482.    3         Error.  Path not found. 
  483.  
  484.    5         Error.  Access denied. 
  485.  
  486.    26        Error.  Not DOS disk. 
  487.  
  488.    32        Error.  Sharing violation. 
  489.  
  490.    36        Error.  Sharing buffer exceeded. 
  491.  
  492.    87        Error.  Invalid parameter 
  493.  
  494.    206       Error.  Filename exceeds range error 
  495.  
  496.  
  497. ΓòÉΓòÉΓòÉ 9.10. RxDeleteGroup ΓòÉΓòÉΓòÉ
  498.  
  499. Function: RxDeleteGroup 
  500.  
  501. Syntax:   rc = RxDeleteGroup([inifile], group) 
  502.  
  503.    inifile   The name of the INI file which you would like to work with.  This 
  504.              parameter should be a file specification, or one of the following: 
  505.  
  506.       'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the 
  507.                 default. 
  508.  
  509.       'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI). 
  510.  
  511.    group     The group that should be deleted (ie 'Main'). 
  512.  
  513. Purpose:  Deletes a specified Desktop Manager group from a specified INI file. 
  514.  
  515. RC:       Return Codes 
  516.  
  517.    0         Group was deleted successfully. 
  518.  
  519.    3         Error.  Could not delete group. 
  520.  
  521.    4         Error.  Group specified does not exist. 
  522.  
  523.    9         Invalid INI file entry.  You may have specified the current user 
  524.              or system INI file via a 'relative' filespec.  Make sure to use 
  525.              the full filespec, specifying drive, path, and file name. 
  526.  
  527.  
  528. ΓòÉΓòÉΓòÉ 9.11. RxDeleteProgram ΓòÉΓòÉΓòÉ
  529.  
  530. Function: RxDeleteProgram 
  531.  
  532. Syntax:   rc = RxDeleteProgram([inifile], group, program) 
  533.  
  534.    inifile   The name of the INI file which you would like to work with.  This 
  535.              parameter should be a file specification, or one of the following: 
  536.  
  537.       'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the 
  538.                 default. 
  539.  
  540.       'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI). 
  541.  
  542.    group     The group from which the program should be deleted (ie 'Main'). 
  543.  
  544.    program   The program title to delete (ie OS/2 Window). 
  545.  
  546. Purpose:  Deletes a specified program in a specified group from a specified INI 
  547.           file. 
  548.  
  549. RC:       Return Codes 
  550.  
  551.    0         Program was deleted successfully. 
  552.  
  553.    3         Error.  Could not delete program. 
  554.  
  555.    4         Error.  Program specified does not exist. 
  556.  
  557.    9         Invalid INI file entry.  You may have specified the current user 
  558.              or system INI file via a 'relative' filespec.  Make sure to use 
  559.              the full filespec, specifying drive, path, and file name. 
  560.  
  561.  
  562. ΓòÉΓòÉΓòÉ 9.12. RxDevConfig ΓòÉΓòÉΓòÉ
  563.  
  564. Function: RxDevConfig 
  565.  
  566. Syntax:   result = RxDevConfig(device) 
  567.  
  568.    result    The result from the query of one of the devices specfied by the 
  569.              device parameter. 
  570.  
  571.    device    A string which represents a device or system attribute of 
  572.              interest.  The following device strings are supported: 
  573.  
  574.       Device    Result 
  575.  
  576.       LPT       Number of physical printer (LPT) ports in the system 
  577.  
  578.       COM       Number of physical serial or RS232 (COM) ports in the system 
  579.  
  580.       DISKETTES Number of diskette drives in the system 
  581.  
  582.       MATHCO    Presence of math coprocessor (where 0 = not present, 1 = 
  583.                 present) 
  584.  
  585.       SUBMODEL  PC Submodel Type (where the return is the system submodel byte 
  586.                 in hex) 
  587.  
  588.       MODEL     PC Model Type (where the return is the system model byte in 
  589.                 hex) 
  590.  
  591.       DISPLAY   Display adapter type (where 0 = monochrome mode compatible, 1 = 
  592.                 other) 
  593.  
  594.       DESKTOP   PM Desktop width and height returned as 'width, height' 
  595.  
  596.    Purpose:  Use this function to query information on a number of system 
  597.              devices. 
  598.  
  599. /* Sample Code */
  600.  
  601. say 'Printer ports='RxDevConfig("LPT")
  602. say 'Com ports='RxDevConfig("COM")
  603. say 'Diskette drives='RxDevConfig("DISKETTES")
  604. say 'Mach Coprocessor='RxDevConfig("MATHCO")
  605. say 'Submodel='RxDevConfig("SUBMODEL")
  606. say 'Model='RxDevConfig("MODEL")
  607. say 'Display='RxDevConfig("DISPLAY")
  608. say 'Desktop Size='RxDevConfig("DESKTOP")
  609.  
  610. /* Sample output */
  611.  
  612. Printer ports=1
  613. Com ports=2
  614. Diskette drives=1
  615. Mach Coprocessor=1
  616. Submodel=11
  617. Model=F8
  618. Display=1
  619. Desktop Size=1280, 1024
  620.  
  621.  
  622. ΓòÉΓòÉΓòÉ 9.13. RxDirExist ΓòÉΓòÉΓòÉ
  623.  
  624. Function: RxDirExist 
  625.  
  626. Syntax:   rc = RxDirExist(directory) 
  627.  
  628.    directory Name of a directory of interest. 
  629.  
  630. Purpose:  Tells whether or not the specified directory exists. 
  631.  
  632. RC:       Return Codes 
  633.  
  634.    0         Directory does not exist. 
  635.  
  636.    1         Directory exists. 
  637.  
  638.  
  639. ΓòÉΓòÉΓòÉ 9.14. RxDriveInfo ΓòÉΓòÉΓòÉ
  640.  
  641. Function: RxDriveInfo 
  642.  
  643. Syntax:   info = RxDriveInfo(drive [, opt]) 
  644.  
  645.    info      Drive information returned in the following form: 'Drive=d: 
  646.              Label=s  Free=n  Total=n'.  If the drive is not accessible, then 
  647.              info will equal ''. 
  648.  
  649.    drive     The drive of interest, ie 'C:'. 
  650.  
  651.    opt       Output options.  More than one option may be specified if 
  652.              seperated by commas. The following options are valid: 
  653.  
  654.       'FSINFO'  If specified, File System information will be returned.  This 
  655.                 information includes the type of the file system and optionally 
  656.                 any additional file system information for the drive specified. 
  657.                 The default is not to include file system information. 
  658.  
  659.       'NOFORMAT' If specified the returned information will not be formatted 
  660.                 with FIELD= text.  The position of each piece of data will 
  661.                 remain the same, but each piece of data will not be preceded 
  662.                 with text.  This option is useful in making the output easier 
  663.                 to parse.  The default is to format the returned string. 
  664.  
  665. Purpose:  Gives drive information. 
  666.  
  667. /* Sample Code */
  668.  
  669. /* Code */
  670. say RxDriveInfo('C:')
  671. say RxDriveInfo('C:', 'FSINFO')
  672. say RxDriveInfo('J:', 'FSINFO')
  673. say RxDriveInfo('C:', 'FSINFO', 'NOFORMAT')
  674. say RxDriveInfo('J:', 'FSINFO', 'NOFORMAT')
  675.  
  676. /* Output */
  677. Disk=C:  Label=TRIGGER_C     Free=33392640     Total=83687424
  678. Disk=C:  Label=TRIGGER_C     Free=33392640     Total=83687424  Type=HPFS
  679. Disk=J:  Label=NFS           Free=157744128    Total=262127616 Type=NFS  FSdata=yktup01:d:\world
  680. C: TRIGGER_C 33392640 83687424 HPFS
  681. J: NFS 157744128 262127616 NFS yktup01:d:\world
  682.  
  683.  
  684. ΓòÉΓòÉΓòÉ 9.15. RxDriveMap ΓòÉΓòÉΓòÉ
  685.  
  686. Function: RxDriveMap 
  687.  
  688. Syntax:   map = RxDriveMap([drive], [opt]) 
  689.  
  690.    map       A string containing all accessible drives. 
  691.  
  692.    drive     Drive letter with which to start the drive map. The default is 
  693.              'C'. 
  694.  
  695.    opt       The drivemap report option.  May be any one of the following: 
  696.  
  697.       'USED'    Report drives which are accessible or in use.  This is the 
  698.                 default. This includes all local and remote drives. 
  699.  
  700.       'FREE'    Report drives which are free or not in use. 
  701.  
  702.       'LOCAL'   Reports only those drives which are local drives. 
  703.  
  704.       'REMOTE'  Reports only those drives which are remote drives; such as 
  705.                 redirected LAN resources, IFS attached drives, etc. 
  706.  
  707.       'DETACHED' Report drives which are detached LAN resources. 
  708.  
  709.    Purpose:  Reports all accessible drives in the form 'C: D: E:...' 
  710.  
  711. Example:
  712.  
  713.  /* Code */
  714.  say 'Used drives include:'
  715.  say RxDriveMap('C:', 'USED')
  716.  
  717.  /* Output */
  718.  Used drives include:
  719.  C: D: E: F: W:
  720.  
  721.  
  722. ΓòÉΓòÉΓòÉ 9.16. RxDropFuncs ΓòÉΓòÉΓòÉ
  723.  
  724. Function: RxDropFuncs 
  725.  
  726. Syntax:   call RxDropFuncs 
  727.  
  728. Purpose:  Use this function to drop all the loaded RxUtils functions.  Once 
  729.           this function is executed by a REXX exec, the RxUtils functions will 
  730.           not be accessible in any OS/2 sessions. 
  731.  
  732.  
  733. ΓòÉΓòÉΓòÉ 9.17. RxFileExist ΓòÉΓòÉΓòÉ
  734.  
  735. Function: RxFileExist 
  736.  
  737. Syntax:   RxFileExist(filename) 
  738.  
  739.    filename  Name of a file of interest. 
  740.  
  741. Purpose:  Tells whether or not the specified file exists. 
  742.  
  743. RC:       Return Codes 
  744.  
  745.    0         File does not exist. 
  746.  
  747.    1         File exists. 
  748.  
  749.  
  750. ΓòÉΓòÉΓòÉ 9.18. RxGetKey ΓòÉΓòÉΓòÉ
  751.  
  752. Function: RxGetKey 
  753.  
  754. Syntax:   key = RxGetKey([opt], [seconds]) 
  755.  
  756.    key       The key which was pressed. 
  757.  
  758.    opt        Any one of the following: 
  759.  
  760.       'ECHO'    Echo the typed character  (Default) 
  761.  
  762.       'NOECHO'  Do not echo the typed character 
  763.  
  764.    seconds   Number of seconds to wait for keystroke before aborting.  If no 
  765.              keystroke is received before this timeout or if the user presses 
  766.              CTRL-BREAK then a null string is returned. 
  767.  
  768.              Note:  Actual number of seconds before timeout will be a fraction 
  769.              of a second less than the specified timeout.  If you need more 
  770.              accuracy then you probably shouldn't be using REXX. 
  771.  
  772. Purpose:  Gets the next key from the keyboard buffer, or waits for one if none 
  773.           exist.  Works similiar to the C function getch(). 
  774.  
  775.  
  776. ΓòÉΓòÉΓòÉ 9.19. RxGetMessage ΓòÉΓòÉΓòÉ
  777.  
  778. Function: RxGetMessage 
  779.  
  780. Syntax:   msg = RxGetMessage(num, [file] [str1],...[str9]) 
  781.  
  782.    msg       The message associated with the number given. 
  783.  
  784.    num       The message number. 
  785.  
  786.    file      The message file to be searched.  The default message file is 
  787.              OSO001.MSG. Message files will be searched for in the system root 
  788.              directory (ie C:\), the current directory, and along the DPATH. 
  789.  
  790.    str1,...str9 Insertion text variables.  If the message contains insertion 
  791.              fields designated by %x, in the range %1 to %9, then the optional 
  792.              parameters str1 through str9 may be used to designate the 
  793.              replacement strings. 
  794.  
  795. Purpose:  This function can be used to query a message from a specified message 
  796.           file given a message number.  Optionally, insertion text strings may 
  797.           be specified that will be inserted into the returned message wherever 
  798.           appropriate.  Please see documentation in the OS/2 Programmer's 
  799.           Toolkit regarding the MKMSGF utility if needed for further 
  800.           information on message files, their use, and their creation. 
  801.  
  802. /*** Sample code segment using RxGetMessage and insertion text vars ***/
  803. msg =  RxGetMessage(34, , 'A:', 'the diskette labeled "Disk 2"', 'SER0002')
  804. say msg
  805.  
  806. /** Output **/
  807. The wrong diskette is in the drive.
  808. Insert the diskette labeled "Disk 2" (Volume Serial Number: SER0002)
  809. into drive A:.
  810.  
  811.  
  812. ΓòÉΓòÉΓòÉ 9.20. RxGrep ΓòÉΓòÉΓòÉ
  813.  
  814. Function: RxGrep 
  815.  
  816. Syntax:   call RxGrep target, file, stem, [options], [scol], [ecol] 
  817.  
  818.    target    The string to search for. 
  819.  
  820.    file      The file to search. 
  821.  
  822.    stem      The name of the stem variable to place the results. 
  823.  
  824.              Note:  stem.0 contains the number of lines found. 
  825.  
  826.    options   Any logical combination of the following: 
  827.  
  828.       C         Case sensitive search. 
  829.  
  830.       N         Give line numbers when reporting hits. 
  831.  
  832.       I         Find all lines which do not contain the target string. 
  833.  
  834.                 Note:  Default is to find lines containing the target string in 
  835.                 a case insensitive manner without reporting line numbers. 
  836.  
  837.    scol      The starting column of the search.  The default is 1, which 
  838.              indicates the first character of each line. 
  839.  
  840.    ecol      The ending column of the search.  The default is the last 
  841.              character of each line. 
  842.  
  843. Purpose:  Finds all lines in specified file which contain a specified target 
  844.           string, and places said lines in a stem variable. 
  845.  
  846. RC:       Return Codes 
  847.  
  848.    0         Successful. 
  849.  
  850.    2         Error.  Not enough memory. 
  851.  
  852.    3         Error.  Error opening file. 
  853.  
  854. Example:  call RxGrep 'DEVICE', 'c:\config.sys', 'file', 'CN' 
  855.  
  856. Examples:
  857.  
  858.  /* Find DEVICE statements in CONFIG.SYS */
  859.  call RxGrep 'DEVICE', 'C:\CONFIG.SYS', 'file.'
  860.  do i=1 to file.0
  861.   say file.i
  862.  end
  863.  
  864.  /* Output */
  865.  DEVICE=C:\OS2\DOS.SYS
  866.  DEVICE=C:\OS2\PMDD.SYS
  867.  DEVICE=C:\OS2\COM02.SYS
  868.  SET VIDEO_DEVICES=VIO_IBM8514A
  869.  SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)
  870.  DEVICE=C:\OS2\POINTDD.SYS
  871.  DEVICE=C:\OS2\MSPS202.SYS
  872.  DEVICE=C:\OS2\MOUSE.SYS TYPE=MSPS2$
  873.  
  874.  /* Find DEVICE statements in CONFIG.SYS (along with line nums) */
  875.  call RxGrep 'DEVICE', 'C:\CONFIG.SYS', 'file.', 'N'
  876.  do i=1 to file.0
  877.   say file.i
  878.  end
  879.  
  880.  /* Output */
  881.  20 DEVICE=C:\OS2\DOS.SYS
  882.  21 DEVICE=C:\OS2\PMDD.SYS
  883.  22 DEVICE=C:\OS2\COM02.SYS
  884.  33 SET VIDEO_DEVICES=VIO_IBM8514A
  885.  34 SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)
  886.  40 DEVICE=C:\OS2\POINTDD.SYS
  887.  41 DEVICE=C:\OS2\MSPS202.SYS
  888.  42 DEVICE=C:\OS2\MOUSE.SYS TYPE=MSPS2$
  889.  
  890.  
  891. ΓòÉΓòÉΓòÉ 9.21. RxInsMessage ΓòÉΓòÉΓòÉ
  892.  
  893. Function: RxInsMessage 
  894.  
  895. Syntax:   result = RxInsMessage(string, [str1],...[str9]) 
  896.  
  897.    result    The new string created from supplied string with text variables 
  898.              inserted in place of %1, %2, etc. 
  899.  
  900.    string    The template string which should contain a various number of 
  901.              insertion text variable designators (%1, %2, etc). 
  902.  
  903.    str1,...str9 Insertion text variables.  If the string parameter contains 
  904.              insertion fields designated by %x, in the range %1 to %9, then the 
  905.              optional parameters str1 through str9 should be used to designate 
  906.              the replacement strings. 
  907.  
  908. Purpose:  Use this function to create a text string given specified insertion 
  909.           strings and a template string. 
  910.  
  911. /* Sample Code */
  912.  
  913. /* Setup label stem elements and drive letter variable */
  914. label.0=3
  915. label.1='Install'
  916. label.2='Disk 1'
  917. label.3='Disk 2'
  918. drive = 'A:'
  919.  
  920. do i=1 to label.0
  921.   say RxInsMessage('Please insert the diskette labeled "%1" into the %2 drive...',,
  922.     label.i, drive)
  923. end
  924.  
  925. /** Output **/
  926. Please insert the diskette labeled "Install" into the A: drive...
  927. Please insert the diskette labeled "Disk 1" into the A: drive...
  928. Please insert the diskette labeled "Disk 2" into the A: drive...
  929.  
  930.  
  931. ΓòÉΓòÉΓòÉ 9.22. RxListFuncs ΓòÉΓòÉΓòÉ
  932.  
  933. Function: RxListFuncs 
  934.  
  935. Syntax:   call RxListFuncs list 
  936.  
  937.    list      A list of all RxUtils functions, seperated by spaces. 
  938.  
  939. Purpose:  Use this function to get a list of all functions. 
  940.  
  941. /*** Sample code segment which adds all functions via RxFuncAdd ***/
  942.  
  943. call RxFuncAdd 'RxListFuncs', 'RXUTILS', 'RXLISTFUNCS'
  944.  
  945. call RxListFuncs 'list'
  946. do until list=''
  947.   parse var list func list
  948.   say 'Adding 'func'...'
  949.   call RxFuncAdd func, 'RXUTILS', translate(func)
  950. end
  951.  
  952.  
  953. ΓòÉΓòÉΓòÉ 9.23. RxLoadFuncs ΓòÉΓòÉΓòÉ
  954.  
  955. Function: RxLoadFuncs 
  956.  
  957. Syntax:   ver = RxLoadFuncs(['QUIET']) 
  958.  
  959.    ver       The version of the RxUtils functions that were loaded. 
  960.  
  961. Purpose:  Use this function to load all RxUtils functions so that each function 
  962.           will be accessible.  To suppress the copyright notice, call 
  963.           RxLoadFuncs with the 'QUIET' parameter 
  964.  
  965. /*** Sample which adds all functions via RxLoadFuncs ***/
  966. say 'Loading RxUtils functions...'
  967. call RxFuncAdd 'RxLoadFuncs', 'RXUTILS', 'RXLOADFUNCS'
  968. ver = RxLoadFuncs()
  969. say 'RxUtils version 'ver' loaded.'
  970.  
  971.  
  972. ΓòÉΓòÉΓòÉ 9.24. RxMkDir ΓòÉΓòÉΓòÉ
  973.  
  974. Function: RxMkDir 
  975.  
  976. Syntax:   rc = RxMkDir(dirspec) 
  977.  
  978.    dirspec   The directory which should be created. 
  979.  
  980. Purpose:  Creates a specified directory quickly.  In case of failure, one of 
  981.           many return codes are given so that the exact reason for failure may 
  982.           be determined. 
  983.  
  984. RC:       Return Codes 
  985.  
  986.    0         Directory creation was successful. 
  987.  
  988.    2         Error.  File not found. 
  989.  
  990.    3         Error.  Path not found. 
  991.  
  992.    5         Error.  Access denied. 
  993.  
  994.    26        Error.  Not a DOS disk. 
  995.  
  996.    87        Error.  Invalid parameter. 
  997.  
  998.    108       Error.  Drive locked. 
  999.  
  1000.    206       Error.  Filename exceeds range. 
  1001.  
  1002. Example:  call RxMkDir 'c:\rexx' 
  1003.  
  1004.  
  1005. ΓòÉΓòÉΓòÉ 9.25. RxOS2Ini ΓòÉΓòÉΓòÉ
  1006.  
  1007. Function: RxOS2Ini 
  1008.  
  1009.    Syntax - Mode 1: Setting single key value. 
  1010.  
  1011.              result = RxOS2Ini([inifile], app, key, val) 
  1012.  
  1013.    Syntax - Mode 2: Querying single key value. 
  1014.  
  1015.              result = RxOS2Ini([inifile], app, key) 
  1016.  
  1017.    Syntax - Mode 3: Deleting a single key. 
  1018.  
  1019.              result = RxOS2Ini([inifile], app, key, '$RXDEL') 
  1020.  
  1021.    Syntax - Mode 4: Deleting an app and all associated keys. 
  1022.  
  1023.              result = RxOS2Ini([inifile], app, ['$RXDEL']) 
  1024.  
  1025.              Note:  Due to previous version syntax, the '$RXDEL' parameter is 
  1026.              optional. 
  1027.  
  1028.    Syntax - Mode 5: Querying names of all keys associated with a certain app. 
  1029.  
  1030.              result = RxOS2Ini([inifile], app, '$RXALL', 'stem') 
  1031.  
  1032.    Syntax - Mode 6: Querying names of all apps. 
  1033.  
  1034.              result = RxOS2Ini([inifile], '$RXALL', 'stem') 
  1035.  
  1036.    result    For successful 'setting' invocations, result will equal ''. For 
  1037.              successful 'querying' invocations, result will be given the value 
  1038.              of the specified application keyword.  For successful 'deleting' 
  1039.              invocations, result will equal ''. 
  1040.  
  1041.              The following error strings may be returned if an error occurs: 
  1042.  
  1043.       o '$RXERROR' 
  1044.  
  1045.         Returned if error occurs in setting, querying, or deleting then result 
  1046.         will equal '$RXERROR'. 
  1047.  
  1048.       o '$INI_ERROR' 
  1049.  
  1050.         Returned if error occurs in opening the specified INI file. You may 
  1051.         have specified the current user or system INI file via a 'relative' 
  1052.         filespec.  Make sure to use the full filespec, specifying drive, path, 
  1053.         and file name. 
  1054.  
  1055.    inifile   The name of the INI file which you would like to work with.  This 
  1056.              parameter should be a file specification, or one of the following: 
  1057.  
  1058.       'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the 
  1059.                 default. 
  1060.  
  1061.       'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI). 
  1062.  
  1063.       'BOTH'    For querying invocations, both the user and system INI files 
  1064.                 will be searched. For setting invocations, the user INI file 
  1065.                 will be written to. 
  1066.  
  1067.    app       The application name or some other meaningful value with which you 
  1068.              would like to store keywords (some sort of data). 
  1069.  
  1070.    key       The name of a keyword which is used to hold data. 
  1071.  
  1072.    val       The value to associate with the keyword of the specified 
  1073.              application. 
  1074.  
  1075.    stem      The name of the stem variable to store the resultant information 
  1076.              in.  STEM.0 will be set equal to the number of elements. 
  1077.  
  1078. Purpose:  This functions allows limited editing of INI file variables. 
  1079.           Variables are stored in the INI file under 'Application Names' and 
  1080.           their associated 'Key Names' or keywords.  RxOS2Ini can be used to 
  1081.           share variables between applications or as a way of implementing 
  1082.           GLOBALV under OS/2. 
  1083.  
  1084.           Note:  This function will work on all types if data stored in an INI 
  1085.           file (ie text, numeric, binary), therefore be careful! 
  1086.  
  1087. /* Sample code segments */
  1088.  
  1089.  /***  Save the user entered name under the key 'NAME' of the  *****
  1090.  ****  application 'MYAPP'.                                    ****/
  1091.  pull name .
  1092.  call RxOS2Ini , 'MYAPP', 'NAME', name   /* Save the value        */
  1093.  say  RxOS2Ini(, 'MYAPP', 'NAME')        /* Query the value       */
  1094.  call RxOS2Ini , 'MYAPP'                 /* Delete all MYAPP info */
  1095.  exit
  1096.  
  1097.  /***  Type all OS2INI file information to the screen  *****/
  1098.  call RxOS2INI , '$RXALL', 'Apps'             /* Stem Var=Apps */
  1099.  if Result<>'$RXERROR' then
  1100.   do i=1 to Apps.0
  1101.     call RxOS2INI , Apps.i, '$RXALL', 'Keys'  /* Stem Var=Keys */
  1102.     if Result<>'$RXERROR' then
  1103.      do j=1 to Keys.0
  1104.        val = RxOS2INI( , Apps.i, Keys.j)
  1105.        say left(Apps.i, 20) left(Keys.j, 20),
  1106.              'Len=x'left(d2x(length(val)),4) left(val, 20)
  1107.      end
  1108.   end
  1109.  exit
  1110.  
  1111.  
  1112. ΓòÉΓòÉΓòÉ 9.26. RxOS2Ver ΓòÉΓòÉΓòÉ
  1113.  
  1114. Function: RxOS2Ver 
  1115.  
  1116. Syntax:   ver = RxOS2Ver() 
  1117.  
  1118.    ver       String containing OS/2 version info in the form 'x.xx' 
  1119.  
  1120. Purpose:  Returns the OS/2 version information. 
  1121.  
  1122.  
  1123. ΓòÉΓòÉΓòÉ 9.27. RxPasswordAge ΓòÉΓòÉΓòÉ
  1124.  
  1125. Function: RxPasswordAge 
  1126.  
  1127. Syntax:   age = RxPasswordAge(domain, userid) 
  1128.  
  1129.    age       The age in days of the specified userid's password on the 
  1130.              specified domain or the totals number of days a password is 
  1131.              allowed before it expires (see userid parameter for details). 
  1132.  
  1133.    domain    The domain of interest. 
  1134.  
  1135.              Note:  If the domain is not accessible then 
  1136.              '$RXERROR_NO_SUCH_DOMAIN' will be returned. 
  1137.  
  1138.    userid    The userid of interest OR to determine the expiration period on a 
  1139.              given domain, replace the userid parameter with '$RXEXPIRES'. 
  1140.  
  1141.              Note: 
  1142.  
  1143.              If the userid is not known to the domain then 
  1144.              '$RXERROR_NO_SUCH_USER' will be returned. 
  1145.  
  1146.              If the expiration period is queried on a server which does not 
  1147.              have a set expiration period, '$RXERROR_NO_EXPIRATION' is 
  1148.              returned. 
  1149.  
  1150. Purpose:  Given a domain name, and a userid, this function will return the age 
  1151.           of the users password on said domain in days.  This function may also 
  1152.           be used to determine the expiration period on a given domain. 
  1153.  
  1154. Example:
  1155.  
  1156. /* Code */
  1157.  parse value RxUserInfo() with uid mach domain
  1158.  age = RxPasswordAge(domain, uid)
  1159.  expires = RxPasswordAge(domain, '$RXEXPIRES')
  1160.  say 'Age of 'uid'''s password on 'domain' is 'age' day(s).'
  1161.  if left(expires, 1)='$' then
  1162.    say uid'''s password on 'domain' does not expire.'
  1163.  else
  1164.    say uid'''s password on 'domain' expires in 'expires-age' day(s).'
  1165.  
  1166. /* Output */
  1167.  Age of ROY's password on YKCOD02 is 3 days.
  1168.  ROY's password on YKCOD02 does not expire.
  1169.  
  1170.  
  1171. ΓòÉΓòÉΓòÉ 9.28. RxPause ΓòÉΓòÉΓòÉ
  1172.  
  1173. Function: RxPause 
  1174.  
  1175. Syntax:   call RxPause [prompt] 
  1176.  
  1177.    prompt    The message to give the user.  The default message is 'Press any 
  1178.              key when ready...' 
  1179.  
  1180. Purpose:  Similar to OS/2 PAUSE.  Waits for the user to press a key before 
  1181.           continuing. Also allows for optional prompt. 
  1182.  
  1183.  
  1184. ΓòÉΓòÉΓòÉ 9.29. RxPriority ΓòÉΓòÉΓòÉ
  1185.  
  1186. Function: RxPriority 
  1187.  
  1188.    Syntax - Mode 1: Quering current priority 
  1189.  
  1190.              result = RxPriority() 
  1191.  
  1192.    Syntax - Mode 2: Setting Priority Class and Priority Level 
  1193.  
  1194.              result = RxPriority(PriorityClass [,PriorityDelta]) 
  1195.  
  1196.    result 
  1197.  
  1198.              In the case of the querying of the current priority, result will 
  1199.              be set to a string containing the current Priority Class followed 
  1200.              by a comma, followed by a space, followed by the current Priority 
  1201.              Level. 
  1202.  
  1203.              In the case of setting the priority of the current process, the 
  1204.              result will be an empty string in the case of success, else the 
  1205.              string 'ERROR:n' where n is the return code of the failing 
  1206.              DosSetPrty() function. 
  1207.  
  1208.    PriorityClass 
  1209.  
  1210.              Priority class of a process. The values and descriptions are: 
  1211.  
  1212.                               Value     Definition
  1213.                               0         No change, leave as is
  1214.                               1         Idle-time
  1215.                               2         Regular
  1216.                               3         Time-critical.
  1217.                               4         Fixed-high.
  1218.  
  1219.    PriorityDelta 
  1220.  
  1221.              Delta priority to apply to the process's current base priority 
  1222.              level.  This value must range from -31 to +31. 
  1223.  
  1224. Purpose: 
  1225.  
  1226.           The RxPriority function uses the DosGetPrty() function when querying 
  1227.           the current process priority and the DosSetPrty() when setting the 
  1228.           current process priority.  The following documentation has been 
  1229.           excerpted from the OS/2 Toolkit Documentation and should be used to 
  1230.           better understand the setting of process priorities. 
  1231.  
  1232.           The OS/2 scheduler has a concept of priority classes and levels. 
  1233.           DosSetPrty allows threads to move between classes in response to 
  1234.           changes in their execution environments. Within each class, a 
  1235.           thread's priority level can vary because of a DosSetPrty request or 
  1236.           action taken by the system. System-initiated priority variation is 
  1237.           performed as a combination of a specific thread's actions and the 
  1238.           overall system activity. 
  1239.  
  1240.           A time-critical thread has the highest priority class and executes 
  1241.           before any fixed-high, regular, or idle-time threads. A fixed-high 
  1242.           thread has a priority class that is lower than time-critical but 
  1243.           executes before any regular or idle-time threads. 
  1244.  
  1245.           Time-critical threads have static priorities that are not varied by 
  1246.           OS/2.  Threads are scheduled in priority order, with round-robin 
  1247.           scheduling of threads of equal priority. 
  1248.  
  1249.           For each of the four priority classes, there are 32 distinct priority 
  1250.           levels, 0 to +31. Whenever DosSetPrty is issued with a class 
  1251.           specification, but no value is specified for PriorityDelta, the base 
  1252.           priority level defaults to zero. 
  1253.  
  1254.           The priority level of a process consists of a computed priority value 
  1255.           that is based upon the display status (foreground or background) of 
  1256.           the process, its recent I/O and processor time-usage history, and 
  1257.           other factors. The signed value specified in PriorityDelta is added 
  1258.           to the computed priority to produce the actual priority used by the 
  1259.           scheduler. The result is restricted to the valid range, based upon 
  1260.           the current priority class. 
  1261.  
  1262.           Specifying a higher priority delta allows a thread to obtain better 
  1263.           processor scheduling than it normally would.  A lower priority delta 
  1264.           gives the thread less processor resource than it normally receives. 
  1265.  
  1266.           When used with PriorityClass to change to a different class, the 
  1267.           delta value applies to the base priority. A new base level of 0 is 
  1268.           assigned the target thread and any PriorityDelta specified is 
  1269.           relative to zero. 
  1270.  
  1271. /* Example which queries and sets priority */
  1272.  
  1273.  parse value RxPriority() with pClass', 'pLevel
  1274.  say 'Current process Priority Class='pClass' and Priority Level='pLevel
  1275.  say
  1276.  
  1277.  say 'Incrementing Priority Level by 10...'
  1278.  call RxPriority 0, 10
  1279.  
  1280.  parse value RxPriority() with pClass', 'pLevel
  1281.  say 'Current process Priority Class='pClass' and Priority Level='pLevel
  1282.  say
  1283.  
  1284.  say 'Setting process Priority Class to Fixed-High...'
  1285.  call RxPriority 4, 1
  1286.  
  1287.  parse value RxPriority() with pClass', 'pLevel
  1288.  say 'Current process Priority Class='pClass' and Priority Level='pLevel
  1289.  
  1290. /* Output from above code */
  1291.  
  1292. Current process Priority Class=2 and Priority Level=0
  1293.  
  1294. Incrementing Priority Level by 10...
  1295. Current process Priority Class=2 and Priority Level=10
  1296.  
  1297. Setting process Priority Class to Fixed-High...
  1298. Current process Priority Class=4 and Priority Level=1
  1299.  
  1300.  
  1301. ΓòÉΓòÉΓòÉ 9.30. RxProcessType ΓòÉΓòÉΓòÉ
  1302.  
  1303. Function: RxProcessType 
  1304.  
  1305. Syntax:   type = RxProcessType() 
  1306.  
  1307.    type      The type of the current process.  The type is returned as a 
  1308.              number.  Valid types are: 
  1309.  
  1310.                           Type  Description
  1311.  
  1312.                           0     Full screen protect mode session.
  1313.                           1     Requires real mode.
  1314.                           2     VIO windowable protect mode session.
  1315.                           3     Presentation Manager protect mode session.
  1316.                           4     Detached protect mode process.
  1317.  
  1318. Purpose:  Use this function to determine the type of the session which the 
  1319.           REXXSAA interpreter is executing in.  This is often useful as you 
  1320.           sometimes want your code to perform different tasks if running in a 
  1321.           detached session of under the control of a PM program such as PMREXX. 
  1322.  
  1323. /* Sample Code */
  1324.  
  1325.  /* Get process type */
  1326.  ptype = RxProcessType()
  1327.  
  1328.  /* If not a PM or Detached session then do screen I/O stuff */
  1329.  if ptype<>3 & ptype<>4 then do
  1330.     /* etc, etc */
  1331.  end
  1332.  
  1333.  
  1334. ΓòÉΓòÉΓòÉ 9.31. RxQueryGroup ΓòÉΓòÉΓòÉ
  1335.  
  1336. Function: RxQueryGroup 
  1337.  
  1338. Syntax:   rc = RxQueryGroup([inifile], group, stem) 
  1339.  
  1340.    inifile   The name of the INI file which you would like to work with.  This 
  1341.              parameter should be a file specification, or one of the following: 
  1342.  
  1343.       'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the 
  1344.                 default. 
  1345.  
  1346.       'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI). 
  1347.  
  1348.    group     The group from which program title information is to be queried 
  1349.              (ie 'Main'). 
  1350.  
  1351.              Note:  If group='ROOT_GROUP' then the titles of all the groups of 
  1352.              the Start Programs/Desktop Manager will be returned. 
  1353.  
  1354.    stem      The name of the stem variable in which the program titles for the 
  1355.              specified group will be stored.  Stem.0 will be set to the number 
  1356.              of titles, stem.1 will contain the title of the first program, 
  1357.              etc. 
  1358.  
  1359.              Note:  stem.0 contains the number of lines read. 
  1360.  
  1361. Purpose:  Get all the program titles contained in a given Group in the Start 
  1362.           Propgrams/Desktop Manager. 
  1363.  
  1364. RC:       Return Codes 
  1365.  
  1366.    0         Query was successful. 
  1367.  
  1368.    2         Error.  Not enough memory. 
  1369.  
  1370.    4         Error.  Group specified does not exist. 
  1371.  
  1372.    9         Invalid INI file entry.  You may have specified the current user 
  1373.              or system INI file via a 'relative' filespec.  Make sure to use 
  1374.              the full filespec, specifying drive, path, and file name. 
  1375.  
  1376. /* Sample Code Segment */
  1377. call RxQueryGroup , 'Main', 'MainProgram'
  1378. do i=1 to MainProgram.0
  1379.  say MainProgram.i
  1380. end
  1381.  
  1382. /* OutPut */
  1383. OS/2 Window
  1384. OS/2 Full Screen
  1385. OS/2 Programming Reference
  1386. OS/2 System Editor
  1387. OS/2 Command Reference
  1388. OS/2 LAN Command Reference
  1389. File Manager
  1390. Print Manager
  1391. LAN Requester
  1392. LAN Messaging
  1393. Communications Manager
  1394.  
  1395.  
  1396. ΓòÉΓòÉΓòÉ 9.32. RxQueryProgram ΓòÉΓòÉΓòÉ
  1397.  
  1398. Function: RxQueryProgram 
  1399.  
  1400. Syntax:   rc = RxQueryProgram([inifile], group, program, stem) 
  1401.  
  1402.    inifile   The name of the INI file which you would like to work with.  This 
  1403.              parameter should be a file specification, or one of the following: 
  1404.  
  1405.       'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the 
  1406.                 default. 
  1407.  
  1408.       'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI). 
  1409.  
  1410.    group     The title of the group in which the program resides (ie 'Main'). 
  1411.  
  1412.    program   The title of the program of interest. 
  1413.  
  1414.    stem      A stem variable in which the program information will be returned. 
  1415.              The value of stem.0 is 9, and stem.1 through stem.9 are the 
  1416.              following: 
  1417.  
  1418.       'TITLE=...' The title of the program. 
  1419.  
  1420.       'TYPE=...' The program type, any one of the following: 
  1421.  
  1422.          'DEFAULT' The system decides how to run the program. 
  1423.  
  1424.          'FULLSCREEN' The program will be run in a Full Screen OS/2 Window. 
  1425.  
  1426.          'VIOWINDOW' The program will be run in a VIO OS/2 Window. 
  1427.  
  1428.          'PM'      The program is a PM application and will be started from the 
  1429.                    PM shell. 
  1430.  
  1431.          'REAL'    'The program is a DOS application and will be run from the 
  1432.                    DOS box. 
  1433.  
  1434.                    Note:  Supported by OS/2 1.2+ only. 
  1435.  
  1436.       'VISIBILITY=...' Either one of the following: 
  1437.  
  1438.          'VISIBLE' The program entry is displayed in the Desktop Manager group. 
  1439.  
  1440.          'INVISIBLE' The program entry is displayed in the Desktop Manager 
  1441.                    group. 
  1442.  
  1443.       'EXE=...' The complete path and filename of the program. 
  1444.  
  1445.       'PARAMS=...' The parameters to be used when running the program. 
  1446.  
  1447.       'WORKDIR=...' The working directory of the program. 
  1448.  
  1449.       'ICONFILE=...' The full path and filename of the icon associated with the 
  1450.                 program. 
  1451.  
  1452.       'XYSIZE=x, y, cx, cy' The position and size of the running program.  The 
  1453.                 values of x and y denote the position of the lower left of the 
  1454.                 program's presentation space.  While the values of cx and cy 
  1455.                 denote the width and height of the presentation space, 
  1456.                 respectively.  If all values are 0 (the default) the system 
  1457.                 decides the best values for the application. 
  1458.  
  1459.       'XYSTYLE=...' Any logical combination of the following: 
  1460.  
  1461.          NORMAL    Session is normal and has none of the styles or attributes 
  1462.                    listed below. 
  1463.  
  1464.          NOAUTOCLOSE Upon termination of the running program, the session will 
  1465.                    close automatocally. For VIOWINDOW sessions, the session is 
  1466.                    terminated by selecting the System Menu Close menu item (or 
  1467.                    by pressing ALT-F4 or by double clicking on the System 
  1468.                    Menu). 
  1469.  
  1470.          MINIMIZED The session starts in the minimized state. 
  1471.  
  1472.          MAXIMIZED The session starts in the maximized state. 
  1473.  
  1474.          INVISIBLE The session is not seen while executing (but does show up in 
  1475.                    the Task List). 
  1476.  
  1477.                 Note: 
  1478.  
  1479.                 Multiple XYSTYLE attributes can be returned in one stem entry. 
  1480.  
  1481.                 For example: 
  1482.  
  1483.                                 'XYSTYLE=NOAUTOCLOSE, MINIMIZED'
  1484.  
  1485.    Purpose:  This function returns inforamtion about a program entry in a 
  1486.              certain group in the Start Programs/Desktop Manager window. 
  1487.  
  1488.    RC        Return Codes 
  1489.  
  1490.       0         Program information query was successful. 
  1491.  
  1492.       2         Error.  Not enough memory. 
  1493.  
  1494.       4         Error.  Program specified does not exist. 
  1495.  
  1496.       9         Invalid INI file entry.  You may have specified the current 
  1497.                 user or system INI file via a 'relative' filespec.  Make sure 
  1498.                 to use the full filespec, specifying drive, path, and file 
  1499.                 name. 
  1500.  
  1501.  
  1502. ΓòÉΓòÉΓòÉ 9.33. RxRead ΓòÉΓòÉΓòÉ
  1503.  
  1504. Function: RxRead 
  1505.  
  1506. Syntax:   rc = RxRead(filename, stem) 
  1507.  
  1508.    filename  The name of the file to read. 
  1509.  
  1510.    stem      The name of the stem to place the file in. 
  1511.  
  1512.              Note:  stem.0 contains the number of lines read. 
  1513.  
  1514. Purpose:  Reads a specified file into a stem variable. 
  1515.  
  1516. RC:       Return Codes 
  1517.  
  1518.    0         File read was successful. 
  1519.  
  1520.    2         Error.  Not enough memory. 
  1521.  
  1522.    3         Error.  Error opening file. 
  1523.  
  1524.    4         Error.  Error reading file. 
  1525.  
  1526. Example:  call RxRead 'c:\config.sys', 'file' 
  1527.  
  1528.  
  1529. ΓòÉΓòÉΓòÉ 9.34. RxReadScreen ΓòÉΓòÉΓòÉ
  1530.  
  1531. Function: RxReadScreen 
  1532.  
  1533. Syntax:   string = RxReadScreen(row, col, [len]) 
  1534.  
  1535.    row       The row from which to start reading. 
  1536.  
  1537.    col       The col from which to start reading. 
  1538.  
  1539.    len       The number of characters to read.  The default is read up to the 
  1540.              end of the screen. 
  1541.  
  1542.    string    The characters read from the screen.  This includes CR and LF 
  1543.              characters which comprise the end of lines should the number of 
  1544.              character read span multiple lines. 
  1545.  
  1546. Purpose:  Reads a specified number of characters from a specified location of 
  1547.           the screen. 
  1548.  
  1549. Limitations  This function only reads in characters and does not consider the 
  1550. color attributes of each character read.  When restoring the character string 
  1551. to the screen via say or RxSay the previous color settings will be lost. 
  1552.  
  1553. /* Example which reads in the entire screen */
  1554.  screen = RxReadScreen( 0, 0 )
  1555.  
  1556. /* Example which reads in one line */
  1557.  line = RxReadScreen( 2, 0, 80 )
  1558.  
  1559.  
  1560. ΓòÉΓòÉΓòÉ 9.35. RxRmDir ΓòÉΓòÉΓòÉ
  1561.  
  1562. Function: RxRmDir 
  1563.  
  1564. Syntax:   rc = RxRmDir(dirspec) 
  1565.  
  1566.    dirspec   The directory which should be deleted. 
  1567.  
  1568. Purpose:  Deletes a specified directory quickly.  In case of failure, one of 
  1569.           many return codes are given so that the exact reason for failure may 
  1570.           be determined. 
  1571.  
  1572. RC:       Return Codes 
  1573.  
  1574.    0         Directory removal was successful. 
  1575.  
  1576.    2         Error.  File not found. 
  1577.  
  1578.    3         Error.  Path not found. 
  1579.  
  1580.    5         Error.  Access denied. 
  1581.  
  1582.    16        Error.  Current directory. 
  1583.  
  1584.    26        Error.  Not a DOS disk. 
  1585.  
  1586.    87        Error.  Invalid parameter. 
  1587.  
  1588.    108       Error.  Drive locked. 
  1589.  
  1590.    206       Error.  Filename exceeds range. 
  1591.  
  1592. Example:  call RxRmDir 'c:\rexx' 
  1593.  
  1594.  
  1595. ΓòÉΓòÉΓòÉ 9.36. RxRun ΓòÉΓòÉΓòÉ
  1596.  
  1597. Function: RxRun 
  1598.  
  1599. Syntax:   rc = RxRun(command, [stem, tempfile]) 
  1600.  
  1601.    rc        The return code of the executed command. 
  1602.  
  1603.    command   The OS/2 command to be run along with any needed arguments. 
  1604.  
  1605.    stem      The name of the stem variable in which to place the output of the 
  1606.              executed command.  If a stem name is specified, a temporary output 
  1607.              file must also be specified. 
  1608.  
  1609.    tempfile  The file name to be used to temporarily store the output of the 
  1610.              command. This file must be able to be created by the running 
  1611.              process and should be on a disk with adequate free space.  The 
  1612.              file will be deleted once processed. The standard error and 
  1613.              standard output data streams will be redirected to this file, so 
  1614.              make sure not to redirect either of these in your command.  Only 
  1615.              non-interactive commands should be redirected. 
  1616.  
  1617. Purpose:  Executes a specified OS/2 command and retains the return code.  The 
  1618.           output of the command may be placed in a specified stem variable if 
  1619.           needed. 
  1620.  
  1621. RC:       The return code of the executed command. 
  1622.  
  1623. /* Sample Code */
  1624. BD = RxBootDrive()
  1625. call RxRun 'dir 'BD'\*.*', 'stem.', BD'\temp.fil'
  1626. do i=1 to stem.0
  1627.   say stem.i
  1628. end
  1629.  
  1630.  
  1631. ΓòÉΓòÉΓòÉ 9.37. RxSay ΓòÉΓòÉΓòÉ
  1632.  
  1633. Function: RxSay 
  1634.  
  1635. Syntax    call RxSay string 
  1636.  
  1637.    string    Anything you want to be printed to the screen. 
  1638.  
  1639. Purpose:  RxSay works like the REXX 'say' command but does not produce a 
  1640.           newline. Great for prompts. 
  1641.  
  1642.  
  1643. ΓòÉΓòÉΓòÉ 9.38. RxScreenSize ΓòÉΓòÉΓòÉ
  1644.  
  1645. Function: RxScreenSize 
  1646.  
  1647. Syntax    result = RxScreenSize() 
  1648.  
  1649.    result    The size of the screen.  The format of the result string is 'row, 
  1650.              col'. 
  1651.  
  1652. Purpose:  This function returns the size of the screen. 
  1653.  
  1654. /* Example */
  1655. parse value RxScreenSize() with row', 'col
  1656. say 'Rows='row', Columns='col
  1657.  
  1658.  
  1659. ΓòÉΓòÉΓòÉ 9.39. RxSearchPath ΓòÉΓòÉΓòÉ
  1660.  
  1661. Function: RxSearchPath 
  1662.  
  1663. Syntax:   filespec = RxSearchPath(path, filename) 
  1664.  
  1665.    filespec  The complete filespec of the file found, or '' if the filename was 
  1666.              not located along the path. 
  1667.  
  1668.    path      Any environment variable that resembles a path, or 'LIBPATH'. 
  1669.  
  1670.    filename  The file to search the path for. 
  1671.  
  1672. Purpose:  Searches the specified path for the specified file and returns the 
  1673.           full filespec of the file if found, else returns ''. 
  1674.  
  1675. Example:
  1676.  
  1677.  /* Code */
  1678.  fspec = RxSearchPath('PATH', 'CMD.EXE')
  1679.  say fspec
  1680.  
  1681.  /* Output */
  1682.  C:\OS2\CMD.EXE
  1683.  
  1684.  
  1685. ΓòÉΓòÉΓòÉ 9.40. RxSem ΓòÉΓòÉΓòÉ
  1686.  
  1687. Function: RxSem 
  1688.  
  1689. Syntax:   rc = RxSem(semname, action, [msecs]) 
  1690.  
  1691.    semname   The semaphore name to be worked with.  Semaphore names must start 
  1692.              with '\SEM\'. If the semaphore name does not start with '\SEM\' 
  1693.              and is a valid numerical value then it will be assumed that it is 
  1694.              a semaphore handle.  Only valid semphore handles returned by the 
  1695.              CREATE2 action should be used. 
  1696.  
  1697.    action    Any one of the following: 
  1698.  
  1699.       'CLOSE'   Close a semaphore previously created by CREATE2..  The semname 
  1700.                 parameter specified must be a valid semaphore handle. 
  1701.  
  1702.       'CREATE'  Create the semaphore if it does not already exist. 
  1703.  
  1704.       'CREATE2' Just like CREATE, but instead of returning a regular return 
  1705.                 code, the handle of the semaphore which was created will be 
  1706.                 returned.  This handle looks like a numeric string.  The handle 
  1707.                 returned may be used in place of the semname parameter in all 
  1708.                 actions except for CREATE and CREATE2. 
  1709.  
  1710.       'SET'     Set the semaphore if it can be set. 
  1711.  
  1712.       'CLEAR'   Clear the semaphore if it can be cleared. 
  1713.  
  1714.       'WAIT'    Wait until the specified semaphore is cleared. When using WAIT, 
  1715.                 the third argument (msecs) specifies the timeout factor. 
  1716.  
  1717.    msecs     Any of the following: 
  1718.  
  1719.       -1        Wait indefinitely. 
  1720.  
  1721.       0         Do not wait, timeout immediately (default). 
  1722.  
  1723.       >0        Wait specified time then timeout. 
  1724.  
  1725.              Limitations  So that semaphores could be closed, the CREATE2 and 
  1726.              CLOSE actions were added to RxSem.  These actions added to RxSem 
  1727.              the concept of a semaphore handle.  A semaphore handle is really 
  1728.              just a numerical value which is a FAR Pointer to a memory 
  1729.              location.  Keep this in mind!  If you call RxSem with an invalid 
  1730.              semaphore handle, a TRAP-D or Protection Violation is sure to 
  1731.              result. 
  1732.  
  1733. Purpose:  RxSem provides an interface to using OS/2 system semaphores. 
  1734.           Semaphores provide a convenient vehicle in which separate processes 
  1735.           may determine the states of one another. 
  1736.  
  1737. RC:       Return Codes 
  1738.  
  1739.    0         Successful. 
  1740.  
  1741.    6         Error.  Invalid semaphore handle. 
  1742.  
  1743.    95        Error.  Wait interrupted. 
  1744.  
  1745.    100       Error.  Create failed.  Too many semaphores. 
  1746.  
  1747.    101       Error.  Exclusive semaphore already owned. 
  1748.  
  1749.    102       Error.  Cannot close set semaphore. 
  1750.  
  1751.    121       Error.  Wait timed out. 
  1752.  
  1753.    123       Error.  Invalid semaphore name. 
  1754.  
  1755.    183       Error.  Semaphore already exists. 
  1756.  
  1757.    187       Error.  Semaphore name not found. 
  1758.  
  1759. /** Example **/
  1760.  
  1761. semHandle = RxSem('\SEM\MYAPP', 'CREATE2')
  1762.  
  1763. call RxSem semHandle, 'SET'
  1764.   /* Start of critical code segment */
  1765.        /* blah, blah, blah */
  1766.   /* End of critical code segment */
  1767. call RxSem semHandle, 'CLEAR'
  1768.  
  1769. call RxSem semHandle, 'CLOSE'
  1770.  
  1771.  
  1772. ΓòÉΓòÉΓòÉ 9.41. RxSleep ΓòÉΓòÉΓòÉ
  1773.  
  1774. Function: RxSleep 
  1775.  
  1776. Syntax:   call RxSleep secs 
  1777.  
  1778.    secs      The number of seconds to sleep. 
  1779.  
  1780. Purpose:  Sleep a specified number of seconds. 
  1781.  
  1782.  
  1783. ΓòÉΓòÉΓòÉ 9.42. RxStemDelete ΓòÉΓòÉΓòÉ
  1784.  
  1785. Function: RxStemDelete 
  1786.  
  1787. Syntax:   rc = RxStemDelete(stem, num) 
  1788.  
  1789.    stem      The name of the stem to work with. 
  1790.  
  1791.    num       The stem element to delete. 
  1792.  
  1793.              Note:  If the stem name is 'FILE' and the value of num is '5' then 
  1794.              'FILE.5' will be deleted. 
  1795.  
  1796. Purpose:  Delete or remove a stem element then compact the stem. 
  1797.  
  1798.  
  1799. ΓòÉΓòÉΓòÉ 9.43. RxStemGrep ΓòÉΓòÉΓòÉ
  1800.  
  1801. Function: RxStemGrep 
  1802.  
  1803. Syntax:   call RxStemGrep target, source, hits, [options], [scol], [ecol] 
  1804.  
  1805.    target    The string to search for. 
  1806.  
  1807.    source    The name of the source stem variable to search. 
  1808.  
  1809.    hits      The name of the stem variable to place the results. 
  1810.  
  1811.              Note:  hits.0 contains the number of lines found. 
  1812.  
  1813.    options   Any logical combination of the following: 
  1814.  
  1815.       C         Case sensitive search. 
  1816.  
  1817.       N         Give element numbers when reporting hits. 
  1818.  
  1819.       I         Find all elements which do not contain the target string. 
  1820.  
  1821.                 Note:  Default is to find elements containing the target string 
  1822.                 in a case insensitive manner without reporting element numbers. 
  1823.  
  1824.    scol      The starting column of the search.  The default is 1, which 
  1825.              indicates the first character of each line. 
  1826.  
  1827.    ecol      The ending column of the search.  The default is the last 
  1828.              character of each line. 
  1829.  
  1830. Purpose:  Finds all elements in a specified stem which contain a specified 
  1831.           target string, and places said elements in a specified stem variable. 
  1832.  
  1833. RC:       Return Codes 
  1834.  
  1835.    0         Successful. 
  1836.  
  1837.    2         Error.  Not enough memory. 
  1838.  
  1839. /** Example **/
  1840. call RxRead 'c:\config.sys', 'file'
  1841. call RxStemGrep 'DEVICE', 'file', 'grep', 'CN'
  1842.  
  1843.  
  1844. ΓòÉΓòÉΓòÉ 9.44. RxStemInsert ΓòÉΓòÉΓòÉ
  1845.  
  1846. Function: RxStemInsert 
  1847.  
  1848. Syntax:   call RxStemInsert stem, num, val 
  1849.  
  1850.    stem      The name of the stem to work with. 
  1851.  
  1852.    num       The stem element which will be inserted. 
  1853.  
  1854.              Note:  If the stem name is 'FILE' and the value of num is '5', 
  1855.              then val will be inserted as 'FILE.5'.  All values from the 
  1856.              original 'FILE.5' to the last element will be moved up one. 
  1857.  
  1858. Purpose:  Inserts or adds a stem element then expands the stem. 
  1859.  
  1860. RC:       Return Codes 
  1861.  
  1862.    0         Successful. 
  1863.  
  1864.    2         Error.  Not enough memory. 
  1865.  
  1866.  
  1867. ΓòÉΓòÉΓòÉ 9.45. RxStemSort ΓòÉΓòÉΓòÉ
  1868.  
  1869. Function: RxStemSort 
  1870.  
  1871. Syntax:   call RxStemSort stem, [opt], [scol], [ecol] 
  1872.  
  1873.    stem      The name of the stem to sort.  Due to the fact that RXUTILS is 
  1874.              currently a 16-bit DLL, and therefore restricted to a segmented 
  1875.              memory architecture, the stem to be sorted must be limited to a 
  1876.              maximum of 16383 elements. 
  1877.  
  1878.    opt       The sorting option.  May be either of the following: 
  1879.  
  1880.       'A'       Ascending sort (default). 
  1881.  
  1882.       'D'       Descending sort. 
  1883.  
  1884.    scol      The starting column of the sort.  The default is 1, which 
  1885.              indicates the first character of each stem element. 
  1886.  
  1887.    ecol      The ending column of the sort.  The default is the last character 
  1888.              of each stem element. 
  1889.  
  1890.              Note:  RxStemSort uses the Quicksort algorithm.  Due to the nature 
  1891.              of this alogrithm, any previous order in a given stem is lost. 
  1892.              Therefore, always make sure that the scol and ecol parameters 
  1893.              create substrings for each stem element.  If this is not the case, 
  1894.              spurious results may occur. 
  1895.  
  1896. Purpose:  Sorts a stem quickly via the Quicksort algorithm. 
  1897.  
  1898. RC:       Return Codes 
  1899.  
  1900.    0         Successful. 
  1901.  
  1902.    2         Error.  Not enough memory.  Either out of memory and swap space or 
  1903.              a stem with more than 16383 elements was specified. 
  1904.  
  1905.  
  1906. ΓòÉΓòÉΓòÉ 9.46. RxSysLevel ΓòÉΓòÉΓòÉ
  1907.  
  1908. Function: RxSysLevel 
  1909.  
  1910. Syntax:   result = RxSysLevel([file] [,option]) 
  1911.  
  1912.    result    The result of the SYSLEVEL query. 
  1913.  
  1914.    file      A full qualified SYSLEVEL.xxx file to be processed.  Information 
  1915.              regarding the name of the component that the file corresponds to, 
  1916.              as well are current and previous Corrective Service levels are 
  1917.              contained in the file. 
  1918.  
  1919.              If no file is specified, then the default file to be processed is 
  1920.              the \OS2\INSTALL\SYSLEVEL.OS2 file found on the drive from which 
  1921.              the system was booted. 
  1922.  
  1923.    option    If no option parameter is specified all information contained in 
  1924.              the SYSLEVEL file will be returned as the result.  See the example 
  1925.              below for the format of the result when all information is 
  1926.              queried. 
  1927.  
  1928.              You may also query the information one field at a time by 
  1929.              providing a valid option.  Valid options include: 
  1930.  
  1931.       Option    Description 
  1932.  
  1933.       LEVEL     Returns the current Corrective Service level of the component 
  1934.  
  1935.       PREV_LEVEL Returns the previous Corrective Service level of the component 
  1936.  
  1937.       COMPONENT Returns the name of the component 
  1938.  
  1939.       VER       Returns operating system version level of the component 
  1940.  
  1941.       EDITION   Returns editon type (either 'Standard Edition' or 'Extended 
  1942.                 Edition') 
  1943.  
  1944.    Purpose:  This function parses information from a specified SYSLEVEL.xxx 
  1945.              file.  It is often necessary to create REXX execs that are able to 
  1946.              determine the Corrective Service level of a particular OS/2 
  1947.              component. 
  1948.  
  1949. /* Sample code */
  1950.  
  1951. file = 'c:\cmlib\syslevel.acs'
  1952. say RxSysLevel(file)
  1953. say RxSysLevel(file, 'LEVEL')
  1954. say RxSysLevel(file, 'PREV_LEVEL')
  1955. say RxSysLevel(file, 'COMPONENT')
  1956. say RxSysLevel(file, 'VER')
  1957. say RxSysLevel(file, 'EDITION')
  1958.  
  1959. /* Output */
  1960.  
  1961. WR05015 WR05001 Extended Edition 1.30.1 IBM OS/2 Communications Manager
  1962. WR05015
  1963. WR05001
  1964. IBM OS/2 Communications Manager
  1965. 1.30.1
  1966. Extended Edition
  1967.  
  1968.  
  1969. ΓòÉΓòÉΓòÉ 9.47. RxTempFileName ΓòÉΓòÉΓòÉ
  1970.  
  1971. Function: RxTempFileName 
  1972.  
  1973. Syntax:   file = RxTempFileName(template, [filter]) 
  1974.  
  1975.    template  The template which describes the temporary file or directory name 
  1976.              to be returned.  The template should resemble a valid file or 
  1977.              directory specification with up to 5 filter characters. 
  1978.  
  1979.    filter    The filter character found in the template.  Each filter character 
  1980.              found in the template will be replaced with a numeric value.  The 
  1981.              resultant string represents a file or directory which does not 
  1982.              exist  The default filter character is ?. 
  1983.  
  1984.    file      A file or directory that does not currently exist.  If an error 
  1985.              occurred or if no unique file or directory exists given the 
  1986.              template provided, a null string is returned. 
  1987.  
  1988. Purpose:  Returns a unique file or directory name given a certain template. 
  1989.           Useful when an exec requires a temporary file but doesn't want to 
  1990.           have to worry about overwriting an existing file. 
  1991.  
  1992. Examples:
  1993.  
  1994.  /* Code */
  1995.  say RxTempFileName('C:\TEMP\MYEXEC.???')
  1996.  say RxTempFileName('C:\TEMP\??MYEXEC.???')
  1997.  say RxTempFileName('C:\MYEXEC@.@@@', '@')
  1998.  
  1999.  /* Output */
  2000.  C:\TEMP\MYEXEC.251
  2001.  C:\TEMP\10MYEXEC.392
  2002.  C:\MYEXEC6.019
  2003.  
  2004. Note: 
  2005.  
  2006. Since it is not required that the filter characters be contiguous within the 
  2007. template it is impossible to quickly determine the number of files already 
  2008. residing in the target directory that would fit the template description. 
  2009.  
  2010. RxTempFileName uses a random number algorithm to determine a number to replace 
  2011. the filter characters with.  It then tests if the resulting file exists.  If it 
  2012. does not, it increments the number, replaces the filter characters, and tests 
  2013. for the existence of the new file, etc, etc.  This continues until a free file 
  2014. is found or all possibilities have been exhausted. 
  2015.  
  2016.  
  2017. ΓòÉΓòÉΓòÉ 9.48. RxTree ΓòÉΓòÉΓòÉ
  2018.  
  2019. Function: RxTree 
  2020.  
  2021. Syntax:   rc = RxTree(filespec, stem, [options], [tattrib], [nattrib]) 
  2022.  
  2023.    filespec  The filespec to search for. 
  2024.  
  2025.    stem      The name of the stem variable to place the results. 
  2026.  
  2027.              Note:  stem.0 contains the number of files and/or directories 
  2028.              found. 
  2029.  
  2030.    options   Any logical combination of the following: 
  2031.  
  2032.       F         Search for files only. 
  2033.  
  2034.       D         Search for directories only. 
  2035.  
  2036.       B         Search for both files and directories. (default) 
  2037.  
  2038.       S         Scan subdirectories recursively. (non-default). 
  2039.  
  2040.       T         Return time and date fields as one easily digestible field in 
  2041.                 the form: 
  2042.  
  2043.                                 YY/MM/DD/HH/MM
  2044.  
  2045.       O         Only report fully qualified file names.  The default is to 
  2046.                 report date, time, size, attributes and fully qualified file 
  2047.                 name for each file found. 
  2048.  
  2049.    tattrib   The target attribute mask used when searching for filespec 
  2050.              matches. Only filespecs which match the mask will be reported. 
  2051.              The default mask is '*****' which means the Archive, Directory, 
  2052.              Hidden, Read-Only, and System bits may be either set or clear. 
  2053.              The attributes in the mask are positional dependant and in the 
  2054.              alphabetical order 'ADHRS'. 
  2055.  
  2056.       Mask Options (Target Mask) 
  2057.  
  2058.          *         The specified attribute may be either set or clear. 
  2059.  
  2060.          +         The specified attribute must be set. 
  2061.  
  2062.          -         The specified attribute must be clear. 
  2063.  
  2064.       Examples: (Target Mask) 
  2065.  
  2066.          '***+*'   Find all files which have set Read-Only bits. 
  2067.  
  2068.          '+**+*'   Find all files which have set Read-Only and Archive bits. 
  2069.  
  2070.          '*++**'   Find all hidden subdirectories. 
  2071.  
  2072.          '---+-'   Find all files which have only the Read-Only bit set. 
  2073.  
  2074.    nattrib   The new attribute mask which will be used to set the attributes of 
  2075.              each filespec found to match the target mask.  The default mask is 
  2076.              '*****' which means the Archive, Directory, Hidden, Read-Only, and 
  2077.              System bits will not be changed.  The attributes in the mask are 
  2078.              positional dependant and in the alphabetical order 'ADHRS'. 
  2079.  
  2080.       Mask Options (New Atrribute Mask) 
  2081.  
  2082.          *         The specified attribute will not be changed. 
  2083.  
  2084.          +         The specified attribute will be set. 
  2085.  
  2086.          -         The specified attribute will be cleared. 
  2087.  
  2088.       Examples: (New Attribute Mask) 
  2089.  
  2090.          '***+*'   Set the Read-Only bit on all files. 
  2091.  
  2092.          '-**+*'   Set the Read-Only and clear the Archive bits of each file. 
  2093.  
  2094.          '+*+++'   Set all attributes on all files, excluding directory 
  2095.                    attribute. 
  2096.  
  2097.          '-----'   Clear all attribute on all files. 
  2098.  
  2099.                    Note:  You cannot set the directory bit on non-directory 
  2100.                    filespecs.  The attribute field which is displayed in the 
  2101.                    stem variable is that of the current attribute setting after 
  2102.                    any changes have been applied. 
  2103.  
  2104.       Purpose:  Finds all files which are equal to the specified filespec, and 
  2105.                 places their descriptions (date time size attr filespec) in a 
  2106.                 stem variable. 
  2107.  
  2108.       RC:       Return Codes 
  2109.  
  2110.          0         Successful. 
  2111.  
  2112.          2         Error.  Not enough memory. 
  2113.  
  2114.  Examples:
  2115.  
  2116.   /****<<< Syntax Examples >>>***********************/
  2117.  
  2118.   /* Find all subdirectories on C: */
  2119.    call RxTree 'c:\*.*', 'file', 'SD'
  2120.  
  2121.   /* Find all Read-Only files */
  2122.    call RxTree 'c:\*.*', 'file', 'S', '***+*'
  2123.  
  2124.   /* Clear Archive and Read-Only bits for all files which have them set */
  2125.    call RxTree 'c:\*.*', 'file', 'S', '+**+*', '-**-*'
  2126.  
  2127.   /****<<< Sample Code and Output Example >>>********/
  2128.  
  2129.   /* Code */
  2130.    call RxTree 'c:\os2*.', 'file', 'B'
  2131.    do i=1 to file.0
  2132.      say file.i
  2133.    end
  2134.  
  2135.  /* Actual Output */
  2136. 12-15-89  12:00a        4096  A-HRS  C:\OS2LDR
  2137. 12-15-89  12:00a       29477  A-HRS  C:\OS2KRNL
  2138.  5-24-89   4:59p           0  -D---  C:\OS2
  2139.  
  2140.  
  2141. ΓòÉΓòÉΓòÉ 9.49. RxUserInfo ΓòÉΓòÉΓòÉ
  2142.  
  2143. Function: RxUserInfo 
  2144.  
  2145. Syntax:   info = RxUserInfo() 
  2146.  
  2147.    info      Userid, workstation name, and logon domain separated by spaces. 
  2148.              For example: 
  2149.  
  2150.                           'ROY TRIGGER YKCOD02'
  2151.  
  2152. Purpose:  This function may be used to determine the userid logged on at the 
  2153.           workstation; the name of the workstation; and the domain which the 
  2154.           user is logged onto.  Each of these items of information is returned 
  2155.           separated by a space.  If a given item is not available, then the 
  2156.           period character, . will be returned in its place. 
  2157.  
  2158.           Note:  This function will only return valid information for OS/2 1.2 
  2159.           EE LAN workstations.  This function loads the NetWkstaGetInfo() 
  2160.           function contained in NETAPL.DLL dynamically, if it is available.  If 
  2161.           it cannot load this function, the return information string will be 
  2162.           '. . .'. 
  2163.  
  2164. /* Sample Code */
  2165. parse value RxUserInfo() with userid machine domain
  2166. say 'Userid is' userid
  2167. say 'Workstation name is' machine
  2168. say 'Domain is' domain
  2169.  
  2170.  
  2171. ΓòÉΓòÉΓòÉ 9.50. RxUtilsVer ΓòÉΓòÉΓòÉ
  2172.  
  2173. Function: RxUtilsVer 
  2174.  
  2175. Syntax:   ver = RxUtilsVer() 
  2176.  
  2177.    ver       String containing RxUtils version info in the form 'x.xx' 
  2178.  
  2179. Purpose:  Returns the version of the RXUTILS.DLL which is currently running. 
  2180.  
  2181.  
  2182. ΓòÉΓòÉΓòÉ 9.51. RxWrite ΓòÉΓòÉΓòÉ
  2183.  
  2184. Function: RxWrite 
  2185.  
  2186. Syntax:   rc = RxWrite(filename, stem, [num], [start], [opt]) 
  2187.  
  2188.    filename  The name of the file to write. 
  2189.  
  2190.    stem      The name of the file stem variable. 
  2191.  
  2192.    num       The number of lines to write.  If not specified, all lines up to 
  2193.              the number specified by stem.0. will be written.  A number which 
  2194.              would cause a write past the number of lines specified in stem.0 
  2195.              is not permitted. 
  2196.  
  2197.    start     The line number to start with.  The default is 1. 
  2198.  
  2199.    opt       Any logical combination of the following: 
  2200.  
  2201.       A         Append the stem to the specified file.  Create a new file if 
  2202.                 the specified file does not exist.  If not specified, the stem 
  2203.                 contents will overwrite the contents of the specified file if 
  2204.                 it already exists.  This option is active only if the file 
  2205.                 exists prior to calling RxWrite. 
  2206.  
  2207.       E         Append the EOF character (0x1A) to the end of the written file. 
  2208.                 This is not the default. 
  2209.  
  2210.       F         Force the file to be written, even if the file currently exists 
  2211.                 and its file attributes are set to READ_ONLY or SYSTEM.  This 
  2212.                 is not the default.  In the default mode, RxWrite will fail if 
  2213.                 trying to write to a file which has its READ_ONLY or SYSTEM 
  2214.                 file attributes set.  This option is active only if the file 
  2215.                 exists prior to calling RxWrite. 
  2216.  
  2217.       R         Retain previous file attributes.  By default the previous file 
  2218.                 attributes will be preserved with the addition of the setting 
  2219.                 of the ARCHIVE bit.  If the R option is specified, the previous 
  2220.                 files attributes are retained without change.  This option is 
  2221.                 active only if the file exists prior to calling RxWrite. 
  2222.  
  2223.       T         Restore the original time and date stamp of the file.  This is 
  2224.                 not the default.  In the default mode, the current time and 
  2225.                 date are used for the time and date stamp of the new file. 
  2226.                 This option is active only if the file exists prior to calling 
  2227.                 RxWrite. 
  2228.  
  2229.    Purpose:  Writes a specified file stem variable to a specified file. 
  2230.  
  2231.    RC:       Return Codes 
  2232.  
  2233.       0         Stem was written successfully. 
  2234.  
  2235.       2         Error.  Not enough memory. 
  2236.  
  2237.       3         Error.  Error opening file. 
  2238.  
  2239.       4         Error.  Error writing file. 
  2240.  
  2241. /* Sample Code */
  2242. call RxWrite 'c:\config.sys', 'file', file.0, , 'A'
  2243.  
  2244.  
  2245. ΓòÉΓòÉΓòÉ 10. Macrospace Functions Overview ΓòÉΓòÉΓòÉ
  2246.  
  2247. The following section describes the REXX interpreter macrospace and functions 
  2248. for dealing with it. 
  2249.  
  2250. The functions provided are direct interfaces into the RxMacro...() functions 
  2251. provided by the REXXSAA API. 
  2252.  
  2253. Note:  The following documentation describing the REXX macrospace has been 
  2254. copied from the Operating System/2 Version 1.3 Procedures Language 2/REXX 
  2255. Reference guide.  The author of RXUTILS is not responsible for any of its 
  2256. content and as usual, the names have been changed to protect the innocent. 
  2257.  
  2258.  
  2259. ΓòÉΓòÉΓòÉ 10.1. Macrospace Interface ΓòÉΓòÉΓòÉ
  2260.  
  2261. The macrospace interface can reduce the search time for REXX functions existing 
  2262. on disk by allowing a function image to be maintained in memory for immediate 
  2263. load and execution. This is especially useful for procedures and functions 
  2264. which are used frequently in a program, such as editor macros and other 
  2265. high-use functions. 
  2266.  
  2267. As far as the REXX programmer is concerned, calling a macrospace-registered 
  2268. function is essentially identical to calling any other function.  The 
  2269. macrospace functions are global to all REXX procedures.  The sole difference in 
  2270. execution is the priority it is given in the external-function search order. 
  2271. Functions registered in the macrospace can be placed in this search order to be 
  2272. executed before or after all other external functions. 
  2273.  
  2274. The REXX interpreter environment during the execution of the macrospace 
  2275. functions is essentially the same as if the functions existed in external REXX 
  2276. files. 
  2277.  
  2278.  
  2279. ΓòÉΓòÉΓòÉ 10.2. Search Order ΓòÉΓòÉΓòÉ
  2280.  
  2281. When a function is registered in the macrospace by way of the interface 
  2282. functions, a flag is passed requesting the function position in the external 
  2283. function search order for the REXX interpreter. There are only two valid 
  2284. requests for search order positioning; before all other external functions and 
  2285. after all other external functions. 
  2286.  
  2287.  
  2288. ΓòÉΓòÉΓòÉ 10.3. Pre-External Function Registration ΓòÉΓòÉΓòÉ
  2289.  
  2290. If the function is registered with the BEFORE flag, then that function will be 
  2291. located by the REXX interpreter before any functions existing in external REXX 
  2292. files or in function packages.  This allows the user to temporarily supersede 
  2293. the normal execution of the function by replacing an external function without 
  2294. deleting or renaming the file or canceling the function registration in the 
  2295. packages. 
  2296.  
  2297.  
  2298. ΓòÉΓòÉΓòÉ 10.4. Post-External Function Registration ΓòÉΓòÉΓòÉ
  2299.  
  2300. If a function is registered with the AFTER flag, then the function will be 
  2301. located by the REXX interpreter after any functions existing in external REXX 
  2302. files or in function packages.  This allows the user to provide a default 
  2303. function for use by the REXX interpreter in the event some external function 
  2304. required by the interpreter cannot be found in an external REXX file or 
  2305. function packages. 
  2306.  
  2307.  
  2308. ΓòÉΓòÉΓòÉ 10.5. Storage of Macrospace Libraries ΓòÉΓòÉΓòÉ
  2309.  
  2310. Functions registered in the macrospace can be saved to a permanent storage file 
  2311. on disk for loading at a later date.  This allows an application, such as an 
  2312. editor, to create its own library of frequently-used functions, and load the 
  2313. entire macrospace library into memory for fast access by the language 
  2314. processor. This macrospace library is specified by a filename.  Thus, multiple 
  2315. macrospace function libraries can exist concurrently on a disk. 
  2316.  
  2317. Some consideration must be given to storage and memory utilization. 
  2318.  
  2319. The fact that the macrospace interface is designed to enhance performance for 
  2320. the external functions places severe limitations on the number of restrictions 
  2321. which can be imposed by the API.  Therefore, the only limitations on the number 
  2322. of restrictions which will be placed on the user will be the constraints of 
  2323. available memory imposed by the OS/2 program.  The macrospace will be allowed 
  2324. to grow so long as memory is available.  However, if the macrospace grows too 
  2325. large (relative to the amount of available memory), then performance of the 
  2326. operating system may deteriorate due to an increased number of disk accesses to 
  2327. maintain its swap file. 
  2328.  
  2329. It is recommended then, that the macrospace not be used to hold all the 
  2330. function needed by the user for a normal day of use.  A more efficient method 
  2331. is to maintain only those functions that are going to be used by the current 
  2332. process in the macrospace, and to either delete or omit others for the 
  2333. macrospace. 
  2334.  
  2335.  
  2336. ΓòÉΓòÉΓòÉ 10.6. RxMacChange ΓòÉΓòÉΓòÉ
  2337.  
  2338. Function: RxMacChange 
  2339.  
  2340. Syntax:   result = RxMacChange(FuncName, SourceFile, Position) 
  2341.  
  2342.    FuncName  The string specifying the name by which the function will be 
  2343.              known.  This function name must be validated to follow the REXX 
  2344.              rules for function names; it should also correspond to function 
  2345.              names implemented as part of external function package. 
  2346.  
  2347.    SourceFile Is the name of the file specification of the disk file containing 
  2348.              the source for this function.  If no file extension is supplied, 
  2349.              it will default to .CMD.  If the full path is not specified, the 
  2350.              standard search will be conducted (search current directory and 
  2351.              OS/2 path). 
  2352.  
  2353.    Position  This flag indicates where the function should be placed in the 
  2354.              external function search order for REXX. There are two possible 
  2355.              positions; a function can be placed at the beginning of the search 
  2356.              order (that is, before all other external functions) or at the end 
  2357.              of the search order (that is, after all other external functions). 
  2358.  
  2359.              The Position should be one of the following: 
  2360.  
  2361.                            Position   Description
  2362.  
  2363.                            BEFORE     Place before external functions in search order
  2364.                            AFTER      Place after external functions in search order
  2365.  
  2366. Purpose:  This function can be used to add a function to the macrospace.  It 
  2367.           may also be used to change an existing function in the macrospace. 
  2368.  
  2369. result:   Return Codes 
  2370.  
  2371.    Null String Function successfully added/changed. 
  2372.  
  2373.    ERROR:1   Out of storage space. 
  2374.  
  2375.    ERROR:7   Source not found. 
  2376.  
  2377.    ERROR:8   Invalid position. 
  2378.  
  2379. /* Sample Code */
  2380. call RxMacChange 'COREUP', 'COREUP.CMD', 'BEFORE'
  2381.  
  2382.  
  2383. ΓòÉΓòÉΓòÉ 10.7. RxMacDrop ΓòÉΓòÉΓòÉ
  2384.  
  2385. Function: RxMacDrop 
  2386.  
  2387. Syntax:   result = RxMacDrop(FuncName) 
  2388.  
  2389.    FuncName  The string specifying the name of the function to remove from the 
  2390.              macrospace. 
  2391.  
  2392. Purpose:  This function can be used to delete a function from the macrospace. 
  2393.  
  2394. result:   Return Codes 
  2395.  
  2396.    Null String Function successfully removed. 
  2397.  
  2398.    ERROR:2   Function not found in macrospace. 
  2399.  
  2400. /* Sample Code */
  2401. call RxMacDrop 'COREUP'
  2402.  
  2403.  
  2404. ΓòÉΓòÉΓòÉ 10.8. RxMacErase ΓòÉΓòÉΓòÉ
  2405.  
  2406. Function: RxMacErase 
  2407.  
  2408. Syntax:   result = RxMacErase() 
  2409.  
  2410. Purpose:  This function should be called to remove all functions from the 
  2411.           macrospace. 
  2412.  
  2413.           There are no parameters for this function.  Special care should be 
  2414.           taken in using this function, because no verification is done on the 
  2415.           deleted functions, that is, all functions are removed from the 
  2416.           macrospace, regardless of whether or not they are being used by other 
  2417.           processes. 
  2418.  
  2419. result:   Return Codes 
  2420.  
  2421.    Null String All functions successfully removed. 
  2422.  
  2423.    ERROR:2   No functions found in macrospace. 
  2424.  
  2425. /* Sample Code */
  2426. call RxMacErase
  2427.  
  2428.  
  2429. ΓòÉΓòÉΓòÉ 10.9. RxMacLoad ΓòÉΓòÉΓòÉ
  2430.  
  2431. Function: RxMacLoad 
  2432.  
  2433. Syntax:   result = RxMacLoad(MacroLibFile [, Func1, Func2, ...]) 
  2434.  
  2435.    MacroLibFile The name of the file specification from which to load the 
  2436.              macrospace.  Macro library files can be created with the RxMacSave 
  2437.              function. 
  2438.  
  2439.    Func1, Func2, ... The names of the functions to load.  If no function names 
  2440.              are given then all functions contained in the file will be loaded 
  2441.              into the macrospace. 
  2442.  
  2443. Purpose:  This function allows the user to load either all or a specified 
  2444.           subset of all functions from a specified file into the macrospace. 
  2445.  
  2446. result:   Return Codes 
  2447.  
  2448.    Null String Successfully loaded. 
  2449.  
  2450.    ERROR:1   Out of storage space. 
  2451.  
  2452.    ERROR:2   Function not found in macrospace. 
  2453.  
  2454.    ERROR:4   Function already exists in macrospace. 
  2455.  
  2456.    ERROR:5   Macro file error. 
  2457.  
  2458.    ERROR:6   Macro signature error. 
  2459.  
  2460. /* Sample Code */
  2461. /* The following sample code loads the COREUP and COREFIX */
  2462. /* routines from the COREUP.MAC macro library file        */
  2463. call RxMacLoad 'COREUP.MAC', 'COREUP', 'COREFIX'
  2464.  
  2465.  
  2466. ΓòÉΓòÉΓòÉ 10.10. RxMacQuery ΓòÉΓòÉΓòÉ
  2467.  
  2468. Function: RxMacQuery 
  2469.  
  2470. Syntax:   result = RxMacQuery(FuncName) 
  2471.  
  2472.    FuncName  A string specifying the name of the function to search for in the 
  2473.              list of the macrospace functions. 
  2474.  
  2475. Purpose:  This function allows the user to search for a particular function in 
  2476.           the macrospace. 
  2477.  
  2478. result:   Return Codes 
  2479.  
  2480.    Null String Function exists. 
  2481.  
  2482.    ERROR:2   Function not found in macrospace. 
  2483.  
  2484. /* Sample Code */
  2485. if RxMacQuery('COREUP')='' then
  2486.   say 'The COREUP function EXISTS in the macrospace.'
  2487. else
  2488.   say 'The COREUP function DOES NOT EXIST in the macrospace.'
  2489.  
  2490.  
  2491. ΓòÉΓòÉΓòÉ 10.11. RxMacReOrder ΓòÉΓòÉΓòÉ
  2492.  
  2493. Function: RxMacReOrder 
  2494.  
  2495. Syntax:   result = RxMacReOrder(FuncName, Position) 
  2496.  
  2497.    FuncName  A string specifying the name of the function whose search order 
  2498.              positioning is to be changed. 
  2499.  
  2500.    Position  This flag indicates where the function will be moved to in the 
  2501.              external function search order for REXX. There are two possible 
  2502.              positions; a function can be placed at the beginning of the search 
  2503.              order (that is, before all other external functions) or at the end 
  2504.              of the search order (that is, after all other external functions). 
  2505.  
  2506.              The Position should be one of the following: 
  2507.  
  2508.                            Position   Description
  2509.  
  2510.                            BEFORE     Place before external functions in search order
  2511.                            AFTER      Place after external functions in search order
  2512.  
  2513. Purpose:  This function allows the user to change the search-order location of 
  2514.           a function already in the macrospace. 
  2515.  
  2516. result:   Return Codes 
  2517.  
  2518.    Null String Function search position successfully moved. 
  2519.  
  2520.    ERROR:2   Function not found in macrospace. 
  2521.  
  2522.    ERROR:8   Invalid position. 
  2523.  
  2524. /* Sample Code */
  2525. call RxMacReOrder 'COREUP', 'AFTER'
  2526.  
  2527.  
  2528. ΓòÉΓòÉΓòÉ 10.12. RxMacSave ΓòÉΓòÉΓòÉ
  2529.  
  2530. Function: RxMacSave 
  2531.  
  2532. Syntax:   result = RxMacSave(MacroLibFile [, Func1, Func2, ...]) 
  2533.  
  2534.    MacroLibFile The name of the file specification to which to save the 
  2535.              macrospace.  If a file exists, it is overwritten.  If a file does 
  2536.              not exist, it is created.  The file created by the function can be 
  2537.              loaded with the RxMacLoad function. 
  2538.  
  2539.    Func1, Func2, ... The names of the functions in the macrospace to saved.  If 
  2540.              no function names are given then all functions contained in the 
  2541.              macrospace will be saved to the file. 
  2542.  
  2543. Purpose:  This function allows the user to save either all or a specified 
  2544.           subset of all functions in the macrospace to a specified file. 
  2545.  
  2546. result:   Return Codes 
  2547.  
  2548.    Null String Macrospace function(s) successfully saved to macro library file. 
  2549.  
  2550.    ERROR:2   One or more of the specified functions was not found in macrospace 
  2551.              and therefore could not be saved. 
  2552.  
  2553.    ERROR:3   Extension required. 
  2554.  
  2555.    ERROR:5   File error. 
  2556.  
  2557. /* Sample Code */
  2558. call RxMacSave 'COREUP.MAC', 'COREUP', 'COREFIX'
  2559.  
  2560.  
  2561. ΓòÉΓòÉΓòÉ 11. Mailslot Function Overview ΓòÉΓòÉΓòÉ
  2562.  
  2563. The following section describes the RxMailslot function which is a 
  2564. multi-purpose function that provides a REXX interface to Mailslots. 
  2565.  
  2566. The following information regarding OS/2 LAN Requester/Server mailslots can be 
  2567. found in the LAN Server Application Programmer's Reference.  Where appropriate, 
  2568. DosxxxMailslot function names have been replaced with the RxMailslot function 
  2569. name and the information has been slightly modified to be more applicable to 
  2570. RxMailslot. 
  2571.  
  2572. Through OS/2 LAN Requester/Server mailslots, data can be sent to either local 
  2573. or remote applications on the network.  The RxMailslot function creates and 
  2574. deletes mailslots, retrieves information about a mailslot or a message in it, 
  2575. and writes messages to mailslots. 
  2576.  
  2577. An application creates a mailslot on a local computer by calling the RxMailslot 
  2578. function with the CREATE parameter and by assigning the mailslot a name in the 
  2579. format: 
  2580.  
  2581. \mailslot\name 
  2582.  
  2583. where: 
  2584.  
  2585. o name is a unique set of characters distinquishing the mailslot from other 
  2586.   mailslots on the computer. 
  2587.  
  2588. Mailslots come in two types: 
  2589.  
  2590. local     For example:  \mailslot\name 
  2591.  
  2592. remote    For example: \\computername\mailslot\name 
  2593.  
  2594. where: 
  2595.  
  2596. o name is a unique set of characters distinquishing the mailslot from other 
  2597.   mailslots on the computer. 
  2598.  
  2599. o computername specifies the name of a computer on the network.  To send to a 
  2600.   particular mailslot on all computers on the network, specify * in place of 
  2601.   the computername. 
  2602.  
  2603.  
  2604. ΓòÉΓòÉΓòÉ 11.1. RxMailslot CREATE ΓòÉΓòÉΓòÉ
  2605.  
  2606. Function: RxMailslot CREATE 
  2607.  
  2608. Syntax:   handle = RxMailslot('CREATE', name, messagesize, mailslotsize) 
  2609.  
  2610.    name      The name of the mailslot to create.  Must be of the format 
  2611.              \mailslot\name. Only local mailslots may be created. 
  2612.  
  2613.    messagesize Specifies the maximum message size (in bytes) that the mailslot 
  2614.              can accept.  Generally, mailslots cannot accept messages larger 
  2615.              than 65475 bytes. 
  2616.  
  2617.    mailslotsize Specifies the size (in bytes) of the mailslot.  mailslotsize 
  2618.              must equal or exceed messagesize. 
  2619.  
  2620. Purpose:  This function is used to create a specified mailslot.  If 
  2621.           successfully created, the handle of the mailslot is returned.  This 
  2622.           handle my be used by other RxMailslot function calls to READ or PEEK 
  2623.           the mailslot, QUERY information about the mailslot, or DELETE the 
  2624.           mailslot.  You may share this handle with other REXX execs by storing 
  2625.           its value in an INI file via the RxOS2Ini function or via some other 
  2626.           data sharing technique. 
  2627.  
  2628. handle:   Handle or Return Codes 
  2629.  
  2630.    Numeric Value The handle of the successfully created mailslot. 
  2631.  
  2632.    ERROR:3   The path was not found. 
  2633.  
  2634.    ERROR:8   Sufficient memory is not available. 
  2635.  
  2636.    ERROR:87  The specified parameter is invalid. 
  2637.  
  2638.    ERROR:183 The specified mailslot already exists. 
  2639.  
  2640.    ERROR:2102 The redirector NETWKSTA.EXE has not been started. 
  2641.  
  2642. /* Sample Code */
  2643.  say 'Creating mailslot...'
  2644.  handle = RxMailslot('CREATE', '\mailslot\test', 1024, 10*1024)
  2645.  if abbrev(handle, 'ERROR') then do
  2646.    say 'An error occurred while creating the mailslot.  Program aborted.'
  2647.    exit 2
  2648.  end
  2649.  else say 'Mailslot created successfully.'
  2650.  
  2651.  
  2652. ΓòÉΓòÉΓòÉ 11.2. RxMailslot DELETE ΓòÉΓòÉΓòÉ
  2653.  
  2654. Function: RxMailslot DELETE 
  2655.  
  2656. Syntax:   result = RxMailslot('DELETE', handle) 
  2657.  
  2658.    handle    Handle of the local mailslot to delete. 
  2659.  
  2660. Purpose:  This function deletes a previously created mailslot.  Only local 
  2661.           mailslots may be deleted. 
  2662.  
  2663. result:   Return Codes 
  2664.  
  2665.    Null String Mailslot deleted successfully. 
  2666.  
  2667.    ERROR:6   The specified handle is not valid. 
  2668.  
  2669.    ERROR:2102 The redirector NETWKSTA.EXE has not been started. 
  2670.  
  2671. /* Sample Code */
  2672.  call RxMailslot 'DELETE', handle
  2673.  
  2674.  
  2675. ΓòÉΓòÉΓòÉ 11.3. RxMailslot QUERY ΓòÉΓòÉΓòÉ
  2676.  
  2677. Function: RxMailslot QUERY 
  2678.  
  2679. Syntax:   result = RxMailslot('QUERY', handle, stem) 
  2680.  
  2681.    handle    The handle of the mailslot to query information about. 
  2682.  
  2683.    stem      Name of the stem variable in which to store queried information. 
  2684.              The queried information will be returned in the following manner: 
  2685.  
  2686.       o Message size 
  2687.  
  2688.         Returned in STEM.1 in the form: MESSAGESIZE=nnnn 
  2689.  
  2690.       o Mailslot size 
  2691.  
  2692.         Returned in STEM.2 in the form: MAILSLOTSIZE=nnnn 
  2693.  
  2694.       o Next message size 
  2695.  
  2696.         Returned in STEM.3 in the form: NEXTSIZE=nnnn 
  2697.  
  2698.       o Next message priority 
  2699.  
  2700.         Returned in STEM.4 in the form: NEXTPRIORITY=nnnn 
  2701.  
  2702.       o Number of messages 
  2703.  
  2704.         Returned in STEM.5 in the form: MSGCOUNT=nnnn 
  2705.  
  2706. Purpose:  This function returns information about a mailslot. 
  2707.  
  2708. result:   Return Codes 
  2709.  
  2710.    Numeric value Number of pending messages in the mailslot. 
  2711.  
  2712.    ERROR:6   The specified handle is not valid. 
  2713.  
  2714.    ERROR:2102 The redirector NETWKSTA.EXE has not been started. 
  2715.  
  2716. /* Sample Code */
  2717.  say 'Querying mailslot information...'
  2718.  call RxMailslot 'QUERY', handle, 'stem.'
  2719.  do i=1 to stem.0
  2720.    say stem.i
  2721.  end
  2722.  
  2723. /* Output */
  2724. MESSAGESIZE=1024
  2725. MAILSLOTSIZE=10240
  2726. NEXTSIZE=0
  2727. NEXTPRIORITY=0
  2728. MSGCOUNT=0
  2729.  
  2730.  
  2731. ΓòÉΓòÉΓòÉ 11.4. RxMailslot PEEK ΓòÉΓòÉΓòÉ
  2732.  
  2733. Function: RxMailslot PEEK 
  2734.  
  2735. Syntax:   msg = RxMailslot('PEEK', handle, [stem]) 
  2736.  
  2737.    handle    Handle of mailslot to peek message from. 
  2738.  
  2739.    stem      Name of the stem variable in which to store additional message 
  2740.              information.  The information will be returned in the following 
  2741.              manner: 
  2742.  
  2743.       o Bytes read 
  2744.  
  2745.         Returned in STEM.1 in the form: BYTESREAD=nnnn 
  2746.  
  2747.       o Next message size 
  2748.  
  2749.         Returned in STEM.2 in the form: NEXTSIZE=nnnn 
  2750.  
  2751.       o Next message priority 
  2752.  
  2753.       o Next message priority 
  2754.  
  2755.         Returned in STEM.3 in the form: NEXTPRIORITY=nnnn 
  2756.  
  2757. Purpose:  This function reads the next message from a mailslot without actually 
  2758.           removing the message from the mailslot. 
  2759.  
  2760. msg:      Message or Return Codes 
  2761.  
  2762.    Message   The message that was successfully peeked. 
  2763.  
  2764.    ERROR:6   The specified handle is not valid. 
  2765.  
  2766.    ERROR:109 Write on pipe with no reader. 
  2767.  
  2768.    ERROR:2102 The redirector NETWKSTA.EXE has not been started. 
  2769.  
  2770. /* Sample Code */
  2771.  say 'Peeking at mailslot...'
  2772.  msg =  RxMailslot('PEEK', handle, 'stem.')
  2773.  say 'Message='msg
  2774.  do i=1 to stem.0
  2775.    say stem.i
  2776.  end
  2777.  
  2778. /* Output */
  2779. Peeking at mailslot...
  2780. Message=Hello there
  2781. BYTESREAD=11
  2782. NEXTSIZE=0
  2783. NEXTPRIORITY=0
  2784.  
  2785.  
  2786. ΓòÉΓòÉΓòÉ 11.5. RxMailslot READ ΓòÉΓòÉΓòÉ
  2787.  
  2788. Function: RxMailslot READ 
  2789.  
  2790. Syntax:   msg = RxMailslot('READ', handle, [stem], [timeout]) 
  2791.  
  2792.    handle    Handle of mailslot to read message from. 
  2793.  
  2794.    stem      Name of the stem variable in which to store additional message 
  2795.              information.  The information will be returned in the following 
  2796.              manner: 
  2797.  
  2798.       o Bytes read 
  2799.  
  2800.         Returned in STEM.1 in the form: BYTESREAD=nnnn 
  2801.  
  2802.       o Next message size 
  2803.  
  2804.         Returned in STEM.2 in the form: NEXTSIZE=nnnn 
  2805.  
  2806.       o Next message priority 
  2807.  
  2808.         Returned in STEM.3 in the form: NEXTPRIORITY=nnnn 
  2809.  
  2810.    timeout   Timeout of the read in milliseconds.  Default timeout is 1000 
  2811.              milliseconds (1 second). Specifying a timeout of -1 makes the read 
  2812.              wait until something is in the mailslot. It should be noted that 
  2813.              the timeout variable must be the fourth parameter to the 
  2814.              RxMailslot 'READ' call.  This means that the stem paramater must 
  2815.              be specified (even if only with a null parameter) when specifying 
  2816.              a timeout value. 
  2817.  
  2818. Purpose:  This function reads the next message from a mailslot and removes said 
  2819.           message. 
  2820.  
  2821. msg:      Message or Return Codes 
  2822.  
  2823.    Message   The message that was successfully read. 
  2824.  
  2825.    ERROR:6   The specified handle is not valid. 
  2826.  
  2827.    ERROR:95  Program interrupted. 
  2828.  
  2829.    ERROR:109 Write on pipe with no reader. 
  2830.  
  2831.    ERROR:2102 The redirector NETWKSTA.EXE has not been started. 
  2832.  
  2833. /* Sample Code */
  2834.  say 'Reading mailslot...'
  2835.  msg =  RxMailslot('READ', handle, 'stem.')
  2836.  say 'Message='msg
  2837.  do i=1 to stem.0
  2838.    say stem.i
  2839.  end
  2840.  
  2841. /* Output */
  2842. Peeking at mailslot...
  2843. Message=Hello there
  2844. BYTESREAD=11
  2845. NEXTSIZE=0
  2846. NEXTPRIORITY=9
  2847.  
  2848.  
  2849. ΓòÉΓòÉΓòÉ 11.6. RxMailslot WRITE ΓòÉΓòÉΓòÉ
  2850.  
  2851. Function: RxMailslot WRITE 
  2852.  
  2853. Syntax:   result = RxMailslot('WRITE', name, msg, priority, class, timeout) 
  2854.  
  2855.    name      The name of the local or remote mailslot to write to. 
  2856.  
  2857.    msg       The message to write to the mailslot.  Special care should be 
  2858.              taken to make sure that the message is not too long for the 
  2859.              mailslot in which it is being sent.  No error indication is given 
  2860.              if an attempt to write a message is unsuccessful because it is too 
  2861.              long.  Use RxMailSlot QUERY to query information about the maximum 
  2862.              message size of a mailslot. 
  2863.  
  2864.    priority  The priority (0 through 9) of the message.  High-priority messages 
  2865.              are generally placed ahead of previously stored messages with 
  2866.              lower priority. 9 is the highest priority message level, 0 is the 
  2867.              lowest. 
  2868.  
  2869.    class     The class of mail service to be provided: 
  2870.  
  2871.       o First-class mail (1) 
  2872.  
  2873.         The function waits until a mailslot has enough room to accept the 
  2874.         message or until timeout expires.  First class mail can only be 
  2875.         delivered to remote servers or local computers. 
  2876.  
  2877.       o Second-class mail (2) 
  2878.  
  2879.         The function fails immediately if there is not enough room in the 
  2880.         mailslot to write the message.  Second-class mail can be delivered to 
  2881.         remote requesters OR servers as well as to local computers. 
  2882.  
  2883.    timeout   Specifies the number of milliseconds to wait when attempting to 
  2884.              write a message to a mailslot.  If 0, the function attempts to 
  2885.              write the message only once.  If -1, the function attempts to 
  2886.              write to the mailslot for an indefinite amount of time. 
  2887.  
  2888. Purpose:  This function is used to write a message to a specified local or 
  2889.           remote mail slot.  When writing to remote mailslots, a broadcast to 
  2890.           all computers with said mailslot may be achieved by using a * in 
  2891.           place of the computername. 
  2892.  
  2893. result:   Return Codes 
  2894.  
  2895.    Null String Mailslot message written successfully. 
  2896.  
  2897.    ERROR:3   The path was not found. 
  2898.  
  2899.    ERROR:67  The network name cannot be found or attempt was made to send a 
  2900.              remote 1st class message. 
  2901.  
  2902.    ERROR:87  The specified parameter is invalid. 
  2903.  
  2904.    ERROR:2102 The redirector NETWKSTA.EXE has not been started. 
  2905.  
  2906.    ERROR:2351 The specified computer name is invalid. 
  2907.  
  2908.              Note:  This is only a partial list.  Please see DosWriteMailslot() 
  2909.              function definition in LAN Server Application Programmer's 
  2910.              Reference if needed. 
  2911.  
  2912. /* Sample Code */
  2913.  
  2914.  /* Broadcast a 2nd-class, high priority message */
  2915.  call RxMailslot 'WRITE', '\\*\MAILSLOT\MAILQ', 'Hello', 9, 2, 0
  2916.  
  2917.  /* Send a 1st-class message to a known computer */
  2918.  call RxMailslot 'WRITE', '\\JOESCOMP\MAILSLOT\TESTSLOT', 'Test Msg', 9, 1, -1
  2919.  
  2920.  /* Send a low-priority message to a local mailslot */
  2921.  call RxMailslot 'WRITE', '\MAILSLOT\MYSLOT', 'Local Msg', 0, 1, 0
  2922.  
  2923.  
  2924. ΓòÉΓòÉΓòÉ 12. Sample REXX Exec using RxUtils ΓòÉΓòÉΓòÉ
  2925.  
  2926. Run the RXTEST.CMD exec for a sample usage of most RxUtils functions. 
  2927.  
  2928. It is encouraged that programmer's look at the code of RXTEST.CMD as a sample 
  2929. that uses the RXUTILS functions. 
  2930.  
  2931.  
  2932. ΓòÉΓòÉΓòÉ 13. Support of RxUtils ΓòÉΓòÉΓòÉ
  2933.  
  2934. Support and enhancements for RxUtils will be performed by the author on an 'as 
  2935. time permits' basis.  Please append bug reports, requests for new features, and 
  2936. general discussion of RxUtils to the RXUTILS FORUM on IBMPC. 
  2937.  
  2938. RXUTILS PROCS also exists on IBMPC.  Feel free to append any execs or 
  2939. procedures that use RxUtils functions there.