home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / SAAREXX.ZIP / SAAREXX.INF (.txt) < prev    next >
OS/2 Help File  |  1991-08-20  |  185KB  |  6,700 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. SAA Procedures Language REXX Reference 
  5. Version 1.00
  6. (c) Copyright W. David Ashley and Pedagogic Software 1991. All rights reserved.
  7. Licensed to AMR, Inc. and all subsidiaries (no fee required).
  8. Documentation by 
  9. W. David Ashley 
  10.  
  11. No warranties, guarantees, etc. are implied, and no liability is assumed for 
  12. the code, examples, DLLs or documentation. 
  13.  
  14. Any mis-statements of fact or mis-representations in this reference are my own. 
  15. I hereby apologize ahead of time should mistakes in this reference mislead you. 
  16. If you will contact me I will make every effort to correct any errors in this 
  17. reference. 
  18.  
  19. This documentation is user-supported and may be freely copied and used by 
  20. anyone who wishes to do so as long as the following conditions are met: 
  21.  
  22.   1. The files and documentation may not be used by any program for which a fee 
  23.      is charged unless the owner of the program has paid the registration fee. 
  24.  
  25.   2. If you transmit a copy of this software to another party you must give 
  26.      them the complete unaltered contents of the SAAREXX.ZIP file. 
  27.  
  28.  If you feel that this program/documentation has benefited you, please register 
  29.  it by sending $25.00 (no fee required by AMR, Inc. and all subsidiaries) to: 
  30.  
  31.  Pedagogic Software 
  32.  W. David Ashley 
  33.  5 Timberline Dr. 
  34.  Trophy Club, Tx 76262 
  35.  
  36.  The source code for SAAREXX.INF can be obtained by sending $75.00 ($25.00 
  37.  registration + $50.00 source code) to the same address (no fee required by 
  38.  AMR, Inc. and all subsidiaries). 
  39.  
  40.  If you have questions, comments or suggestions please contact me through the 
  41.  OS/2 Shareware BBS or at the address above (AMR employees may contact me 
  42.  through PROFS, my user ID is Z2277). 
  43.  
  44.  This online reference is a complete update of Brian Buck's REXREF.INF. It has 
  45.  been reorganized, expanded, cleaned up and otherwise modified to support only 
  46.  IBM SAA environments (all DOS REXX product references have been eliminated). 
  47.  Many thanks to Brian for an outstanding job in getting this off the ground. 
  48.  Brian, if you're out there somewhere, contact me. 
  49.  
  50.  This is a reference for quick online lookups of REXX syntax; it is NOT a 
  51.  substitute for the real REXX reference manuals. Neither is it a tutorial; 
  52.  unless you have some programming experience, you probably could not learn REXX 
  53.  from this reference alone. It is assumed that you may know some REXX, but are 
  54.  still learning and need to look things up frequently, or are an experienced 
  55.  user who nonetheless hasn't yet memorized every function in the entire 
  56.  language, or the variants for every environment and implementation. 
  57.  
  58.  You can lookup REXX topics  for the SAA, OS/2, TSO, and VM environments. 
  59.  
  60.  Why an Online REXX Reference? 
  61.  
  62.  Why? - Like Brian Buck, I needed one; so did the people in my company. 
  63.  Unfortunately, IBM did not see fit to provide either a written or online one 
  64.  with OS/2 1.x (the beta version of the OS/2 2.0 REXX online reference from IBM 
  65.  is only slightly better than nothing). I also got tired of needing a different 
  66.  REXX manual for every environment and implementation, plus the SAA one --- 
  67.  important, but useless by itself.  That's why this reference covers all the 
  68.  SAA environments that have REXX implementations. (Yes, I know, there is now 
  69.  REXX for AS/400, but I don't have those manuals; volunteers, anyone?  Send me 
  70.  the details and I'll update this reference). 
  71.  
  72.           Warning: Author mounting soapbox! 
  73.  
  74.           Also, I wanted to encourage the widespread use of REXX as a macro 
  75.           language for editors, communications packages, spreadsheets, etc. A 
  76.           universal macro and procedures language is needed; it is crazy to 
  77.           have to learn a new language for every new package you buy. Maybe 
  78.           REXX isn't the best possible choice, but it's here now and available 
  79.           in most environments, and is a pretty good language for this 
  80.           specialized purpose. 
  81.  
  82.           Demand REXX interfaces from your vendors -- vote with your dollars; 
  83.           include them in your products if you author software yourself. It is 
  84.           encouraging to see companies like Lotus coming out in favor of REXX 
  85.           (as reported in PC Week from the SLAC REXX symposium). 
  86.  
  87.  Trademarks 
  88.  
  89.  The following trademarks apply to all online information: 
  90.  
  91.  o IBM is a registered trademark of International Business Machines 
  92.    Corporation. 
  93.  
  94.  o Microsoft is a trademark of the Microsoft Corporation. 
  95.  
  96.  o Operating System/2 and OS/2 are trademarks of International Business 
  97.    Machines Corporation. 
  98.  
  99.  o Personal System/2 and PS/2 are registered trademarks of International 
  100.    Business Machines Corporation. 
  101.  
  102.  o Presentation Manager is a trademark of International Business Machines 
  103.    Corporation. 
  104.  
  105.  o Systems Application Architecture and SAA are trademarks of International 
  106.    Business Machines Corporation. 
  107.  
  108.  o TSO is a trademark of International Business Machines Corporation. 
  109.  
  110.  o VM is a trademark of International Business Machines Corporation. 
  111.  
  112.  o MVS is a trademark of International Business Machines Corporation. 
  113.  
  114.  
  115. ΓòÉΓòÉΓòÉ 1.1. Other References ΓòÉΓòÉΓòÉ
  116.  
  117. The following references were consulted during the preparation of this 
  118. reference: 
  119.  
  120.  Order# / ISBN         Manual, Book, or Article 
  121.  
  122.  S01F-0284             OS/2 Procedures Language 2/REXX Reference (OS/2), IBM 
  123.  
  124.  SC24-5239-03          VM/SP System Product Interpreter Reference (VM/SP 
  125.                        Release 6), IBM 
  126.  
  127.  SC28-1883-2           TSO/E Version 2 REXX Reference (TSO/E 2.2), IBM 
  128.  
  129.  SC26-4358-2           SAA CPI Procedures Language Reference, IBM 
  130.  
  131.  0-13-780651-5         The Rexx Language: a Practical Approach to Programming 
  132.                        2nd edition, by M. F. Cowlishaw, IBM UK Scientific 
  133.                        Centre; 1990, Prentice-Hall, Inc., Englewood Cliffs, New 
  134.                        Jersey 07632 
  135.  
  136.  Additional and introductory information can be found in: 
  137.  
  138.  Order# / ISBN         Manual, Book, or Article 
  139.  
  140.  S01F-0283             OS/2 Procedures Language 2/REXX User's Guide, IBM 
  141.  
  142.  SC24-5549             SAA CPI Procedures Language Level 2 Reference, IBM 
  143.  
  144.  SC28-1882-1           TSO/E Version 2 REXX User's Guide, IBM 
  145.  
  146.  SC24-5357             VM/IS Writing Simple Programs with REXX, IBM 
  147.  
  148.  SC24-5238             VM/SP Product Interpreter User's Guide, IBM 
  149.  
  150.  GH19-8118             CMS REXX Compiler General Information, IBM 
  151.  
  152.  SH19-8120             CMS REXX Compiler User's Guide and Reference, IBM 
  153.  
  154.  SH19-8146             CMS REXX Compiler User's Guide Reference Supplemental, 
  155.                        IBM 
  156.  
  157.  GG22-9361             System Product Interpreter REXX Examples and Techniques, 
  158.                        (VM) IBM 
  159.  
  160.  G321-5359             REXX on TSO/E, IBM Systems Journal article reprint from 
  161.                        Vol. 28 No. 2, 1989 
  162.  
  163.  G321-5228             The Design of the REXX Language, IBM Systems Journal 
  164.                        article reprint from Vol. 23 No. 4, 1984 
  165.  
  166.  0-89435-354-3         REXX in the TSO Environment, by Gabriel F. Gargiulo; 
  167.                        1990, QED Information Sciences, Inc., P.O. Box 82-181, 
  168.                        Wellesley, MA 02181 
  169.  
  170.  0-13-682790-X         Practical Usage of REXX, by Anthony S. Rudd; 1990, Ellis 
  171.                        Horwood Limited, Market Cross House, Cooper street, 
  172.                        Chichester, West Sussex, PO19 1EB, England 
  173.  
  174.  
  175. ΓòÉΓòÉΓòÉ 2. Usage Instructions ΓòÉΓòÉΓòÉ
  176.  
  177. (The following instructions are taken from the OS/2 online Command Reference.) 
  178.  
  179. When the Contents window first appears, some topics have a plus (+) sign beside 
  180. them. The plus sign indicates that additional topics are available. 
  181.  
  182. To expand the Contents if you are using a mouse, click on the plus sign.  If 
  183. you are using the keyboard, use the Up or Down Arrow key to highlight the 
  184. topic, and press the plus (+) key. For example, Keyword Instructions has a plus 
  185. sign beside it. To see the complete list of REXX keyword instructions, click on 
  186. the plus sign or highlight that topic and press the plus (+) key. 
  187.  
  188. To view a topic, double-click on the topic (or press the Up or Down Arrow key 
  189. to highlight the topic, and then press the Enter key). 
  190.  
  191. How to Obtain Additional Information 
  192.  
  193. After you select a topic, the information for that topic appears in a window. 
  194. You will notice that certain words in the text may be specially highlighted 
  195. (The default color for this special highlighting is green). These words are 
  196. links to additional information. If you are using a mouse, double-click on the 
  197. highlighted word.  If you are using a keyboard, press the Tab key to move to 
  198. the highlighted word, and then press the Enter key.  Additional information 
  199. will appear in a pop-up window. 
  200.  
  201. How to Use Action Bar Choices 
  202.  
  203. A number of choices are available for managing information presented in the 
  204. REXX Quick Reference. If you want to see more information about these choices, 
  205. click on the name of the choice (or press the Tab key to move to the choice and 
  206. press Enter). 
  207.  
  208.  Bookmark    Allows you to set a placeholder so you can retrieve information of 
  209.              interest to you. (This choice is available from the Services 
  210.              pull-down). 
  211.  
  212.  Search      Allows you to find occurrences of a word or phrase in the current 
  213.              topic, selected topics, or all topics. (This choice is available 
  214.              from the Services pull-down). 
  215.  
  216.  Print       Allows you to print one or more topics. (This choice is available 
  217.              from the Services pull-down). 
  218.  
  219.  Copy        Allows you to copy a topic you are viewing to a file you can edit. 
  220.              (This choice is available from the Services pull-down). 
  221.  
  222.  Options     Allows you to change the way your Contents is displayed. 
  223.  
  224.  
  225. ΓòÉΓòÉΓòÉ 3. How to Read the Syntax Diagrams ΓòÉΓòÉΓòÉ
  226.  
  227. The first thing you see above a syntax diagram is a list of icons that 
  228. represent the applicable environments for each item. 
  229.  
  230.                 indicates that IBM OS/2 Procedures Language/2 REXX does/doesn't 
  231.                 have this item. 
  232.                 indicates that the IBM mainframe VM implementation of REXX 
  233.                 does/doesn't contain this item. 
  234.                 indicates that the item is/isn't valid in TSO/E REXX. 
  235.                 indicates that this item is/isn't in the SAA Procedures 
  236.                 Language Specification. 
  237.                 indicates that this item is/isn't in M.F.Cowlishaw's REXX book. 
  238.  
  239.  If a particular option or parameter is not supported in every environment, 
  240.  then you will see "X'ed" icons for the unsupported environments.  Language 
  241.  elements that are unique to one particular environment are also shown with a 
  242.  yellow background, as if you had run a highlighting pen over them. 
  243.  
  244.  The symbols are not buttons or hypertext links;  they are just visual clues to 
  245.  the set of environments which implements each item. 
  246.  
  247.  Syntax Diagram 
  248.  
  249.  The syntax diagram shows you how to specify a command so that the REXX 
  250.  interpreter can correctly understand what you typed. These diagrams are 
  251.  sometimes called railroad track diagrams. In general, you can just follow the 
  252.  lines and arrows, and any path you trace will be syntactically valid. The 
  253.  symbol ΓöÇΓöÇ identifies the start of a syntax diagram; ΓöÇΓöÇ pinpoints the end. 
  254.  When a diagram must be continued because it doesn't fit on a single line, the 
  255.  continued line ends in ΓöÇΓöÇ and the continuation begins with ΓöÇΓöÇ . The 
  256.  horizontal line is the main path.  Required parameters are displayed on the 
  257.  main path; optional parameters are displayed below it. 
  258.  
  259.  Parameters are classified as keywords or variables. Keywords are displayed in 
  260.  uppercase letters and must be typed exactly as shown. 
  261.  
  262.  Variables appear in lowercase letters and represent names or values you 
  263.  supply.  A filename is a variable.  Note that a parameter can be a combination 
  264.  of a keyword and a variable. Include all punctuation shown in the diagram, 
  265.  such as colons, semicolons, commas, quotation marks, and equal signs. 
  266.  
  267.  The words in the diagram that appear in a different color are hypertext links 
  268.  to footnotes or other parts of the online reference.  You can tab to them and 
  269.  press Enter to view the related information.  Alternatively, you can double 
  270.  click with the mouse selection button (by default, the left mouse button) to 
  271.  view the same information. 
  272.  
  273.  Specify a Sequence More Than Once: An arrow that returns to a previous point 
  274.  means the sequence of items included by the arrow can be specified more than 
  275.  once. 
  276.  
  277.    ΓöÇΓöÇΓöÇΓöÇPROCEDUREΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇ
  278.                     Γöé          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
  279.                     Γöé                 Γöé Γöé
  280.                     ΓööΓöÇΓöÇEXPOSEΓöÇΓöÇΓö┤ΓöÇnameΓöÇΓöÇΓö┤ΓöÇΓöÿ
  281.  
  282.  Choose One Item from a Stack: A stack of parameters with no return arrow means 
  283.  that you cannot choose more than one from the stack. 
  284.  
  285.    ΓöÇΓöÇNUMERICΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇDIGITSΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇ
  286.                  Γöé         ΓööΓöÇexpressionΓöÇΓöÿ          Γöé
  287.                  Γö£ΓöÇΓöÇFORMΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöñ
  288.                  Γöé        Γö£ΓöÇSCIENTIFICΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
  289.                  Γöé        Γö£ΓöÇENGINEERINGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
  290.                  Γöé        ΓööΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇexpressionΓöÇΓöÿ Γöé
  291.                  Γöé          ΓööΓöÇVALUEΓöÇΓöÿ              Γöé
  292.                  ΓööΓöÇΓöÇFUZZΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  293.                           ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  294.  
  295.  
  296. ΓòÉΓòÉΓòÉ 4. Basic Concepts ΓòÉΓòÉΓòÉ
  297.  
  298. REXX is a programming language that is appropriate for writing command 
  299. procedures and for developing macros for products such as editors, 
  300. communications packages, and data bases. Personal computing tasks are 
  301. conveniently and quickly done in REXX. 
  302.  
  303. REXX was developed at IBM in the early eighties for use on the VM mainframe 
  304. operating system.  Mike Cowlishaw of IBM UK created the REXX language as a 
  305. successor for the existing VM command languages, EXEC and EXEC2.  This is how 
  306. REXX got its name: the Restructured Extended Executor language. 
  307.  
  308. You will be seeing more and more use of REXX as time goes on;  it has been 
  309. designated as the SAA (Systems Application Architecture) standard procedures 
  310. language.  IBM Implementations exist for VM, MVS, OS/2, OS/400, and I think 
  311. AIX. Mansfield Software Group has implementations for OS/2 and DOS.  A variant 
  312. called AREXX is widespread in the AMIGA world. A company called Ix has spent 
  313. the last two years developing multitasking REXX interpreters, written in C, for 
  314. the VM, MVS, PCDOS, UNIX, and OS/2 environments. 
  315.  
  316. In the OS/2 environment, REXX can be used anywhere that the BAT batch language 
  317. could be used - and more. REXX can be used as the macro language for several 
  318. common editors.  REXX is used as the scripting language for several shareware 
  319. and commercial communications products.  REXX can be used with the OS/2 EE 
  320. Database Manager and Query Manager to perform various SQL operations. 
  321.  
  322. You can use REXX as the command and/or macro language with your own products 
  323. and applications.  There is an API that allows any program to interact with 
  324. REXX execs (procedures);  this makes it easy to enhance your application's 
  325. functionality. 
  326.  
  327. You can extend REXX's capabilities with function packages of your own devising; 
  328. these functions you provide, which can be written in any language, are invoked 
  329. just like the builtin REXX functions.  Unfortunately, the SAA specification for 
  330. REXX does not extend to include a standard for function packages or the 
  331. registration and APIs for host command environments. It would be fruitful for 
  332. an SAA or possibly an ANSI standard to address these areas. 
  333.  
  334. The IBM version of REXX for OS/2 is now a component of every copy of OS/2 sold 
  335. (from version 1.3 forward). 
  336.  
  337. The point is that REXX is automatically available on almost every OS/2 machine. 
  338. Once vendors discover that a REXX capability makes their products more 
  339. marketable (because customers need not learn yet another unique language) 
  340. you'll begin to see it everywhere. 
  341.  
  342. REXX is fundamentally an interpreted language.  Some implementations offer a 
  343. partial or complete compilation process as well. There is a REXX compiler for 
  344. VM from IBM. As demand for a compilation feature grows, we are likely to see 
  345. ports of the IBM compiler to OS/2 and MVS.  Sources have indicated that work is 
  346. proceeding on an MVS REXX compiler in Vienna, Austria. 
  347.  
  348.  
  349. ΓòÉΓòÉΓòÉ 4.1. Language Syntax ΓòÉΓòÉΓòÉ
  350.  
  351. REXX programs are built from clauses; the structure of a clause is shown below: 
  352.  
  353.                   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  354.                          Γöé
  355. ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇtokenΓöÇΓö┤ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
  356.      ΓööΓöÇΓöÇblanksΓöÇΓöÇΓöÿ             ΓööΓöÇΓöÇblanksΓöÇΓöÇΓöÿ  ΓööΓöÇend of lineΓöÇΓöÿ
  357.  
  358. It is important to note that the semicolon is optional for the last clause on 
  359. the line;  in some implementations there is actually a performance penalty by 
  360. including the semicolon in this situation. 
  361.  
  362. Tokens 
  363.  
  364.  Comments            The C and PL/I style of /* and */ is used. The comments 
  365.                      may span multiple lines, but may not be nested.  CLIST 
  366.                      writers should note that comments are not terminated by 
  367.                      the end of line. 
  368.  
  369.  Character string literals Either single (') or double (") quotes can be used 
  370.                      to delimit the beginning and end of a string literal. Use 
  371.                      the same delimiter for the end as for the beginning.  If 
  372.                      the delimiter must occur within the literal, then double 
  373.                      it.  The literal should be contained within one line, and 
  374.                      can contain any character. On OS/2, the linefeed character 
  375.                      ('0A'x) cannot be contained within the literal.  On CMS 
  376.                      and TSO/E, the literal can span lines;  however, this is 
  377.                      not a good practice. 
  378.  
  379.                      Examples: 
  380.  
  381.                                           'This is a string literal.'
  382.                                           "So is this."
  383.                                           "Delimiters of one kind won't cause problems inside the other."
  384.                                           'Delimiters of same kind should''ve been doubled.'
  385.  
  386.  Hexadecimal string literals Either single (') or double (") quotes can be used 
  387.                      to delimit the hexadecimal string literal.  Use the same 
  388.                      delimiter for the end as for the beginning.  Follow the 
  389.                      ending delimiter with any case of the letter X. The 
  390.                      literal can contain any sequence take from the digits 0-9, 
  391.                      or any case of the letters A-F. Odd numbers of hex digits 
  392.                      can be used, in which case a leading "0" is assumed. A 
  393.                      nice feature is that blanks can be used within the 
  394.                      literals at byte boundaries (but not at the beginning or 
  395.                      end) to enhance readability. 
  396.  
  397.                      Examples: 
  398.  
  399.                                           '0123456789abcdef'x
  400.                                           "13 10"X
  401.                                           "e3c8c9e2 c9e2 C5C2C3C4C9C3"x
  402.                                           '4159434949'X
  403.  
  404.                                           CAUTION:
  405.                      Don't use "X" as a variable name -- it can cause you 
  406.                      unexpected difficulties, as in: Say "X="x which gives an 
  407.                      error "invalid hexadecimal string." 
  408.  
  409.                      Note:  Be careful when using hexadecimal literals; 
  410.                      dependencies on particular character sets (ASCII or 
  411.                      EBCDIC) or particular codepages (850, 437, etc.) can 
  412.                      greatly impair portability. 
  413.  
  414.  Binary string literals (IBM OS/2, SAA Level 2, and REXX 4.00 only) Either 
  415.                      single (') or double (") quotes can be used to delimit the 
  416.                      binary string literal.  Use the same delimiter for the end 
  417.                      as for the beginning.  Follow the ending delimiter with 
  418.                      any case of the letter B. The literal can contain any 
  419.                      sequence taken from the digits 0 or 1. If the number of 
  420.                      binary digits is not a multiple of four (4), enough 
  421.                      leading "0s" are added to make it so. A nice feature is 
  422.                      that blanks can be used within the literals at byte or 
  423.                      nibble (half-byte) boundaries (but not at the beginning or 
  424.                      end) to enhance readability. 
  425.  
  426.                      Warning: The implementation first examines the "B" 
  427.                      following the literal's ending delimiter to determine that 
  428.                      this is a binary string literal; as a result , any 
  429.                      ordinary character string literal followed immediately by 
  430.                      a token consisting only of the letter "B" is treated as an 
  431.                      invalid binary string literal. 
  432.  
  433.                      Examples: 
  434.  
  435.                                           '1'B       /* same as "0001"b */
  436.                                           "0010101111010100"b
  437.                                           "0010 1011 1101 0100"b /* same as above */
  438.  
  439.  Numbers             Integers, decimals, and exponential notation are used. 
  440.                      Here is the formal definition: 
  441.  
  442.                                            ΓöÇΓö¼ΓöÇΓö¼Γö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γö¼dΓöÇΓöÇΓö¼Γö¼ΓöÇΓö¼Γö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ      where b=blanks
  443.                                               ΓööbΓöÿΓöösΓö¼ΓöÇΓö¼ΓöÿΓö£d.dΓöñΓööbΓöÿΓööEΓö¼ΓöÇΓö¼dΓöÿ               s=sign
  444.                                                    ΓööbΓöÿ Γö£.dΓöÇΓöñ     ΓöösΓöÿ                 d=digits
  445.                                                        Γööd.ΓöÇΓöÿ                         E=E or e
  446.  
  447.                      The number of digits that can be used is determined by the 
  448.                      NUMERIC DIGITS instruction; the default is 9, but there is 
  449.                      no limit to the number of digits that may be specified, 
  450.                      other than total storage. Larger numbers of digits will, 
  451.                      of course, lead to increased execution times. 
  452.  
  453.                      Note:  For some implementations, using a NUMERIC DIGITS 
  454.                      specification less than nine may slow execution. 
  455.  
  456.  Operators           The single character operators are: + - \ / % *  |  &  = 
  457.                      ╨║  >  <. The multiple character operators are: >= ╨║< \< <= 
  458.                      ╨║> \>  ╨║=  \=  <>  ><  //  &&  ||  **  >>  <<  ==  >>= 
  459.                      ╨║<<  \<<  <<=  ╨║>>  \>> ╨║==  \==. The (\) and (╨║) 
  460.                      characters are interchangeable (both mean "not"). 
  461.                      Occurrences of one or more blanks in expressions but not 
  462.                      adjacent to operators (e.g. between symbols and/or 
  463.                      parenthesized sub-expressions) are also an operator 
  464.                      (concatenate with one blank between). Since the (\) is 
  465.                      universally available on modern terminal and personal 
  466.                      computer keyboards and on both mainframe and personal 
  467.                      printers, while the (╨║) is usually available only on IBM 
  468.                      terminal keyboards, usage of the (\) is preferable. Blanks 
  469.                      and comments can be embedded within the multiple character 
  470.                      operators, but for goodness sake, don't code them that 
  471.                      way!  (Just because it's legal doesn't make it right.) 
  472.  
  473.  Special characters  The characters ( ) : , ; and the individual characters 
  474.                      that compose the operators act as special characters: they 
  475.                      delimit tokens, and "suck up" all blanks they are adjacent 
  476.                      to. 
  477.  
  478.  Symbols             Symbols can be numbers, REXX keywords, or names used for 
  479.                      variables, labels, functions, etc.  Names can't begin with 
  480.                      digits or a period. All implementations allow names to 
  481.                      include: a-z A_Z 0-9 underscore(_) exclamation(!) and 
  482.                      question(?).  The period can also be used, but it has a 
  483.                      special meaning concerned with compound symbols. Symbols 
  484.                      are not case sensitive, i.e., lower-case letters in 
  485.                      symbols are translated to upper-case. The VM, MVS , and 
  486.                      TSO environments also support the characters @ #$╨½ in 
  487.                      symbols.  Avoid them for the sake of portability. 
  488.  
  489.  Continued clauses 
  490.  
  491.  End a line with a comma (,) to continue a clause.  Blank or comment tokens may 
  492.  follow this comma.  Clauses cannot be continued within string literals. 
  493.  
  494.  Example: 
  495.  
  496.   Say "first",
  497.          "second"
  498.  
  499.  displays 
  500.  
  501.   first second
  502.  
  503.  Example: 
  504.  
  505.   Say "ABC",
  506.       ||"DEF"
  507.  
  508.  displays 
  509.  
  510.   ABCDEF
  511.  
  512.  
  513. ΓòÉΓòÉΓòÉ 4.2. Expressions ΓòÉΓòÉΓòÉ
  514.  
  515. REXX expressions are sequences of terms, operators, and parentheses (round 
  516. brackets, for those of you in the UK). 
  517.  
  518. Terms are: 
  519.  
  520.  o Literals, which include character strings, hexadecimal strings, binary 
  521.    strings, and numbers. 
  522.  o Variables,which are simple or compound symbols. 
  523.  o Function References, which are the invocation of builtin, internal, or 
  524.    external functions.  They look like this: 
  525.  
  526.         ΓöÇΓö¼ΓöÇsymbol(ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇ
  527.            ΓööΓöÇstring(ΓöÇΓöÿ Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
  528.                        Γöé                 Γöé Γöé
  529.                        ΓööΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÿ
  530.                            ΓööΓöÇexpressionΓöÇΓöÿ
  531.  
  532.    The parameters in a function call are passed by value.  Everything in REXX 
  533.    is a string.  Strings that contain numbers can be manipulated with 
  534.    arithmetic operators, but fundamentally we are still dealing with strings. 
  535.  
  536.  Operators 
  537.  
  538.  o Concatenation 
  539.  
  540.     ||             concatenate (with no blank in between) 
  541.     (juxtaposition)concatenate (with no blank in between) 
  542.     (blanks)       concatenate with just one blank between 
  543.  
  544.                    Examples: 
  545.  
  546.                                       myvar1 = "the"
  547.                                       myvar2 = " time"
  548.                                       say "Now"     "is "myvar||myvar2" for all good men ..."
  549.                                                ΓööΓöÇΓö¼ΓöÇΓöÿ    ΓööΓöñ    Γö£Γöÿ     ΓööΓöñ
  550.                                                         Γöé           ΓööΓöÇΓöÇΓöÇΓöÉ
  551.                                               (blanks)   Γöé   (||)         
  552.                                                                        (juxtaposition)
  553.                                                    (juxtaposition)
  554.  
  555.                    displays: 
  556.  
  557.                                       "Now is the time for all good men ..."
  558.  
  559.  o Arithmetic 
  560.  
  561.     +           add 
  562.     -           subtract 
  563.     *           multiply 
  564.     /           divide 
  565.     %           return an integer quotient from the division 
  566.     //          return the integer remainder from the division.  This is not 
  567.                 the modulus operation, because negative remainders are returned 
  568.                 when the dividend is negative. 
  569.     **          power (only integral exponents) 
  570.     prefix -    negation (like 0 - term ) 
  571.     prefix +    (like 0 + term ) 
  572.  
  573.  o Comparison 
  574.  
  575.    REXX has two sets of comparison operators: the forgiving and the strict. The 
  576.    strict ones do an exact character comparison with no padding. The forgiving 
  577.    ones will do numeric comparisons if both operands are numeric; if not, then 
  578.    leading and trailing blanks are ignored, and the shorter string is padded 
  579.    with blanks on the right.  Comparisons are case sensitive.  Since REXX is a 
  580.    multi-environment language, you should be careful about character set 
  581.    dependencies, e.g., with respect to ASCII vs. EBCDIC. 
  582.  
  583.     - Forgiving 
  584.  
  585.        =                          equal 
  586.        >                          greater than 
  587.        <                          less than 
  588.        >=  or  \<  or  ╨║<         greater than or equal to (same as not less 
  589.                                   than) 
  590.        <=  or  \>  or  ╨║>         less than or equal to (same as not greater 
  591.                                   than) 
  592.        \=  or  ╨║=  or  <>  or  >< not equal 
  593.  
  594.     - Strict 
  595.  
  596.        ==                         equal (C programmers, be careful here) 
  597.        >>                         greater than 
  598.        <<                         less than 
  599.        >>=  or  \<<  or ╨║<<       greater than or equal to (same as not less 
  600.                                   than) 
  601.        <<=  or  \>>  or ╨║>>       less than or equal to (same as not greater 
  602.                                   than) 
  603.        \==  or ╨║==                not equal 
  604.  
  605.  o Logical 
  606.  
  607.    Character strings with a value of zero ("0") have a logical value of false. 
  608.    Character strings with a value of one ("1") have a logical value of true. 
  609.    Any other value for a character string can not be used where a logical value 
  610.    is required. 
  611.  
  612.    C and CLIST programmers should be especially careful with the logical 
  613.    operators -- there can be a high astonishment factor if you let your typing 
  614.    habitstake over when entering the logical operators. 
  615.  
  616.     &              AND returns 1 if both operands are true, else 0 
  617.     |              OR returns 1 if either operand is true, else 0 (inclusive 
  618.                    OR) 
  619.     &&             XOR returns 1 if exactly one operand is true, else 0 
  620.                    (exclusive OR) 
  621.     prefix \       NOT inverts operand; if 1 then 0, else 1 
  622.     prefix ╨║       NOT inverts operand; if 1 then 0, else 1 
  623.  
  624.                    The OR character may appear as a split vertical bar ( | ) or 
  625.                    solid vertical bar ( | ) on the keycap of your keyboard. 
  626.                    OS/2 uses the one that maps to ASCII 124 ("7C"x). 
  627.  
  628.  Evaluation of Expressions 
  629.  
  630.  Terms are evaluated when they are needed, in a left to right order.  The 
  631.  expression is evaluated according to the usual precedence of the operators in 
  632.  the expression: 
  633.  
  634.   1. prefix operators (minus, plus, not) 
  635.   2. exponentiation (power) 
  636.   3. multiplication (multiply, divide, quotient, remainder) 
  637.   4. addition (add, subtract) 
  638.   5. concatenation 
  639.   6. comparison 
  640.   7. logical AND 
  641.   8. logical OR, XOR 
  642.  
  643.  As you would expect, the use of parentheses can effectively change the order 
  644.  of evaluation.  The only thing really different here is that the prefix 
  645.  operators bind more tightly than exponentiation, e.g., -2**4 yields 16, not 
  646.  -16. 
  647.  
  648.  
  649. ΓòÉΓòÉΓòÉ 4.3. Clauses ΓòÉΓòÉΓòÉ
  650.  
  651. REXX has five types of clauses: 
  652.  
  653.  Assignment statements A single clause of the form symbol = expression 
  654.  
  655.  Keyword instructions A series of related clauses that begin with a keyword 
  656.            symbol. E.g., the IF instruction consists of the IF keyword, the 
  657.            IF's condition, the THEN keyword and its clause(s), and the optional 
  658.            ELSE keyword and its clause(s). 
  659.  
  660.  Commands  A single clause consisting of just an expression.  The evaluated 
  661.            expression is passed to an "environment" program, which could be the 
  662.            operating system, a communications program, a data base manager, 
  663.            etc. 
  664.  
  665.  Labels    A symbol followed by a colon defines a label.  Labels are used to 
  666.            identify function or subroutine definitions. There is no GOTO in 
  667.            REXX. 
  668.  
  669.  Null clauses A clause with only blanks or comments; it is ignored.  This is 
  670.            NOT like a null instruction;  you can't just add a semicolon to mean 
  671.            a null operation.  There is a NOP instruction for that purpose (like 
  672.            the "CONTINUE" or "NEXT SENTENCE" in COBOL. 
  673.  
  674.  
  675. ΓòÉΓòÉΓòÉ 4.4. Variables ΓòÉΓòÉΓòÉ
  676.  
  677. Variables are symbols that don't begin with a digit or a period. A variable has 
  678. a value that is a character string; it can hold any characters and be of 
  679. unbounded length.  These character strings can be numbers, and if so, you can 
  680. do arithmetic on them.  Variables do not have to be declared before use, or 
  681. declared at all -- in fact, they cannot be declared. The name of a variable is 
  682. not case sensitive, i.e., the names MyVar, myvar, and MYVAR all refer to the 
  683. same variable MYVAR (C programmers take note). 
  684.  
  685. There are two kinds of variables in REXX: simple and compound. A simple 
  686. variable is just like an ordinary variable you see in other programming 
  687. languages -- it holds a single value.  A compound variable is kind of like an 
  688. array, kind of like a structure, kind of like a hash table, and quite unlike 
  689. variables you may have seen in most other programming languages. 
  690.  
  691. Compound variables are symbols composed of what looks like a simple variable 
  692. name, followed by a period, and then a sequence of other periods and/or valid 
  693. symbol characters. 
  694.  
  695. OneD_Array.12
  696. TwoD_Array.I.J
  697. SymbolTable.Symbol
  698.  
  699. The first part of the compound variable name (up to and including the first 
  700. period) is called the stem.  Compound variables are often referred to as stem 
  701. variables.  The general form of a compound variable is: 
  702.  
  703.               ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  704.                                    Γöé
  705. ΓöÇΓöÇΓöÇstempartΓöÇΓö┤ΓöÇ . ΓöÇΓöÇΓöÇsimplesymbolΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  706.  
  707. When a compound variable is used, the stempart name is converted to all upper 
  708. case, and the value of each simplesymbol is substituted into the name; the 
  709. resulting derived name is then used like an ordinary variable name. You can see 
  710. how it would be easy to use compound variables like multi-dimensional arrays, 
  711. where the sequence of simple symbols after the stempart have numeric values. 
  712. However, you can extend the idea because the simple symbols in the name can 
  713. take on any value!  You can use this powerful concept to create and manipulate 
  714. stacks, queues, deques, heaps, trees, lists, etc. -- properly encapsulated, any 
  715. type of data structure can be created using compound variables. 
  716.  
  717. The following code fragment, part of a word counting and cross-reference 
  718. program, demonstrates a common use of compound variables -- as an array of 
  719. structures, with an content-addressable index into the array: 
  720.  
  721. /* assume user functions exist    */
  722. /* called morewords()             */
  723. /* and nextword()                 */
  724.  
  725. /* no words in list, yet          */
  726. WordListNr = 0
  727.  
  728. /* This initializes ALL variables */
  729. /*     beginning with this stem: */
  730. WordIndex. = ""
  731.  
  732. do while morewords()
  733.   thisword = nextword()
  734.   /* Lookup index for word */
  735.   thisindex = WordIndex.thisword
  736.   if thisindex = "" then do
  737.     /* First occurrence of this word */
  738.     /* Save info in WordList.. array */
  739.     /*     of structures             */
  740.     WordListNr = WordListNr + 1
  741.     WordList.WORDVALUE.WordListNr = thisword
  742.     WordList.WORDCOUNT.WordListNr = 1
  743.     WordIndex.thisword = WordListNr
  744.     end
  745.   else do
  746.     WordList.WORDCOUNT.thisindex = WordList.WORDCOUNT.thisindex + 1
  747.     end
  748.   end /* while morewords() */
  749.  
  750. Uninitialized Variables 
  751.  
  752. Variables that are used before they have been given values are uninitialized; 
  753. the value of an uninitialized simple variable is its own name in upper case. 
  754. Contrast this to other programming languages in which an uninitialized value is 
  755. zero or the null string, or undefined.  E.g., if variable NoInitValue has not 
  756. been initialized, its value is "NOINITVALUE" (like WORDCOUNT and WORDVALUE in 
  757. the example above). 
  758.  
  759. Similarly, the value of an uninitialized compound variable is the value of its 
  760. derived name, in upper case.  E.g., the uninitialized value of FileType.this 
  761. when this = "exe" is "FILETYPE.EXE". 
  762.  
  763.  
  764. ΓòÉΓòÉΓòÉ 4.5. Commands ΓòÉΓòÉΓòÉ
  765.  
  766. The whole reason for REXX is to issue commands  --  commands to the operating 
  767. system, commands to an editor, commands to a communications package, etc. 
  768. Depending on where your REXX exec runs, it will have access to one or more host 
  769. system environments which receive and proccess the commands from your REXX 
  770. exec.  Any program can use a REXX API to register itself as an environment that 
  771. will then be available to REXX execs. 
  772.  
  773. When your REXX exec begins execution, one of these environments is chosen as 
  774. the default environment.  When your exec contains a clause like: 
  775.  
  776. expression
  777.  
  778. it is a command.  The value of the expression is evaluated, and the resulting 
  779. character string is passed to the current host environment. You can send 
  780. commands to more than one environment in the same REXX exec.  See the ADDRESS 
  781. keyword instruction and the ADDRESS( ) builtin function for details. 
  782.  
  783. The default environment in OS/2 is CMD  --  which processes the commands in the 
  784. same way as the OS/2 command processor. Here is an OS/2 example: 
  785.  
  786.  /* assume variable drive = 'C'             */
  787.  /* assume variable directory = 'OS2'       */
  788. 'dir' drive':\'directory'\*'
  789.  /* The command sent to the environment is: */
  790.  /* dir C:\OS2\*                            */
  791.  
  792. It is very important to enclose the parts of your command that are not to be 
  793. evaluated in quotes.  If you do not, REXX thinks you want variable 
  794. substitution, which may not give you the desired results. For example, if the 
  795. command above had been coded as: 
  796.  
  797. dir drive':\'directory'\*'
  798.  
  799. then you would get different results depending on whether a variable called dir 
  800. existed.  If it did not exist, its uninitialized value would be used ("DIR"). 
  801. This would be OK, but if the variable existed and had a value of "erase" then 
  802. the command issued to the environment would be the ERASE command rather than 
  803. the DIR command! 
  804.  
  805. You may see examples of REXX code that are not rigorous about quoting command 
  806. strings;  don't follow their style -- these are sleeping bugs that someday will 
  807. wake up and bite you when a change is made elsewhere in the REXX exec, e.g., to 
  808. begin using dir as a variable name. 
  809.  
  810.  
  811. ΓòÉΓòÉΓòÉ 5. Keyword Instructions ΓòÉΓòÉΓòÉ
  812.  
  813. Keyword instructions provide the structure on which the rest of a REXX program 
  814. hangs; the commands and builtin functions flesh out this skeleton. 
  815.  
  816. For a description of the icons displayed and the syntax diagrams, see How to 
  817. Read These Syntax Diagrams. 
  818.  
  819. In the sections that follow, the REXX keyword instructions are described. The 
  820. respective sections can be jumped to directly by selecting one of the names 
  821. from the list below: 
  822.  
  823.  o ADDRESS - Set Subcommand Environment 
  824.  o ARG - Fetch Argument 
  825.  o CALL - Invoke Subroutine/Function 
  826.  o DO - Begin Block 
  827.  o DROP - Free Variable 
  828.  o EXIT - Terminate Program 
  829.  o IF - Condition Execution 
  830.  o INTERPRET - Execute Variable Statement 
  831.  o ITERATE - Terminate DO-Loop Cycle 
  832.  o LEAVE - Terminate DO-Loop 
  833.  o NOP - No-Operation 
  834.  o NUMERIC - Set Numeric Formats 
  835.  o OPTIONS - Set Language Processor Parameters 
  836.  o PARSE - Fetch and Assign Data 
  837.  o PROCEDURE - Define Internal Subroutine/Function 
  838.  o PULL - Fetch Element From the Head of the Stack 
  839.  o PUSH - Push Element To the Head of the Stack 
  840.  o QUEUE - Push Element to the Tail of the Stack 
  841.  o RETURN - Return From Subroutine/Function 
  842.  o SAY - Display Output 
  843.  o SELECT - Conditional Execution 
  844.  o SIGNAL - Enable/Disable Execption Condition 
  845.  o TRACE - Set Debugging Options 
  846.  o UPPER - Lower to Upper Case Conversion 
  847.  
  848.  
  849. ΓòÉΓòÉΓòÉ 5.1. ADDRESS - Set Subcommand Environment ΓòÉΓòÉΓòÉ
  850.  
  851. The ADDRESS instruction will change the destination of commands, either 
  852. temporarily or permanently. 
  853.  
  854.  ΓöÇΓöÇADDRESSΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇ
  855.               Γö£ΓöÇenvironmentΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöñ
  856.               Γöé             ΓööΓöÇexpressionΓöÇΓöÿ Γöé
  857.               ΓööΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇexpression1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  858.                ΓööΓöÇVALUEΓöÇΓöÿ
  859.  
  860. Related Function: ADDRESS( ) 
  861.  
  862. Use the ADDRESS instruction to issue commands to a host or command environment, 
  863. e.g., OS/2 commands, CMS or TSO commands, ISPEXEC or ISREDIT services.  Many 
  864. products, such as editors and communications packages, "register" their command 
  865. environments for use in REXX procedures.  You can write and register your own 
  866. environments for use with your programs. 
  867.  
  868. Your REXX exec begins executing with one of the environments considered to be 
  869. the default. You can change the environment temporarily to issue one command to 
  870. a different environment, when more than one command environment is available, 
  871. or you can change the environment permanently (until the next ADDRESS 
  872. instruction). Commands that are being issued to the default environment need 
  873. not be preceded by the ADDRESS keyword. 
  874.  
  875. Typical ADDRESS environments: 
  876.  
  877.  o OS/2 
  878.  
  879.     CMD         Used for OS/2 commands, just like in a windowed or full screen 
  880.                 OS/2 command session 
  881.     DSQCIX      Used to send commands to the OS/2 EE Query Manager. 
  882.     ISPCIR      Used to issue OS/2 Dialog Manager services. 
  883.     LPEX        Used in LPEX edit macros to issue commands to the editor. 
  884.                 (LPEX, the Live Parsing Editor, is an IBM PM editor 
  885.                 commercially available only in Europe). 
  886.     SQLDBS      Used to send commands to the OS/2 EE Database Manager. 
  887.  
  888.  o VM 
  889.  
  890.     CMS         Used for CMS commands, just as in the normal interactive mode. 
  891.     COMMAND     Used in "system" EXECs to pass commands directly to CMS via SVC 
  892.                 202, bypassing EXEC or CP cmd search, and without parmlist 
  893.                 translation. 
  894.     XEDIT       Used in XEDIT sessions to issue commands to the editor. 
  895.     ISPEXEC     Used in ISPF sessions to issue ISPF or ISPF/PDF services. 
  896.     ISREDIT     Used in ISPF/PDF Edit macros. 
  897.  
  898.  o TSO 
  899.  
  900.     TSO         Used for TSO/E commands, just as in the normal interactive 
  901.                 mode. 
  902.     MVS         Used in any MVS address space to issue a subset of TSO/E REXX 
  903.                 commands. 
  904.     LINK        Used in any MVS address space to link to any MVS or user module 
  905.                 at the same task level. 
  906.     ATTACH      Used in any MVS address space to attach any MVS or user module 
  907.                 at a daughter task (TCB) level. 
  908.     ISPEXEC     Used in ISPF sessions to issue ISPF or ISPF/PDF services. 
  909.     ISREDIT     Used in ISPF/PDF Edit macros. 
  910.     NETVIEW     Used in NetView Network Management Clists 
  911.  
  912.  Examples: 
  913.  
  914.   ADDRESS CMD 'TYPE C:\CONFIG.SYS'
  915.  
  916.  In this example, the default environment is TSO: 
  917.  
  918.   /* command goes to environment TSO */
  919.   "listdsi" dataset_name_variable
  920.  
  921.   /* command goes to environment ISPEXEC */
  922.   address ispexec "LIBDEF ISPPLIB DATASET ID("dataset_name_variable") COND"
  923.  
  924.   /* command goes to environment TSO     */
  925.   "alloc f(applwork) unit(vio) sp(1) tracks'
  926.  
  927.   /* commands go to environment ISREDIT     */
  928.   address ISREDIT
  929.   "change 'DOS' 'OS/2' all"
  930.   "save"
  931.  
  932.  
  933. ΓòÉΓòÉΓòÉ 5.2. ARG - Fetch Argument ΓòÉΓòÉΓòÉ
  934.  
  935. The ARG instruction parses incoming parameters. 
  936.  
  937.  ΓöÇΓöÇARGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇ
  938.               ΓööΓöÇΓöÇtemplateΓöÇΓöÇΓöÿ
  939.  
  940. Short form of PARSE UPPER ARG. Used to upper-case and receive parameters in an 
  941. exec. 
  942.  
  943. Related Instructions: CALL, PARSE, PROCEDURE 
  944. Related Function: ARG( ) 
  945.  
  946. Example: 
  947.  
  948. /* Suppose that the REXX exec has been
  949.  *     invoked with the parameter:
  950.  *
  951.  * "This string is in MiXeD CaSe."
  952.  */
  953.  
  954. arg first second TheRest
  955.  
  956. /* Contents of variables
  957.  *     after the ARG instruction:
  958.  *
  959.  * first   : "THIS"
  960.  * second  : "STRING"
  961.  * TheRest : "IS IN MIXED CASE."
  962.  */
  963.  
  964.  
  965. ΓòÉΓòÉΓòÉ 5.3. CALL - Invoke Subroutine/Function ΓòÉΓòÉΓòÉ
  966.  
  967. The CALL instruction invokes an internal routine (contained in the same 
  968. exec/program), or a builtin REXX function, or an external routine (located 
  969. elsewhere -- details differ by operating system).  CALL also is used for 
  970. enabling and disabling condition traps for error recovery. 
  971.  
  972.  ΓöÇΓöÇCALLΓöÇΓöÇΓö¼ΓöÇΓöÇnameΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇ
  973.            Γöé            Γöé  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ       Γöé
  974.            Γöé            Γöé                    Γöé       Γöé
  975.            Γöé            ΓööΓöÇΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  976.            Γöé                 ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ         Γöé
  977.            Γöé                                          Γöé
  978.            Γö£ΓöÇΓöÇOFFΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇERRORΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  979.            Γöé            Γö£ΓöÇΓöÇFAILUREΓöÇΓöÇΓöñ                 Γöé
  980.            Γöé            Γö£ΓöÇΓöÇHALTΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                 Γöé
  981.            Γöé            ΓööΓöÇΓöÇNOTREADYΓöÇΓöÿ                 Γöé
  982.            Γöé                                          Γöé
  983.            ΓööΓöÇΓöÇONΓöÇΓöÇΓö¼ΓöÇΓöÇERRORΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
  984.                   Γö£ΓöÇΓöÇFAILUREΓöÇΓöÇΓöñ ΓööΓöÇΓöÇNAMEΓöÇΓöÇtrapnameΓöÇΓöÇΓöÿ
  985.                   Γö£ΓöÇΓöÇHALTΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  986.                   ΓööΓöÇΓöÇNOTREADYΓöÇΓöÿ
  987.  
  988. Related Instructions: ARG, PARSE, PROCEDURE, SIGNAL 
  989. Related Functions: ARG( ), CONDITION( ) 
  990.  
  991. A routine can alternatively be invoked as a function reference, if it is 
  992. defined as returning a result;  the function reference can be used any where 
  993. that an expression can: 
  994.  
  995.  ΓöÇΓöÇname(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇ
  996.            Γöé  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ       Γöé
  997.            Γöé                    Γöé       Γöé
  998.            ΓööΓöÇΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  999.                 ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  1000.  
  1001. Note:  The name and the left parenthesis in the above MUST be adjacent (no 
  1002. intervening blank) or else REXX will see this not as a function reference but a 
  1003. blank operator between two string expressions. 
  1004.  
  1005. When a routine returns a result, but has been invoked with the CALL syntax, the 
  1006. returned result is still accessible to the caller in the special variable 
  1007. RESULT. If the called routine did NOT return a result, then the RESULT variable 
  1008. is dropped, i.e., becomes uninitialized (its value = "RESULT"). 
  1009.  
  1010. Recursive calls are supported;  in fact, in OS/2, you cannot invoke a REXX 
  1011. program from a REXX program via the command environment -- you must use the 
  1012. CALL instruction. It is possible to invoke builtin functions in this way, but 
  1013. strange terminations of the REXX exec usually happen. 
  1014.  
  1015. There is some overloading on CALL in REXX: as you can see above in the syntax 
  1016. diagram, CALL is used both for invoking routines and for setting error recovery 
  1017. options.  When a condition has been enabled, as in: 
  1018.  
  1019. call on error name MyError
  1020.  
  1021. then should the ERROR condition be raised, the routine MyError will be called. 
  1022. It could take some action and return, or exit (terminate the entire REXX 
  1023. program). 
  1024.  
  1025. Parameters: 
  1026.  
  1027.  name          A symbol or string literal that names the routine to be called. 
  1028.                The search order for finding the routine is: 
  1029.  
  1030.      1. internal routine 
  1031.      2. external routine 
  1032.      3. builtin function 
  1033.  
  1034.         When a string literal is used, internal routines are not invoked, only 
  1035.         external or builtin routines are called. The string literal should be 
  1036.         in upper case because builtin routines and external routines in most 
  1037.         environments must be in upper case. 
  1038.  
  1039.  ON            Enables the named condition. 
  1040.  
  1041.  OFF           Disables the named condition. 
  1042.  
  1043.  ERROR         The ERROR condition is raised if an environment command 
  1044.                indicates an error upon its return to REXX, or if it indicates a 
  1045.                failure and the FAILURE condition is not enabled. 
  1046.  
  1047.  FAILURE       The FAILURE condition is raised if an environment command 
  1048.                indicates a failure upon its return to REXX. 
  1049.  
  1050.  HALT          The HALT condition is raised if an external attempt is made to 
  1051.                halt the REXX program. In OS/2, this is not implemented for REXX 
  1052.                programs invoked from the command session. 
  1053.  
  1054.  NOTREADY      The NOTREADY condition is only valid in OS/2; this condition is 
  1055.                raised if there is an error during an I/O operation. 
  1056.  
  1057.  trapname      The name of a routine to be called when the associated condition 
  1058.                is raised. 
  1059.  
  1060.  Example: 
  1061.  
  1062.    ...
  1063.   call fcn dataset, member
  1064.   valuefromfcn = RESULT
  1065.    ...
  1066.   fcn: procedure
  1067.   arg dsn, mbr
  1068.    ...
  1069.   return somevalue
  1070.  
  1071.  
  1072. ΓòÉΓòÉΓòÉ 5.4. DO - Begin Block ΓòÉΓòÉΓòÉ
  1073.  
  1074. The DO instruction (and it's paired END keyword) bracket a block of 
  1075. instructions that can be executed repetitively. 
  1076.  
  1077.  ΓöÇDOΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ;ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ENDΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼;ΓöÇ
  1078.        ΓöörepetitorΓöÿ ΓööconditionalΓöÿ   ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé    ΓööΓöÇsymbolΓöÿ
  1079.                                    Γöé              ΓöéΓöé
  1080.                                    ΓööΓö┤ΓöÇinstructionsΓöÇΓö┤Γöÿ
  1081.  
  1082.      repetitor:
  1083.  
  1084.         ΓöÇΓöÇΓö¼ΓöÇname=expriΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇ
  1085.             Γöé            ΓööTOΓöÇexprtΓöÿ ΓööBYΓöÇexprbΓöÿ ΓööFORΓöÇexprfΓöÿ Γöé
  1086.             Γö£ΓöÇΓöÇFOREVERΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1087.             ΓööΓöÇΓöÇexprrΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  1088.  
  1089.      conditional:
  1090.  
  1091.         ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇWHILEΓöÇexprwΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ
  1092.                ΓööΓöÇUNTILΓöÇexpruΓöÇΓöÇΓöÿ
  1093.  
  1094. Related Instructions: ITERATE, LEAVE, NUMERIC 
  1095.  
  1096. For C programmers, this is like while (condition) { ... } and for 
  1097. (initial;condition;repetitor) { ... } all rolled into one instruction. 
  1098.  
  1099. Used to control the looping of instructions. Note that REXX, unlike other 
  1100. languages, does NOT allow the use of both the WHILE and UNTIL keywords in the 
  1101. same DO statement. 
  1102.  
  1103. The exprr, exprw and expru expressions must evaluate to 1 or 0 (true or false). 
  1104.  
  1105. The DO must have a matching END keyword. 
  1106.  
  1107. Example: 
  1108.  
  1109. do i = 1 to CellNr by 2 until Cell.i = 'empty'
  1110.    end
  1111.  
  1112. Control Flow in a DO Loop 
  1113.  
  1114.            Evaluate expi, expt, expb
  1115.                       Γöé
  1116.                       
  1117.                 DO name=expi
  1118.                       Γöé
  1119.                       
  1120.            ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇTO exprtΓöÇΓöÇΓöÇΓöÇEND
  1121.            Γöé          Γöé
  1122.            Γöé          
  1123.            Γöé     FOR exprfΓöÇΓöÇΓöÇΓöÇEND
  1124.            Γöé          Γöé
  1125.            Γöé          
  1126.            Γöé    WHILE exprwΓöÇΓöÇΓöÇEND
  1127.            Γöé          Γöé
  1128.            Γöé          
  1129.            Γöé    instruction(s)
  1130.            Γöé          Γöé
  1131.            Γöé          
  1132.            Γöé    UNTIL expruΓöÇΓöÇΓöÇEND
  1133.            Γöé          Γöé
  1134.            Γöé          
  1135.            Γöé      BY exprb
  1136.            ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  1137.  
  1138.  
  1139. ΓòÉΓòÉΓòÉ 5.5. DROP - Free Variable ΓòÉΓòÉΓòÉ
  1140.  
  1141. The DROP instruction unassigns variables;  restores them to their original 
  1142. uninitialized state. 
  1143.  
  1144.               ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  1145.                              Γöé
  1146.  ΓöÇΓöÇΓöÇΓöÇDROPΓöÇΓöÇΓöÇΓö┤Γö¼ΓöÇΓöÇΓöÇΓöÇnameΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1147.                ΓööΓöÇ(name-expr)ΓöÇΓöÿ
  1148.  
  1149. Related Instruction: PROCEDURE 
  1150.  
  1151. It's OK to specify the names of variables that are uninitialized already. 
  1152.  
  1153. If an exposed variable is named via PROCEDURE EXPOSE, the variable in the older 
  1154. generation is dropped. 
  1155.  
  1156. CAUTION:
  1157. In some environments, excessive use of DROP can slow the execution. 
  1158.  
  1159. Example: 
  1160.  
  1161. a = "This is a"
  1162. b = "variable B here"
  1163. c = "a C variable"
  1164. d = "a b"
  1165. e.1 = "E sub 1"
  1166. drop (d) c e.
  1167. say "a   = " a
  1168. say "b   = " b
  1169. say "c   = " c
  1170. say "d   = " d
  1171. say "e.1 = " e.1
  1172.  
  1173. Output 
  1174.  
  1175. a   = A    /* uninitialized value */
  1176. b   = B    /* uninitialized value */
  1177. c   = C    /* uninitialized value */
  1178. d   = a b
  1179. e.1 = E.1  /* uninitialized value */
  1180.  
  1181. The variables in a list are dropped in order, left to right. 
  1182.  
  1183. Example: 
  1184.  
  1185. a = "This is a"
  1186. b = "variable B here"
  1187. c = "a C variable"
  1188. d = "a b"
  1189. e.1 = "E sub 1"
  1190. drop d (d) c e.
  1191. say "a   = " a
  1192. say "b   = " b
  1193. say "c   = " c
  1194. say "d   = " d
  1195. say "e.1 = " e.1
  1196.  
  1197. Output 
  1198.  
  1199. a   = This is a
  1200. b   = variable B here
  1201. c   = C               /* uninitialized value */
  1202. d   = D               /* uninitialized value */
  1203. e.1 = E.1             /* uninitialized value */
  1204.  
  1205.  
  1206. ΓòÉΓòÉΓòÉ 5.6. EXIT - Terminate Program ΓòÉΓòÉΓòÉ
  1207.  
  1208. The EXIT instruction leaves a REXX program; an optional expression is returned 
  1209. in the caller's REXX variable named RESULT. 
  1210.  
  1211.  ΓöÇΓöÇΓöÇΓöÇEXITΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1212.               ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  1213.  
  1214. Related Instruction: RETURN 
  1215.  
  1216. A REXX program that is intended to be invoked as an external function must 
  1217. return a result.  EXIT in an internal routine terminates the whole program. 
  1218.  
  1219. Note:  On VM, the optional expression is returned to caller upon termination 
  1220. (not in RESULT). 
  1221.  
  1222.  
  1223. ΓòÉΓòÉΓòÉ 5.7. IF - Conditional Execution ΓòÉΓòÉΓòÉ
  1224.  
  1225. Use to control execution sequencing;  can be nested to accommodate complex 
  1226. conditional logic. 
  1227.  
  1228.  ΓöÇIFΓöÇexpressionΓöÇΓö¼ΓöÇΓö¼THENΓöÇΓö¼ΓöÇΓö¼instructionΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
  1229.                   Γöö;Γöÿ     Γöö;Γöÿ            ΓööΓöÇELSEΓöÇΓö¼ΓöÇΓö¼instructionΓöÿ
  1230.                                                 Γöö;Γöÿ
  1231.  
  1232. Note:  If you need a "null" instruction, you must use the NOP instruction. 
  1233. Simply coding a blank line, or adjacent semicolons (;;) does NOT work as in 
  1234. PL/I. 
  1235.  
  1236. Most of the semicolons in the syntax for IF are optional; this is a syntactic 
  1237. sugaring that makes writing REXX programs easier for those who also work in 
  1238. other languages.  Imagine what would happen if the semicolon after the THEN 
  1239. were required! 
  1240.  
  1241. A result of this convenience is that a variable named THEN cannot be used in 
  1242. the expression of an IF instruction. This doesn't constitute a hardship, as any 
  1243. programmer who names variables this way should be shot, anyway. 
  1244.  
  1245.  
  1246. ΓòÉΓòÉΓòÉ 5.8. INTERPRET - Execute Variable Statement ΓòÉΓòÉΓòÉ
  1247.  
  1248. The INTERPRET is used to dynamically interpret sequences of REXX instructions, 
  1249. and to perform multiple levels of symbolic substitution. 
  1250.  
  1251.  ΓöÇΓöÇΓöÇΓöÇINTERPRETΓöÇΓöÇΓöÇΓöÇexpressionΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1252.  
  1253. This can be tricky, but is powerful when necessary.  Overuse of INTERPRET makes 
  1254. programs HARD to read, and thus hard to maintain.  Real world examples could 
  1255. include usage to invoke subroutines whose names are not known until run time. 
  1256. Could be used in this way to crudely implement some aspects of object oriented 
  1257. methods. 
  1258.  
  1259. The REXX instruction or instructions in the expression of an INTERPRET 
  1260. instruction must be syntactically complete, i.e., no unpaired DO loops, etc. 
  1261. Labels can be coded in these instructions, but are ignored, so don't use them. 
  1262.  
  1263. Programmers used to other languages, especially TSO CLISTs, tend to use 
  1264. INTERPRET as a substitute for REXX compound variables.  This is not as 
  1265. efficient, and stylistically is at variance with the mainstream of REXX 
  1266. programming. 
  1267.  
  1268. Example: 
  1269.  
  1270. things_to_do = "do 5; say 'Hi there ...'; end"
  1271. INTERPRET things_to_do
  1272.  
  1273. Output 
  1274.  
  1275. Hi there ...
  1276. Hi there ...
  1277. Hi there ...
  1278. Hi there ...
  1279. Hi there ...
  1280.  
  1281.  
  1282. ΓòÉΓòÉΓòÉ 5.9. ITERATE - Terminate DO-Loop Cycle ΓòÉΓòÉΓòÉ
  1283.  
  1284. The ITERATE instruction is used in DO loops; it is like transferring to the 
  1285. bottom of current loop, then cycling. 
  1286.  
  1287.  ΓöÇΓöÇΓöÇΓöÇITERATEΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1288.                ΓööΓöÇnameΓöÇΓöÿ
  1289.  
  1290. Related Instructions: DO, LEAVE 
  1291.  
  1292. Used to control flow in DO loops;  a special purpose substitute for GOTO. 
  1293.  
  1294. Example: 
  1295.  
  1296. /* copy a file, omitting blank lines */
  1297. arg infile outfile
  1298. call lineout outfile,,1     /* position to start of file */
  1299. do while lines(infile) \= 0
  1300.   line = linein(infile)
  1301.   if line = "" then iterate
  1302.   call lineout outfile, line
  1303.   end
  1304.  
  1305.  
  1306. ΓòÉΓòÉΓòÉ 5.10. LEAVE - Terminate DO-Loop ΓòÉΓòÉΓòÉ
  1307.  
  1308. The LEAVE instruction leaves the innermost DO loop, or the named DO loop. 
  1309.  
  1310.  ΓöÇΓöÇΓöÇΓöÇLEAVEΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1311.                 ΓööΓöÇnameΓöÇΓöÿ
  1312.  
  1313. Related Instructions: DO, ITERATE, EXIT, RETURN 
  1314.  
  1315. Use to control flow in DO loops;  a special purpose substitute for GOTO. 
  1316.  
  1317. Example: 
  1318.  
  1319. /* compute the next "perfect" number  */
  1320. /* (number = sum of its divisors,     */
  1321. /* excluding itself, but including 1) */
  1322. arg startnum
  1323. if startnum // 1 \= 0 then do
  1324.     say "Starting number must be an integer."
  1325.     exit 1
  1326.     end
  1327. if startnum <= 0 then do
  1328.     say "Starting number must be positive."
  1329.     exit 1
  1330.     end
  1331. currnum = startnum + 1
  1332. do while 1
  1333.     sum = 0
  1334.     do i = 1 to currnum - 1
  1335.         if currnum // i = 0 then
  1336.             sum = sum + i
  1337.         end
  1338.     if sum = currnum then leave
  1339.     say currnum sum
  1340.     currnum = currnum + 1
  1341.     end
  1342. say "The next perfect number, starting after" startnum", is" currnum"."
  1343. exit 0
  1344.  
  1345.  
  1346. ΓòÉΓòÉΓòÉ 5.11. NOP - No-Operation ΓòÉΓòÉΓòÉ
  1347.  
  1348. Does nothing - a placeholder, like "CONTINUE" or "NEXT SENTENCE" in COBOL. 
  1349.  
  1350.  ΓöÇΓöÇΓöÇΓöÇNOPΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1351.  
  1352. Example: 
  1353.  
  1354. Say "Enter a positive integer"
  1355. pull I
  1356. if I > 0 then nop
  1357. else do
  1358.   say 'Number must be positive.'
  1359.   exit
  1360.   end
  1361. if I // 1 = 0 then nop
  1362. else do
  1363.   say 'Number must be an integer.'
  1364.   exit
  1365.   end
  1366. do forever
  1367.     /* always stops;
  1368.      * can you PROVE it does?
  1369.      */
  1370.     say I
  1371.     if I=1 then leave
  1372.     if I//2 = 0 then do
  1373.         I = I/2
  1374.         iterate
  1375.         end
  1376.     I = (3*I + 1)/2
  1377.     end
  1378.  
  1379.  
  1380. ΓòÉΓòÉΓòÉ 5.12. NUMERIC - Set Numeric Formats ΓòÉΓòÉΓòÉ
  1381.  
  1382. The NUMERIC instruction changes the way in which arithmetic is done: precision 
  1383. of numbers, format of display, and accuracy of comparison. 
  1384.  
  1385.  ΓöÇΓöÇNUMERICΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇDIGITSΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇ
  1386.                Γöé         ΓööΓöÇexpressionΓöÇΓöÿ          Γöé
  1387.                Γö£ΓöÇΓöÇFORMΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöñ
  1388.                Γöé        Γö£ΓöÇSCIENTIFICΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
  1389.                Γöé        Γö£ΓöÇENGINEERINGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
  1390.                Γöé        ΓööΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇexpressionΓöÇΓöÿ Γöé
  1391.                Γöé          ΓööΓöÇVALUEΓöÇΓöÿ              Γöé
  1392.                ΓööΓöÇΓöÇFUZZΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  1393.                         ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  1394.  
  1395. Default DIGITS is 9;  max DIGITS is implementation dependent, but usually 
  1396. bigger than you have any reasonable excuse to use (e.g., 9999 digits!). 
  1397.  
  1398. Use to control precision of arithmetic results; to specify display format of 
  1399. floating point numbers; to indicate how close floating point numbers have to be 
  1400. before they are considered equal in comparisons (the "fuzz"). 
  1401.  
  1402. NUMERIC settings are saved across subroutine and internal function calls. 
  1403.  
  1404. Note:  A high value for digits adversely affects performance; non-intuitively, 
  1405. a value less than nine in 32-bit environments also hurts performance (e.g., in 
  1406. TSO). 
  1407.  
  1408. Note:  On VM, the FORM keyword is only valid with options SCIENTIFIC and 
  1409. ENGINEERING for releases before VM/SP Release 6. 
  1410.  
  1411.  
  1412. ΓòÉΓòÉΓòÉ 5.13. OPTIONS - Set Language Processor Parameters ΓòÉΓòÉΓòÉ
  1413.  
  1414. The OPTIONS instruction is for notifying the REXX language processor about the 
  1415. user's choice for particular implementation options. 
  1416.  
  1417.  ΓöÇΓöÇΓöÇΓöÇOPTIONSΓöÇΓöÇΓöÇΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇ
  1418.  
  1419. The SAA REXX processors use this instruction in support of DBCS. (DBCS is 
  1420. Double Byte Character Set, for use with natural languages like Japanese or 
  1421. Chinese with enormous numbers of unique glyphs.) 
  1422.  
  1423. Valid expressions in TSO, VM and OS/2 are: 
  1424.  
  1425.  ETMODE         enables use of DBCS strings 
  1426.  NOETMODE       disables use of DBCS strings 
  1427.  EXMODE         preserves logical DBCS character integrity 
  1428.  NOEXMODE       byte basis; DBCS integrity not guaranteed (default) 
  1429.  
  1430.  Other processors use this instruction for run-time support. The VM REXX 
  1431.  compiler uses this instruction to specify compile options. 
  1432.  
  1433.  
  1434. ΓòÉΓòÉΓòÉ 5.14. PARSE - Fetch and Assign Data ΓòÉΓòÉΓòÉ
  1435.  
  1436. The PARSE instruction extracts data into one or more variables from arguments, 
  1437. variables, and other sources. 
  1438.  
  1439.  ΓöÇΓöÇPARSEΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇARGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ;ΓöÇ
  1440.            ΓööΓöÇUPPERΓöÇΓöÿ Γö£ΓöÇΓöÇEXTERNALΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓööΓöÇtemplateΓöÇΓöÿ
  1441.                      Γö£ΓöÇΓöÇNUMERICΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1442.                      Γö£ΓöÇΓöÇLINEINΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1443.                      Γö£ΓöÇΓöÇPULLΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1444.                      Γö£ΓöÇΓöÇSOURCEΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1445.                      Γö£ΓöÇΓöÇVALUEΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇWITHΓöÇΓöñ
  1446.                      Γöé        ΓööΓöÇexpressionΓöÇΓöÿ      Γöé
  1447.                      Γö£ΓöÇΓöÇVARΓöÇΓöÇnameΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1448.                      ΓööΓöÇΓöÇVERSIONΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  1449.  
  1450. Note:  EXTERNAL and NUMERIC are TSO and VM only; LINEIN is OS/2 only. 
  1451.  
  1452. Related Instructions: ARG, PULL 
  1453. Related Function: LINEIN( ) 
  1454.  
  1455. PARSE is a powerful text pattern matching/extraction instruction used to parse 
  1456. words/parameters/keywords in arguments, from terminal input, from variables;  a 
  1457. variety of matching and positional templates are available. 
  1458.  
  1459. You can use PARSE SOURCE and PARSE VERSION to write multi-environment REXX 
  1460. procedures that execute on all systems, under all implementations. 
  1461.  
  1462. PARSE ARG 
  1463.  
  1464. The string(s) passed to the program, subroutine, or function as input arguments 
  1465. are parsed. To parse multiple argument strings, multiple templates must be 
  1466. supplied seperated by commas. For example: 
  1467.  
  1468. parse arg arg1, arg2, , arg4
  1469.  
  1470. assigns the first argument string to arg1, the second argument to arg2 and the 
  1471. fourth argument to arg4. 
  1472.  
  1473. PARSE EXTERNAL 
  1474.  
  1475. Reads from the user's terminal (the standard input stream). 
  1476.  
  1477. PARSE NUMERIC 
  1478.  
  1479. Parses the current numeric controls (as set by the NUMERIC statement. For 
  1480. example: 
  1481.  
  1482. parse numeric var1
  1483.  
  1484. might set var1 to the value "9 0 SCIENTIFIC". 
  1485.  
  1486. PARSE LINEIN 
  1487.  
  1488. The next line from the default input stream is parsed. If no line is available 
  1489. execution pauses until one becomes available. This is a short form of PARSE 
  1490. VALUE LINEIN() WITH template. 
  1491.  
  1492. PARSE PULL 
  1493.  
  1494. The next line from the default queue is parsed. If the queue is empty a line is 
  1495. read from the default input stream. 
  1496.  
  1497. PARSE SOURCE 
  1498.  
  1499. The SOURCE consists of a list of tokens that describe the origin of the 
  1500. procedure being executed. The first token is CMS or TSO or OS/2; Second is 
  1501. COMMAND, or SUBROUTINE or FUNCTION;  the rest differ according to the 
  1502. environment and the implementation: 
  1503.  
  1504.  OS/2              fully qualified file name of procedure 
  1505.  
  1506.  CMS Compiler      file name or syn 
  1507.                    file type; * if running as MODULE 
  1508.                    file mode; * if running as MODULE 
  1509.                    name invoked as or syn or ? 
  1510.                    default address env 
  1511.  
  1512.  CMS Interpreter   file name 
  1513.                    file type or * 
  1514.                    file mode or * 
  1515.                    name invoked as or syn or ? 
  1516.                    default address env 
  1517.  
  1518.  TSO               name of exec in upper case or ? 
  1519.                    name of DDNAME fo exec or ? 
  1520.                    name of data set for exec, or ? 
  1521.                    name of exec as invoked, or ? 
  1522.                    default address env 
  1523.                    name of address space 
  1524.                    8 character user-specified token 
  1525.  
  1526.  PARSE VALUE 
  1527.  
  1528.  The expression is parsed with the specified template. 
  1529.  
  1530.  PARSE VAR 
  1531.  
  1532.  The name REXX variable is parsed with the specified template. 
  1533.  
  1534.  PARSE VERSION 
  1535.  
  1536.  The VERSION string consists of five tokens in three groups: 
  1537.  
  1538.   1. A word naming the implementation of the language.  It must begin with the 
  1539.      four characters "REXX," and the rest can be any characters valid in a 
  1540.      symbol. 
  1541.  
  1542.     REXXSAA      OS/2 
  1543.     REXX370      TSO, TSO/E, VM interpreter 
  1544.     REXXC370     VM CMS REXX compiler 
  1545.  
  1546.   2. The language level of the REXX implementation: 
  1547.  
  1548.     4.00    OS/2, the Cowlishaw book (2nd edition) 
  1549.     3.46    CMS Release 6 with SPE 
  1550.             TSO/E Version  2 Release 1 with an APAR, TSO/E V2R1.1 
  1551.             CMS Compiler 
  1552.     3.45    CMS Release 6 
  1553.             TSO/E V2R1 
  1554.     3.40    CMS Releases 4, 5 and 5.5 
  1555.     3.20    CMS Release 3 (original) 
  1556.  
  1557.   3. The date of the implementation, in three tokens: 
  1558.  
  1559.     06 Feb 1990     OS/2 
  1560.  
  1561.  Example: (pull off one word at a time) 
  1562.  
  1563.   do until bigstring = ""
  1564.       PARSE VARIABLE bigstring oneword bigstring
  1565.       say oneword
  1566.       end
  1567.  
  1568.  Example: (multiple parallel assignment) 
  1569.  
  1570.   PARSE VALUE '1 10 100' WITH one ten hundred
  1571.   /* assigns '1'   to variable "one"     */
  1572.   /* assigns '10'  to variable "ten"     */
  1573.   /* assigns '100' to variable "hundred" */
  1574.  
  1575.  Example: (assignment of one value to multiple variables) 
  1576.  
  1577.   xyz = "same value"
  1578.   PARSE VAR xyz 1 copy1 1 copy2 1 copy3
  1579.   /* assigns "same value" to variable "copy1" */
  1580.   /* assigns "same value" to variable "copy2" */
  1581.   /* assigns "same value" to variable "copy3" */
  1582.  
  1583.  Note:  If you are coding in a TSO/E environment and need to replace a CLIST 
  1584.  that used "PROC" statement parameter parsing, you will find that there is no 
  1585.  convenient way to do this in REXX.  Until someone writes a public domain 
  1586.  external function to do this in a general way, or until IBM decides to remedy 
  1587.  this obvious hole in TSO/E REXX functionality, the easiest way to accomplish 
  1588.  this is to retain a shell of the original CLIST, that contains the original 
  1589.  CLIST PROC statement (to perform the parsing and prompting).  The only other 
  1590.  statement in the CLIST would be an invocation of the REXX exec, passing the 
  1591.  parsed parameters in a manner convenient to the exec. 
  1592.  
  1593.  
  1594. ΓòÉΓòÉΓòÉ 5.15. PROCEDURE - Define Internal Subroutine/Function ΓòÉΓòÉΓòÉ
  1595.  
  1596. The PROCEDURE instruction defines a scoping level for variables, i.e., 
  1597. variables used within the routine are local to the routine, and hiding all 
  1598. variables in the calling routine from query or update by this routine. 
  1599.  
  1600.  ΓöÇΓöÇΓöÇΓöÇPROCEDUREΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇ
  1601.                   Γöé          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
  1602.                   Γöé                 Γöé Γöé
  1603.                   ΓööΓöÇΓöÇEXPOSEΓöÇΓöÇΓö┤ΓöÇnameΓöÇΓöÇΓö┤ΓöÇΓöÿ
  1604.  
  1605. Related Instructions: CALL, RETURN 
  1606.  
  1607. PROCEDURE begins an internal procedure or function; EXPOSE gives access to 
  1608. selected variables in the containing procedure. 
  1609.  
  1610. You use this to control the scoping of variables in procedures and functions; 
  1611. internal procedures should ususally be specified with this instruction, and the 
  1612. EXPOSE operand should be used judiciously.  Although internal routines do not 
  1613. have to begin with the PROCEDURE instruction, seldom is it warranted to omit 
  1614. it. 
  1615.  
  1616. A variety of tricks and useful techniques are based on the fact that one level 
  1617. of substitution can be performed in the EXPOSE clause prior to establishing the 
  1618. exposed variable names.  Another trick is to use a stem in the EXPOSE 
  1619. statement. 
  1620.  
  1621. Example: 
  1622.  
  1623. GlobalVariables = "MyVariable HisVariable CompoundVariables."
  1624.  ...
  1625. TestObjectVariables = "TestMode TestName TestConditions. TestNr"
  1626. call TestProcedure
  1627.  ...
  1628. TestProcedure: procedure expose (GlobalVariables) (TestObjectVariables)
  1629.  
  1630. In the example above, the values of GlobalVariables and TestObjectVariables are 
  1631. substituted prior to determining which variables are to be exposed.  Thus, all 
  1632. of the following variables are exposed in the procedure TestProcedure: 
  1633. MyVariable, HisVariable, all compund forms of CompoundVariables., TestMode, 
  1634. TestName, all compound forms of TestConditions., and TestNr. 
  1635.  
  1636.  
  1637. ΓòÉΓòÉΓòÉ 5.16. PULL - Fetch Element From the Head of the Stack ΓòÉΓòÉΓòÉ
  1638.  
  1639. The PULL instructions is used to obtain line mode input from the currently 
  1640. active REXX queue;  usually the command line or the terminal. 
  1641.  
  1642.  ΓöÇΓöÇPULLΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇ
  1643.               ΓööΓöÇΓöÇtemplateΓöÇΓöÇΓöÿ
  1644.  
  1645. Related Instructions: PARSE, PUSH, QUEUE 
  1646. Related Functions: QUEUED( ), RXQUEUE( ) 
  1647.  
  1648. This is short for PARSE UPPER PULL. 
  1649.  
  1650. Example: 
  1651.  
  1652. say "Please enter your name:"
  1653. pull input
  1654. say "Howdy," input"!"
  1655.  
  1656.  
  1657. ΓòÉΓòÉΓòÉ 5.17. PUSH - Push Element To the Head of the Stack ΓòÉΓòÉΓòÉ
  1658.  
  1659. The PUSH instruction places an expression on top of the REXX queue. 
  1660.  
  1661.  ΓöÇΓöÇPUSHΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇ
  1662.               ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  1663.  
  1664. Related Instructions: PULL, QUEUE 
  1665. Related Functions: QUEUED( ), RXQUEUE( ) 
  1666.  
  1667. The expression goes on top of the queue in LIFO (Last in, first out) order. You 
  1668. can use to push a value on data stack for later use by a subroutine or I/O 
  1669. routines. 
  1670.  
  1671. Example: 
  1672.  
  1673. push "Simon Nash"
  1674. push "Linda Green"
  1675. push "Herr VandeWater"
  1676. do while queued( ) \= 0
  1677.     call NameRoutine
  1678.     end
  1679. exit
  1680. NameRoutine: procedure
  1681. pull input
  1682. say "Howdy," input"!"
  1683. return
  1684.  
  1685. Output 
  1686.  
  1687. Howdy, HERR VANDEWATER!
  1688. Howdy, LINDA GREEN!
  1689. Howdy, SIMON NASH!
  1690.  
  1691.  
  1692. ΓòÉΓòÉΓòÉ 5.18. QUEUE - Push Element To the Tail of the Stack ΓòÉΓòÉΓòÉ
  1693.  
  1694. The QUEUE instruction places an expression on the bottom of the REXX queue. 
  1695.  
  1696.  ΓöÇΓöÇQUEUEΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇ
  1697.               ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  1698.  
  1699. Related Instructions: PARSE, PULL, PUSH, QUEUE 
  1700. Related Functions: QUEUED( ), RXQUEUE( ) 
  1701.  
  1702. Places expression on the bottom of the REXX queue in FIFO (First in, first out) 
  1703. order. You can use QUEUE to queue a value on the queue for later use; more 
  1704. natural than PUSH when adding several items to an empty queue. 
  1705.  
  1706. Note:  REXX queues are NOT the same as OS/2 queues. 
  1707.  
  1708. Example: 
  1709.  
  1710. queue "Poughkeepsie"
  1711. queue "Vienna"
  1712. call ItineraryRoutine
  1713. exit
  1714. ItineraryRoutine: procedure
  1715. pull from
  1716. pull to
  1717. say "Goodbye," from", hello" to"!"
  1718. return
  1719.  
  1720. Output 
  1721.  
  1722. Goodbye POUGHKEEPSIE, hello VIENNA!
  1723.  
  1724.  
  1725. ΓòÉΓòÉΓòÉ 5.19. RETURN - Return From Subroutine/Function ΓòÉΓòÉΓòÉ
  1726.  
  1727. Leaves an internal routine or function; expression is returned in variable 
  1728. RESULT. 
  1729.  
  1730.  ΓöÇΓöÇRETURNΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇ
  1731.               ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  1732.  
  1733. Related Instructions: CALL, EXIT, PROCEDURE 
  1734.  
  1735. You can use this to return a value from a function;  use of the expression is 
  1736. required when a routine is invoked as a function as opposed to a subroutine; it 
  1737. is a good (or at least, safe ...) programming practice in REXX to always return 
  1738. a value. 
  1739.  
  1740. Example: 
  1741.  
  1742. /* compute the "Nth" Fibonacci number */
  1743. do i=1 to 12
  1744.     say i Fibonacci(i)
  1745.     end
  1746. exit
  1747. Fibonacci: procedure
  1748. arg N
  1749. if N <= 2 then do
  1750.     return 1
  1751.     end
  1752. return (Fibonacci(N-1) + Fibonacci(N-2))
  1753.  
  1754. Output 
  1755.  
  1756. 1 1
  1757. 2 1
  1758. 3 2
  1759. 4 3
  1760. 5 5
  1761. 6 8
  1762. 7 13
  1763. 8 21
  1764. 9 34
  1765. 10 55
  1766. 11 89
  1767. 12 144
  1768.  
  1769.  
  1770. ΓòÉΓòÉΓòÉ 5.20. SAY - Display Output ΓòÉΓòÉΓòÉ
  1771.  
  1772. Use SAY to display a line of output. 
  1773.  
  1774.  ΓöÇΓöÇSAYΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇ
  1775.               ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ
  1776.  
  1777. Places expression on output device (terminal for foreground TSO or CMS;  DDNAME 
  1778. SYSTSPRT for background TSO; command session or redirection or piping for OS/2. 
  1779.  
  1780. There is no REXX analog of the CLIST WRITENR statement or 'C' printf( ) with no 
  1781. "\n"; one could easily be provided as an external function if desired. 
  1782.  
  1783.  
  1784. ΓòÉΓòÉΓòÉ 5.21. SELECT - Conditional Execution ΓòÉΓòÉΓòÉ
  1785.  
  1786. Use SELECT to choose among several options. 
  1787.  
  1788.              ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  1789.                                                         Γöé
  1790.  ΓöÇΓöÇSELECT;ΓöÇΓö┤ΓöÇWHENΓöÇΓöÇexpressionΓöÇΓö¼ΓöÇΓö¼ΓöÇTHENΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇinstructionΓö┤ΓöÇΓöÇ
  1791.                                 Γöö;Γöÿ      Γöö;Γöÿ
  1792.  
  1793.           ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇEND;ΓöÇΓöÇΓöÇΓöÇ
  1794.               ΓööΓöÇOTHERWISEΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  1795.                           Γöö;Γöÿ Γöé  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé
  1796.                               Γöé               Γöé  Γöé
  1797.                               ΓööΓöÇΓöÇΓö┤ΓöÇinstructionΓöÇΓö┤ΓöÇΓöÇΓöÿ
  1798.  
  1799. SELECT is more convenient and readable in most cases than extended nested-IF 
  1800. logic.  This is like a PL/I SELECT or EASEL switch;  it is NOT like a C switch 
  1801. -- no drop-through of cases are allowed.  PL/I programmers, be careful - this 
  1802. is very close, but not identical to your language;  don't let your habits lead 
  1803. you astray here. 
  1804.  
  1805. Example: 
  1806.  
  1807. Select
  1808. When environment  = 'TSO' & REXX_manuals = "not available" then
  1809.     say "For now, you'd better write a CLIST."
  1810. When environment  = 'CMD' & REXX_manuals = "not available" then
  1811.     say "For now, you'd better write a .BAT style command list."
  1812. When REXX_manuals = "not available" then
  1813.     say "Better write a program."
  1814. Otherwise
  1815.     say 'A REXX exec should do the trick.'
  1816. End /* Select */
  1817.  
  1818.  
  1819. ΓòÉΓòÉΓòÉ 5.22. SIGNAL - Enable/Disable Execption Condition ΓòÉΓòÉΓòÉ
  1820.  
  1821. SIGNAL raises certain CONDITIONs to perform various error recovery functions. 
  1822.  
  1823.  ΓöÇΓöÇSIGNALΓöÇΓöÇΓöÇΓö¼ΓöÇlabelnameΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇ
  1824.               Γö£ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1825.               Γöé ΓööΓöÇVALUEΓöÇΓöÿ                           Γöé
  1826.               Γö£ΓöÇΓöÇΓöÇOFFΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇERRORΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1827.               Γöé           Γö£ΓöÇΓöÇFAILUREΓöÇΓöÇΓöÇΓöÇΓöñ           Γöé
  1828.               Γöé           Γö£ΓöÇΓöÇHALTΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ           Γöé
  1829.               Γöé           Γö£ΓöÇΓöÇNOVALUEΓöÇΓöÇΓöÇΓöÇΓöñ           Γöé
  1830.               Γöé           Γö£ΓöÇΓöÇSYNTAXΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ           Γöé
  1831.               Γöé           ΓööΓöÇΓöÇNOTREADYΓöÇΓöÇΓöÇΓöÿ           Γöé
  1832.               Γöé                                     Γöé
  1833.               ΓööΓöÇΓöÇONΓöÇΓöÇΓö¼ΓöÇERRORΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  1834.                      Γö£ΓöÇFAILUREΓöÇΓöñ ΓööΓöÇNAMEΓöÇtrapnameΓöÇΓöÇΓöÿ
  1835.                      Γö£ΓöÇHALTΓöÇΓöÇΓöÇΓöÇΓöñ
  1836.                      Γö£ΓöÇNOVALUEΓöÇΓöñ
  1837.                      Γö£ΓöÇSYNTAXΓöÇΓöÇΓöñ
  1838.                      ΓööΓöÇNOTREADYΓöÿ
  1839.  
  1840. Note:  NOTREADY is for OS/2 only. NAME is not available on VM. 
  1841.  
  1842. Related Instructions: CALL, PROCEDURE 
  1843. Related Function: CONDITION( ) 
  1844.  
  1845. A special purpose instruction for dealing with CONDITIONs and condition traps; 
  1846. NOT a substitue for a GOTO statement, and NOT a general purpose error handling 
  1847. solution. 
  1848.  
  1849. Use to perform special-case, out-of-line processing, usually of a 
  1850. "windup-processing" or "fatal error" nature; any other use of SIGNAL impairs 
  1851. readability and maintenance, and should be avoided  --  it probably WON'T do 
  1852. what you think it does, or at least the next person to maintain your code 
  1853. probably won't understand it. 
  1854.  
  1855. Consider using the "CALL ON condition NAME trapname" instead. 
  1856.  
  1857.  
  1858. ΓòÉΓòÉΓòÉ 5.23. TRACE - Set Debugging Options ΓòÉΓòÉΓòÉ
  1859.  
  1860. TRACE supports the interactive debugging of REXX command procedures. 
  1861.  
  1862.  ΓöÇΓöÇTRACEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇ
  1863.             Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇnumberΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1864.             Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                            Γöé
  1865.             Γöé            Γöé                            Γöé
  1866.             ΓööΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  1867.                 Γö£ΓöÇΓöÇΓöÇ?ΓöÇΓöÇΓöÇΓöñ   Γö£ΓöÇΓöÇΓöÇ'All'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1868.                 ΓööΓöÇΓöÇΓöÇ!ΓöÇΓöÇΓöÇΓöÿ   Γö£ΓöÇΓöÇΓöÇ'Commands'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1869.                             Γö£ΓöÇΓöÇΓöÇ'Error'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1870.                             Γö£ΓöÇΓöÇΓöÇ'Failure'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1871.                             Γö£ΓöÇΓöÇΓöÇ'Intermediates'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1872.                             Γö£ΓöÇΓöÇΓöÇ'Labels'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1873.                             Γö£ΓöÇΓöÇΓöÇ'Normal'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1874.                             Γö£ΓöÇΓöÇΓöÇ'Off'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1875.                             Γö£ΓöÇΓöÇΓöÇ'Results'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1876.                             ΓööΓöÇΓöÇΓöÇ'Scan'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  1877.   Or, alternatively:
  1878.  
  1879.  ΓöÇΓöÇTRACEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1880.             Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇsymbolΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1881.             ΓööΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÿ
  1882.                 ΓööΓöÇVALUEΓöÇΓöÿ
  1883.  
  1884. Note:  Scan is for TSO and VM only. Failure is not available on VM; Negative 
  1885. may be used in place of Normal on VM only. 
  1886.  
  1887. You can use TRACE to perform a wide variety of tracing on REXX execs. 
  1888.  
  1889. The following TRACE symbols are supported. 
  1890.  
  1891.  All            All expressions a displayed before being exectued. 
  1892.  Commands       Host commands are displayed before being exectued. 
  1893.  Error          Host commands which return a non-zero return code are displayed 
  1894.                 after being executed. 
  1895.  Failure        Host commands which return a negative return code are displayed 
  1896.                 after being executed. This is the same as the Normal setting. 
  1897.  Intermediate   All expressions are displayed before being executed, 
  1898.                 intermediate results are also displayed. 
  1899.  Labels         Labels are displayed as they are reached. 
  1900.  Normal         Host commands which return a negative return code are displayed 
  1901.                 after being executed. This is the default. 
  1902.  Off            Stop tracing. 
  1903.  Results        All expressions are displayed before being executed as well as 
  1904.                 the end results. 
  1905.  Scan           Check syntax without processing the statements. Note: This is 
  1906.                 no longer supported under the SAA definition. 
  1907.  
  1908.  Any of the above symbol values may be prefixed with the "?" to turn off that 
  1909.  trace setting. 
  1910.  
  1911.  
  1912. ΓòÉΓòÉΓòÉ 5.24. UPPER - Lower to Upper Case Conversion ΓòÉΓòÉΓòÉ
  1913.  
  1914. UPPER translates text to uppercase. 
  1915.  
  1916.                ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  1917.                           Γöé
  1918.  ΓöÇΓöÇΓöÇΓöÇUPPERΓöÇΓöÇΓöÇΓö┤ΓöÇvariableΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  1919.  
  1920. Note:  TSO and VM only. 
  1921.  
  1922. Use on variables or values prior to comparisons to implement case-insensitive 
  1923. checking.  For greater portability, use the PARSE UPPER keyword instruction or 
  1924. the TRANSLATE( ) builtin function. 
  1925.  
  1926.  
  1927. ΓòÉΓòÉΓòÉ 6. Rexx Builtin Functions ΓòÉΓòÉΓòÉ
  1928.  
  1929. This section details the syntax of the REXX builtin functions, and certain 
  1930. external functions that are supplied in particular environments. 
  1931.  
  1932. This part will talk about the general syntax of functions, and about function 
  1933. argument resolution, search order, error recovery, and will distinguish builtin 
  1934. vs external vs internal functions. 
  1935.  
  1936. The sections respective to each builtin function may be jumped to directly by 
  1937. selecting one of the names from the following list: 
  1938.  
  1939.  o ABBREV( ) - Test String Abbreviation 
  1940.  o ABS( ) - Return Absolute Value 
  1941.  o ADDRESS( ) - Return Name of Current Environment 
  1942.  o ARG( ) - Return Argument 
  1943.  o BEEP( ) - Sound Alarm 
  1944.  o BITAND( ) - Logical AND 
  1945.  o BITOR( ) - Logical OR 
  1946.  o BITXOR( ) - Logical XOR 
  1947.  o B2X( ) - Bit to Hex Conversion 
  1948.  o CENTER( ) - Center Data 
  1949.  o CHARIN( ) - Read Character String 
  1950.  o CHAROUT( ) - Write Character String 
  1951.  o CHARS( ) - Return Status of Input Stream 
  1952.  o CMSFLAG( ) - Return Status of CMSFLAG 
  1953.  o COMPARE( ) - Compare Strings 
  1954.  o CONDITION( ) - Return Condition 
  1955.  o COPIES( ) - Duplicate String Data 
  1956.  o CSL( ) - Call a routine in a Callable Services Library 
  1957.  o C2D( ) - Character String to Decimal Conversion 
  1958.  o C2X( ) - Character String to Hex Conversion 
  1959.  o DATATYPE( ) - Determine Data Type 
  1960.  o DATE( ) - Return System Date 
  1961.  o DBCS( ) - Set DBCS Option 
  1962.  o DELSTR( ) - Delete Substring 
  1963.  o DELWORD( ) - Delete Words 
  1964.  o DIAG( ) - Communicate with CP 
  1965.  o DIAGRC( ) - Communicate with CP 
  1966.  o DIGITS( ) - Return NUMERIC DIGITE Settings 
  1967.  o DIRECTORY( ) - Change OS/2 Directory 
  1968.  o D2C( ) - Decimal to Character String Conversion 
  1969.  o D2X( ) - Decimal to Hex Conversion 
  1970.  o ENDLOCAL( ) - End OS/2 Local Setting 
  1971.  o ERRORTEXT( ) - Return Error Message Text 
  1972.  o EXTERNALS( ) 
  1973.  o FILESPEC( ) 
  1974.  o FIND( ) - Search for Word 
  1975.  o FORM( ) - Return NUMERIC FORM Setting 
  1976.  o FORMAT( ) - Format Numeric Strings 
  1977.  o FUZZ( ) - Return NUMERIC FUZZ Settings 
  1978.  o GETMSG( ) 
  1979.  o INDEX( ) - Search for Substring 
  1980.  o INSERT( ) - Insert Substring 
  1981.  o JUSTIFY( ) - Justify String of Words 
  1982.  o LASTPOS( ) - Determine Last Position of Phrase 
  1983.  o LEFT( ) - Left-Align String 
  1984.  o LENGTH( ) - Return Length of String 
  1985.  o LINEIN( ) - Read a Line 
  1986.  o LINEOUT( ) - Write a Line 
  1987.  o LINES( ) - Return Status of Input Stream 
  1988.  o LINESIZE( ) - Return Width of Terminal 
  1989.  o LISTDSI( ) - Determine Dataset Status 
  1990.  o MAX( ) - Return Maximum Value From a Set 
  1991.  o MIN( ) - Return Minimum Value From a Set 
  1992.  o MSG( ) - Set MSG Option 
  1993.  o OUTTRAP( ) - Trap TSO Display Output 
  1994.  o OVERLAY( ) - Replace Phrase in a String 
  1995.  o POS( ) - Search for Substring 
  1996.  o PROMPT( ) - Set TSO PROMPT Option 
  1997.  o QUEUED( ) - Return Number of Entries in Queue 
  1998.  o RANDOM( ) - Return Random Number 
  1999.  o REVERSE( ) - Reverse String 
  2000.  o RIGHT( ) - Right-Align String 
  2001.  o RXFUNCADD( ) - Add an External Function 
  2002.  o RXFUNCDROP( ) - Drop an External Function 
  2003.  o RXFUNCQUERY( ) - Query For an External Function 
  2004.  o RXQUEUE( ) - Manipulate Queue 
  2005.  o SETLANG( ) - Set International Language 
  2006.  o SETLOCAL( ) - Set OS/2 Local Setting 
  2007.  o SIGN( ) - Return Numeric Sign 
  2008.  o SOURCELINE( ) - Return Program Line 
  2009.  o SPACE( ) - Insert Fill-Character 
  2010.  o STORAGE( ) 
  2011.  o STREAM( ) - Stream Command 
  2012.  o STRIP( ) - Remove Padding 
  2013.  o SUBSTR( ) - Return Substring 
  2014.  o SUBWORD( ) - Return Word From String 
  2015.  o SYMBOL( ) - Return Status of Symbol 
  2016.  o SYSDSN( ) - Return Status of Dataset 
  2017.  o SYSVAR( ) - Return System Variable 
  2018.  o TIME( ) - Return System Time 
  2019.  o TRACE( ) - Return TRACE Mode 
  2020.  o TRANSLATE( ) - Translate String 
  2021.  o TRUNC( ) - Truncate Numeric Value 
  2022.  o USERID( ) - Return Logon User ID 
  2023.  o VALUE( ) - Return Content of Symbol 
  2024.  o VERIFY( ) - Test Character String 
  2025.  o WORD( ) - Get Word 
  2026.  o WORDINDEX( ) - Return Word Position 
  2027.  o WORDLENGTH( ) - Return Word Length 
  2028.  o WORDPOS( ) - Return Word Position 
  2029.  o WORDS( ) - Return Number of Words 
  2030.  o XRANGE( ) - Define Range of Hex Values 
  2031.  o X2C( ) - Hex to Character String Conversion 
  2032.  o X2D( ) - Hex to Decimal Conversion 
  2033.  
  2034.  
  2035. ΓòÉΓòÉΓòÉ 6.1. ABBREV( ) - Test String Abbreviation ΓòÉΓòÉΓòÉ
  2036.  
  2037. Use ABBREV for matching several variants of command names, parameter names, 
  2038. etc. 
  2039.  
  2040.  ΓöÇΓöÇABBREV(information,infoΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2041.                              ΓööΓöÇ,lengthΓöÇΓöÇΓöÿ
  2042.  
  2043. Returns 1 if info value is a prefix of information value, and is at least 
  2044. length characters long, else 0.  A null string (for info) is considered to 
  2045. match anything.  Be careful about uppercase/lowercase -- the ABBREV functions 
  2046. is case sensitive. 
  2047.  
  2048. length defaults to the length of info. 
  2049.  
  2050. Examples: 
  2051.  
  2052. abbrev("BROWSE","BROWSER")  returns  0
  2053. abbrev("BROWSE","BROWSE")   returns  1
  2054. abbrev("BROWSE","BROWS")    returns  1
  2055. abbrev("BROWSE","BROW")     returns  1
  2056. abbrev("BROWSE","BRO")      returns  1
  2057. abbrev("BROWSE","BR")       returns  1
  2058. abbrev("BROWSE","B")        returns  1
  2059. abbrev("BROWSE","")         returns  1
  2060. abbrev("BROWSE","browse")   returns  0
  2061.  
  2062.  
  2063. ΓòÉΓòÉΓòÉ 6.2. ABS( ) - Return Absolute Value ΓòÉΓòÉΓòÉ
  2064.  
  2065. ABS returns the absolute value of a number formatted according to the current 
  2066. NUMERIC settings. 
  2067.  
  2068.  ΓöÇΓöÇABS(number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2069.  
  2070. Related Instruction: NUMERIC 
  2071.  
  2072. The parameter to ABS must be a valid number. 
  2073.  
  2074. Examples: 
  2075.  
  2076. abs(1)   returns  1
  2077. abs(0)   returns  0
  2078. abs(-1)  returns  1
  2079. abs(.01) returns  .01
  2080. abs("")  gives an (OS/2) error like:
  2081.  
  2082.     12 +++     Say 'abs("a") returns' abs('a');
  2083.     REX0040: Error 40 running D:\Commands\TestREXX.cmd, line 12:
  2084.              Incorrect call to routine
  2085.  
  2086.  
  2087. ΓòÉΓòÉΓòÉ 6.3. ADDRESS( ) - Return Name of Current Environment ΓòÉΓòÉΓòÉ
  2088.  
  2089. ADDRESS returns the name of the current environment for "host" commands, e.g., 
  2090. CMD, CMS, TSO, ISREDIT, etc. 
  2091.  
  2092.  ΓöÇΓöÇADDRESS( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2093.  
  2094. Related Instruction: ADDRESS 
  2095.  
  2096. This function is used only to query the current environment, not to set it. 
  2097.  
  2098.  
  2099. ΓòÉΓòÉΓòÉ 6.4. ARG( ) - Return Argument ΓòÉΓòÉΓòÉ
  2100.  
  2101. ARG returns the number of arguments, or the value of a specific argument. 
  2102.  
  2103.  ΓöÇΓöÇARG(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2104.           ΓööΓöÇnΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
  2105.                ΓööΓöÇ,optionΓöÇΓöÇΓöÇΓöÿ
  2106.  
  2107. Related Instructions: ARG PARSE 
  2108.  
  2109. ARG is used in receiving parameters passed to a main or subroutine REXX 
  2110. program.  It is important to remember that REXX considers discrete arguments to 
  2111. have been separated by commas in the invocation. 
  2112.  
  2113. If n is omitted ,ARG returns the number of arguments passed . 
  2114.  
  2115. If no option is specified, ARG returns the nth argument string. 
  2116.  
  2117. If option "E" (Exists) is specified, returns 1 if nth argument exists; else 0. 
  2118.  
  2119. If option "O" (Omitted) is specified, returns 1 if nth argument was omitted, 
  2120. that is, does not exist; else 0. 
  2121.  
  2122. Example: 
  2123.  
  2124.  ...
  2125. call ArgTester "parm1",, "This is 3"
  2126.  ...
  2127. ArgTester: procedure
  2128. /* arg( )     returns  3            */
  2129. /* arg(1)     returns  <<parm1>>    */
  2130. /* arg(2)     returns  <<>>         */
  2131. /* arg(3)     returns  <<This is 3>>*/
  2132. /* arg(4)     returns  <<>>         */
  2133. /* arg(1,'E') returns  1            */
  2134. /* arg(2,'E') returns  0            */
  2135. /* arg(3,'E') returns  1            */
  2136. /* arg(4,'E') returns  0            */
  2137. /* arg(1,'O') returns  0            */
  2138. /* arg(2,'O') returns  1            */
  2139. /* arg(3,'O') returns  0            */
  2140. /* arg(4,'O') returns  1            */
  2141. return ""
  2142.  
  2143.  
  2144. ΓòÉΓòÉΓòÉ 6.5. BEEP( ) - Sound Alarm ΓòÉΓòÉΓòÉ
  2145.  
  2146. BEEP drives the speaker;  this is basically just DosBeep. 
  2147.  
  2148.  ΓöÇΓöÇBEEP(frequency,duration)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2149.  
  2150. Note:  OS/2 only. 
  2151.  
  2152. Frequency is in Hertz in range [37..32767]. Duration is in milliseconds in 
  2153. range [1..60000]. On most machines, you can't really have a duration less than 
  2154. 32 ms. 
  2155.  
  2156. Note:  Remember that in OS/2 the speaker is a serially reusable resource, for 
  2157. which there is no explicit synchronization provided.  In other words, except 
  2158. for VERY brief passages, NEVER issue "beeps" from a process that doesn't have 
  2159. the input focus.  No application "owns" the speaker. 
  2160.  
  2161. Musical Note Frequencies 
  2162.  
  2163. The western tempered scale musical notes, based on a concert pitch of A=440 Hz, 
  2164. and rounded to the nearest integral Hz, are shown below: 
  2165.  
  2166. C6 is middle C on the piano ;  A6 is the "concert a." 
  2167.  
  2168. D3           37
  2169. D3sharp      39
  2170. E3flat       39
  2171. E3           41
  2172. F3           44
  2173. F3sharp      46
  2174. G3flat       46
  2175. G3           49
  2176. G3sharp      52
  2177. A3flat       52
  2178. A3           55
  2179. A3sharp      58
  2180. B3flat       58
  2181. B3           62
  2182.  
  2183. C4           65
  2184. C4sharp      69
  2185. D4flat       69
  2186. D4           73
  2187. D4sharp      78
  2188. E4flat       78
  2189. E4           82
  2190. F4           87
  2191. F4sharp      92
  2192. G4flat       92
  2193. G4           98
  2194. G4sharp     104
  2195. A4flat      104
  2196. A4          110
  2197. A4sharp     117
  2198. B4flat      117
  2199. B4          123
  2200.  
  2201. C5          131
  2202. C5sharp     139
  2203. D5flat      139
  2204. D5          147
  2205. D5sharp     156
  2206. E5flat      156
  2207. E5          165
  2208. F5          175
  2209. F5sharp     185
  2210. G5flat      185
  2211. G5          196
  2212. G5sharp     208
  2213. A5flat      208
  2214. A5          220
  2215. A5sharp     233
  2216. B5flat      233
  2217. B5          247
  2218.  
  2219. C6          262
  2220. C6sharp     277
  2221. D6flat      277
  2222. D6          294
  2223. D6sharp     311
  2224. E6flat      311
  2225. E6          330
  2226. F6          349
  2227. F6sharp     370
  2228. G6flat      370
  2229. G6          392
  2230. G6sharp     415
  2231. A6flat      415
  2232. A6          440
  2233. A6sharp     466
  2234. B6flat      466
  2235. B6          494
  2236.  
  2237. C7          523
  2238. C7sharp     554
  2239. D7flat      554
  2240. D7          587
  2241. D7sharp     622
  2242. E7flat      622
  2243. E7          659
  2244. F7          698
  2245. F7sharp     740
  2246. G7flat      740
  2247. G7          784
  2248. G7sharp     831
  2249. A7flat      831
  2250. A7          880
  2251. A7sharp     932
  2252. B7flat      932
  2253. B7          988
  2254.  
  2255. C8         1047
  2256. C8sharp    1109
  2257. D8flat     1109
  2258. D8         1175
  2259. D8sharp    1245
  2260. E8flat     1245
  2261. E8         1319
  2262. F8         1397
  2263. F8sharp    1480
  2264. G8flat     1480
  2265. G8         1568
  2266. G8sharp    1661
  2267. A8flat     1661
  2268. A8         1760
  2269. A8sharp    1865
  2270. B8flat     1865
  2271. B8         1976
  2272.  
  2273. C9         2093
  2274. C9sharp    2217
  2275. D9flat     2217
  2276. D9         2349
  2277. D9sharp    2489
  2278. E9flat     2489
  2279. E9         2637
  2280. F9         2794
  2281. F9sharp    2960
  2282. G9flat     2960
  2283. G9         3136
  2284. G9sharp    3332
  2285. A9flat     3332
  2286. A9         3520
  2287. A9sharp    3729
  2288. B9flat     3729
  2289. B9         3951
  2290.  
  2291. C10        4186
  2292. C10sharp   4435
  2293. D10flat    4435
  2294. D10        4699
  2295. D10sharp   4978
  2296. E10flat    4978
  2297. E10        5274
  2298. F10        5588
  2299. F10sharp   5920
  2300. G10flat    5920
  2301. G10        6272
  2302. G10sharp   6645
  2303. A10flat    6645
  2304. A10        7040
  2305. A10sharp   7459
  2306. B10flat    7459
  2307. B10        7902
  2308.  
  2309. C11        8372
  2310. C11sharp   8870
  2311. D11flat    8870
  2312. D11        9397
  2313. D11sharp   9956
  2314. E11flat    9956
  2315. E11       10548
  2316. F11       11175
  2317. F11sharp  11840
  2318. G11flat   11840
  2319. G11       12544
  2320. G11sharp  13290
  2321. A11flat   13290
  2322. A11       14080
  2323. A11sharp  14917
  2324. B11flat   14917
  2325. B11       15804
  2326.  
  2327. C12       16744
  2328. C12sharp  17740
  2329. D12flat   17740
  2330. D12       18795
  2331. D12sharp  19912
  2332. E12flat   19912
  2333. E12       21096
  2334. F12       22351
  2335. F12sharp  23680
  2336. G12flat   23680
  2337. G12       25088
  2338. G12sharp  26580
  2339. A12flat   26580
  2340. A12       28160
  2341. A12sharp  29834
  2342. B12flat   29834
  2343. B12       31609
  2344.  
  2345. Typical tempo: quarternote=120, 
  2346. so quarter note duration = 500 milliseconds. 
  2347.  
  2348. FULL        2000
  2349. HALF        1000
  2350. QUARTER      500
  2351. EIGHTH       250
  2352. SIXTEENTH    125
  2353. THIRTYSECOND  62
  2354. SIXTYFOURTH   31
  2355.  
  2356.  
  2357. ΓòÉΓòÉΓòÉ 6.6. BITAND( ) - Logical AND ΓòÉΓòÉΓòÉ
  2358.  
  2359. BITAND does a logical AND of two strings on a bit-by-bit basis. 
  2360.  
  2361.  ΓöÇΓöÇBITAND(string1ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
  2362.                     ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  2363.                         ΓööΓöÇstring2Γöÿ ΓööΓöÇ,padΓöÇΓöÿ
  2364.  
  2365. Related Functions: BITOR( ), BITXOR( ) 
  2366.  
  2367. Returns a string that is the result of ANDing the two input strings together, 
  2368. bit by bit. 
  2369.  
  2370. If a pad is specified, is extends the shorter of the two strings on the right. 
  2371. If no pad is specified, it defaults to '1111 1111'B. 
  2372.  
  2373. There are really two different kinds of operations that are encoded in BITAND. 
  2374. The first is simply doing an AND between two strings. The second, which you 
  2375. obtain by omitting string2, and supplying a pad is one in which the pad is 
  2376. ANDed with each character of the string1. 
  2377.  
  2378. Logical AND bit-by-bit operation: 
  2379.  
  2380.      0   1
  2381.    ΓöîΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÉ
  2382.  0 Γöé 0 Γöé 0 Γöé
  2383.    Γö£ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöñ
  2384.  1 Γöé 0 Γöé 1 Γöé
  2385.    ΓööΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÿ
  2386.  
  2387. Examples: 
  2388.  
  2389. BITAND('C1 C2 C3'x, '12 34 56'x)    returns '00 00 42'x
  2390. BITAND('F7 F8 F9'x, '20'x, '2F'x)   returns '20 28 29'x
  2391. BITAND('F0 F1 F2'x,, '0F'x)         returns '00 01 02'x
  2392.  
  2393.  
  2394. ΓòÉΓòÉΓòÉ 6.7. BITOR( ) - Logical OR ΓòÉΓòÉΓòÉ
  2395.  
  2396. BITOR does a logical OR of two strings on a bit-by-bit basis. 
  2397.  
  2398.  ΓöÇΓöÇBITOR(string1ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2399.                    ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  2400.                        ΓööΓöÇstring2Γöÿ ΓööΓöÇ,padΓöÇΓöÿ
  2401.  
  2402. Related Functions: BITAND( ), BITXOR( ) 
  2403.  
  2404. Returns a string that is the result of ORing the two input strings together, 
  2405. bit by bit. 
  2406.  
  2407. If a pad is specified, is extends the shorter of the two strings on the right. 
  2408. If no pad is specified, it defaults to '0000 0000'B. 
  2409.  
  2410. There are really two different kinds of operations that are encoded in BITOR. 
  2411. The first is simply doing an OR between two strings. The second, which you 
  2412. obtain by omitting string2, and supplying a pad is one in which the pad is ORed 
  2413. with each character of the string1. 
  2414.  
  2415. Logical OR bit-by-bit operation: 
  2416.  
  2417.      0   1
  2418.    ΓöîΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÉ
  2419.  0 Γöé 0 Γöé 1 Γöé
  2420.    Γö£ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöñ
  2421.  1 Γöé 1 Γöé 1 Γöé
  2422.    ΓööΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÿ
  2423.  
  2424. Examples: 
  2425.  
  2426. BITOR('C1 C2 C3'x, '12 34 56'x)    returns 'D3 F6 D7'x
  2427. BITOR('87 88 89'x, '20'x, '2F'x)   returns 'A7 AF AF'x
  2428. BITOR('41 42 43'x,, '20'x)         returns '61 62 63'x
  2429.  
  2430.  
  2431. ΓòÉΓòÉΓòÉ 6.8. BITXOR( ) - Logical XOR ΓòÉΓòÉΓòÉ
  2432.  
  2433. BITXOR does a logical XOR (exclusive OR) of two strings on a bit-by-bit basis. 
  2434.  
  2435.  ΓöÇΓöÇBITXOR(string1ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
  2436.                     ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  2437.                         ΓööΓöÇstring2Γöÿ ΓööΓöÇ,padΓöÇΓöÿ
  2438.  
  2439. Related Functions: BITAND( ), BITOR( ) 
  2440.  
  2441. Returns a string that is the result of XORing the two input strings together, 
  2442. bit by bit. 
  2443.  
  2444. If a pad is specified, is extends the shorter of the two strings on the right. 
  2445. If no pad is specified, it defaults to '1111 1111'B. 
  2446.  
  2447. There are really two different kinds of operations that are encoded in BITXOR. 
  2448. The first is simply doing an XOR between two strings. The second, which you 
  2449. obtain by omitting string2, and supplying a pad is one in which the pad is 
  2450. XORed with each character of the string1. 
  2451.  
  2452. Logical XOR bit-by-bit operation: 
  2453.  
  2454.      0   1
  2455.    ΓöîΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÉ
  2456.  0 Γöé 0 Γöé 1 Γöé
  2457.    Γö£ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöñ
  2458.  1 Γöé 1 Γöé 0 Γöé
  2459.    ΓööΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÿ
  2460.  
  2461. Examples: 
  2462.  
  2463. BITXOR('C1 C2 C3'x, '12 34 56'x)    returns 'D3 F6 95'x
  2464. BITXOR('F7 F8 F9'x, '20'x, '2F'x)   returns 'D7 D7 D6'x
  2465. BITXOR('F0 F1 F2'x,, '0F'x)         returns 'FF FE FD'x
  2466.  
  2467.  
  2468. ΓòÉΓòÉΓòÉ 6.9. B2X( ) - Bit to Hex Conversion ΓòÉΓòÉΓòÉ
  2469.  
  2470. B2X converts a character string containing ones and zeros into a character 
  2471. string containing hexadecimal characters. 
  2472.  
  2473.  ΓöÇΓöÇB2X(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2474.  
  2475. Note:  Not in TSO or VM. 
  2476.  
  2477. Converts binary (bit) to hexadecimal.  The binary string can contain zeros, 
  2478. ones, and blanks.  The converted string only uses the upper case letters to 
  2479. represent the hexadecimal digits A-F.  There will be no blanks in the converted 
  2480. string. 
  2481.  
  2482. Examples: 
  2483.  
  2484. B2X('11110001')                       returns 'F1'
  2485. B2X('101')                            returns '5'
  2486. B2X('1000 0010 1001 0001 1000 0010')  returns '829182'
  2487.  
  2488.  
  2489. ΓòÉΓòÉΓòÉ 6.10. CENTER( ) - Center Data ΓòÉΓòÉΓòÉ
  2490.  
  2491. CENTER returns a string that is length characters long, and has string centered 
  2492. in it. 
  2493.  
  2494.      ΓöîΓöÇCENTER(ΓöÇΓöÉ
  2495.  ΓöÇΓöÇΓöñ         Γö£ΓöÇΓöÇstringΓöÇΓöÇ,lengthΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2496.      ΓööΓöÇCENTRE(ΓöÇΓöÿ                  ΓööΓöÇ,padΓöÇΓöÇΓöÿ
  2497.  
  2498. When the string is shorter than the length, pad characters are added at both 
  2499. ends to center the string and bring it to the required length. CENTER operates 
  2500. as though the characters were added one at a time, first on the right, then on 
  2501. the left, another on the right, and so on. 
  2502.  
  2503. When the string is longer than the length, then characters are removed from 
  2504. both ends of the string until the string has been reduced to the required 
  2505. length. CENTER operates as though the characters were removed one at a time, 
  2506. first on the right, then on the left, another on the right, and so on. 
  2507.  
  2508. The default pad is the blank character. 
  2509.  
  2510. Examples: 
  2511.  
  2512. CENTER("ABC",8,'+')        returns '++ABC+++'
  2513. CENTER('Catastrophe',5)    returns 'astro'
  2514. CENTER('stints',0)         returns ''
  2515. CENTER('stints',1)         returns 'i'
  2516. CENTER('stints',2)         returns 'in'
  2517. CENTER('stints',3)         returns 'tin'
  2518. CENTER('stints',4)         returns 'tint'
  2519. CENTER('stints',5)         returns 'stint'
  2520. CENTER('stints',6)         returns 'stints'
  2521. CENTER('stints',7)         returns 'stints '
  2522. CENTER('stints',8)         returns ' stints '
  2523.  
  2524. Note:  The British spelling (CENTRE) is due to the origins of REXX with IBMer 
  2525. Mike Cowlishaw from England. 
  2526.  
  2527.  
  2528. ΓòÉΓòÉΓòÉ 6.11. CHARIN( ) - Read Character String ΓòÉΓòÉΓòÉ
  2529.  
  2530. CHARIN returns up to length characters from the character input stream name. 
  2531.  
  2532.  ΓöÇΓöÇCHARIN(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇ
  2533.              ΓööΓöÇnameΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  2534.                            ΓööΓöÇstartΓöÇΓöÇΓöÿ ΓööΓöÇ,lengthΓöÇΓöÿ
  2535.  
  2536. Note:  OS/2 has the only implementation; the new SAA REXX Level 2 specification 
  2537. includes this function. 
  2538.  
  2539. Related Functions: CHAROUT( ), CHARS( ) 
  2540.  
  2541. The stream name defaults to STDIN:, which is the default input stream. The 
  2542. default length is 1. 
  2543.  
  2544. There are two types of streams: transient and persistent. Transient streams are 
  2545. associated with devices, like the console, a printer, and STDIN:. Persistent 
  2546. streams have an existence after a close of the stream; files are persistent 
  2547. streams, for example.  A current position is maintained for persistent streams. 
  2548. The default start for persistent streams is the current position, but any 
  2549. position that lies within the bounds of the character stream can be specified 
  2550. (1 to the length of the stream). 
  2551.  
  2552. A length of zero positions the stream, but returns the null string (no 
  2553. characters are read). 
  2554.  
  2555. Be careful using CHARIN( ) to read from the keyboard; your REXX program will 
  2556. not regain control until the Enter key has been pressed.  It does NOT get 
  2557. control immediately after each press of a character. 
  2558.  
  2559.  
  2560. ΓòÉΓòÉΓòÉ 6.12. CHAROUT( ) - Write Character String ΓòÉΓòÉΓòÉ
  2561.  
  2562. CHAROUT writes length characters to the name stream. 
  2563.  
  2564.  ΓöÇΓöÇCHAROUT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇ
  2565.               ΓööΓöÇnameΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  2566.                             ΓööΓöÇstartΓöÇΓöÇΓöÿ ΓööΓöÇ,lengthΓöÇΓöÿ
  2567.  
  2568. Note:  OS/2 has the only implementation. It is included in the new SAA REXX 
  2569. Level 2 specification. 
  2570.  
  2571. Related Functions: CHARIN( ), CHARS( ) 
  2572.  
  2573. CHAROUT returns a count of any characters remaining after attempting to write 
  2574. to the the name stream.  Any value other than 0 indicates some type of error 
  2575. ocurred, and the NOTREADY condition has been raised. 
  2576.  
  2577. The stream name defaults to STDOUT:, which is the default output stream. The 
  2578. default length is 1. 
  2579.  
  2580. There are two types of streams: transient and persistent. Transient streams are 
  2581. associated with devices, like the console, a printer, and STDOUT:. Persistent 
  2582. streams have an existence after a close of the stream; files are persistent 
  2583. streams, for example.  A current position is maintained for persistent streams. 
  2584. The default start for persistent streams is the current position, but any 
  2585. position that lies within the bounds of the character stream can be specified 
  2586. (1 to the length of the stream). 
  2587.  
  2588. A length of zero positions the stream, but returns zero and no characters are 
  2589. written. 
  2590.  
  2591. Warning: The default initial position for output persistent streams is at the 
  2592. end of the stream. Repeated CHAROUT( ) operations append to the end of the 
  2593. stream.  If you wish to overwrite a stream, you must explicitly set the 
  2594. position of the stream to one (e.g., call CHAROUT stream,,1). 
  2595.  
  2596.  
  2597. ΓòÉΓòÉΓòÉ 6.13. CHARS( ) - Return Status of Input Stream ΓòÉΓòÉΓòÉ
  2598.  
  2599. CHARS either returns a 1 or a 0 depending on whether characters exist in the 
  2600. input stream name, or returns the actual number of characters remaining in the 
  2601. input stream. 
  2602.  
  2603.  ΓöÇΓöÇCHARS(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇ
  2604.             ΓööΓöÇnameΓöÇΓöÿ
  2605.  
  2606. Note:  OS/2 has the only implementation. The new SAA REXX Level 2 specification 
  2607. includes it. 
  2608.  
  2609. Related Functions: CHARIN( ), CHAROUT( ) 
  2610.  
  2611. For transient streams, where it is impossible to determine the number of 
  2612. characters that remain, 0 means no more data, and 1 means there is more data. 
  2613.  
  2614. Example: 
  2615.  
  2616. /* Sample program to convert a file with */
  2617. /* only line ending LINEFEED characters  */
  2618. /* to one with both Carriage Return and  */
  2619. /* LINEFEED characters (e.g., Unix to    */
  2620. /* DOS file conversion)                  */
  2621. LF = '0A'x  /* linefeed character        */
  2622. CR = '0D'x  /* carriage return character */
  2623. arg instream outstream
  2624. lastchar = ""
  2625. /* Position outstream to beginning.      */
  2626. call charout outstream,,1
  2627. do while chars(instream) \= 0
  2628.     thischar = charin(instream)
  2629.     if thischar = LF,
  2630.      & lastchar \= CR then do
  2631.         call charout outstream, CR||LF
  2632.         end
  2633.     else do
  2634.         call charout outstream, thischar
  2635.         end
  2636.     lastchar = thischar
  2637.     end
  2638.  
  2639.  
  2640. ΓòÉΓòÉΓòÉ 6.14. CMSFLAG( ) - Return Status of CMSFLAG ΓòÉΓòÉΓòÉ
  2641.  
  2642. CMSFLAG returns information about the CMS environment in VM. 
  2643.  
  2644.  ΓöÇΓöÇCMSFLAG(flag)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2645.  
  2646. Note:  VM only. 
  2647.  
  2648. Returns 1 or 0 depending on flag.  Use the CMS SET command to set flags ON or 
  2649. OFF, except as specfied: 
  2650.  
  2651.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  2652.  Γöé  Flag    Γöé      Definition                        Γöé
  2653.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2654.  Γöé ABBREV   Γöé returns 1 if truncations will be       Γöé
  2655.  Γöé          Γöé  accepted; else 0                      Γöé
  2656.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2657.  Γöé AUTOREAD Γöé returns 1 if console read will be      Γöé
  2658.  Γöé          Γöé  issued immediately after command      Γöé
  2659.  Γöé          Γöé  execution; else 0                     Γöé
  2660.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2661.  Γöé CMSTYPE  Γöé returns 1 if console output will be    Γöé
  2662.  Γöé          Γöé  displayed within the exec; else 0     Γöé
  2663.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2664.  Γöé DOS      Γöé returns 1 if your virtual machine is   Γöé
  2665.  Γöé          Γöé  in the DOS environment; else 0        Γöé
  2666.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2667.  Γöé EXECTRAC Γöé returns 1 if EXEC tracing is turned on;Γöé
  2668.  Γöé          Γöé  else 0                                Γöé
  2669.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2670.  Γöé IMPCP    Γöé returns 1 if commands not recognized byΓöé
  2671.  Γöé          Γöé  CMS will be passed to CP; else 0      Γöé
  2672.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2673.  Γöé IMPEX    Γöé returns 1 if EXECs may be invoked by   Γöé
  2674.  Γöé          Γöé  filename; else 0                      Γöé
  2675.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2676.  Γöé PROTECT  Γöé returns 1 if the CMS nucleus is        Γöé
  2677.  Γöé          Γöé  storage-protected; else 0             Γöé
  2678.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2679.  Γöé RELPAGE  Γöé returns 1 if pages are to be released  Γöé
  2680.  Γöé          Γöé  following completion of certain       Γöé
  2681.  Γöé          Γöé  commands; else 0                      Γöé
  2682.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2683.  Γöé SUBSET   Γöé returns 1 if you are in the CMS subset;Γöé
  2684.  Γöé          Γöé  else 0 - set by issuing SUBSET, reset Γöé
  2685.  Γöé          Γöé  using RETURN                          Γöé
  2686.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  2687.  
  2688.  
  2689. ΓòÉΓòÉΓòÉ 6.15. COMPARE( ) - Compare Strings ΓòÉΓòÉΓòÉ
  2690.  
  2691. COMPARE returns 0 if the two strings are equal, else the position of the 
  2692. leftmost mismatch. 
  2693.  
  2694.  ΓöÇΓöÇCOMPARE(string1,string2ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2695.                              ΓööΓöÇ,padΓöÇΓöÇΓöÿ
  2696.  
  2697. The shorter of string1 and string2 is padded on the right with the pad 
  2698. character before performing the comparison. The default pad character is the 
  2699. blank. 
  2700.  
  2701. Examples: 
  2702.  
  2703. COMPARE('close','cigar')          returns  2
  2704. COMPARE('microsoft','micro')      returns  6
  2705. COMPARE('C','C  ')                returns  0
  2706. COMPARE('apples','oranges')       returns  1
  2707.  
  2708.  
  2709. ΓòÉΓòÉΓòÉ 6.16. CONDITION( ) - Return Condition ΓòÉΓòÉΓòÉ
  2710.  
  2711. CONDITION returns information about a trapped condition, or the null string if 
  2712. no condition is currently trapped. 
  2713.  
  2714.  ΓöÇΓöÇCONDITION(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2715.                 ΓööΓöÇoptionΓöÇΓöÿ
  2716.  
  2717. Note:  Not available on VM. 
  2718.  
  2719. Related Instructions: CALL, SIGNAL 
  2720. Related Functions: ERRORTEXT( ) 
  2721.  
  2722. The chart below summarizes the different options that are available: 
  2723.  
  2724.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  2725.  Γöé Option         Γöé Returns                          Γöé
  2726.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2727.  Γöé Condition name Γöé name of trapped condition        Γöé
  2728.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2729.  Γöé Description    Γöé descriptive string assoc'd w/trapΓöé
  2730.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2731.  Γöé Instruction    Γöé CALL or SIGNAL (how raised)      Γöé
  2732.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2733.  Γöé Status         Γöé ON, OFF, or DELAY                Γöé
  2734.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  2735.  
  2736. Only the first, capitalized letter of option need be specified.  CONDITION 
  2737. information is local to each subroutine level; the information is saved prior 
  2738. to calling a subroutine, and restored upon return.  (PL/I programmers take 
  2739. note;  conditions cannot percolate upward to different levels.) 
  2740.  
  2741.  
  2742. ΓòÉΓòÉΓòÉ 6.17. COPIES( ) - Duplicate String Data ΓòÉΓòÉΓòÉ
  2743.  
  2744. COPIES returns n copies of the string, all strung together. 
  2745.  
  2746.  ΓöÇΓöÇCOPIES(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2747.  
  2748. The number n cannot be less than zero. 
  2749.  
  2750. Examples: 
  2751.  
  2752. COPIES("Tu",2)      returns  "TuTu"
  2753. COPIES("nada",0)    returns  ""
  2754.  
  2755.  
  2756. ΓòÉΓòÉΓòÉ 6.18. CSL( ) - Call a routine in a Callable Services Library ΓòÉΓòÉΓòÉ
  2757.  
  2758. Refer to the IBM System Product Interpreter Reference for more information on 
  2759. the use of this function. 
  2760.  
  2761.  ΓöÇΓöÇCSL('rtname retcodeΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2762.                          ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé
  2763.                          Γöé      ΓöéΓöé
  2764.                          ΓööΓö┤ΓöÇparmΓöÇΓö┤Γöÿ
  2765.  
  2766. VM only. 
  2767.  
  2768.  
  2769. ΓòÉΓòÉΓòÉ 6.19. C2D( ) - Character String to Decimal Conversion ΓòÉΓòÉΓòÉ
  2770.  
  2771. C2D converts the binary representation of string to a decimal number. 
  2772.  
  2773.  ΓöÇΓöÇC2D(stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2774.                 ΓööΓöÇ,nΓöÇΓöÇΓöÿ
  2775.  
  2776. When n is not specified, an unsigned whole number is always returned.  When n 
  2777. is specified, it represents the length of the binary number to be converted, in 
  2778. bytes.  These numbers are assumed to represent signed two's complement numbers, 
  2779. and thus may return negative numbers.  If the string is shorter than the length 
  2780. n it is extended on the left by binary zeroes; it is not sign extended. An 
  2781. error condition is raised when the result requires more precision than the 
  2782. current setting of NUMERIC DIGITS. 
  2783.  
  2784. Note:  Because this function involves the binary representation of strings, it 
  2785. is heavily dependent on the character set and code page being used. Portable 
  2786. REXX programs should not make assumptions about this. 
  2787.  
  2788. Examples: 
  2789.  
  2790. C2D('A')        returns 193     /* EBCDIC */
  2791. C2D('A',1)      returns -63     /* EBCDIC */
  2792. C2D('A',2)      returns 193     /* EBCDIC */
  2793. C2D('A')        returns 65      /* ASCII */
  2794. C2D('A',1)      returns 65      /* ASCII */
  2795. C2D('A',2)      returns 65      /* ASCII */
  2796. C2D('2350'x)    returns 9040    /* portable */
  2797.  
  2798.  
  2799. ΓòÉΓòÉΓòÉ 6.20. C2X( ) - Character String to Hex Conversion ΓòÉΓòÉΓòÉ
  2800.  
  2801. C2X converts the binary representation of string to a decimal number. 
  2802.  
  2803.  ΓöÇΓöÇC2X(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2804.  
  2805. Converts character to hexadecimal, like you would see in a dump of a file. 
  2806.  
  2807. Examples: 
  2808.  
  2809. C2X('Aa.')      returns 'C1814B'   /* EBCDIC */
  2810. C2X('Aa.')      returns '41612E'   /* ASCII */
  2811. C2X('2350'x)    returns '2350'
  2812.  
  2813.  
  2814. ΓòÉΓòÉΓòÉ 6.21. DATATYPE( ) - Determine Data Type ΓòÉΓòÉΓòÉ
  2815.  
  2816. DATATYPE classifies character strings as belonging to various lexical 
  2817. categories. 
  2818.  
  2819.  ΓöÇΓöÇDATATYPE(stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2820.                      ΓööΓöÇΓöÇ,typeΓöÇΓöÇΓöÿ
  2821.  
  2822. Related Instruction: NUMERIC 
  2823.  
  2824. If type is omitted, DATATYPE returns NUM when the string represents a valid 
  2825. REXX number (including decimals or floating point).  It returns CHAR otherwise. 
  2826.  
  2827. When the type is specified, DATATYPE returns a 1 when the string is in the 
  2828. typed category, and 0 when it is not. For reasons that are beyond me, the null 
  2829. string is considered to be only a hexadecimal string, i.e., DATATYPE on the 
  2830. null string will return 0 for every type except X, in which case it will return 
  2831. a 1. 
  2832.  
  2833.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  2834.  Γöé  Type         Γöé      Definition                        Γöé
  2835.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2836.  Γöé  Alphanumeric Γöé returns 1 if string has only chars in  Γöé
  2837.  Γöé               Γöé        ranges a-z, A-Z, 0-9            Γöé
  2838.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2839.  Γöé  Bits         Γöé returns 1 if string has only chars in  Γöé
  2840.  Γöé               Γöé  ranges 0-1                            Γöé
  2841.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2842.  Γöé  C            Γöé returns 1 if string is a mixed SBCS/   Γöé OS/2, VM and TSO
  2843.  Γöé               Γöé  DBCS string                           Γöé
  2844.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2845.  Γöé  DBCS         Γöé returns 1 if string is a pure DBCS     Γöé OS/2, VM and TSO
  2846.  Γöé               Γöé  string                                Γöé
  2847.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2848.  Γöé  Lowercase    Γöé returns 1 if string has only chars in  Γöé
  2849.  Γöé               Γöé range a-z                              Γöé
  2850.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2851.  Γöé  Mixed case   Γöé returns 1 if string has only chars in  Γöé
  2852.  Γöé               Γöé ranges a-z and A-Z                     Γöé
  2853.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2854.  Γöé  Number       Γöé returns 1 if string is a valid REXX    Γöé
  2855.  Γöé               Γöé number <remember, it could be floating Γöé
  2856.  Γöé               Γöé point>                                 Γöé
  2857.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2858.  Γöé  Symbol       Γöé returns 1 if string is a valid REXX    Γöé
  2859.  Γöé               Γöé  symbol                                Γöé
  2860.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2861.  Γöé  Uppercase    Γöé returns 1 if string has only chars in  Γöé
  2862.  Γöé               Γöé  range A-Z                             Γöé
  2863.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2864.  Γöé  Whole number Γöé returns 1 if string is a REXX whole    Γöé
  2865.  Γöé               Γöé  number <according to current setting  Γöé
  2866.  Γöé               Γöé of NUMERIC DIGITS>                     Γöé
  2867.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2868.  Γöé heXadecimal   Γöé returns 1 if string has only chars in  Γöé
  2869.  Γöé               Γöé ranges a-f, A-F, 0-9, and blank        Γöé
  2870.  Γöé               Γöé <blanks can appear between pairs of    Γöé
  2871.  Γöé               Γöé hexadecimal characters for readability>Γöé
  2872.  Γöé               Γöé also returns 1 for the null string     Γöé
  2873.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  2874.  
  2875. Only the underscored, capitalized letter in the types above is required by 
  2876. DATATYPE. 
  2877.  
  2878. Examples: 
  2879.  
  2880. DATATYPE('654  ')                       returns 'NUM'
  2881. DATATYPE('')                            returns 'CHAR'
  2882. DATATYPE('12-1')                        returns 'CHAR'
  2883. DATATYPE('abc','A')                     returns 1
  2884. DATATYPE('abc','N')                     returns 0
  2885. DATATYPE('a285839985a3  83968485','X')  returns 1
  2886. DATATYPE('?X','S')                      returns 1
  2887.  
  2888. More examples, in a tabular form: 
  2889.  
  2890.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  2891.  Γöé          Γöé         type               Γöé
  2892.  Γöé string   Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöñ
  2893.  Γöé          Γöé(none)ΓöéAΓöéBΓöéCΓöéDΓöéLΓöéMΓöéNΓöéSΓöéUΓöéWΓöéXΓöé
  2894.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2895.  Γöé'123.45'  Γöé NUM  Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé1Γöé1Γöé0Γöé0Γöé0Γöé
  2896.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2897.  Γöé'-4e9'    Γöé NUM  Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé1Γöé0Γöé0Γöé0Γöé0Γöé
  2898.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2899.  Γöé'5e6'     Γöé NUM  Γöé1Γöé0Γöé0Γöé0Γöé0Γöé0Γöé1Γöé1Γöé0Γöé1Γöé1Γöé
  2900.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2901.  Γöé'+1.'     Γöé NUM  Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé1Γöé0Γöé0Γöé1Γöé0Γöé
  2902.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2903.  Γöé'1'       Γöé NUM  Γöé1Γöé1Γöé0Γöé0Γöé0Γöé0Γöé1Γöé1Γöé0Γöé1Γöé1Γöé
  2904.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2905.  Γöé'10101010'Γöé NUM  Γöé1Γöé1Γöé0Γöé0Γöé0Γöé0Γöé1Γöé1Γöé0Γöé0Γöé1Γöé
  2906.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2907.  Γöé''        Γöé CHAR Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé0Γöé
  2908.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2909.  Γöé'Ab'      Γöé CHAR Γöé1Γöé0Γöé0Γöé0Γöé0Γöé1Γöé0Γöé1Γöé0Γöé0Γöé1Γöé
  2910.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2911.  Γöé'MS'      Γöé CHAR Γöé1Γöé0Γöé0Γöé0Γöé0Γöé1Γöé0Γöé1Γöé1Γöé0Γöé0Γöé
  2912.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓö╝ΓöÇΓöñ
  2913.  Γöé'xy'      Γöé CHAR Γöé1Γöé0Γöé1Γöé1Γöé1Γöé1Γöé0Γöé1Γöé0Γöé0Γöé0Γöé
  2914.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓöÿ
  2915.  
  2916.  
  2917. ΓòÉΓòÉΓòÉ 6.22. DATE( ) - Return System Date ΓòÉΓòÉΓòÉ
  2918.  
  2919. DATE returns a variety of formats for the current date. 
  2920.  
  2921.  ΓöÇΓöÇDATE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2922.            ΓööΓöÇΓöÇoptionΓöÇΓöÇΓöÿ
  2923.  
  2924. Related Functions: TIME( ) 
  2925.  
  2926. The default option is "Normal."  All calls in the same statement return the 
  2927. same value. 
  2928.  
  2929.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  2930.  Γöé Option Γöé Example                                             Γöé
  2931.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2932.  ΓöéBasedateΓöé726236     Γöédays since Jan 1, 0001; date(b)//7       Γöéno VM
  2933.  Γöé        Γöé           Γöégives 0-6, where 0 is Monday, 6 is SundayΓöé(R.4)
  2934.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2935.  ΓöéCentury Γöé32642      Γöédays since Jan 1 1900 (in next century,  ΓöéTSO
  2936.  Γöé        Γöé           Γöéwill be days since Jan 1 2000)           ΓöéVM
  2937.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2938.  ΓöéDays    Γöé135        Γöédays so far in year, including today     Γöé
  2939.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2940.  ΓöéEuropeanΓöé15/05/89   Γöédd/mm/yy                                 Γöé
  2941.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2942.  ΓöéJulian  Γöé89135      Γöéyyddd                                    ΓöéTSO,VM
  2943.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2944.  ΓöéLanguageΓöé?????????? Γöédate in an implementation & language     Γöé
  2945.  Γöé        Γöé           Γöédependent format; assume NOTHING of its  ΓöéOS/2
  2946.  Γöé        Γöé           Γöéinternal structure -- use it as a whole  Γöé
  2947.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2948.  ΓöéMonth   ΓöéMay        Γöémonth of year, spelled out in English    Γöé
  2949.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2950.  ΓöéNormal  Γöé15 May 1989Γöépreferred because there is no confusion  Γöé
  2951.  Γöé        Γöé           Γöébetween European and USA conventions     Γöé
  2952.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2953.  ΓöéOrdered Γöé89/05/15   Γöéyy/mm/dd                                 Γöé
  2954.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2955.  ΓöéSorted  Γöé           Γöé                                         Γöé
  2956.  Γöé    or  Γöé890515     Γöéyyyymmdd                                 Γöé
  2957.  ΓöéStandardΓöé           Γöé                                         Γöé
  2958.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2959.  ΓöéUsa     Γöé05/15/89   Γöémm/dd/yy                                 Γöé
  2960.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2961.  ΓöéWeekday ΓöéMonday     Γöéday of week, English, mixed case         Γöé
  2962.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  2963.  
  2964. Only the underscored, capitalized letter in the types above is required by 
  2965. DATE. 
  2966.  
  2967. Examples: 
  2968.  
  2969. DATE( )      returns  23 Sep 1990
  2970. DATE('B')    returns  726732
  2971. DATE('D')    returns  266
  2972. DATE('E')    returns  23/09/90
  2973. /* Remember, you cannot rely on the */
  2974. /* format of the 'L' option date.   */
  2975. DATE('L')    returns  23 September 1990 /* OS/2   */
  2976. DATE('L')    returns  90266             /* TSO,VM */
  2977. DATE('M')    returns  September
  2978. DATE('N')    returns  23 Sep 1990
  2979. DATE('O')    returns  90/09/23
  2980. DATE('S')    returns  19900923
  2981. DATE('U')    returns  09/23/90
  2982. DATE('W')    returns  Sunday
  2983.  
  2984.  
  2985. ΓòÉΓòÉΓòÉ 6.23. DBCS( ) - Set DBCS Option ΓòÉΓòÉΓòÉ
  2986.  
  2987. There are some special DBCS functions; see the reference manuals. DBCS stands 
  2988. for Double Byte Character Set. DBCS is used for languages which are 
  2989. ideographic, like Japanese, Korean, and Chinese, et. al. 
  2990.  
  2991. DBADJUST  DBBRACKET DBCENTER DBLEFT      DBRIGHT    DBRLEFT
  2992. DBRRIGHT  DBTODBCS  DBTOSBCS DBUNBRACKET DBVALIDATE DBWIDTH
  2993. DBJUSTIFY
  2994.  
  2995.  
  2996. ΓòÉΓòÉΓòÉ 6.24. DELSTR( ) - Delete Substring ΓòÉΓòÉΓòÉ
  2997.  
  2998. DELSTR removes length characters from a string starting at position n. 
  2999.  
  3000.  ΓöÇΓöÇDELSTR(string,nΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3001.                      ΓööΓöÇΓöÇ,lengthΓöÇΓöÇΓöÿ
  3002.  
  3003. The length defaults to the remainder of the string. 
  3004.  
  3005. Examples: 
  3006.  
  3007. DELSTR('carpet',4)        returns 'car'
  3008. DELSTR('carpet',4,1)      returns 'caret'
  3009. DELSTR('carpet',4,2)      returns 'cart'
  3010. DELSTR('carpet',1,3)      returns 'pet'
  3011.  
  3012.  
  3013. ΓòÉΓòÉΓòÉ 6.25. DELWORD( ) - Delete Words ΓòÉΓòÉΓòÉ
  3014.  
  3015. DELWORD removes length number of blank-delimited words from a string starting 
  3016. with the nth word. 
  3017.  
  3018.  ΓöÇΓöÇDELWORD(string,nΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3019.                       ΓööΓöÇΓöÇ,lengthΓöÇΓöÇΓöÿ
  3020.  
  3021. The length defaults to the remainder of the string. 
  3022.  
  3023. Examples: 
  3024.  
  3025. DELWORD('response is not valid',3,1)  returns 'response is valid'
  3026. DELWORD('response is not valid',2)    returns 'response'
  3027.  
  3028.  
  3029. ΓòÉΓòÉΓòÉ 6.26. DIAG( ) - Communicate with CP ΓòÉΓòÉΓòÉ
  3030.  
  3031. DIAG communicates with the CP via a dummy DIAGNOSE instruction. 
  3032.  
  3033.  ΓöÇΓöÇDIAG(nΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3034.              ΓööΓöÇ?ΓöÇΓöÿ  ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé
  3035.                     Γöé         ΓöéΓöé
  3036.                     ΓööΓö┤ΓöÇ,numberΓöÇΓö┤Γöÿ
  3037.  
  3038. Note:  VM only. 
  3039.  
  3040. Related Functions: DIAGRC( ) 
  3041.  
  3042. See the VM manual for details. 
  3043.  
  3044.  
  3045. ΓòÉΓòÉΓòÉ 6.27. DIAGRC( ) ΓòÉΓòÉΓòÉ
  3046.  
  3047. DIAGRC is like DIAG, except data returned is prefixed by return and condition 
  3048. codes. 
  3049.  
  3050.  ΓöÇΓöÇDIAGRC(nΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3051.                ΓööΓöÇ?ΓöÇΓöÿ  ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé
  3052.                       Γöé         ΓöéΓöé
  3053.                       ΓööΓö┤ΓöÇ,numberΓöÇΓö┤Γöÿ
  3054.  
  3055. Note:  VM only. 
  3056.  
  3057. Related Functions: DIAG( ) 
  3058.  
  3059. See the VM manual for details. 
  3060.  
  3061.  
  3062. ΓòÉΓòÉΓòÉ 6.28. DIGITS( ) - Return NUMERIC DIGITS Settings ΓòÉΓòÉΓòÉ
  3063.  
  3064. DIGITS returns the current NUMERIC DIGITS setting. 
  3065.  
  3066.  ΓöÇΓöÇDIGITS( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3067.  
  3068. Related Instruction: NUMERIC 
  3069.  
  3070. DIGITS returns the maximum number of digits that can used for numbers in REXX 
  3071. programs, based on the current setting of NUMERIC DIGITS.  The default NUMERIC 
  3072. DIGITS specification is 9. 
  3073.  
  3074.  
  3075. ΓòÉΓòÉΓòÉ 6.29. DIRECTORY( ) - Change  OS/2 Directory ΓòÉΓòÉΓòÉ
  3076.  
  3077. DIRECTORY returns and/or changes the current directory. 
  3078.  
  3079.  ΓöÇΓöÇDIRECTORY(ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3080.                  ΓööΓöÇnewdirectoryΓöÇΓöÇΓöÿ
  3081.  
  3082. Note:  OS/2 only. 
  3083.  
  3084. DIRECTORY returns the current directory, FIRST changing it to the newdirectory 
  3085. if it has been specified. It includes a drive letter;  newdirectory can 
  3086. optionally contain a drive letter, in which case the drive is also changed, not 
  3087. just the directory. 
  3088.  
  3089. CAUTION:
  3090. This function is somewhat unusual compared to other similarly structured REXX 
  3091. functions in that the value returned is the new value, not the old value. 
  3092.  
  3093.  
  3094. ΓòÉΓòÉΓòÉ 6.30. D2C( ) - Decimal to Character String Conversion ΓòÉΓòÉΓòÉ
  3095.  
  3096. D2C converts a number to the character string whose binary representation is 
  3097. the number. 
  3098.  
  3099.  ΓöÇΓöÇD2C(wholenumberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3100.                      ΓööΓöÇ,nΓöÇΓöÇΓöÿ
  3101.  
  3102. If the number n (the length of the final result) is omitted, then the input 
  3103. wholenumber must not be negative.  The result returned is the minimum number of 
  3104. characters whose binary representation is the number. 
  3105.  
  3106. When n is specified, it indicates what the length of the final result should 
  3107. be.  If n is longer than it needs to be to express the number in binary, then 
  3108. the result is sign extended on the left (negative numbers being represented in 
  3109. two's complement notation).  If n is shorter than it needs to be to fully 
  3110. express the number in binary, then the result is simply truncated from the 
  3111. left. 
  3112.  
  3113. Examples: 
  3114.  
  3115. D2C(193)         returns 'C1'x /* 'A' in EBCDIC */
  3116. D2C(65)          returns '41'x /* 'A' in ASCII */
  3117. D2C(-1)          returns /* illegal */
  3118. D2C(-1,2)        returns 'FFFF'x
  3119. D2C(-1,4)        returns 'FFFFFFFF'x
  3120. D2C(10000012,4)  returns '0098968C'x
  3121. D2C(9040)        returns '2350'x
  3122. D2C(9040,1)      returns '50'x
  3123. D2C(9040,2)      returns '2350'x
  3124. D2C(9040,3)      returns '002350'x
  3125. D2C(9040,4)      returns '00002350'x
  3126.  
  3127.  
  3128. ΓòÉΓòÉΓòÉ 6.31. D2X( ) - Decimal to Hex Conversion ΓòÉΓòÉΓòÉ
  3129.  
  3130. D2X converts a number to hexadecimal. 
  3131.  
  3132.  ΓöÇΓöÇD2X(wholenumberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3133.                      ΓööΓöÇ,nΓöÇΓöÇΓöÿ
  3134.  
  3135. If n (the length in characters of the result) is omitted, then the wholenumber 
  3136. must not be negative, and the result is as long as it needs to be without using 
  3137. leading zeros. 
  3138.  
  3139. When n is specified and longer than it needs to be, then the result is 
  3140. sign-extended on the left (two's complement notation). When n is specified and 
  3141. shorter than it needs to be, the result is truncated on the left. 
  3142.  
  3143. Examples: 
  3144.  
  3145. D2X(193)       returns 'C1'
  3146. D2X(193,1)     returns '1'
  3147. D2X(193,2)     returns 'C1'
  3148. D2X(193,3)     returns '0C1'
  3149. D2X(193,4)     returns '00C1'
  3150. D2X(-1)        returns /* illegal */
  3151. D2X(-1,1)      returns 'F'
  3152. D2X(-1,2)      returns 'FF'
  3153. D2X(-1,3)      returns 'FFF'
  3154. D2X(-1,4)      returns 'FFFF'
  3155.  
  3156. C2X(D2C(number,n))  returns D2X(number,2*n)
  3157.  
  3158.  
  3159. ΓòÉΓòÉΓòÉ 6.32. ENDLOCAL( ) - End OS/2 Local Setting ΓòÉΓòÉΓòÉ
  3160.  
  3161. ENDLOCAL undoes the effect of the last SETLOCAL. 
  3162.  
  3163.  ΓöÇΓöÇENDLOCAL( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3164.  
  3165. Note:  OS/2 only. 
  3166.  
  3167. Related Functions: SETLOCAL( ) 
  3168.  
  3169. ENDLOCAL returns 1 for a succesful restore of the drive, directory, and 
  3170. environment variables.  It returns 0 if there was no previous SETLOCAL, or for 
  3171. any other failure. 
  3172.  
  3173. Note:  SETLOCAL and ENDLOCAL can be nested in REXX programs; this is not 
  3174. possible in regular batch procedures. 
  3175.  
  3176. If a REXX program that issues SETLOCAL ends without calling ENDLOCAL, an 
  3177. implicit ENDLOCAL is performed at termination. 
  3178.  
  3179. Example: 
  3180.  
  3181. call setlocal
  3182. oldpath = value('path',,'OS2ENVIRONMENT')
  3183. call value 'path',,
  3184.     newpathpart';'oldpath,,
  3185.     'OS2ENVIRONMENT'
  3186.  ...
  3187. /* do some things with new path */
  3188.  ...
  3189. call endlocal
  3190.  
  3191.  
  3192. ΓòÉΓòÉΓòÉ 6.33. ERRORTEXT( ) - Return Error Message Text ΓòÉΓòÉΓòÉ
  3193.  
  3194. ERRORTEXT returns the error message text for REXX error message n. 
  3195.  
  3196.  ΓöÇΓöÇERRORTEXT(n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3197.  
  3198. Related Functions: CONDITION( ) 
  3199.  
  3200. Most implementations use identical text and meaning for all REXX error codes 
  3201. less than 50.  The SAA specification only lists error messages from 1 to 50. 
  3202.  
  3203. Error Messages 
  3204.  
  3205.    1: File Table full
  3206.    2: Interpret expression > 64000 characters
  3207.    3: Program is unreadable
  3208.    4: Program interrupted
  3209.    5: Machine resources exhausted
  3210.    6: Unmatched "/*" or quote
  3211.    7: WHEN or OTHERWISE expected
  3212.    8: Unexpected THEN or ELSE
  3213.    9: Unexpected WHEN or OTHERWISE
  3214.   10: Unexpected or unmatched END
  3215.   11: Control stack full
  3216.   12: Clause too long
  3217.   13: Invalid character in program
  3218.   14: Incomplete DO/SELECT/IF
  3219.   15: Invalid hexadecimal or binary string
  3220.   16: Label not found
  3221.   17: Unexpected PROCEDURE
  3222.   18: THEN expected
  3223.   19: String or symbol expected
  3224.   20: Symbol expected
  3225.   21: Invalid data on end of clause
  3226.   22: Invalid character string
  3227.   23: Invalid data string
  3228.   24: Invalid TRACE request
  3229.   25: Invalid sub-keyword found
  3230.   26: Invalid whole number
  3231.   27: Invalid DO syntax
  3232.   28: Invalid LEAVE or ITERATE
  3233.   29: Environment name too long
  3234.   30: Name or string too long
  3235.   31: Name starts with number or "."
  3236.   32: Invalid use of stem
  3237.   33: Invalid expression result
  3238.   34: Logical value not 0 or 1
  3239.   35: Invalid expression
  3240.   36: Unmatched "(" in expression
  3241.   37: Unexpected "," or ")"
  3242.   38: Invalid template or pattern
  3243.   39: Evaluation stack overflow
  3244.   40: Incorrect call to routine
  3245.   41: Bad arithmetic conversion
  3246.   42: Arithmetic overflow/underflow
  3247.   43: Routine not found
  3248.   44: Function did not return data
  3249.   45: No data specified on function RETURN
  3250.   46: Invalid variable reference
  3251.   48: Failure in system service
  3252.   49: Interpretation error
  3253.  115: The RXSUBCOM parameters are incorrect
  3254.  116: The RXSUBCOM parameter REGISTER is incorrect
  3255.  117: The RXSUBCOM parameter DROP is incorrect
  3256.  118: The RXSUBCOM parameter LOAD is incorrect
  3257.  119: Invalid file name
  3258.  
  3259.  
  3260. ΓòÉΓòÉΓòÉ 6.34. EXTERNALS( ) ΓòÉΓòÉΓòÉ
  3261.  
  3262. EXTERNALS returns the number of elements in the terminal input buffer 
  3263. (type-ahead). 
  3264.  
  3265.  ΓöÇΓöÇEXTERNALS( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3266.  
  3267. Note:  In TSO always returns 0. 
  3268.  
  3269.  
  3270. ΓòÉΓòÉΓòÉ 6.35. FILESPEC( ) ΓòÉΓòÉΓòÉ
  3271.  
  3272. FILESPEC can return the drive, the directory, or the filename of a given file 
  3273. specification. 
  3274.  
  3275.  ΓöÇΓöÇFILESPEC(option,filespec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3276.  
  3277. Note:  OS/2 only. 
  3278.  
  3279. This is only guaranteed to work on file specifications that are valid. The 
  3280. valid options are: 
  3281.  
  3282.  o Drive 
  3283.  o Path 
  3284.  o Name 
  3285.  
  3286.  Only the first character of each option need be specified. 
  3287.  
  3288.  The drive is identified as anything up to and including the first colon (:) in 
  3289.  the filespec. The path is identified as anything from the first character 
  3290.  after the colon (or the absolute first character, if no colon is present) in 
  3291.  the filespec up to and including the last slash (/) or backslash (\).  The 
  3292.  name is identified as anything after the last slash or backslash or colon 
  3293.  through the end of the filespec.  Since this is entirely driven by delimiters, 
  3294.  no considerations of IFS or HPFS long names or special characters, or even of 
  3295.  valid characters, enter into the processing. 
  3296.  
  3297.  Examples: 
  3298.  
  3299.   filespec("d","C:CONFIG.SYS")          returns "C:"
  3300.   filespec("p","C:CONFIG.SYS")          returns ""
  3301.   filespec("n","C:CONFIG.SYS")          returns "CONFIG.SYS"
  3302.   filespec("d","C:\CONFIG.SYS")         returns "C:"
  3303.   filespec("p","C:\CONFIG.SYS")         returns "\"
  3304.   filespec("n","C:\CONFIG.SYS")         returns "CONFIG.SYS"
  3305.   filespec("D","C:/os2\cmd.Exe")        returns "C:"
  3306.   filespec("P","C:/os2\cmd.Exe")        returns "/os2\"
  3307.   filespec("N","C:/os2\cmd.Exe")        returns "cmd.exe"
  3308.   filespec("D","abc\def")               returns ""
  3309.   filespec("P","abc\def")               returns "abc\def"
  3310.   filespec("N","abc\def")               returns ""
  3311.   filespec("D","abc\def:g:a.b/c") returns "abc\def:"
  3312.   filespec("P","abc\def:g:a.b/c") returns "abc\def:g:a.b/"
  3313.   filespec("N","abc\def:g:a.b/c") returns "c"
  3314.  
  3315.  
  3316. ΓòÉΓòÉΓòÉ 6.36. FIND( ) - Search for Word ΓòÉΓòÉΓòÉ
  3317.  
  3318. FIND is the same as WORDPOS(phrase, string). 
  3319.  
  3320.  ΓöÇΓöÇFIND(string,phrase)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3321.  
  3322. Related Functions: WORDPOS( ) 
  3323.  
  3324. Same as WORDPOS(phrase,string); WORDPOS is prefered but may not be implemented 
  3325. in older versions. 
  3326.  
  3327.  
  3328. ΓòÉΓòÉΓòÉ 6.37. FORM( ) - Return NUMERIC FORM Settings ΓòÉΓòÉΓòÉ
  3329.  
  3330. FORM returns the current setting of NUMERIC FORM (SCIENTIFIC or ENGINEERING). 
  3331.  
  3332.  ΓöÇΓöÇFORM( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3333.  
  3334. Related Instructions: NUMERIC 
  3335.  
  3336.  
  3337. ΓòÉΓòÉΓòÉ 6.38. FORMAT( ) - Format Numeric Strings ΓòÉΓòÉΓòÉ
  3338.  
  3339. FORMAT prepares a number for display, rounding and formatting. 
  3340.  
  3341.  ΓöÇΓöÇFORMAT(numberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇ
  3342.                    ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  3343.                        ΓööbeforeΓöÿ Γöö,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  3344.                                    ΓööafterΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  3345.                                                ΓööexppΓöÿ ΓööexptΓöÿ
  3346.  
  3347. Related Instruction: NUMERIC 
  3348.  
  3349. Note:  VM (R.4) does not implement expp and expt. 
  3350.  
  3351. The before and after specify how many positions to use before and after the 
  3352. decimal point, respectively.  These default to using as many positions as are 
  3353. needed. 
  3354.  
  3355. The expp specifies exponent precision, or number of places in the exponent; 
  3356. the default is to use as many as are necessary. The expt specifies the exponent 
  3357. trigger. 
  3358.  
  3359. Examples: 
  3360.  
  3361. FORMAT('3',4)            returns ' 3'
  3362. FORMAT('2.7128',2,0)     returns ' 3'
  3363. FORMAT('2.7128',2,3)     returns ' 2.713'
  3364. FORMAT('-2.7128',2,5)    returns '-2.71280'
  3365. FORMAT('3.14159262',0,4) returns '.1416'
  3366.  
  3367.  
  3368. ΓòÉΓòÉΓòÉ 6.39. FUZZ( ) - Return NUMERIC FUZZ Settings ΓòÉΓòÉΓòÉ
  3369.  
  3370.  ΓöÇΓöÇFUZZ( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3371.  
  3372. Related Instructions: NUMERIC 
  3373.  
  3374. Returns current setting of NUMERIC FUZZ. 
  3375.  
  3376. Examples: 
  3377.  
  3378. FUZZ()               returns 0  /* by default */
  3379.  
  3380.  
  3381. ΓòÉΓòÉΓòÉ 6.40. GETMSG( ) ΓòÉΓòÉΓòÉ
  3382.  
  3383. Retrieves session console messages. 
  3384.  
  3385.  ΓöÇΓöÇGETMSG(msgstemΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇ
  3386.                     Γöö,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3387.                        Γöö,msgtypeΓöÿ Γöö,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3388.                                      Γöö,cartΓöÿ Γöö,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3389.                                                 Γöö,maskΓöÿ Γöö,timeΓöÿ
  3390.  
  3391. Note:  Available on TSO only. 
  3392.  
  3393. Refer to the TSO Extensions Version 2 Procedures Language MVS / REXX Reference 
  3394. manual for a full description of this function. 
  3395.  
  3396.  
  3397. ΓòÉΓòÉΓòÉ 6.41. INDEX( ) - Search for Substring ΓòÉΓòÉΓòÉ
  3398.  
  3399.  ΓöÇΓöÇINDEX(haystack,needleΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3400.                             ΓööΓöÇ,startΓöÇΓöÇΓöÿ
  3401.  
  3402. Returns position of leftmost needle string in haystack string, starting from 
  3403. position start in haystack, or returns 0 if needle is not found. 
  3404.  
  3405. Note:  This function has been replaced in the SAA specification by the POS( ) 
  3406. function. POS( ) should be used wherever possible for future compatibility. 
  3407.  
  3408. Examples: 
  3409.  
  3410. INDEX('abracadabra','dab')     returns 7
  3411. INDEX('abracadabra','dba')     returns 0
  3412. INDEX('abracadabra','ab')      returns 1
  3413. INDEX('abracadabra','ab',2)    returns 8
  3414. INDEX('abracadabra','ab',9)    returns 0
  3415.  
  3416.  
  3417. ΓòÉΓòÉΓòÉ 6.42. INSERT( ) - Insert Substring ΓòÉΓòÉΓòÉ
  3418.  
  3419.  ΓöÇΓöÇINSERT(new,targetΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3420.                        ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  3421.                            ΓööΓöÇnΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  3422.                                      ΓöölengthΓöÿ Γöö,padΓöÿ
  3423.  
  3424. Inserts length characters of new string into the target string, padding with 
  3425. the pad string, after position n in the target string;  n defaults to 0, i.e., 
  3426. insert before the beginning of target. The default pad is the blank character. 
  3427.  
  3428. Examples: 
  3429.  
  3430. INSERT('abcd','efg')              returns 'abcdefg'
  3431. INSERT('abcd','efg',3)            returns 'efgabcd'
  3432. INSERT(' ','efg',2)               returns 'ef g'
  3433. INSERT('second','first',9,8,'*')  returns 'first***second**'
  3434.  
  3435.  
  3436. ΓòÉΓòÉΓòÉ 6.43. JUSTIFY( ) - Justify String of Words ΓòÉΓòÉΓòÉ
  3437.  
  3438.  ΓöÇΓöÇJUSTIFY(string,lengthΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3439.                             ΓööΓöÇ,padΓöÇΓöÇΓöÿ
  3440.  
  3441. Takes the words (blank-delimited) in string, and spreads them out evenly to a 
  3442. length of length by inserting blanks between words.  If length is less than the 
  3443. length of string, truncate letters on the right. 
  3444.  
  3445. Examples: 
  3446.  
  3447. JUSTIFY('This is balanced.',21)   returns 'This   is   balanced.'
  3448.  
  3449.  
  3450. ΓòÉΓòÉΓòÉ 6.44. LASTPOS( ) - Determine Last Position of Phrase ΓòÉΓòÉΓòÉ
  3451.  
  3452.  ΓöÇΓöÇLASTPOS(needle,haystackΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3453.                               ΓööΓöÇ,startΓöÇΓöÇΓöÿ
  3454.  
  3455. Related Functions: POS( ) 
  3456.  
  3457. Returns the position of the rightmost occurrence of the needle string in the 
  3458. haystack string, or returns 0 if not found;  start is the rightmost character 
  3459. which the is to be scanned in the right to left direction. 
  3460.  
  3461. start defaults to the last position in haystack. 
  3462.  
  3463. Examples: 
  3464.  
  3465. LASTPOS('abra','abracadabra')  returns 8
  3466.  
  3467.  
  3468. ΓòÉΓòÉΓòÉ 6.45. LEFT( ) - Left-Align String ΓòÉΓòÉΓòÉ
  3469.  
  3470.  ΓöÇΓöÇLEFT(string,lengthΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3471.                          ΓööΓöÇ,padΓöÇΓöÇΓöÿ
  3472.  
  3473. Related Functions: RIGHT( ) 
  3474.  
  3475. Returns the leftmost length characters of string, padded, if necessary, with 
  3476. pad. The default pad is the blank character. 
  3477.  
  3478. Examples: 
  3479.  
  3480. LEFT('abracadabra',2)          returns 'ab'
  3481. LEFT('a',4)LEFT('b',4)'c'      returns 'a b c'
  3482.  
  3483.  
  3484. ΓòÉΓòÉΓòÉ 6.46. LENGTH( ) - Return Length of String ΓòÉΓòÉΓòÉ
  3485.  
  3486.  ΓöÇΓöÇLENGTH(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3487.  
  3488. Returns the length of string. 
  3489.  
  3490. Examples: 
  3491.  
  3492. LENGTH('ab c')         returns 4
  3493. LENGTH('ab c  ')       returns 6
  3494. LENGTH('')             returns 0
  3495.  
  3496.  
  3497. ΓòÉΓòÉΓòÉ 6.47. LINEIN( ) - Read a Line ΓòÉΓòÉΓòÉ
  3498.  
  3499.  ΓöÇΓöÇLINEIN(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇ
  3500.              ΓööΓöÇnameΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
  3501.                            ΓööΓöÇstartΓöÇΓöÇΓöÿ ΓööΓöÇ,countΓöÇΓöÿ
  3502.  
  3503. Related Functions: LINEOUT( ), LINES( ) 
  3504.  
  3505. Note:  OS/2 has the only implementation. 
  3506.  
  3507. Returns a line from the input stream name.  The count defaults to 1.  Count is 
  3508. 0 or 1. 
  3509.  
  3510.  
  3511. ΓòÉΓòÉΓòÉ 6.48. LINEOUT( ) - Write a Line ΓòÉΓòÉΓòÉ
  3512.  
  3513.  ΓöÇΓöÇLINEOUT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇ
  3514.               ΓööΓöÇnameΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
  3515.                             ΓööΓöÇstringΓöÇΓöÿ ΓööΓöÇ,lineΓöÇΓöÿ
  3516.  
  3517. Related Functions: LINEIN( ), LINES( ) 
  3518.  
  3519. Note:  OS/2 has the only implementation. 
  3520.  
  3521. Returns count of lines remaining after attempting to write to the the name 
  3522. stream.  Any value other than 0 indicates some type of error ocurred.  1 is 
  3523. only value other than 0.  If name is omitted, the default output stream 
  3524. (STDOUT:) is used.  The default positioning for output streams is at the end of 
  3525. the file. E.g., use: 
  3526.  
  3527. call lineout(myfile,,1)
  3528.  
  3529. to open file, if not already open, and position to the beginning of the file. 
  3530.  
  3531.  
  3532. ΓòÉΓòÉΓòÉ 6.49. LINES( ) - Return Status of Input Stream ΓòÉΓòÉΓòÉ
  3533.  
  3534.  ΓöÇΓöÇLINES(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇ
  3535.             ΓööΓöÇnameΓöÇΓöÿ
  3536.  
  3537. Related Functions: LINEIN( ), LINEOUT( ) 
  3538.  
  3539. Note:  OS/2 has the only implementation. 
  3540.  
  3541. Returns 1 if any data is remaining in the input stream between the current 
  3542. positions and the end.  name defaults to "STDIN:". The following is a common 
  3543. construct to copy a file: 
  3544.  
  3545. Example: 
  3546.  
  3547. call lineout outfile,,1 /* open, position to end */
  3548. do while lines(myfile)
  3549.    call linein myfile, thisline
  3550.    call lineout myfile, thisline
  3551.    end
  3552.  
  3553.  
  3554. ΓòÉΓòÉΓòÉ 6.50. LINESIZE( ) - Return Width of Terminal ΓòÉΓòÉΓòÉ
  3555.  
  3556.  ΓöÇΓöÇLINESIZE( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3557.  
  3558. Note:  VM and TSO only. 
  3559.  
  3560. Returns the terminal line width - 1; in background TSO, always returns 132. 
  3561. When in full-screen VM, always returns 999999999. 
  3562.  
  3563.  
  3564. ΓòÉΓòÉΓòÉ 6.51. LISTDSI( ) - Determine Dataset Status ΓòÉΓòÉΓòÉ
  3565.  
  3566.  ΓöÇΓöÇLISTDSI(ΓöÇΓö¼ΓöÇdsnΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ
  3567.               Γöé     ΓööΓöÇlocationΓöÇΓöÿ Γöé ΓööΓöÇdirectoryΓöÇΓöÿ ΓööΓöÇrecallΓöÇΓöÿ
  3568.               ΓööΓöÇfilenameΓöÇΓöÇΓöÇΓöÇtypeΓöÇΓöÿ
  3569.  
  3570. Note:  TSO only. 
  3571.  
  3572. Returns information about the data set specified by dsn. The following REXX 
  3573. variables are assigned values on successful execution: 
  3574.  
  3575.  SYSDSNAME           The data set name. 
  3576.  SYSVOLUME           The data set volume serial number. 
  3577.  SYSUNIT             The unit of the volume serial number. 
  3578.  SYSDSORG            "PS" for sequential; "PO" for partitioned; "DA" for 
  3579.                      direct; "VS" for VSAM. 
  3580.  SYSRECFM            "F" for fixed; "V" for variable; "A" for asa printer 
  3581.                      control; "B" for blocked. 
  3582.  SYSRECL             The logical record length. 
  3583.  SYSBLKSIZE          The block size ("VS" for VSAM). 
  3584.  SYSKEYLEN           The key length. 
  3585.  SYSALLOC            The space allocation. 
  3586.  SYSUSED             The space used. 
  3587.  SYSPRIMARY          The primary space allocation. 
  3588.  SYSSECONDS          The secondary space allocation. 
  3589.  SYSUNITS            The space units ("CYLINDER", "TRACK" or "BLOCK"). 
  3590.  SYSEXTENTS          The space extents used. 
  3591.  SYSCREATE           The creation date. 
  3592.  SYSREFDATE          The last reference date. 
  3593.  SYSEXDATE           The expiration date. 
  3594.  SYSPASSWORD         The type of password protection ("NONE", "READ" or 
  3595.                      "WRITE"). 
  3596.  SYSRACFA            The type of RACF protection ("NONE", "GENERIC" or 
  3597.                      "DISCRETE"). 
  3598.  SYSUPDATED          Data set updated ("YES" or "NO"). 
  3599.  SYSTRKSCYL          The tracks per cylinder on the volume. 
  3600.  SYSBLKSTRK          The number of blocks per track on the volume. 
  3601.  SYSADIRBLK          The number of directory blocks allocated. 
  3602.  SYSUDIRBLK          The number of directory blocks used. 
  3603.  SYSMEMBERS          The number of partitioned members. 
  3604.  SYSREASON           The reason code for command failure. 
  3605.  SYSMSGLVL1          The first level error message. 
  3606.  SYSMSGLVL2          The second level error message. 
  3607.  
  3608.  Returns 0 if the function was successful, 16 if not. 
  3609.  
  3610.  
  3611. ΓòÉΓòÉΓòÉ 6.52. MAX( ) - Return Maximum Value From a Set ΓòÉΓòÉΓòÉ
  3612.  
  3613.  ΓöÇΓöÇMAX(numberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3614.                 ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé
  3615.                 Γöé         ΓöéΓöé
  3616.                 ΓööΓö┤ΓöÇ,numberΓöÇΓö┤Γöÿ
  3617.  
  3618. Related Instruction: NUMERIC 
  3619.  
  3620. Returns the largest number in the list; up to 20 can be specified;  for more, 
  3621. can nest MAX( ) calls; can not be used with non-numeric arguments. (On VM, up 
  3622. to 10 numbers can be specified). 
  3623.  
  3624.  
  3625. ΓòÉΓòÉΓòÉ 6.53. MIN( ) - Return Minimum Value From a Set ΓòÉΓòÉΓòÉ
  3626.  
  3627.  ΓöÇΓöÇMIN(numberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3628.                 ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé
  3629.                 Γöé         ΓöéΓöé
  3630.                 ΓööΓö┤ΓöÇ,numberΓöÇΓö┤Γöÿ
  3631.  
  3632. Related Instruction: NUMERIC 
  3633.  
  3634. Returns the smallest number in the list; up to 20 can be specified;  for more, 
  3635. can nest MIN( ) calls; can not be used with non-numeric arguments. (On VM, up 
  3636. to 10 numbers can be specified). 
  3637.  
  3638.  
  3639. ΓòÉΓòÉΓòÉ 6.54. MSG( ) - Set TSO MSG Option ΓòÉΓòÉΓòÉ
  3640.  
  3641.  ΓöÇΓöÇMSG(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3642.           Γö£ΓöÇONΓöÇΓöÇΓöñ
  3643.           ΓööΓöÇOFFΓöÇΓöÿ
  3644.  
  3645. Returns and/or sets the value of the TSO MSG setting. The MSG setting 
  3646. determines whether or not TSO messages are displayed. The return value will be 
  3647. either ON or OFF. 
  3648.  
  3649. Note:  TSO only. 
  3650.  
  3651.  
  3652. ΓòÉΓòÉΓòÉ 6.55. OUTTRAP( ) - Trap TSO Display Output ΓòÉΓòÉΓòÉ
  3653.  
  3654.  ΓöÇΓöÇOUTTRAP(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3655.               Γö£ΓöÇOFFΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3656.               ΓööΓöÇvarnameΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3657.                         ΓööΓöÇmaxΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  3658.                                     ΓööΓöÇconcatΓöÇΓöÿ
  3659.  
  3660. Note:  TSO only. 
  3661.  
  3662. Turns on the capture of display output from TSO commands. Each display line is 
  3663. captured in a different element of the array formed from varname (a period at 
  3664. the end of varname is required). varname.0 will contain the number of elements 
  3665. in the array on successful execution. 
  3666.  
  3667. The OFF keyword discontinues the trapping of TSO commands. 
  3668.  
  3669.  
  3670. ΓòÉΓòÉΓòÉ 6.56. OVERLAY( ) - Replace Phrase in String ΓòÉΓòÉΓòÉ
  3671.  
  3672.  ΓöÇΓöÇOVERLAY(new,targetΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3673.                         ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  3674.                             ΓööΓöÇnΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  3675.                                       ΓöölengthΓöÿ Γöö,padΓöÿ
  3676.  
  3677. Overlays length characters in target starting at position n with characters 
  3678. from string new, padded if necessary with pad;  the length defaults to the 
  3679. length of new. The default pad is the blank character. If n is not given then 1 
  3680. is the default. 
  3681.  
  3682. Example: 
  3683.  
  3684. OVERLAY('  ','invalid')                                returns ' valid'
  3685. OVERLAY('1',OVERLAY('2','Version 1 Release 4',9),19)   returns 'Version 2 Release 1'
  3686.  
  3687.  
  3688. ΓòÉΓòÉΓòÉ 6.57. POS( ) - Search for Substring ΓòÉΓòÉΓòÉ
  3689.  
  3690.  ΓöÇΓöÇPOS(needle,haystackΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3691.                           ΓööΓöÇ,startΓöÇΓöÇΓöÿ
  3692.  
  3693. Related Functions: LASTPOS( ) 
  3694.  
  3695. Returns the leftmost position of the needle string in the haystack string, 
  3696. starting at the start position;  returns 0 if the needle string is not found. 
  3697. If start is not given then 1 is the default. 
  3698.  
  3699. Example: 
  3700.  
  3701. POS('/','09/23/52')      returns 3
  3702. POS('/','09/23/52',4)    returns 5
  3703. POS('6','09/23/52',4)    returns 0
  3704.  
  3705.  
  3706. ΓòÉΓòÉΓòÉ 6.58. PROMPT( ) - Set TSO PROMPT Option ΓòÉΓòÉΓòÉ
  3707.  
  3708.  ΓöÇΓöÇPROMPT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3709.              Γö£ΓöÇONΓöÇΓöÇΓöñ
  3710.              ΓööΓöÇOFFΓöÇΓöÿ
  3711.  
  3712. Returns and/or sets the value of the TSO PROMPT setting. The PROMPT setting 
  3713. determines TSO commands can prompt or not. The return value will be either ON 
  3714. or OFF. 
  3715.  
  3716. Note:  TSO only. 
  3717.  
  3718.  
  3719. ΓòÉΓòÉΓòÉ 6.59. QUEUED( ) - Return Number of Entries in Queue ΓòÉΓòÉΓòÉ
  3720.  
  3721.  ΓöÇΓöÇQUEUED( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3722.  
  3723. Related Instructions: PARSE, PULL, PUSH, QUEUE 
  3724. Related Function: RXQUEUE( ) 
  3725.  
  3726. Returns the number of lines in the data stack (see the TSO/E REXX User's Guide 
  3727. for a complete discussion of all the things you can do with the data stack; 
  3728. the data stack should not be confused with the old TSO command stack). Also 
  3729. available on VM: returns the number of lines in the program stack. 
  3730.  
  3731.  
  3732. ΓòÉΓòÉΓòÉ 6.60. RANDOM( ) - Return Random Number ΓòÉΓòÉΓòÉ
  3733.  
  3734.  ΓöÇΓöÇRANDOM(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3735.              Γö£ΓöÇmaxΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3736.              Γö£ΓöÇmin,ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  3737.              ΓööΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇmaxΓöÇΓöÿ ΓööΓöÇ,seedΓöÇΓöÿ
  3738.  
  3739. Returns a pseudo-random whole number in the range MAX(0,min) to max; min 
  3740. defaults to 0, and max defaults to 999;  the seed can be used to obtain 
  3741. repeatable results for testing;  useful for simulation and modeling 
  3742. applications. The singular max option is not available on VM. 
  3743.  
  3744.  
  3745. ΓòÉΓòÉΓòÉ 6.61. REVERSE( ) - Reverse String ΓòÉΓòÉΓòÉ
  3746.  
  3747.  ΓöÇΓöÇREVERSE(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3748.  
  3749. Reverses the order of characters in a string; can be used with functions that 
  3750. work left to right to create versions that work right to left. 
  3751.  
  3752. Examples: 
  3753.  
  3754. REVERSE('stop')      returns 'pots'
  3755. REVERSE('oprah')     returns 'harpo'
  3756. REVERSE('radar')     returns 'radar'
  3757.  
  3758.  
  3759. ΓòÉΓòÉΓòÉ 6.62. RIGHT( ) - Right-Align String ΓòÉΓòÉΓòÉ
  3760.  
  3761.  ΓöÇΓöÇRIGHT(string,lengthΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3762.                           ΓööΓöÇ,padΓöÇΓöÇΓöÿ
  3763.  
  3764. Related Functions: LEFT( ) 
  3765.  
  3766. Returns the rightmost length characters of string, padded, if necessary, with 
  3767. pad. The default pad is the blank character. 
  3768.  
  3769. Examples: 
  3770.  
  3771. RIGHT('example',5)            returns 'ample'
  3772. RIGHT('a',4)RIGHT('b',4)'c'   returns ' a bc'
  3773.  
  3774.  
  3775. ΓòÉΓòÉΓòÉ 6.63. RXFUNCADD( ) - Add an External Function ΓòÉΓòÉΓòÉ
  3776.  
  3777. RXFUNCADD adds the function name, making it available to REXX procedures. 
  3778.  
  3779.  ΓöÇΓöÇRXFUNCADD(name, module, procedure)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3780.  
  3781. Related Functions: RXFUNCDROP( ), RXFUNCQUERY( ) 
  3782.  
  3783. name is the name you wish the new REXX procedure to be known by. module is the 
  3784. filename of the OS/2 DLL that contains the procedure to be invoked when the new 
  3785. function is referenced by REXX. The DLL must reside in the OS/2 LIBPATH. 
  3786.  
  3787. The function returns 0 (zero) if name was successfully registered; 1 (one) 
  3788. otherwise. 
  3789.  
  3790. Examples: 
  3791.  
  3792. if rxfuncquery('RXCLS') then
  3793.    do
  3794.    if rxfuncadd('RXCLS', 'REXXUTIL', 'RXCLS_FUNC') then
  3795.       do
  3796.       say 'Unable to add RXCLS function.'
  3797.       exit
  3798.       end
  3799.    end
  3800.  ...
  3801. call rxcls
  3802.  ...
  3803. call rxfuncdrop 'RXCLS'
  3804.  
  3805.  
  3806. ΓòÉΓòÉΓòÉ 6.64. RXFUNCDROP( ) - Drop an External Function ΓòÉΓòÉΓòÉ
  3807.  
  3808. RXFUNCDROP drops the function name, making it unavailable to REXX procedures. 
  3809.  
  3810.  ΓöÇΓöÇRXFUNCDROP(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3811.  
  3812. Related Functions: RXFUNCADD( ), RXFUNCQUERY( ) 
  3813.  
  3814. name is the name of the REXX function you wish to drop. The function name must 
  3815. have been previously registered to REXX via the RXFUNCADD( ) function. 
  3816.  
  3817. The function returns 0 (zero) if name was successfully dropped; 1 (one) 
  3818. otherwise. 
  3819.  
  3820. Examples: 
  3821.  
  3822. if rxfuncquery('RXCLS') then
  3823.    do
  3824.    if rxfuncadd('RXCLS', 'REXXUTIL', 'RXCLS_FUNC') then
  3825.       do
  3826.       say 'Unable to add RXCLS function.'
  3827.       exit
  3828.       end
  3829.    end
  3830.  ...
  3831. call rxcls
  3832.  ...
  3833. call rxfuncdrop 'RXCLS'
  3834.  
  3835.  
  3836. ΓòÉΓòÉΓòÉ 6.65. RXFUNCQUERY( ) - Query For an External Function ΓòÉΓòÉΓòÉ
  3837.  
  3838. RXFUNCQUERY queries whether or not the name function has been registered via 
  3839. RXFUNCADD( ). 
  3840.  
  3841.  ΓöÇΓöÇRXFUNCQUERY(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3842.  
  3843. Related Functions: RXFUNCADD( ), RXFUNCDROP( ) 
  3844.  
  3845. name is the name you used to register the function by with RXFUNCADD( ). 
  3846.  
  3847. The function returns 0 (zero) if name is available; 1 (one) otherwise. 
  3848.  
  3849. Examples: 
  3850.  
  3851. if rxfuncquery('RXCLS') then
  3852.    do
  3853.    if rxfuncadd('RXCLS', 'REXXUTIL', 'RXCLS_FUNC') then
  3854.       do
  3855.       say 'Unable to add RXCLS function.'
  3856.       exit
  3857.       end
  3858.    end
  3859.  ...
  3860. call rxcls
  3861.  ...
  3862. call rxfuncdrop 'RXCLS'
  3863.  
  3864.  
  3865. ΓòÉΓòÉΓòÉ 6.66. RXQUEUE( ) - Manipulate Queue ΓòÉΓòÉΓòÉ
  3866.  
  3867. RXQUEUE is used to manipulate external data queues. 
  3868.  
  3869.  ΓöÇΓöÇRXQUEUE(ΓöÇΓö¼ΓöÇ'Get'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3870.               Γö£ΓöÇ'Set'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇnewqueuenameΓöÇΓöÇΓöÇΓöñ
  3871.               Γö£ΓöÇ'Delete'ΓöÇΓöÇΓöÇqueuenameΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3872.               ΓööΓöÇ'Create'ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  3873.                          ΓööΓöÇΓöÇ,queuenameΓöÇΓöÇΓöÿ
  3874.  
  3875. Related Instructions: PARSE, PUSH, QUEUE 
  3876. Related Function: QUEUED( ) 
  3877.  
  3878. This function is used to create and delete queues and to set and query their 
  3879. names. The first parameter determines the function performed. 
  3880.  
  3881. Parameters: 
  3882.  
  3883.  Create    Creates a queue with the name, queuename (if specified); If no name 
  3884.            is specified, then REXX will provide a name. Returns the name of the 
  3885.            queue in either case. 
  3886.  
  3887.  Delete    Deletes the named queue; returns 0 (zero) if successful, a non-zero 
  3888.            number if an error occurs; the possible return values are: 
  3889.  
  3890.     0     Queue has been deleted. 
  3891.     5     Not a valid queue name. 
  3892.     9     Queue named does not exist. 
  3893.     10    Queue is busy; wait is active. 
  3894.     12    A memory failure has occurred. 
  3895.     1000  Initialization error; chek file OS2.INI. 
  3896.  
  3897.  Get       Returns the name of the queue currently in use. 
  3898.  
  3899.  Set       Sets the name of the current queue to newqueuename and returns the 
  3900.            previous name of the queue. 
  3901.  Examples: 
  3902.  
  3903.   if rxfuncquery('RXCLS') then
  3904.  
  3905.  
  3906. ΓòÉΓòÉΓòÉ 6.67. SETLANG( ) - Set International Language ΓòÉΓòÉΓòÉ
  3907.  
  3908. Sets/returns the three character code indicating the language in which REXX 
  3909. messages are currently being displayed. 
  3910.  
  3911.  ΓöÇΓöÇSETLANG(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3912.               ΓööΓöÇlangcodeΓöÇΓöÿ
  3913.  
  3914. Note:  TSO only. 
  3915.  
  3916. The following values are the valid for langcode. 
  3917.  
  3918.  CHS   Simplified Chinese 
  3919.  CHT   Traditional Chinese 
  3920.  DAN   Danish 
  3921.  DEU   German 
  3922.  ENP   US English - all upper case 
  3923.  ENU   US English - mixed case 
  3924.  ESP   Spanish 
  3925.  FRA   French 
  3926.  JPN   Japanese 
  3927.  KOR   Korean 
  3928.  PTB   Brazilian Portuguese 
  3929.  
  3930.  Example: 
  3931.  
  3932.   call setlocal
  3933.   if setlang() <> 'ENU' then
  3934.      do
  3935.         oldlang = setlang()
  3936.         call setlang 'ENU'
  3937.      end
  3938.  
  3939.  
  3940. ΓòÉΓòÉΓòÉ 6.68. SETLOCAL( ) - Set OS/2 Local Setting ΓòÉΓòÉΓòÉ
  3941.  
  3942. SETLOCAL creates a local environment until the next ENDLOCAL is executed. 
  3943.  
  3944.  ΓöÇΓöÇSETLOCAL( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3945.  
  3946. Note:  OS/2 only. 
  3947.  
  3948. Related Functions: ENDLOCAL( ) 
  3949.  
  3950. SETLOCAL returns 1 for a succesful store of the drive, directory, and 
  3951. environment variables.  It returns 0 if unsuccessful. 
  3952.  
  3953. Note:  SETLOCAL and ENDLOCAL can be nested in REXX programs; this is not 
  3954. possible in regular batch procedures. 
  3955.  
  3956. If a REXX program that issues SETLOCAL ends without calling ENDLOCAL, an 
  3957. implicit ENDLOCAL is performed at termination. 
  3958.  
  3959. Example: 
  3960.  
  3961. call setlocal
  3962. oldpath = value('path',,'OS2ENVIRONMENT')
  3963. call value 'path',,
  3964.     newpathpart';'oldpath,,
  3965.     'OS2ENVIRONMENT'
  3966.  ...
  3967. /* do some things with new path */
  3968. call endlocal
  3969.  
  3970.  
  3971. ΓòÉΓòÉΓòÉ 6.69. SIGN( ) - Return Numeric Sign ΓòÉΓòÉΓòÉ
  3972.  
  3973.  ΓöÇΓöÇSIGN(number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3974.  
  3975. Returns -1 if negative, +1 if positive, 0 if zero. 
  3976.  
  3977.  
  3978. ΓòÉΓòÉΓòÉ 6.70. SOURCELINE( ) - Return Program Line ΓòÉΓòÉΓòÉ
  3979.  
  3980.  ΓöÇΓöÇSOURCELINE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3981.                  ΓööΓöÇΓöÇnΓöÇΓöÇΓöÿ
  3982.  
  3983. Returns the nth line of the REXX exec currently executing;  returns the number 
  3984. of source lines if n is omitted; useful in error reporting procedures in 
  3985. production REXX execs. 
  3986.  
  3987.  
  3988. ΓòÉΓòÉΓòÉ 6.71. SPACE( ) - Insert Fill-Character ΓòÉΓòÉΓòÉ
  3989.  
  3990.  ΓöÇΓöÇSPACE(stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  3991.                   ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  3992.                        ΓööΓöÇnΓöÇΓöÿ ΓööΓöÇΓöÇ,padΓöÇΓöÇΓöÿ
  3993.  
  3994. Reformats the words in string by placing exactly n copies of pad between each 
  3995. word. The default pad is the blank character. n defaults to 1. 
  3996.  
  3997. Example: 
  3998.  
  3999. SPACE('a b cd',3)                    returns 'a b cd'
  4000. SPACE('a b cd',0)                    returns 'abcd'
  4001. SPACE('This   is  an    example')    returns 'This is an example'
  4002.  
  4003.  
  4004. ΓòÉΓòÉΓòÉ 6.72. STORAGE( ) ΓòÉΓòÉΓòÉ
  4005.  
  4006.  ΓöÇΓöÇSTORAGE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇ
  4007.               ΓööΓöÇaddressΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  4008.                               ΓööΓöÇlengthΓöÇΓöÿ ΓööΓöÇ,dataΓöÇΓöÿ
  4009.  
  4010. Note:  VM only. 
  4011.  
  4012. If no arguments are specified, returns the current virtual machine size. 
  4013. Otherwise, returns length bytes from your virtual machine's memory starting at 
  4014. address.  If data is specified, storage starting at address is over-written for 
  4015. length, but not past the end of your virtual machine.  Consult the VM manual 
  4016. before using this option. 
  4017.  
  4018.  
  4019. ΓòÉΓòÉΓòÉ 6.73. STREAM( ) - Stream Command ΓòÉΓòÉΓòÉ
  4020.  
  4021.  ΓöÇΓöÇSTREAM(nameΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇ
  4022.                  ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  4023.                       Γö£ΓöÇC,ΓöÇΓöÇstreamcommandΓöÇΓöÇΓöñ
  4024.                       Γö£ΓöÇDΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4025.                       ΓööΓöÇSΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  4026.  
  4027. Note:  OS/2 has the only implementation. 
  4028.  
  4029. Returns a string describing the state of, or result of an operation on the 
  4030. character stream name. 
  4031.  
  4032.  Command        Issue a stream command. The following commands are available 
  4033.                 under OS/2: 
  4034.  
  4035.     'OPEN'                Opens a named stream. The words 'READ' and 'WRITE' 
  4036.                           may optionally be appended to 'OPEN' to specifiy 
  4037.                           those conditions. 
  4038.     'CLOSE'               Closes the named stream. 
  4039.     'SEEK offset'         Sets the read or write position to a given offset 
  4040.                           within a persistent stream. The offset may be 
  4041.                           prefixed with the following: 
  4042.  
  4043.        =     Explicit offset. 
  4044.        <    Specifies offset from the end of the stream. 
  4045.        +    Specifies offset forward from the current position. 
  4046.        -    Specifies offset backward from the current position. 
  4047.     'QUERY EXISTS'        Returns the full path specification of the persistent 
  4048.                           stream if it exists, else returns the null string. 
  4049.     'QUERY SIZE'          Returns the size in bytes of the persistent stream if 
  4050.                           it exists, else returns 0. 
  4051.     'QUERY DATETIME'      Returns the date and time stamps of the stream. 
  4052.  
  4053.  Description    Identical to the STATE option except that the returned string 
  4054.                 is followed by a colon and, if available, additional 
  4055.                 information about the ERROR or NOTREADY state. 
  4056.  
  4057.  State          Returns the following strings: 
  4058.  
  4059.     'ERROR'        An error in a stream operation has taken place. 
  4060.     'NOTREADY'     A stream is in a state in which a requested operation would 
  4061.                    raise the NOTREADY condition. 
  4062.     'READY'        Normal operations are available for the stream. 
  4063.     'UNKNOWN'      The stream in is an unknown state. 
  4064.  
  4065.  Only the first character of each option need be specified. 
  4066.  
  4067.  Examples: 
  4068.  
  4069.   state = STREAM(myfile)
  4070.   state = STREAM(myfile, 'S')
  4071.   state = STREAM(myfile, 'D')
  4072.   state = STREAM(myfile, 'C', 'OPEN')
  4073.   state = STREAM(myfile, 'C', 'CLOSE')
  4074.   size = STREAM(myfile, 'QUERY SIZE')
  4075.  
  4076.  
  4077. ΓòÉΓòÉΓòÉ 6.74. STRIP( ) - Remove Padding ΓòÉΓòÉΓòÉ
  4078.  
  4079.  ΓöÇΓöÇSTRIP(stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇ
  4080.                   ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  4081.                        ΓööΓöÇoptionΓöÇΓöÿ ΓööΓöÇΓöÇ,charΓöÇΓöÿ
  4082.  
  4083. Removes the leading and/or trailing char from the string; the options are: 
  4084.  
  4085.  o Leading 
  4086.  o Trailing 
  4087.  o Both (default) 
  4088.  
  4089.  Only the first character of each option need be specified. The default char is 
  4090.  the blank character. 
  4091.  
  4092.  Examples: 
  4093.  
  4094.   STRIP('0000981.3',L,0)          returns '981.3'
  4095.   STRIP('  how   are   you?  ')   returns 'how are you?'
  4096.  
  4097.  A useful combination is: 
  4098.  
  4099.   SPACE(STRIP('  how   are   you?  '))    returns 'how are you?'
  4100.  
  4101.  
  4102. ΓòÉΓòÉΓòÉ 6.75. SUBSTR( ) - Return Substring ΓòÉΓòÉΓòÉ
  4103.  
  4104.  ΓöÇΓöÇSUBSTR(string,nΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇ
  4105.                      ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  4106.                           ΓööΓöÇlengthΓöÇΓöÿ ΓööΓöÇ,padΓöÇΓöÿ
  4107.  
  4108. Returns length characters from string starting at position n and padding, if 
  4109. necessary, with pad.  The length defaults to the rest of the string; the pad 
  4110. defaults to a blank. 
  4111.  
  4112. Examples: 
  4113.  
  4114. SUBSTR('basic',2,3)         returns 'asi'
  4115. SUBSTR('basic',2)           returns 'asic'
  4116. SUBSTR('DTSS CO',6,5,'.')   returns 'CO...'
  4117.  
  4118.  
  4119. ΓòÉΓòÉΓòÉ 6.76. SUBWORD( ) - Return Word From String ΓòÉΓòÉΓòÉ
  4120.  
  4121.  ΓöÇΓöÇSUBWORD(string,nΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4122.                       ΓööΓöÇ,lengthΓöÇΓöÇΓöÿ
  4123.  
  4124. Returns length number of blank-delimited words from string, starting at word n; 
  4125. length defaults to the rest of the string. 
  4126.  
  4127. Examples: 
  4128.  
  4129. SUBWORD('A quick brown ',2)    returns 'quick brown'
  4130. SUBWORD('A quick brown ',2,1)  returns 'quick'
  4131. SUBWORD('A quick brown ',4,1)  returns ''
  4132.  
  4133.  
  4134. ΓòÉΓòÉΓòÉ 6.77. SYMBOL( ) - Return Status of Symbol ΓòÉΓòÉΓòÉ
  4135.  
  4136.  ΓöÇΓöÇSYMBOL(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4137.  
  4138. Returns the class of the symbol represented by name;  returns "BAD" if the name 
  4139. is not a valid REXX symbol (variable name or constant);  returns "LIT" if it is 
  4140. a constant, or a variable that has never been assigned a value; returns "VAR" 
  4141. if the symbol represents the name of a variable that has been assigned a value. 
  4142.  
  4143.  
  4144. ΓòÉΓòÉΓòÉ 6.78. SYSDSN( ) - Return Status of Dataset ΓòÉΓòÉΓòÉ
  4145.  
  4146.  ΓöÇΓöÇSYSDSN(dsn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4147.  
  4148. Returns 'OK' if the specified dsn exists, or what status it is. One of the 
  4149. following values will always be returned: 
  4150.  
  4151. OK
  4152. MEMBER NOT FOUND
  4153. MEMBER SPECIFIED, BUT DATASET IS NOT PARTITIONED
  4154. DATASET NOT FOUND
  4155. ERROR PROCESSING REQUESTED DATASET
  4156. PROTECTED DATASET                                   /* RACF Protected */
  4157. VOLUME NOT ON SYSTEM
  4158. INVALID DATASET NAME, dsn
  4159. MISSING DATASET NAME
  4160. UNAVAILABLE DATASET
  4161.  
  4162. Note:  TSO only. 
  4163.  
  4164.  
  4165. ΓòÉΓòÉΓòÉ 6.79. SYSVAR( ) - Return System Variable ΓòÉΓòÉΓòÉ
  4166.  
  4167.  ΓöÇΓöÇSYSVAR(info)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4168.  
  4169. Note:  TSO only. 
  4170.  
  4171. Returns information about the specified system variable info. The following 
  4172. info system variables may be specified: 
  4173.  
  4174.  SYSPREF        The TSO prefix for unqualified dataset names. 
  4175.  SYSPROC        The TSO logon procedure. 
  4176.  SYSUID         The TSO user id. 
  4177.  SYSLTERM       The number of line available on the terminal screen. 
  4178.  SYSWTERM       The number of characters in width available on the terminal 
  4179.                 screen. 
  4180.  SYSENV         The current environment, either 'FORE' or 'BACK'. 
  4181.  SYSICMD        The implicit name of the current exec. 
  4182.  SYSISPF        'ACTIVE' if executing under ISPF, else 'NOT ACTIVE'. 
  4183.  SYSNEST        'YES' if executing under a nested condition, else 'NO'. 
  4184.  SYSPCMD        The most recently executed TSO command. 
  4185.  SYSSCMD        The most recently executed TSO subcommand. 
  4186.  SYSCPU         The number of CPU seconds used so far. 
  4187.  SYSHSM         Null if HSM not available, else the release level of HSM. 
  4188.  SYSLRACF       Null if RACF not installed, else the release level of RACF. 
  4189.  SYSRACF        'AVAILABLE' if RACF available, 'NOT AVAILABLE' if not not 
  4190.                 available, else 'NOT INSTALLED'. 
  4191.  SYSSRV         How many SRM service units used so far. 
  4192.  SYSTSOE        The level of TSO/E installed. 
  4193.  
  4194.  Other info is available. Refer to the TSO reference manual. 
  4195.  
  4196.  Returns 0 if the function was successful, 16 if not. 
  4197.  
  4198.  
  4199. ΓòÉΓòÉΓòÉ 6.80. TIME( ) - Return System Time ΓòÉΓòÉΓòÉ
  4200.  
  4201. TIME returns a variety of formats for the current time. 
  4202.  
  4203.  ΓöÇΓöÇTIME(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4204.            ΓööΓöÇoptionΓöÇΓöÿ
  4205.  
  4206. Related Functions: DATE( ) 
  4207.  
  4208. The default option is "Normal."  All calls in the same statement return the 
  4209. same value. 
  4210.  
  4211.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  4212.  Γöé   Option   Γöé Example                                      Γöé
  4213.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4214.  Γöé   Civil    Γöé '7:15pm'                                     Γöé
  4215.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4216.  Γöé   Elapsed  Γöé 123456789.123456                             Γöé
  4217.  Γöé            Γöé time since elapsed-time clock started/reset  Γöé
  4218.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4219.  Γöé   Hours    Γöé '19'                                         Γöé
  4220.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4221.  Γöé   Long     Γöé '19:15:31.123456                             Γöé
  4222.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4223.  Γöé   Minutes  Γöé 1155   /* 15 + 60*19         */              Γöé
  4224.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4225.  Γöé   Normal   Γöé '19:15:31'                                   Γöé
  4226.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4227.  Γöé   Reset    Γöé 123456789.123456                             Γöé
  4228.  Γöé            Γöé time since elapsed-time clock started/reset  Γöé
  4229.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4230.  Γöé   Seconds  Γöé 69331  /* 31 + 60*(15+60*19) */              Γöé
  4231.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  4232.  
  4233. Only the underscored, capitalized letter in the option above is required by 
  4234. TIME. 
  4235.  
  4236.  
  4237. ΓòÉΓòÉΓòÉ 6.81. TRACE( ) - Return TRACE Mode ΓòÉΓòÉΓòÉ
  4238.  
  4239.  ΓöÇΓöÇTRACE(ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4240.               Γö£ΓöÇ?ΓöÇΓöñ Γöé  ΓööΓöÇoptionΓöÇΓöÿ
  4241.              Γöé ΓööΓöÇ!ΓöÇΓöÿ Γöé
  4242.              ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  4243.  
  4244. Note:  The "!" is not available in OS/2. 
  4245.  
  4246. Related Instructions: TRACE 
  4247.  
  4248. Returns the current TRACE actions; can also set TRACE options. 
  4249.  
  4250.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  4251.  Γöé   Option        Γöé Example                           Γöé
  4252.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4253.  Γöé   All           Γöé All clauses                       Γöé
  4254.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4255.  Γöé   Commands      Γöé All host commands                 Γöé
  4256.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4257.  Γöé   Error         Γöé Host commands generating errors   Γöé
  4258.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4259.  Γöé   Failure       Γöé Host commands generating failures Γöé
  4260.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4261.  Γöé   Intermediates Γöé All clauses with intermediates    Γöé
  4262.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4263.  Γöé   Lables        Γöé All labels                        Γöé
  4264.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4265.  Γöé   Normal        Γöé Host commands generating failures Γöé
  4266.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4267.  Γöé   Off           Γöé All tracing off                   Γöé
  4268.  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4269.  Γöé   Results       Γöé All clauses traced before exec.   Γöé
  4270.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  4271.  
  4272. The default option is "Normal". 
  4273.  
  4274. The "?" turns on an option. 
  4275.  
  4276. Example: 
  4277.  
  4278. save_trace = trace('?R') /* saves, sets */
  4279. /* trace some code */
  4280.  ...
  4281. TRACE VALUE save_trace   /* reset trace     */
  4282.  
  4283.  
  4284. ΓòÉΓòÉΓòÉ 6.82. TRANSLATE( ) - Translate String ΓòÉΓòÉΓòÉ
  4285.  
  4286.  ΓöÇΓöÇTRANSLATE(stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇ
  4287.                       ΓööΓöÇ,Γö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  4288.                          ΓööΓöÇtableoΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
  4289.                                         ΓöötableiΓöÿ Γöö,padΓöÿ
  4290.  
  4291. Translates characters in string according to the correspondence between the 
  4292. characters in tableo and tablei; the shorter of tablei or tableo is padded to 
  4293. equal length with pad for purposes of character translation;  default for 
  4294. tablei is a list of all 256 hexadecimal characters from '00'x to 'FF'x; if 
  4295. neither table is specified, then a translation from lower case to upper case is 
  4296. done. The default pad is the blank character. 
  4297.  
  4298. Example: 
  4299.  
  4300. TRANSLATE('AbCdEfGhI')                          returns 'ABCDEFGHI'
  4301. TRANSLATE('301-41-8397',,'-')                   returns '301 41 8397'
  4302. TRANSLATE('12 34 56 78','C4A49497','12345678')  returns 'C4 A4 94 97'
  4303.  
  4304.  
  4305. ΓòÉΓòÉΓòÉ 6.83. TRUNC( ) - Truncate Numeric Value ΓòÉΓòÉΓòÉ
  4306.  
  4307.  ΓöÇΓöÇTRUNC(numberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4308.                   ΓööΓöÇ,nΓöÇΓöÇΓöÿ
  4309.  
  4310. Truncates the number to n decimal places; n defaults to zero. 
  4311.  
  4312. Example: 
  4313.  
  4314. TRUNC(123.456)      returns 123
  4315. TRUNC(123.456,2)    returns 123.45
  4316. TRUNC(123.4,2)      returns 123.40
  4317.  
  4318.  
  4319. ΓòÉΓòÉΓòÉ 6.84. USERID( ) - Return Logon User ID ΓòÉΓòÉΓòÉ
  4320.  
  4321.  ΓöÇΓöÇUSERID( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4322.  
  4323. Note:  VM and TSO only. 
  4324.  
  4325. Returns to TSO/E userid in the TSO foreground or background environment; 
  4326. returns the system defined user identifier in VM; an environment specific 
  4327. replaceable routine is invoked in other environments. 
  4328.  
  4329. Example: 
  4330.  
  4331. USERID( )     returns '@64BB'
  4332.  
  4333.  
  4334. ΓòÉΓòÉΓòÉ 6.85. VALUE( ) - Return Content of Symbol ΓòÉΓòÉΓòÉ
  4335.  
  4336.  ΓöÇΓöÇVALUE(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4337.  
  4338. Returns the value of the symbol named by name; this is like the CLIST 
  4339. &SYSNSUB(2,&&NAME) function; in general, you should use compound stem variables 
  4340. to implement arrays rather than multiple levels of symbolic substitution. 
  4341.  
  4342.  
  4343. ΓòÉΓòÉΓòÉ 6.86. VERIFY( ) - Test Character String ΓòÉΓòÉΓòÉ
  4344.  
  4345.  ΓöÇΓöÇVERIFY(string,referenceΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇ
  4346.                              ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  4347.                                  ΓööΓöÇoptionΓöÇΓöÿ ΓööΓöÇ,startΓöÇΓöÿ
  4348.  
  4349. Verifies that the substring of string starting at start contains only the 
  4350. characters listed in the reference string; the option can be: 
  4351.  
  4352.  o Match 
  4353.  o Nomatch (default) 
  4354.  
  4355.  "M" says to return the position of the leftmost character in string that is 
  4356.  found in the set of characters in the reference string; "N" says to return the 
  4357.  position of the leftmost character in string that is NOT found in the set of 
  4358.  characters in the reference string; zero is returned when all characters match 
  4359.  (N) or don't match (M). The default start position is 1. 
  4360.  
  4361.  Example: 
  4362.  
  4363.   VERIFY('123','0123456789')      returns 0
  4364.   VERIFY('123','0123456789','N')  returns 0
  4365.   VERIFY('123','0123456789','M')  returns 1
  4366.   VERIFY('A23','0123456789','N')  returns 1
  4367.   VERIFY('A23','0123456789','M')  returns 2
  4368.  
  4369.  
  4370. ΓòÉΓòÉΓòÉ 6.87. WORD( ) - Get Word ΓòÉΓòÉΓòÉ
  4371.  
  4372.  ΓöÇΓöÇWORD(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4373.  
  4374. Returns the nth blank-delimited word from string; same as SUBWORD( ). 
  4375.  
  4376.  
  4377. ΓòÉΓòÉΓòÉ 6.88. WORDINDEX( ) - Return Word Position ΓòÉΓòÉΓòÉ
  4378.  
  4379.  ΓöÇΓöÇWORDINDEX(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4380.  
  4381. Returns the character position of the first character in the nth word of the 
  4382. string. 
  4383.  
  4384. Example: 
  4385.  
  4386. WORDINDEX('Four score and',1)    returns 1
  4387. WORDINDEX('Four score and',2)    returns 6
  4388. WORDINDEX('Four score and',3)    returns 12
  4389. WORDINDEX('Four score and',4)    returns 0
  4390.  
  4391.  
  4392. ΓòÉΓòÉΓòÉ 6.89. WORDLENGTH( ) - Return Word Length ΓòÉΓòÉΓòÉ
  4393.  
  4394.  ΓöÇΓöÇWORDLENGTH(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4395.  
  4396. Returns the length of the nth word in the string. 
  4397.  
  4398. Example: 
  4399.  
  4400. WORDLENGTH('Four score and',1)    returns 4
  4401. WORDLENGTH('Four score and',2)    returns 5
  4402. WORDLENGTH('Four score and',3)    returns 3
  4403. WORDLENGTH('Four score and',4)    returns 0
  4404.  
  4405.  
  4406. ΓòÉΓòÉΓòÉ 6.90. WORDPOS( ) - Return Word Position ΓòÉΓòÉΓòÉ
  4407.  
  4408.  ΓöÇΓöÇWORDPOS(phrase,stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4409.                            ΓööΓöÇ,startΓöÇΓöÿ
  4410.  
  4411. Finds the leftmost match of the phrase in the string, starting at word number 
  4412. start;  if a match is found, returns the relative number of the first matching 
  4413. word in string;  if not found, returns zero. The default start position is 1. 
  4414.  
  4415. Example: 
  4416.  
  4417. WORDPOS('the', 'now is the time')         returns 3
  4418. WORDPOS('The', 'now is the time')         returns 0
  4419. WORDPOS('is the', 'now is the time')      returns 2
  4420.  
  4421.  
  4422. ΓòÉΓòÉΓòÉ 6.91. WORDS( ) - Return Number of Words ΓòÉΓòÉΓòÉ
  4423.  
  4424.  ΓöÇΓöÇWORDS(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4425.  
  4426. Returns the number of words in the string. 
  4427.  
  4428. Example: 
  4429.  
  4430. WORDS('Four score and')    returns 3
  4431. WORDS('Four-score-and')    returns 1
  4432. WORDS('       ')           returns 0
  4433. WORDS('')                  returns 0
  4434.  
  4435.  
  4436. ΓòÉΓòÉΓòÉ 6.92. XRANGE( ) - Define Range of Hex Values ΓòÉΓòÉΓòÉ
  4437.  
  4438.  ΓöÇΓöÇXRANGE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4439.              ΓööΓöÇstartΓöÇΓöÿ ΓööΓöÇ,endΓöÇΓöÇΓöÿ
  4440.  
  4441. Returns a string of all the hexadecimal values from start through end, 
  4442. inclusive; start defaults to '00'x;  end defaults to 'FF'x. Do not make the 
  4443. mistake of using XRANGE("A","Z") to check for only upper case letters;  this 
  4444. range includes more hex values than just the letters, and several of these 
  4445. characters are enterable at a keyboard. 
  4446.  
  4447. Example: 
  4448.  
  4449. upper_case = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  4450. IF verify(test_string,upper_case)=0 THEN ...
  4451.  
  4452. Do NOT use: 
  4453.  
  4454. upper_case = XRANGE('A','Z')
  4455. IF verify(test_string,upper_case)=0 THEN ...
  4456.  
  4457. The former example is character set independent; the latter example will only 
  4458. work correctly with ASCII  --  it includes too many characters with EBCDIC. 
  4459.  
  4460.  
  4461. ΓòÉΓòÉΓòÉ 6.93. X2C( ) - Hex to Character String Conversion ΓòÉΓòÉΓòÉ
  4462.  
  4463.  ΓöÇΓöÇX2C(hexstring)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4464.  
  4465. Converts hexadecimal hexstring to character. 
  4466.  
  4467. Example: 
  4468.  
  4469. X2C('d5a6a64089a240a38885')  returns 'Now is the'
  4470. X2C('F1F2F3')                returns '123'
  4471.  
  4472.  
  4473. ΓòÉΓòÉΓòÉ 6.94. X2D( ) - Hex to Decimal Conversion ΓòÉΓòÉΓòÉ
  4474.  
  4475.  ΓöÇΓöÇX2D(hexstringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4476.                    ΓööΓöÇ,nΓöÇΓöÿ
  4477.  
  4478. Related Instructions: NUMERIC 
  4479.  
  4480. Converts hexadecimal hexstring to decimal;  if n is specified, it represents 
  4481. the number of hexadecimal digits to use in the conversion;  extra ones are 
  4482. truncated from the LEFT;  if padding is needed, hexadecimal zeroes are added on 
  4483. the LEFT;  also, when n is specified, if the leftmost bit is on, the number is 
  4484. considered to be a negative number in two's complement. 
  4485.  
  4486. Example: 
  4487.  
  4488. X2D('C1')          returns 193
  4489. X2D('001')         returns 1
  4490. X2D('2374')        returns 9076
  4491. 9076 X2D('FF')     returns 255
  4492. X2D('FF',0)        returns 0
  4493. X2D('FF',2)        returns -1
  4494. X2D('FF',4)        returns 255
  4495.  
  4496.  
  4497. ΓòÉΓòÉΓòÉ 7. Useful Environment Subcommands ΓòÉΓòÉΓòÉ
  4498.  
  4499. Note:  The examples and descriptions in the following sections are not meant to 
  4500. be a complete reference to all subcommands in all available subcommand 
  4501. environments. Only some of the more useful and common subcommands in each 
  4502. environment are discussed. 
  4503.  
  4504. Remember that the result or status of host REXX commands is set into the RC 
  4505. special variable. 
  4506.  
  4507. The following sections discuss some useful subcommands available in the 
  4508. following execution environments: 
  4509.  
  4510.  o OS/2 CMD Environment 
  4511.  o MVS Environment 
  4512.  o TSO Environment 
  4513.  o VM Environment 
  4514.  
  4515.  
  4516. ΓòÉΓòÉΓòÉ 7.1. OS/2 CMD Environment ΓòÉΓòÉΓòÉ
  4517.  
  4518. This OS/2 CMD subcommand environment is available to REXX programs which are 
  4519. executed by the CMD.EXE command processor. This an EXE registered subcommand 
  4520. environment and is therefore not available to programs called by CMD.EXE or to 
  4521. Presentation Manager programs. 
  4522.  
  4523. Any OS/2 command which can be placed in an OS/2 batch file can be sent to the 
  4524. CMD subcommand environment for processing. 
  4525.  
  4526. Some useful subcommands follow: 
  4527.  
  4528.  o CALL Command 
  4529.  o DEL or ERASE Command 
  4530.  o DIR Command 
  4531.  o PATH Command 
  4532.  o SET Command 
  4533.  o RXSUBCOM Command 
  4534.  o RXQUEUE Command 
  4535.  
  4536.  Other products are beginning to appear on the market which define their own 
  4537.  subcommand environments. 
  4538.  
  4539.  
  4540. ΓòÉΓòÉΓòÉ 7.1.1. CALL Command ΓòÉΓòÉΓòÉ
  4541.  
  4542. Do not confuse this with the REXX CALL statement. This subcommand is used to 
  4543. invoke OS/2 batch (.CMD) files. 
  4544.  
  4545.                        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  4546.                                        Γöé
  4547.  ΓöÇΓöÇCALL ΓöÇΓöÇbatchfileΓöÇΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4548.                          ΓööΓöÇΓöÇargumentΓöÇΓöÇΓöÿ
  4549.  
  4550. The CALL invokes another copy of CMD.EXE and begins execution of the batchfile. 
  4551. The batchfile parameter can be either the name of and OS/2 .CMD file or a REXX 
  4552. program to be called as a subcommand. 
  4553.  
  4554. Any return information generated by the batchfile is lost. 
  4555.  
  4556. Refer to the OS/2 Command Reference for more information. 
  4557.  
  4558. Example: 
  4559.  
  4560. if x = 'OK' then
  4561.    'call startcm'
  4562.  
  4563.  
  4564. ΓòÉΓòÉΓòÉ 7.1.2. DEL or ERASE Command ΓòÉΓòÉΓòÉ
  4565.  
  4566. Deletes OS/2 files. 
  4567.  
  4568.                    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  4569.      ΓöîΓöÇΓöÇDEL ΓöÇΓöÇΓöÇΓöÇΓöÉ                                 Γöé
  4570.  ΓöÇΓöÇΓöñ          Γö£ΓöÇΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇfilenameΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
  4571.      ΓööΓöÇΓöÇERASE ΓöÇΓöÇΓöÿ    ΓööΓöÇdriveΓöÇΓöÿ ΓööΓöÇpathΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   ΓööΓöÇ/PΓöÇΓöÿ
  4572.                                       ΓööΓöÇfilenameΓöÇΓöÿ
  4573.  
  4574. Refer to the OS/2 Command Reference for more information. 
  4575.  
  4576. Example: 
  4577.  
  4578. if x = 'OK' then
  4579.    'del temp.dat'
  4580.  
  4581.  
  4582. ΓòÉΓòÉΓòÉ 7.1.3. DIR Command ΓòÉΓòÉΓòÉ
  4583.  
  4584. Displays a directory of OS/2 files. 
  4585.  
  4586.            ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  4587.                                             Γöé           Γöé
  4588.  ΓöÇΓöÇDIR ΓöÇΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö¼Γö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γö¼ΓöÇΓö┤ΓöÇΓöÇ
  4589.              ΓööΓöÇdriveΓöÇΓöÿ ΓööΓöÇpathΓöÇΓöÿ ΓööΓöÇfilenameΓöÇΓöÿ     ΓöéΓö£ΓöÇ/WΓöÇΓöñΓöé
  4590.                                                  ΓöéΓööΓöÇ/FΓöÇΓöÿΓöé
  4591.                                                  Γö£ΓöÇΓöÇ/PΓöÇΓöÇΓöñ
  4592.                                                  ΓööΓöÇΓöÇ/NΓöÇΓöÇΓöÿ
  4593.  
  4594. Refer to the OS/2 Command Reference for more information. 
  4595.  
  4596. Example: 
  4597.  
  4598. if x = 'SHOW' then
  4599.    'dir *.* /p'
  4600.  
  4601.  
  4602. ΓòÉΓòÉΓòÉ 7.1.4. PATH Command ΓòÉΓòÉΓòÉ
  4603.  
  4604. Displays/sets the directory paths to search cor commands or REXX programs, if 
  4605. not found in the current directory or specified directory. 
  4606.  
  4607.  ΓöÇΓöÇPATH ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4608.               Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
  4609.               Γöé                     Γöé Γöé
  4610.               ΓööΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÿ
  4611.                   ΓööΓöÇdriveΓöÇΓöÿ ΓööΓöÇpathΓöÇΓöÿ
  4612.  
  4613. Refer to the OS/2 Command Reference for more information. 
  4614.  
  4615. Example: 
  4616.  
  4617. if x = 'CHG' then
  4618.    'path c:\os2;d:\bin;'
  4619. else
  4620.    'path'
  4621.  
  4622.  
  4623. ΓòÉΓòÉΓòÉ 7.1.5. SET Command ΓòÉΓòÉΓòÉ
  4624.  
  4625. Displays/sets OS/2 environment variables. 
  4626.  
  4627.  ΓöÇΓöÇSET ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4628.              ΓööΓöÇstringΓöÇΓöÇ=ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  4629.                          ΓööΓöÇstringΓöÇΓöÿ
  4630.  
  4631. Refer to the OS/2 Command Reference for more information. 
  4632.  
  4633. Example: 
  4634.  
  4635. if x = 'CHG' then
  4636.    'set init=d:\init'
  4637.  
  4638.  
  4639. ΓòÉΓòÉΓòÉ 7.1.6. RXSUBCOM Command ΓòÉΓòÉΓòÉ
  4640.  
  4641. Manipulates subcommand environments packaged as DLLs. 
  4642.  
  4643.  ΓöÇΓöÇRXSUBCOMΓöÇΓö¼ΓöÇREGISTER envname dllname procnameΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4644.               Γö£ΓöÇDROPΓöÇΓöÇΓö¼ΓöÇ envnameΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  4645.               Γö£ΓöÇLOADΓöÇΓöÇΓöñ           ΓööΓöÇdllnameΓöÇΓöÿ
  4646.               ΓööΓöÇQUERYΓöÇΓöÿ
  4647.  
  4648.  REGISTER       Register a subcommand environment packaged as a DLL. Performs 
  4649.                 the same service as the RxSubcomRegister( ) C function. This 
  4650.                 subcommand however cannot register subcommand environments 
  4651.                 packaged in EXEs. 
  4652.  
  4653.  DROP           Drops a previously registered subcommand environment. Performs 
  4654.                 the same service as the RxSubcomDrop( ) C function. This 
  4655.                 subcommand however cannot drop subcommand environments packaged 
  4656.                 in EXEs. 
  4657.  
  4658.  LOAD           Loads a previously registered subcommand environment. Performs 
  4659.                 the same service as the RxSubcomLoad( ) C function. This 
  4660.                 subcommand however cannot load subcommand environments packaged 
  4661.                 in EXEs. 
  4662.  
  4663.  QUERY          Queries for a previously registered subcommand environment. 
  4664.                 Performs the same service as the RxSubcomQuery( ) C function. 
  4665.  
  4666.  Examples: 
  4667.  
  4668.   'rxsubcom register sampleenv sample sampleproc'
  4669.  
  4670.   'rxsubcom drop sampleenv'
  4671.  
  4672.   'rxsubcom load sampleenv sampdll'
  4673.  
  4674.   'rxsubcom query sampleenv'
  4675.  
  4676.  
  4677. ΓòÉΓòÉΓòÉ 7.1.7. RXQUEUE Command ΓòÉΓòÉΓòÉ
  4678.  
  4679. Manipulates REXX queues. 
  4680.  
  4681.  ΓöÇΓöÇRXQUEUEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇ/LIFOΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4682.               ΓööΓöÇqueuenameΓöÇΓöÿ  Γö£ΓöÇ/FIFOΓöÇΓöÇΓöñ
  4683.                              ΓööΓöÇ/CLEARΓöÇΓöÿ
  4684.  
  4685. /LIFO stacks items from STDIN on the top of of a named (or defualt) REXX queue. 
  4686.  
  4687. /FIFO queues items from STDIN to the end of a named (or defualt) REXX queue. 
  4688.  
  4689. /CLEAR clears the named (or defualt) REXX queue. 
  4690.  
  4691. Example: 
  4692.  
  4693. 'rxsubcom query sampleenv'
  4694.  
  4695.  
  4696. ΓòÉΓòÉΓòÉ 7.2. MVS Environment ΓòÉΓòÉΓòÉ
  4697.  
  4698. The MVS Subcommand environment includes 15 commands: 
  4699.  
  4700.  o DELSTACK Command 
  4701.  o DROPBUF Command 
  4702.  o EXECIO Command 
  4703.  o EXECUTIL Command 
  4704.  o HI Command 
  4705.  o HT Command 
  4706.  o MAKEBUF Command 
  4707.  o NEWSTACK Command 
  4708.  o QBUF Command 
  4709.  o QELEM Command 
  4710.  o QSTACK Command 
  4711.  o RT Command 
  4712.  o SUBCOM Command 
  4713.  o TE Command 
  4714.  o TS Command 
  4715.  
  4716.  The MVS environment is available to all REXX execs running in any address 
  4717.  spaces. 
  4718.  
  4719.  
  4720. ΓòÉΓòÉΓòÉ 7.2.1. DELSTACK Command ΓòÉΓòÉΓòÉ
  4721.  
  4722. The DELSTACK commands deletes the most recently created stack. If no stack has 
  4723. been created (via the NEWSTACK command), then all elements from the original 
  4724. stack are deleted. 
  4725.  
  4726.  ΓöÇΓöÇDELSTACKΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4727.  
  4728. Example: 
  4729.  
  4730. 'delstack'
  4731.  
  4732.  
  4733. ΓòÉΓòÉΓòÉ 7.2.2. DROPBUF Command ΓòÉΓòÉΓòÉ
  4734.  
  4735. The DROPBUF command deletes the specified buffer (and its elements) from the 
  4736. current stack. Buffers are created via the MAKEBUF command. 
  4737.  
  4738.  ΓöÇΓöÇDROPBUFΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4739.               ΓööΓöÇbufnumberΓöÇΓöÿ
  4740.  
  4741.  bufnumber The number of the buffer to be deleted. This buffer and all higher 
  4742.            numbered buffers are deleted. The default is the most recently 
  4743.            created buffer. 
  4744.  
  4745.  Example: 
  4746.  
  4747.   'dropbuf 4'
  4748.  
  4749.  
  4750. ΓòÉΓòÉΓòÉ 7.2.3. EXECIO Command ΓòÉΓòÉΓòÉ
  4751.  
  4752. The EXECIO command performs input/output operations. 
  4753.  
  4754.  ΓöÇΓöÇEXECIOΓöÇΓö¼ΓöÇreccountΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4755.             ΓööΓöÇ*ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  4756.  
  4757.     ΓöÇΓöÇΓöÇΓö¼ΓöÇDiskW ddnameΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇ
  4758.         Γöé              ΓööΓöÇ(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé
  4759.         Γöé                  ΓööΓöÇSTEM varnameΓöÇΓöÿ ΓööΓöÇFINISΓöÇΓöÿ   Γöé
  4760.         Γö£ΓöÇDISKRΓöÇΓöÇΓö¼ΓöÇddnameΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4761.         ΓööΓöÇDISKRUΓöÇΓöÿ        ΓööΓöÇstartrecnumberΓöÇΓöÿ ΓööΓöÇ( optionΓöÇΓöÿ
  4762.  
  4763.     where option is:
  4764.  
  4765.     ΓöÇΓöÇΓöÇ(ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4766.           Γöé ΓööΓöÇFINISΓöÇΓöÿ    Γö£ΓöÇFIFOΓöÇΓöñ  Γöé
  4767.           Γöé              Γö£ΓöÇLIFOΓöÇΓöñ  Γöé
  4768.           Γöé              ΓööΓöÇSKIPΓöÇΓöÿ  Γöé
  4769.           ΓööΓöÇSTEM varnameΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  4770.                          ΓööΓöÇFINISΓöÇΓöÿ
  4771.  
  4772.  reccount  The number of records to be processed. "*" causes the complete 
  4773.            dataset to be processed. 
  4774.  
  4775.  DISKW     Performs write operations. 
  4776.  
  4777.  DISKR     Performs read operations. 
  4778.  
  4779.  DISKRU    Performs read for update operations. 
  4780.  
  4781.  ddname    Specifies the dataset on which to perform the specified operation. 
  4782.  
  4783.  STEM varname Specifies the REXX stem variable from/to which the specified 
  4784.            operation is to take place. 
  4785.  
  4786.  FINIS     Close the file on completion of the operation. 
  4787.  
  4788.  startrecnumber Specifies the first record on which to perform the operation. 
  4789.  
  4790.  FIFO      Specifies the records are to be stored at the head of the stack. 
  4791.  
  4792.  LIFO      Specifies the records are to be stored at the end (tail) of the 
  4793.            stack. 
  4794.  
  4795.  SKIP      Specifies the number of record to be skipped. 
  4796.  
  4797.  Example: 
  4798.  
  4799.   'execio * DISKR INFILE (STEM line.'
  4800.  
  4801.  
  4802. ΓòÉΓòÉΓòÉ 7.2.4. EXECUTIL Command ΓòÉΓòÉΓòÉ
  4803.  
  4804. The EXECUTIL command specifies the execution (TSO) environment for the REXX 
  4805. exec. 
  4806.  
  4807.  ΓöÇΓöÇEXECUTILΓö¼ΓöÇEXECDD(ΓöÇΓö¼ΓöÇCLOSEΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4808.              Γöé         ΓööΓöÇNOCLOSEΓöÇΓöÿ   Γöé
  4809.              Γö£ΓöÇHIΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4810.              Γö£ΓöÇHTΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4811.              Γö£ΓöÇrenameoptionΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4812.              Γö£ΓöÇRTΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4813.              Γö£ΓöÇSEARCHDD(ΓöÇΓö¼ΓöÇNOΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöñ
  4814.              Γöé           ΓööΓöÇYESΓöÇΓöÿ     Γöé
  4815.              Γö£ΓöÇTEΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  4816.              ΓööΓöÇTSΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  4817.  
  4818.     where renameoption is:
  4819.  
  4820.     ΓöÇΓöÇRENAME NAME(funcname)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4821.  
  4822.     ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4823.         ΓööΓöÇSYSNAME(sysname)ΓöÇΓöÿ ΓööΓöÇDD(sysdd)ΓöÇΓöÿ
  4824.  
  4825.  EXECDD    Specifies the system exec library to be used and the close option 
  4826.            after the library has been loaded. The default option is NOCLOSE. 
  4827.  
  4828.  HI        Halt interpretation. All execs currently active are terminated. 
  4829.  
  4830.  HT        Suppress SAY output. 
  4831.  
  4832.  RENAME    Used to change entries in a function package. 
  4833.  
  4834.  RT        Restart SAY output. 
  4835.  
  4836.  SEARCHDD  Specifies whether the system exec library is to be search in 
  4837.            addition to the system procedure library. 
  4838.  
  4839.  TE        Terminate tracing. 
  4840.  
  4841.  TS        Start tracing. 
  4842.  
  4843.  Example: 
  4844.  
  4845.   'executil searchdd(yes)'
  4846.  
  4847.  
  4848. ΓòÉΓòÉΓòÉ 7.2.5. HI Command ΓòÉΓòÉΓòÉ
  4849.  
  4850. The HI command terminates the execution of all REXX execs currently running. 
  4851.  
  4852.  ΓöÇΓöÇHIΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4853.  
  4854. Example: 
  4855.  
  4856. 'hi'
  4857.  
  4858.  
  4859. ΓòÉΓòÉΓòÉ 7.2.6. HT Command ΓòÉΓòÉΓòÉ
  4860.  
  4861. The HT command suppresses SAY output. 
  4862.  
  4863.  ΓöÇΓöÇHTΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4864.  
  4865. Example: 
  4866.  
  4867. 'ht'
  4868.  
  4869.  
  4870. ΓòÉΓòÉΓòÉ 7.2.7. MAKEBUF Command ΓòÉΓòÉΓòÉ
  4871.  
  4872. The MAKEBUF command creates a new buffer in the current stack. 
  4873.  
  4874.  ΓöÇΓöÇMAKEBUFΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4875.  
  4876. Example: 
  4877.  
  4878. 'makebuf'
  4879. x = RC    /* x now contains the buffer number created by MAKEBUF */
  4880.  
  4881.  
  4882. ΓòÉΓòÉΓòÉ 7.2.8. NEWSTACK Command ΓòÉΓòÉΓòÉ
  4883.  
  4884. The NEWSTACK command creates a new stack, which becomes the current stack. 
  4885.  
  4886.  ΓöÇΓöÇNEWSTACKΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4887.  
  4888. Example: 
  4889.  
  4890. 'newstack'
  4891.  
  4892.  
  4893. ΓòÉΓòÉΓòÉ 7.2.9. QBUF Command ΓòÉΓòÉΓòÉ
  4894.  
  4895. The QBUF command returns the current number of buffers in the current stack.. 
  4896.  
  4897.  ΓöÇΓöÇQBUFΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4898.  
  4899. Example: 
  4900.  
  4901. 'qbuf'
  4902. say 'The current number of buffers is' RC
  4903.  
  4904.  
  4905. ΓòÉΓòÉΓòÉ 7.2.10. QELEM Command ΓòÉΓòÉΓòÉ
  4906.  
  4907. The QELEM command returns the number of elements in the current buffer. 
  4908.  
  4909.  ΓöÇΓöÇQELEMΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4910.  
  4911. Example: 
  4912.  
  4913. 'qbuf'
  4914. say 'The current number of elements is' RC
  4915.  
  4916.  
  4917. ΓòÉΓòÉΓòÉ 7.2.11. QSTACK Command ΓòÉΓòÉΓòÉ
  4918.  
  4919. The QSTACK command returns the current number of stacks. 
  4920.  
  4921.  ΓöÇΓöÇQSTACKΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4922.  
  4923. Example: 
  4924.  
  4925. 'qbuf'
  4926. say 'The current number of stacks is' RC
  4927.  
  4928.  
  4929. ΓòÉΓòÉΓòÉ 7.2.12. SUBCOM Command ΓòÉΓòÉΓòÉ
  4930.  
  4931. The SUBCOM command determine if the exec is running in the specified 
  4932. environment. 
  4933.  
  4934.  ΓöÇΓöÇSUBCOM envΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4935.  
  4936.  env       Specifies the subcommand environment to query. 
  4937.  
  4938.  Example: 
  4939.  
  4940.   'subcom TSO'
  4941.   if RC = 0 then
  4942.      say 'TSO is the active environment'
  4943.   else
  4944.      say 'The TSO environment is not active'
  4945.  
  4946.  
  4947. ΓòÉΓòÉΓòÉ 7.2.13. TE Command ΓòÉΓòÉΓòÉ
  4948.  
  4949. The TE command terminates tracing. 
  4950.  
  4951.  ΓöÇΓöÇTEΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4952.  
  4953. Example: 
  4954.  
  4955. 'te'
  4956.  
  4957.  
  4958. ΓòÉΓòÉΓòÉ 7.2.14. TS Command ΓòÉΓòÉΓòÉ
  4959.  
  4960. The TS command initiates tracing. 
  4961.  
  4962.  ΓöÇΓöÇTSΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4963.  
  4964. Example: 
  4965.  
  4966. 'ts'
  4967.  
  4968.  
  4969. ΓòÉΓòÉΓòÉ 7.2.15. RT Command ΓòÉΓòÉΓòÉ
  4970.  
  4971. The RT command resumes SAY output. 
  4972.  
  4973.  ΓöÇΓöÇRTΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4974.  
  4975. Example: 
  4976.  
  4977. 'rt'
  4978.  
  4979.  
  4980. ΓòÉΓòÉΓòÉ 7.3. TSO Environment ΓòÉΓòÉΓòÉ
  4981.  
  4982. The TSO environment is available to all REXX execs running in the TSO address 
  4983. space. 
  4984.  
  4985. All TSO commands can be addressed to the TSO Subcommand Environment. Refer to 
  4986. the TSO/E Commands Reference manual for details on TSO commands. 
  4987.  
  4988.  
  4989. ΓòÉΓòÉΓòÉ 7.4. VM Environment ΓòÉΓòÉΓòÉ
  4990.  
  4991. *** Not yet written *** 
  4992.  
  4993.  
  4994. ΓòÉΓòÉΓòÉ 8. OS/2 APIs ΓòÉΓòÉΓòÉ
  4995.  
  4996. Note:  The examples and descriptions in the following sections are not meant to 
  4997. be a tutorial of REXX interface programming but a quick reference guide only. 
  4998.  
  4999. The following sections define the Application Programming Interfaces used in 
  5000. the OS/2 environment. 
  5001.  
  5002. The OS/2 APIs for REXX covers 7 topics: 
  5003.  
  5004.  o Data types and structures 
  5005.  o Invoking REXX 
  5006.  o Subcommand Interface 
  5007.  o External Functions 
  5008.  o Macrospace Interface 
  5009.  o Variable Pool Interface 
  5010.  o System Exit Interface 
  5011.  
  5012.  The APIs described here allow the REXX language to be extended in many 
  5013.  different ways. This includes the creation of new subcommand environments, 
  5014.  creation of new REXX functions, program access to REXX variables, manipulation 
  5015.  of the REXX macrospace and many other functions. 
  5016.  
  5017.  A complete example program which utilizes most of the common REXX APIs is 
  5018.  included in the SAAREXX.ZIP file. You can use the example as a starting point 
  5019.  for your own programs. 
  5020.  
  5021.  All of the examples given in this section are shown in C, but other SAA 
  5022.  languages are also capable of utilizing the APIs. 
  5023.  
  5024.  General Characteristics 
  5025.  
  5026.  Some general characteristics apply to applications which will be used as 
  5027.  handlers, subcommands, external functions, and system exit handlers. 
  5028.  
  5029.  o A handler must be written as a large model program. Other requirements are: 
  5030.  
  5031.     - Use the PASCAL calling convention 
  5032.     - All entry points must use the far calling convention 
  5033.     - The function should use the caller's stack 
  5034.     - The function should set up its own data segment 
  5035.  
  5036.  o A handler must be packaged as either: 
  5037.  
  5038.     - An OS/2 Dynamic Link Library (DLL) 
  5039.     - A binary executable (EXE) 
  5040.  
  5041.  o A handler must be registered before it can be used in a REXX program. 
  5042.    Registration of the handler informs the REXX interpreter where the handler 
  5043.    may be found and possibly how it should be invoked. Some constraints for 
  5044.    handlers are noted below: 
  5045.  
  5046.     - EXE handlers are known only to the local registering process. Functions 
  5047.       in the handler may only be invoked by the registering process. 
  5048.     - DLL handlers are known globally to all processes. Any REXX procedure 
  5049.       running in any process may register and access functions in the DLL. 
  5050.  
  5051.  
  5052. ΓòÉΓòÉΓòÉ 8.1. Data Types and Structures ΓòÉΓòÉΓòÉ
  5053.  
  5054. REXX uses several data structures in almost all of its APIs. These data 
  5055. structures are documented below. 
  5056.  
  5057.  o RXSTRING Structure 
  5058.  o RXSYSEXIT Structure 
  5059.  o SCBLOCK Structure 
  5060.  o SHVBLOCK Structure 
  5061.  
  5062.  
  5063. ΓòÉΓòÉΓòÉ 8.1.1. RXSTRING Structure ΓòÉΓòÉΓòÉ
  5064.  
  5065. REXX strings are passed to and from the C application program using the 
  5066. following structure definition and macros: 
  5067.  
  5068. /***    Structure for external interface string (RXSTRING) */
  5069.  
  5070. typedef struct {
  5071.    ULONG           strlength;          /*   length of string         */
  5072.    PCH             strptr;             /*   far pointer to string    */
  5073.    } RXSTRING;
  5074.  
  5075. typedef RXSTRING FAR *PRXSTRING;       /* pointer to a RXSTRING      */
  5076.  
  5077. #define RXNULLSTRING(r)      (!(r).strptr)
  5078. #define RXZEROLENSTRING(r)   ((r).strptr && !(r).strlength)
  5079. #define RXVALIDSTRING(r)     ((r).strptr && (r).strlength)
  5080. #define RXSTRLEN(r)          (RXNULLSTRING(r)?0L:(r).strlength)
  5081. #define RXSTRPTR(r)          (r).strptr
  5082. #define MAKERXSTRING(r,p,l)  (r).strptr=(PCH)p;(r).strlength=(ULONG)l
  5083.  
  5084. REXX strings may be larger than the 64K limit imposed by the 80286 
  5085. architecture. The strings themselves may reside in a single segment or may 
  5086. reside in a huge segment. 
  5087.  
  5088. When used as arguments in APIs, the following notes apply: 
  5089.  
  5090.   1. REXX string arguments may be given a value (which may be a zero-length 
  5091.      string) or not specified at all. 
  5092.  
  5093.     o If an argument is specified then all parts of the RXSTRING structure will 
  5094.       be given values. 
  5095.  
  5096.     o If the null string is specified as an argument then strlength will be set 
  5097.       to zero and strptr will be set to a valid address (it will be non-zero or 
  5098.       non-NULL). 
  5099.  
  5100.     o If no argument is specified the strptr will be set to NULL (zero). 
  5101.  
  5102.   2. When the RXSTRING is larger than 64K, strptr will point to memory that has 
  5103.      been allocated by way of a call to DosAllocHuge. However, the meaning of 
  5104.      the contents of the RXSTRING is exactly the same as for strings. 
  5105.  
  5106.   3. When a handler is called from REXX a return RXSTRING is required by REXX. 
  5107.      In this case REXX will supply a RXSTRING with a strlength and buffer size 
  5108.      of 250 bytes for the called function to use for the returned string. If 
  5109.      the returned string is less than 250 characters in length then the buffer 
  5110.      supplied by the caller should be utilized for the string and the strlength 
  5111.      set to the string's length. 
  5112.  
  5113.  
  5114. ΓòÉΓòÉΓòÉ 8.1.2. RXSYSEXIT Structure ΓòÉΓòÉΓòÉ
  5115.  
  5116. When invoking REXX through the REXXSAA( ) API the following data structure is 
  5117. used to specify which previously registered System Exits are to be utilized 
  5118. during this REXX call: 
  5119.  
  5120. /***    Structure for system exit block (RXSYSEXIT) */
  5121.  
  5122. typedef struct {
  5123.    PSZ   sysexit_name;                 /* subcom enviro for sysexit  */
  5124.    SHORT sysexit_code;                 /* sysexit function code      */
  5125.    } RXSYSEXIT;
  5126.  
  5127. typedef RXSYSEXIT FAR *PRXSYSEXIT;     /* pointer to a RXSYSEXIT     */
  5128.  
  5129. /* System Exit function and sub-function definitions */
  5130.  
  5131. #define RXENDLST    0                 /* End of exit list.           */
  5132. #define RXFNC    2                    /* Process external functions. */
  5133. #define    RXFNCCAL 1                 /* subcode value.              */
  5134. #define RXCMD    3                    /* Process host commands.      */
  5135. #define    RXCMDHST 1                 /* subcode value.              */
  5136. #define RXMSQ    4                    /* Manipulate queue.           */
  5137. #define    RXMSQPLL 1                 /* Pull a line from queue      */
  5138. #define    RXMSQPSH 2                 /* Place a line on queue       */
  5139. #define    RXMSQSIZ 3                 /* Return num of lines on queue*/
  5140. #define    RXMSQNAM 20                /* Set active queue name       */
  5141. #define RXSIO    5                    /* Session I/O.                */
  5142. #define    RXSIOSAY 1                 /* SAY a line to STDOUT        */
  5143. #define    RXSIOTRC 2                 /* Trace output                */
  5144. #define    RXSIOTRD 3                 /* Read from char stream       */
  5145. #define    RXSIODTR 4                 /* DEBUG read from char stream */
  5146. #define    RXSIOTLL 5                 /* Return linelength(N/A OS/2) */
  5147. #define RXHLT    7                    /* Halt processing.            */
  5148. #define    RXHLTCLR 1                 /* Clear HALT indicator        */
  5149. #define    RXHLTTST 2                 /* Test HALT indicator         */
  5150. #define RXTRC    8                    /* Test ext trace indicator.   */
  5151. #define    RXTRCTST 1                 /* subcode value.              */
  5152. #define RXINI    9                    /* Initialization processing.  */
  5153. #define    RXINIEXT 1                 /* subcode value.              */
  5154. #define RXTER   10                    /* Termination processing.     */
  5155. #define    RXTEREXT 1                 /* subcode value.              */
  5156. #define RXNOOFEXITS 11                /* 1 + largest exit number.    */
  5157.  
  5158. typedef PUCHAR PEXIT;                 /* ptr to exit parameter block */
  5159.  
  5160. Structure Member Values 
  5161.  
  5162.  sysexit_name Pointer to a null-terminated character string containing the name 
  5163.              of the System Exit. 
  5164.  
  5165.  sysexit_code Contains one of the following values: 
  5166.  
  5167.     RXENDLST  Specifies the end of the exit list when an array of structures is 
  5168.               used. 
  5169.     RXFNC     Specifies an external function exit. 
  5170.     RXCMD     Specifies a subcommand environment exit. 
  5171.     RXMSQ     Specifies a REXX queue exit. 
  5172.     RXSIO     Specifies a session i/o exit. 
  5173.     RXHLT     Specifies a session halt exit. 
  5174.     RXTRC     Specifies a session trace i/o exit. 
  5175.     RXINI     Specifies a session initialization exit. 
  5176.     RXTER     Specifies a session termination exit. 
  5177.  
  5178.  Refer to the section Exit Handler Function Code Definitions for more 
  5179.  information concerning the sysexit_code codes. 
  5180.  
  5181.  
  5182. ΓòÉΓòÉΓòÉ 8.1.3. SCBLOCK Structure ΓòÉΓòÉΓòÉ
  5183.  
  5184. REXX System Exit handler and Subcommand handler registration utilizes the 
  5185. following data structure: 
  5186.  
  5187. /***    Structure of Rexx Subcomand Block (SCBLOCK) */
  5188.  
  5189. typedef struct subcom_node {
  5190.     struct subcom_node far *next;      /* pointer to the next block  */
  5191.     PSZ    scbname;                    /* subcom environment name    */
  5192.     PSZ    scbdll_name;                /* subcom module name         */
  5193.     PSZ    scbdll_proc;                /* subcom procedure name      */
  5194.     double scbuser;                    /* user area                  */
  5195.     PFN    scbaddr;                    /* subcom environment address */
  5196.     USHORT scbmod_handle;              /* dynalink module handle     */
  5197.     USHORT scbdrop_auth;               /* Permission to drop         */
  5198.     PID    scbpid;                     /* Pid of Registrant          */
  5199.     USHORT scbsid;                     /* Session ID.                */
  5200.     } SCBLOCK;
  5201.  
  5202. typedef SCBLOCK FAR *PSCBLOCK;
  5203.  
  5204. Structure Member Values 
  5205.  
  5206.  subcom_node Pointer to the next SCBLOCK in the chain. This allows multiple 
  5207.              Subcommand and Exit handlers to be registered with a single API 
  5208.              call. The last block in the chain should set this value to NULL. 
  5209.  
  5210.  scbname     Pointer to a null-terminated character string containing the name 
  5211.              of the Subcommand/Exit handler. 
  5212.  
  5213.  scbdll_name Pointer to a null-terminated character string containing the name 
  5214.              of the DLL which packages the handler. This is the field used to 
  5215.              determine if the handler code resides in an EXE or a DLL. If this 
  5216.              field is set to NULL then the handler code resides in an EXE, 
  5217.              otherwise it resides in a DLL. 
  5218.  
  5219.  scbdll_proc Pointer to a null-terminated character string containing the name 
  5220.              of the exported entry point to the handler function in the DLL. 
  5221.              This field should be set to NULL if an EXE registration is being 
  5222.              performed. 
  5223.  
  5224.  scbuser     A double word to be used any way you wish. Usuall coded as 0L. 
  5225.  
  5226.  scbaddr     The address of the handler when performing an EXE registration. 
  5227.              Set this field to NULL for a DLL registration. 
  5228.  
  5229.  scbmod_handle For DLL registrations, if the DLL has already been loaded via 
  5230.              DosLoadModule, then this field should be set to the module handle. 
  5231.              Otherwise set this field to 0. 
  5232.  
  5233.  scbdrop_auth Specifies the handler's drop authority. This field should be set 
  5234.              to RXSUBCOM_DROPPABLE (any process may drop the handler) or 
  5235.              RXSUBCOM_NONDROP (only the registering process may drop the 
  5236.              handler). 
  5237.  
  5238.  scbpid      Specifies the process id of the registering process. 
  5239.  
  5240.  scbsid      Specifies the session id of the registering process. 
  5241.  
  5242.  
  5243. ΓòÉΓòÉΓòÉ 8.1.4. SHVBLOCK Structure ΓòÉΓòÉΓòÉ
  5244.  
  5245. REXX Shared Variable Pool access is performed utilizing the following data 
  5246. structure: 
  5247.  
  5248.  
  5249. /***    Shared Variable Pool Interface */
  5250. #ifdef INCL_RXSHV
  5251.  
  5252. /***    Function Codes for Variable Pool Interface (shvcode) */
  5253.  
  5254. #define RXSHV_SET          0x00       /* Set var from given value    */
  5255. #define RXSHV_FETCH        0x01       /* Copy value of var to buffer */
  5256. #define RXSHV_DROPV        0x02       /* Drop variable               */
  5257. #define RXSHV_SYSET        0x03       /* Symbolic name Set variable  */
  5258. #define RXSHV_SYFET        0x04       /* Symbolic name Fetch variable*/
  5259. #define RXSHV_SYDRO        0x05       /* Symbolic name Drop variable */
  5260. #define RXSHV_NEXTV        0x06       /* Fetch "next" variable       */
  5261. #define RXSHV_PRIV         0x07       /* Fetch private information   */
  5262. #define RXSHV_EXIT         0x08       /* Set function exit value     */
  5263.  
  5264.  
  5265. /***    Return Code Flags for Variable Pool Interface (shvret) */
  5266.  
  5267. #define RXSHV_OK           0x00       /* Execution was OK            */
  5268. #define RXSHV_NEWV         0x01       /* Variable did not exist      */
  5269. #define RXSHV_LVAR         0x02       /* Last var trans via SHVNEXTV */
  5270. #define RXSHV_TRUNC        0x04       /* Truncation occurred-Fetch   */
  5271. #define RXSHV_BADN         0x08       /* Invalid variable name       */
  5272. #define RXSHV_MEMFL        0x10       /* Out of memory failure       */
  5273. #define RXSHV_BADF         0x80       /* Invalid funct code (shvcode)*/
  5274. #define RXSHV_NOAVL        0x90       /* Interface not available     */
  5275.  
  5276.  
  5277. /***    Structure of Shared Variable Request Block (SHVBLOCK) */
  5278.  
  5279. typedef struct shvnode {
  5280.     struct shvnode FAR *shvnext;      /* pointer to the next block   */
  5281.     RXSTRING           shvname;       /* Pointer to the name buffer  */
  5282.     RXSTRING           shvvalue;      /* Pointer to the value buffer */
  5283.     ULONG              shvnamelen;    /* Length of the name value    */
  5284.     ULONG              shvvaluelen;   /* Length of the fetch value   */
  5285.     UCHAR              shvcode;       /* Function code for this block*/
  5286.     UCHAR              shvret;        /* Individual Return Code Flags*/
  5287.     } SHVBLOCK;
  5288.  
  5289. typedef SHVBLOCK FAR *PSHVBLOCK;
  5290.  
  5291. Structure Member Values 
  5292.  
  5293.  shvnext     Pointer to the next SHVBLOCK in the chain. This allows multiple 
  5294.              variable pool requests to be handled with a single API call. 
  5295.  
  5296.  shvname     Pointer to an RXSTRING containing the name of the REXX variable. 
  5297.  
  5298.  shvvalue    Pointer to an RXSTRING buffer. For a shvcode value of RXSHV_SET or 
  5299.              RXSHV_SYSET this is the value to be assigned to the REXX variable. 
  5300.              For a shvcode value of RXSHV_FET or RXSHV_SYFET this points to the 
  5301.              buffer to be used to obtain the current value of the specified 
  5302.              REXX variable. 
  5303.  
  5304.  shvnamelen  Pointer to an RXSTRING that specifies the maximum length of 
  5305.              shvname field. For a shvcode value of RXSHV_FET or RXSHV_SYFET 
  5306.              this points to the buffer to be used to obtain the current value 
  5307.              of the specified REXX variable. This field is unused for RXSHV_SET 
  5308.              and RXSHV_SYSET. 
  5309.  
  5310.  shvvaluelen Pointer to an RXSTRING that specifies the maximum length of 
  5311.              shvvalue field. For a shvcode value of RXSHV_FET or RXSHV_SYFET 
  5312.              this points to the buffer to be used to obtain the current value 
  5313.              of the specified REXX variable. This field is unused for RXSHV_SET 
  5314.              and RXSHV_SYSET. 
  5315.  
  5316.  shvcode     A code which specifies the variable function to be performed. 
  5317.              Possible values are: 
  5318.  
  5319.     RXSHV_SET Assign the shvvalue to the REXX variable specified by shvname. 
  5320.     RXSHV_FETCH Fetch the REXX variable specified by shvname into the buffer 
  5321.               specified by shvvalue and shvvaluelen. 
  5322.     RXSHV_DROPV Drop the REXX variable specified by shvname. Performs the same 
  5323.               function as the REXX DROP statement. 
  5324.     RXSHV_SYSET Assign the shvvalue to the REXX variable specified by shvname. 
  5325.               The shvname specifies an unresolved REXX variable name. 
  5326.     RXSHV_SYFET Fetch the REXX variable specified by shvname into the buffer 
  5327.               specified by shvvalue and shvvaluelen. The shvname specifies an 
  5328.               unresolved REXX variable name. 
  5329.     RXSHV_SYDRO Drop the REXX variable specified by shvname. Performs the same 
  5330.               function as the REXX DROP statement. The shvname specifies an 
  5331.               unresolved REXX variable name. 
  5332.     RXSHV_NEXTV Fetch the next variable from the REXX variable pool into the 
  5333.               buffer specified by shvvalue and shvvaluelen. This code is used 
  5334.               to fetch all of the variables currently active from the REXX 
  5335.               variable pool. 
  5336.     RXSHV_PRIV Fetch REXX private information. Refer to the IBM Procedures 
  5337.               Language 2/REXX Reference manual for a full description of this 
  5338.               code. 
  5339.     RXSHV_EXIT Sets the exit value for an External Function or a Subcommand 
  5340.               handler. May only be executed by an external function or 
  5341.               subcommand handler and may be called only once per invocation of 
  5342.               the handler. 
  5343.  
  5344.  shvret      Return code from the API for this request block. See the example 
  5345.              above for possible values. 
  5346.  
  5347.  
  5348. ΓòÉΓòÉΓòÉ 8.2. Invoking REXX ΓòÉΓòÉΓòÉ
  5349.  
  5350. The following defines the API used to call the REXX interpreter from within a C 
  5351. application: 
  5352.  
  5353. /***    Main Entry Point to the REXXSAA Interpreter */
  5354. #define RXCOMMAND       0             /* Program called as Command   */
  5355. #define RXSUBROUTINE    1             /* Program called as Subroutin */
  5356. #define RXFUNCTION      2             /* Program called as Function  */
  5357.  
  5358.  
  5359. SHORT APIENTRY REXXSAA (
  5360.          SHORT      argc,             /* Num of args passed to REXX  */
  5361.          PRXSTRING  argv,             /* Array of args passed to rex */
  5362.          PSZ        fname,            /* [d:][path]filename[.ext]  */
  5363.          PRXSTRING  instore,          /* Loc of REXX proc in memory  */
  5364.          PSZ        envname,          /* ASCIIZ initial environment. */
  5365.          SHORT      calltype,         /* type (command,subrtn,funct) */
  5366.          PRXSYSEXIT exits,            /* SysExit env. names & codes  */
  5367.          PSHORT     retc,             /* Ret code from if numeric    */
  5368.          PRXSTRING  result);          /* Retvalue from the REXX proc */
  5369.  
  5370. Parameters 
  5371.  
  5372.  argc      Is the number of arguments (the number of members of the array argv) 
  5373.            for this call to REXX. 
  5374.  
  5375.  argv      Is a pointer to an array of RXSTRING structures that describe the 
  5376.            arguments to this invocation of the REXX interpreter. 
  5377.  
  5378.  fname     A pointer to a zero-terminated string containing the filename of the 
  5379.            REXX procedure. If no extension is specified then a default of .CMD 
  5380.            is used. If no drive/path is specified then the OS/2 normal OS/2 
  5381.            program search will be conducted (current directory and then the 
  5382.            PATH environment) for the file. 
  5383.  
  5384.  instore   Is an array of 2 RXSTRING descriptors for instorage REXX procedures. 
  5385.  
  5386.     instore[0] Describes the memory buffer which contains the source of the 
  5387.               REXX procedure. The source must be in the same format as it would 
  5388.               reside on disk complete with all carriage-control characters. 
  5389.  
  5390.     instore[1] Is used by the REXX interpreter to return the tokenized image of 
  5391.               the REXX procedure. The REXX interpreter will allocate the 
  5392.               storage necessary for the image via a call to DosAllocSeg or 
  5393.               DosAllocHuge. 
  5394.  
  5395.               This parameter can also be used to pass a tokenized image to the 
  5396.               interpreter. This could be useful to protect the source code for 
  5397.               REXX procedures from prying eyes. 
  5398.  
  5399.               The following notes apply to the instore parameter. 
  5400.  
  5401.     o If instore is not NULL, then no disk search is performed on pgmname. 
  5402.  
  5403.     o If instore is not NULL then instore[0] must specify a valid memory 
  5404.       location for the program source. 
  5405.  
  5406.     o If insource[1].strptr is NULL then the interpreter will allocate storage 
  5407.       for the tokenized image and set the contents of insource[1]. 
  5408.  
  5409.     o If insource[1].strptr is not NULL then it should specify a valid memory 
  5410.       location for the tokenized image of the procedure source. In this case 
  5411.       insource[0].strptr may be NULL. 
  5412.  
  5413.  envname   Is a pointer to a zero-terminated string containing the name of the 
  5414.            default environment. If envname is NULL then the environment name 
  5415.            will be taken from the extension specified by pgmname. 
  5416.  
  5417.  calltype  A flag which specifies how REXX is to be called. The possible values 
  5418.            are: 
  5419.  
  5420.            RXCOMMAND - Program called as Command 
  5421.            RXSUBROUTINE - Program called as Subroutine 
  5422.            RXFUNCTION - Program called as Function 
  5423.  
  5424.  exits     Is an array of RXSYSEXIT structures which contain information about 
  5425.            the system exits the caller wishes to be utilized during this 
  5426.            invocation of the interpreter. 
  5427.  
  5428.  retc      If result is numeric then it will be converted to a binary integer 
  5429.            and returned in retc. 
  5430.  
  5431.  result    The RETURN or EXIT value from the pgmname procedure. 
  5432.  
  5433.  Returns 
  5434.  
  5435.  REXXSAA( ) return an integer code describing the REXX interpreters action on 
  5436.  the procedure. The possible return codes are: 
  5437.  
  5438.  negative    Interpreter errors. These are standard SAA-defined interpreter 
  5439.              error codes. 
  5440.  
  5441.  0           No errors. The procedure executed normally. 
  5442.  
  5443.  positive    Specifies  an OS/2 error loading the interpreter. Refer to the 
  5444.              error codes from DosLoadModule and DosGetProcAddr for details. 
  5445.  
  5446.  
  5447. ΓòÉΓòÉΓòÉ 8.3. Subcommand Interface ΓòÉΓòÉΓòÉ
  5448.  
  5449. This section describes how to create subcommand environments which can be made 
  5450. known to REXX. 
  5451.  
  5452.  o Subcommand Handler Definition 
  5453.  o Subcommand Handler Registration and Manipulation 
  5454.  
  5455.  
  5456. ΓòÉΓòÉΓòÉ 8.3.1. Subcommand Handler Definition ΓòÉΓòÉΓòÉ
  5457.  
  5458. The following example shows an example subcommand handler definition: 
  5459.  
  5460. USHORT APIENTRY subcom_sample (
  5461.          PRXSTRING cmdstr,  /* command string passed from the caller */
  5462.          PUSHORT   retflag, /* pointer to short for return of flags  */
  5463.          PRXSTRING retstr)  /* pointer to RXSTRING for return string */
  5464. {
  5465.  
  5466. /* subcommand code goes here */
  5467.  
  5468. return (0);
  5469. }
  5470.  
  5471. CAUTION:
  5472. The IBM OS/2 Procedures Language 2/REXX Reference manual's example subcommand 
  5473. procedure is incorrect. The IBM OS/2 Tools and Information Kit REXX subcommand 
  5474. example is correct. The problem is with the first parameter to the function; it 
  5475. should be a pointer to a RXSTRING, not the contents of the structure. 
  5476.  
  5477. Subcommands can be in the same module (EXE or DLL) as the application or can 
  5478. reside in a separate Dynamic Link Library. 
  5479.  
  5480. Subcommand Parameters 
  5481.  
  5482.  cmdstr    The entire command string completely resolved by REXX. 
  5483.  
  5484.  retflag   A flag returned by the subcommand handler to the REXX interpreter 
  5485.            which indicates the command completion condition. 
  5486.  
  5487.     RXSUBCOM_OK      Subcommand completed normally. 
  5488.  
  5489.     RXSUBCOM_ERROR  An error occured during the execution of the subcommand. 
  5490.  
  5491.     RXSUBCOM_FAILURE The subcommand failed. 
  5492.  
  5493.  retstr    The address of a RXSTRING to return the subcommand result. Note that 
  5494.            the REXX interpreter provides a 250 byte area for your result. You 
  5495.            may choose to use that default area or allocate your own area via 
  5496.            DosAllocSeg. 
  5497.  
  5498.  The integer value returned by the subcommand handler function is handled as 
  5499.  follows: 
  5500.  
  5501.  o If the return code is non-zero, that number is assigned to the special REXX 
  5502.    variable RC. 
  5503.  
  5504.  o If zero is returned and the retstr is not empty, then RC is set to the value 
  5505.    of retstr. 
  5506.  
  5507.  o Otherwise RC is set to zero. 
  5508.  
  5509.  
  5510. ΓòÉΓòÉΓòÉ 8.3.2. Subcommand Handler Registration and Manipulation ΓòÉΓòÉΓòÉ
  5511.  
  5512. Subcommand environments can be registered from your own C program or via the 
  5513. OS/2 CMD Environment RXSUBCOM RESISTER command. 
  5514.  
  5515. The following describes the C Language APIs for manipulating subcommand 
  5516. environments: 
  5517.  
  5518.  o RxSubcomRegister( ) 
  5519.  o RxSubcomQuery( ) 
  5520.  o RxSubcomExecute( ) 
  5521.  o RxSubcomLoad( ) 
  5522.  o RxSubcomDrop( ) 
  5523.  
  5524.  
  5525. ΓòÉΓòÉΓòÉ 8.3.2.1. RxSubcomRegister( ) ΓòÉΓòÉΓòÉ
  5526.  
  5527. Registers a subcommand environment. 
  5528.  
  5529.  ΓöÇΓöÇΓöÇRxSubcomRegister(subcomblock)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5530.  
  5531.  Parameter      Definition 
  5532.  
  5533.  subcomblock (PSCBLOCK) Pointer to a user allocated SCBLOCK structure. 
  5534.  
  5535.  Returns   C Define 
  5536.  0         RXSUBCOM_OK - success 
  5537.  10        RXSUBCOM_DUP - success, but a duplicate subcommand environment is 
  5538.            already registered with your specified name ( a fully qualified 
  5539.            subcommand name must be used when addressing this environment) 
  5540.  30        RXSUBCOM_MAXREG - error, cannot register any more environments 
  5541.  1002      RXSUBCOM_NOEMEM - error, no memory available for registration 
  5542.  1003      RXSUBCOM_BADTYPE - error, the subcomblock contains invalid data 
  5543.  
  5544.  
  5545. ΓòÉΓòÉΓòÉ 8.3.2.2. RxSubcomQuery( ) ΓòÉΓòÉΓòÉ
  5546.  
  5547. Queries for a registered subcommand environment name. 
  5548.  
  5549.  ΓöÇΓöÇΓöÇRxSubcomQuery(envname, modulename, flag, userword)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5550.  
  5551.  Parameter      Definition 
  5552.  
  5553.  envname (PSZ)  Pointer to a null-terminated character string containing the 
  5554.                 environment name to be located. 
  5555.  
  5556.  modulename (PSZ) Pointer to a null-terminated character string containing the 
  5557.                 library name of the subcommand environment. This value can be 
  5558.                 NULL if there are no duplicate environment names registered. If 
  5559.                 it is NULL, the standard search order for environment names is 
  5560.                 searched. 
  5561.  
  5562.  flag (PUSHORT) Pointer a USHORT for the return results of the search. If the 
  5563.                 return code from RxSubcomQuery() is RXSUBCOM_OK then this value 
  5564.                 contains either 1 (registered) or 0 (not registered). 
  5565.  
  5566.  userword far * double Pointer a double. If the return code from 
  5567.                 RxSubcomQuery() is RXSUBCOM_OK then this value contains the 
  5568.                 user word assigned at the registration of the environment. 
  5569.  
  5570.  Returns   C Define 
  5571.  0         RXSUBCOM_OK - success 
  5572.  30        RXSUBCOM_NOTREG - specified subcommand environment is not registered 
  5573.  1003      RXSUBCOM_BADTYPE - error, the API parameters are incorrect invalid 
  5574.            data 
  5575.  
  5576.  
  5577. ΓòÉΓòÉΓòÉ 8.3.2.3. RxSubcomExecute( ) ΓòÉΓòÉΓòÉ
  5578.  
  5579. Sends a command to a previously registered subcommand environment. It will load 
  5580. the environment into memory if it has not been loaded previously. 
  5581.  
  5582.  ΓöÇΓöÇΓöÇRxSubcomExecute(envname, modname, cmd, flags, ret, result)ΓöÇΓöÇΓöÇΓöÇ
  5583.  
  5584.  Parameter      Definition 
  5585.  
  5586.  envname (PSZ)  Pointer to a null-terminated character string containing the 
  5587.                 environment name to be used in executing the command. 
  5588.  
  5589.  modname (PSZ)  Pointer to a null-terminated character string containing the 
  5590.                 library name of the subcommand environment. This value can be 
  5591.                 NULL if there are no duplicate environment names registered. If 
  5592.                 it is NULL, the standard search order for environment names is 
  5593.                 used. 
  5594.  
  5595.  cmd (PRXSTRING) Pointer to and RXSTRING containg the command to be executed. 
  5596.  
  5597.  flags (PUSHORT) Pointer a USHORT for the return results from the command 
  5598.                 execution. This is the return flags from the subcommand 
  5599.                 environment function itself. 
  5600.  
  5601.  ret (PUSHORT)  The return code from the subcommand handler function. 
  5602.  
  5603.  result (PRXSTRING) The result string from the subcommand processing. 
  5604.  
  5605.  Returns   C Define 
  5606.  0         RXSUBCOM_OK - success 
  5607.  30        RXSUBCOM_NOTREG - specified subcommand environment is not registered 
  5608.  50        RXSUBCOM_LOADERR - error, not enough memory to load the DLL 
  5609.            containing subcommand environment 
  5610.  127       RXSUBCOM_NOPROC - error, the specified DLL does not contain the 
  5611.            specified procedure (environment) name 
  5612.  
  5613.  
  5614. ΓòÉΓòÉΓòÉ 8.3.2.4. RxSubcomLoad( ) ΓòÉΓòÉΓòÉ
  5615.  
  5616. Loads a subcommand environment packaged as a DLL. 
  5617.  
  5618.  ΓöÇΓöÇΓöÇRxSubcomLoad(envname, modulename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5619.  
  5620.  Parameter      Definition 
  5621.  
  5622.  envname (PSZ)  Pointer to a null-terminated character string containing the 
  5623.                 environment name to be loaded. 
  5624.  
  5625.  modulename (PSZ) Pointer to a null-terminated character string containing the 
  5626.                 library name of the subcommand environment. This value can be 
  5627.                 NULL if there are no duplicate environment names registered. If 
  5628.                 it is NULL, the standard search order for environment names is 
  5629.                 searched. 
  5630.  
  5631.  Returns   C Define 
  5632.  0         RXSUBCOM_OK - success 
  5633.  30        RXSUBCOM_NOTREG - specified subcommand environment is not registered 
  5634.  50        RXSUBCOM_LOADERR - error, not enough memory to load the DLL 
  5635.            containing subcommand environment 
  5636.  127       RXSUBCOM_NOPROC - error, the specified DLL does not contain the 
  5637.            specified procedure (environment) name 
  5638.  
  5639.  
  5640. ΓòÉΓòÉΓòÉ 8.3.2.5. RxSubcomDrop( ) ΓòÉΓòÉΓòÉ
  5641.  
  5642. Drops a subcommand environment packaged as a DLL. 
  5643.  
  5644.  ΓöÇΓöÇΓöÇRxSubcomDrop(envname, modulename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5645.  
  5646.  Parameter      Definition 
  5647.  
  5648.  envname (PSZ)  Pointer to a null-terminated character string containing the 
  5649.                 environment name to be dropped. 
  5650.  
  5651.  modulename (PSZ) Pointer to a null-terminated character string containing the 
  5652.                 library name of the subcommand environment. This value can be 
  5653.                 NULL if there are no duplicate environment names registered. If 
  5654.                 it is NULL, the standard search order for environment names is 
  5655.                 searched. 
  5656.  
  5657.  Returns   C Define 
  5658.  0         RXSUBCOM_OK - success 
  5659.  30        RXSUBCOM_NOTREG - specified subcommand environment is not registered 
  5660.  40        RXSUBCOM_NOCANDROP - error, subcommand environment was registered as 
  5661.            not droppable 
  5662.  1003      RXSUBCOM_BADTYPE - error, the API parameters are incorrect 
  5663.  
  5664.  
  5665. ΓòÉΓòÉΓòÉ 8.4. External Functions ΓòÉΓòÉΓòÉ
  5666.  
  5667. This section describes how to create external functions which can be made known 
  5668. to REXX. 
  5669.  
  5670.  o External Function Definition 
  5671.  o External Function Handler Registration and Manipulation 
  5672.  
  5673.  
  5674. ΓòÉΓòÉΓòÉ 8.4.1. External Function Definition ΓòÉΓòÉΓòÉ
  5675.  
  5676. The following example shows an example external function definition: 
  5677.  
  5678. USHORT APIENTRY extfunc_sample (
  5679.          PSZ       name,    /* function name used by REXX            */
  5680.          SHORT     argc,    /* number of arguments                   */
  5681.          RXSTRING  argv[],  /* array of argument strings             */
  5682.          PSZ       queue,   /* current REXX queue name               */
  5683.          PRXSTRING retstr)  /* pointer to RXSTRING for return string */
  5684. {
  5685.  
  5686. /* function code goes here */
  5687.  
  5688. return (0);
  5689. }
  5690.  
  5691. Function Parameters 
  5692.  
  5693.  name      The name under which REXX invoked the external function. 
  5694.  
  5695.  argc      The number of arguments to the function. 
  5696.  
  5697.  argv      An array of RXSTRINGs which are the arguments to the function. 
  5698.  
  5699.  queue     An name of the currently active REXX queue. 
  5700.  
  5701.  retstr    The address of a RXSTRING to return the function result. Note that 
  5702.            the REXX interpreter provides a 250 byte area for your result. You 
  5703.            may choose to use that default area or allocate your own area via 
  5704.            DosAllocSeg. 
  5705.  
  5706.  The manuals are very unclear about how the return code from external functions 
  5707.  should be handled. I always code this as RXFUNC_OK. 
  5708.  
  5709.  
  5710. ΓòÉΓòÉΓòÉ 8.4.2. External Function Handler Registration and Manipulation ΓòÉΓòÉΓòÉ
  5711.  
  5712. External Functions can be manipulated from your own C program or from your REXX 
  5713. exec via the builtin functions RxFuncAdd( ), RxFuncDrop( ) and RxFuncQuery( ). 
  5714.  
  5715. The following describes the C Language APIs for manipulating external 
  5716. functions. 
  5717.  
  5718.  o RxFunctionRegister( ) 
  5719.  o RxFunctionCall( ) 
  5720.  o RxFunctionDeregister( ) 
  5721.  o RxFunctionQuery( ) 
  5722.  
  5723.  
  5724. ΓòÉΓòÉΓòÉ 8.4.2.1. RxFunctionRegister( ) ΓòÉΓòÉΓòÉ
  5725.  
  5726. Registers an external function packaged in an EXE or DLL. 
  5727.  
  5728.  ΓöÇΓöÇΓöÇRxFunctionRegister(fname, modname, entrypoint, modtype)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5729.  
  5730.  Parameter      Definition 
  5731.  
  5732.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5733.                 name of the function to register. This name should be used when 
  5734.                 refering to the function from your REXX exec. 
  5735.  
  5736.  modname (PSZ)  Pointer to a null-terminated character string containing the 
  5737.                 name of the DLL module packaging the function. This parameter 
  5738.                 is ignored if the modtype is RXFUNC_CALLENTRY. 
  5739.  
  5740.  entrypoint (PSZ) Pointer to a null-terminated character string containing the 
  5741.                 name of the procedure in the DLL. If modtype is RXFUNC_DYNALINK 
  5742.                 then you must cast this argument to the address of the function 
  5743.                 in your EXE. 
  5744.  
  5745.  modtype (USHORT) Flag to indicate the type of registration. 
  5746.                 RXFUNC_CALLENTRY - function is packaged as a DLL. 
  5747.                 RXFUNC_DYNALINK - function is packaged as an entry point in 
  5748.                 memory. 
  5749.  
  5750.  Returns   C Define 
  5751.  0         RXFUNC_OK - success 
  5752.  10        RXFUNC_DEFINED - error, function is already registered 
  5753.  1002      RXFUNC_NOMEM - error, no memory available for registration 
  5754.  
  5755.  
  5756. ΓòÉΓòÉΓòÉ 8.4.2.2. RxFunctionCall( ) ΓòÉΓòÉΓòÉ
  5757.  
  5758. Call a registered external function packaged in an EXE or DLL. 
  5759.  
  5760.  ΓöÇΓöÇΓöÇRxFunctionCall(fname, argc, argv, retv, result, queue)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5761.  
  5762.  Parameter      Definition 
  5763.  
  5764.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5765.                 name of the function to call. 
  5766.  
  5767.  argc (USHORT)  The number of function arguments. 
  5768.  
  5769.  arv (PRXSTRING) Pointer to the array of RXSTRING arguments. 
  5770.  
  5771.  retv (PUSHORT) The return code from the function. 
  5772.  
  5773.  result (PRXSTRING) Pointer to the result string from the function. 
  5774.  
  5775.  queue (PSZ)    Name of the REXX queue to be used by the function. 
  5776.  
  5777.  Returns   C Define 
  5778.  0         RXFUNC_OK - success 
  5779.  30        RXFUNC_NOTREG - error, function is not registered 
  5780.  40        RXFUNC_MODNOTFND - error, Dll not found 
  5781.  50        RXFUNC_ENTNOTFND - error, function entry point in the DLL not found 
  5782.  
  5783.  
  5784. ΓòÉΓòÉΓòÉ 8.4.2.3. RxFunctionDeregister( ) ΓòÉΓòÉΓòÉ
  5785.  
  5786. Drop a registered external function. 
  5787.  
  5788.  ΓöÇΓöÇΓöÇRxFunctionDeregister(fname)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5789.  
  5790.  Parameter      Definition 
  5791.  
  5792.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5793.                 name of the function to drop (deregister). 
  5794.  
  5795.  Returns   C Define 
  5796.  0         RXFUNC_OK - success 
  5797.  30        RXFUNC_NOTREG - error, function is not registered 
  5798.  
  5799.  
  5800. ΓòÉΓòÉΓòÉ 8.4.2.4. RxFunctionQuery( ) ΓòÉΓòÉΓòÉ
  5801.  
  5802. Queries for a registered function. 
  5803.  
  5804.  ΓöÇΓöÇΓöÇRxFunctionQuery(fname)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5805.  
  5806.  Parameter      Definition 
  5807.  
  5808.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5809.                 name of the function to searched for. 
  5810.  
  5811.  Returns   C Define 
  5812.  0         RXFUNC_OK - success, function is registered 
  5813.  30        RXFUNC_NOTREG - error, function is not registered 
  5814.  
  5815.  
  5816. ΓòÉΓòÉΓòÉ 8.5. Macrospace Interface ΓòÉΓòÉΓòÉ
  5817.  
  5818. The REXX Macrospace Interface can reduce the time REXX functions take to load 
  5819. or be found by the interpreter. This especially useful for procrdures which are 
  5820. used repeatedly and never dropped. 
  5821.  
  5822. The following sections describe the C Language APIs for manipulating the REXX 
  5823. Macrospace: 
  5824.  
  5825.  o RxMacroChange( ) 
  5826.  o RxMacroDrop( ) 
  5827.  o RxMacroErase( ) 
  5828.  o RxMacroSave( ) 
  5829.  o RxMacroLoad( ) 
  5830.  o RxMacroQuery( ) 
  5831.  o RxMacroReorder( ) 
  5832.  
  5833.  
  5834. ΓòÉΓòÉΓòÉ 8.5.1. RxMacroChange( ) ΓòÉΓòÉΓòÉ
  5835.  
  5836. Change or add a new macro to the macrospace. 
  5837.  
  5838.  ΓöÇΓöÇΓöÇRxMacroChange(fname, srcfile, position)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5839.  
  5840.  Parameter      Definition 
  5841.  
  5842.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5843.                 name name of the function to change or add. 
  5844.  
  5845.  srcfile (PSZ)  Pointer to a null-terminated character string containing the 
  5846.                 name of the file containing the source for the function. If no 
  5847.                 file extension is supplied then it will default to .CMD. 
  5848.  
  5849.  position (USHORT) Flag indicating the position this function should be placed 
  5850.                 in the macrospace list of functions. Valid values are: 
  5851.  
  5852.     RXMACRO_SEARCH_BEFORE Places the macro function at the head of the list. 
  5853.     RXMACRO_SEARCH_AFTER Places the macro function at the tail of the list. 
  5854.  
  5855.  Returns   C Define 
  5856.  0         RXMACRO_OK - success 
  5857.  1         RXMACRO_NOSTORAGE - error, no memory available 
  5858.  7         RXMACRO_SOURCE_NOT_FOUND - error, source file not found 
  5859.  8         RXMACRO_INVALID_POSITION - invalid position specified 
  5860.  
  5861.  
  5862. ΓòÉΓòÉΓòÉ 8.5.2. RxMacroDrop( ) ΓòÉΓòÉΓòÉ
  5863.  
  5864. Drops a function from the REXX macrospace. 
  5865.  
  5866.  ΓöÇΓöÇΓöÇRxMacroDrop(fname)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5867.  
  5868.  Parameter      Definition 
  5869.  
  5870.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5871.                 name of the function to drop. 
  5872.  
  5873.  Returns   C Define 
  5874.  0         RXMACRO_OK - success 
  5875.  2         RXMACRO_NOT_FOUND - error, specified macro not found 
  5876.  
  5877.  
  5878. ΓòÉΓòÉΓòÉ 8.5.3. RxMacroErase( ) ΓòÉΓòÉΓòÉ
  5879.  
  5880. Drops all known functions from the REXX macrospace. 
  5881.  
  5882.  ΓöÇΓöÇΓöÇRxMacroErase( )ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5883.  
  5884. Note:  This is a very powerful function. Macro functions are dropped from the 
  5885. REXX Macrospace even if they are currently being used by other processes. 
  5886.  
  5887.  Returns   C Define 
  5888.  0         RXMACRO_OK - success 
  5889.  2         RXMACRO_NOT_FOUND - error, no macros found 
  5890.  
  5891.  
  5892. ΓòÉΓòÉΓòÉ 8.5.4. RxMacroSave( ) ΓòÉΓòÉΓòÉ
  5893.  
  5894. Saves the binary image of a function from the REXX macrospace to a file. 
  5895.  
  5896.  ΓöÇΓöÇΓöÇRxMacroSave(fcount, fnames, libfile)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5897.  
  5898.  Parameter      Definition 
  5899.  
  5900.  fcount (USHORT) Count of the number of pointers in the array fnames. 
  5901.  
  5902.  fnames (* PSZ) An array of pointers to macrospace function names to be saved. 
  5903.  
  5904.  libfile (PSZ)  Pointer to a null-terminated character string containing the 
  5905.                 name of the file to use in saving the macro(s) to disk. 
  5906.  
  5907.  Returns   C Define 
  5908.  0         RXMACRO_OK - success 
  5909.  2         RXMACRO_NOT_FOUND - error, specified macro not found 
  5910.  3         RXMACRO_EXTENSION_REQUIRED - error, the libfile must contain a file 
  5911.            extension in its name 
  5912.  5         RXMACRO_FILE_ERROR - error, access to the libfile was denied 
  5913.  
  5914.  Note:  If fcount is 0 (zero) or fnames is NULL then the entire macrospace will 
  5915.  be saved. 
  5916.  
  5917.  
  5918. ΓòÉΓòÉΓòÉ 8.5.5. RxMacroLoad( ) ΓòÉΓòÉΓòÉ
  5919.  
  5920. Loads the binary image of a function into the REXX macrospace from a file. 
  5921.  
  5922.  ΓöÇΓöÇΓöÇRxMacroLoad(fcount, fnames, libfile)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5923.  
  5924.  Parameter      Definition 
  5925.  
  5926.  fcount (USHORT) Count of the number of pointers in the array fnames. 
  5927.  
  5928.  fnames (* PSZ) An array of pointers to macrospace function names to be loaded. 
  5929.  
  5930.  libfile (PSZ)  Pointer to a null-terminated character string containing the 
  5931.                 name of the file to use in loading the macro(s) from disk. 
  5932.  
  5933.  Returns   C Define 
  5934.  0         RXMACRO_OK - success 
  5935.  1         RXMACRO_NOSTORAGE - error, no memory available 
  5936.  2         RXMACRO_NOT_FOUND - error, specified macro not found 
  5937.  4         RXMACRO_ALREADY_EXISTS - error, one or more of the specified macros 
  5938.            already exist in the macrospace 
  5939.  5         RXMACRO_FILE_ERROR - error, access to the libfile was denied 
  5940.  6         RXMACRO_SIGNATURE_ERROR - error, the specified libfile does not 
  5941.            contain a valid macro library 
  5942.  
  5943.  
  5944. ΓòÉΓòÉΓòÉ 8.5.6. RxMacroQuery( ) ΓòÉΓòÉΓòÉ
  5945.  
  5946. Queries for the existence of a function in the REXX Macrospace. 
  5947.  
  5948.  ΓöÇΓöÇΓöÇRxMacroQuery(fname, position)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5949.  
  5950.  Parameter      Definition 
  5951.  
  5952.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5953.                 name name of the function to be searched for. 
  5954.  
  5955.  position (PUSHORT) Pointer to a flag indicating the position in the macrospace 
  5956.                 list of the function. A valid position is only retuned on 
  5957.                 successful execution of the function. 
  5958.  
  5959.  Returns   C Define 
  5960.  0         RXMACRO_OK - success 
  5961.  2         RXMACRO_NOT_FOUND - error, specified macro not found 
  5962.  
  5963.  
  5964. ΓòÉΓòÉΓòÉ 8.5.7. RxMacroReorder( ) ΓòÉΓòÉΓòÉ
  5965.  
  5966. Changes the search-order position of a function in the REXX Macrospace. 
  5967.  
  5968.  ΓöÇΓöÇΓöÇRxMacroReorder(fname, position)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5969.  
  5970.  Parameter      Definition 
  5971.  
  5972.  fname (PSZ)    Pointer to a null-terminated character string containing the 
  5973.                 name name of the function to be repositioned. 
  5974.  
  5975.  position (USHORT) Flag indicating the new search-order position for the 
  5976.                 specified function. Valid values are: 
  5977.  
  5978.     RXMACRO_SEARCH_BEFORE Places the macro function at the head of the list. 
  5979.     RXMACRO_SEARCH_AFTER Places the macro function at the tail of the list. 
  5980.  
  5981.  Returns   C Define 
  5982.  0         RXMACRO_OK - success 
  5983.  2         RXMACRO_NOT_FOUND - error, specified macro not found 
  5984.  8         RXMACRO_INVALID_POSITION - invalid position specified 
  5985.  
  5986.  
  5987. ΓòÉΓòÉΓòÉ 8.6. Variable Pool Interface ΓòÉΓòÉΓòÉ
  5988.  
  5989. The REXX Variable Pool Service allows an OS/2 program to access REXX variables 
  5990. from External Functions, System Exit Handlers and Subcommand Handlers. The 
  5991. following definition describe the interface: 
  5992.  
  5993.  ΓöÇΓöÇΓöÇRxVar(shvblock)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  5994.  
  5995.  Parameter      Definition 
  5996.  
  5997.  shvblock (PSHVBLOCK) Pointer to an array of SHVBLOCK structures. 
  5998.  
  5999.  Returns     C Define 
  6000.  0 or positive Entire SHVBLOCK list was processed. The return code is the 
  6001.              composite OR of the low-order 6 bits of the shvret field from all 
  6002.              the structures. 
  6003.  -1          Invalid API entry conditions. 
  6004.  -2          Not enough storage to process a request set. Some blocks may not 
  6005.              be processed. 
  6006.  -3          The variable interface is not currently enabled. 
  6007.  127         The RxVar routine was not found by REXX. 
  6008.  
  6009.  
  6010. ΓòÉΓòÉΓòÉ 8.7. System Exit Interface ΓòÉΓòÉΓòÉ
  6011.  
  6012. This section describes how to create system exit handlers. Exit handlers are 
  6013. specified on invocation of the REXXSAA( ) API. 
  6014.  
  6015.  o Exit Handler Definition 
  6016.  o Exit Handler Registration and Manipulation 
  6017.  o Exit Handler Function Code Definitions 
  6018.  
  6019.  
  6020. ΓòÉΓòÉΓòÉ 8.7.1. Exit Handler Function Definition ΓòÉΓòÉΓòÉ
  6021.  
  6022. The following example shows an example system exit handler definition: 
  6023.  
  6024. USHORT APIENTRY extfunc_sample (
  6025.          USHORT func,            /* exit function code               */
  6026.          USHORT subfunc,         /* exit subfunction code            */
  6027.          PCHAR  parm)            /* function dependent control block */
  6028. {
  6029.  
  6030. /* exit code goes here */
  6031.  
  6032. return (0);
  6033. }
  6034.  
  6035. Function Parameters 
  6036.  
  6037.  func      The exit function code. 
  6038.  
  6039.  subfunc   The exit subfunction code. 
  6040.  
  6041.  parm      A function dependent control block structure. 
  6042.  
  6043.  Returns 
  6044.  
  6045.  0    Successful handling of the service. The parameter list has been updated 
  6046.       for that service. 
  6047.  
  6048.  1    The exit chooses not to handle the service request. The interpreter will 
  6049.       handle the request in a default manner. 
  6050.  
  6051.  -1   A fatal error occurred during the execution of the service request. REXX 
  6052.       will halt the current exec and issue an error code of 48. 
  6053.  
  6054.  
  6055. ΓòÉΓòÉΓòÉ 8.7.2. Exit Handler Registration and Manipulation ΓòÉΓòÉΓòÉ
  6056.  
  6057. System exit handler must be registered before they may be used. The following 
  6058. sections describe the C Language APIs for manipulating System Exit Handlers: 
  6059.  
  6060.  o RxExitRegister( ) 
  6061.  o RxExitQueryl( ) 
  6062.  o RxExitDrop( ) 
  6063.  
  6064.  
  6065. ΓòÉΓòÉΓòÉ 8.7.2.1. RxExitRegister( ) ΓòÉΓòÉΓòÉ
  6066.  
  6067. Registers a system exit handler in an EXE or DLL. 
  6068.  
  6069.  ΓöÇΓöÇΓöÇRxExitRegister(subcomblock)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  6070.  
  6071. For complete information on the parameters refer to RxSubcomRegister( ). 
  6072.  
  6073.  
  6074. ΓòÉΓòÉΓòÉ 8.7.2.2. RxExitQuery( ) ΓòÉΓòÉΓòÉ
  6075.  
  6076. Queries for a registered system environment name. 
  6077.  
  6078.  ΓöÇΓöÇΓöÇRxExitQuery(envname, modulename, flag, userword)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  6079.  
  6080. For complete information on the parameters refer to RxSubcomQuery( ). 
  6081.  
  6082.  
  6083. ΓòÉΓòÉΓòÉ 8.7.2.3. RxExitDrop( ) ΓòÉΓòÉΓòÉ
  6084.  
  6085. Drops a previouslr registered system environment. 
  6086.  
  6087.  ΓöÇΓöÇΓöÇRxExitDrop(envname, modulename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  6088.  
  6089. For complete information on the parameters refer to RxSubcomDrop( ). 
  6090.  
  6091.  
  6092. ΓòÉΓòÉΓòÉ 8.7.3. Exit Handler Function Code Definitions ΓòÉΓòÉΓòÉ
  6093.  
  6094. The following defines all the system exit function and subfunction codes: 
  6095.  
  6096. /* System Exit function and sub-function definitions */
  6097.  
  6098. #define RXENDLST    0                 /* End of exit list.           */
  6099. #define RXFNC    2                    /* Process external functions. */
  6100. #define    RXFNCCAL 1                 /* subcode value.              */
  6101. #define RXCMD    3                    /* Process host commands.      */
  6102. #define    RXCMDHST 1                 /* subcode value.              */
  6103. #define RXMSQ    4                    /* Manipulate queue.           */
  6104. #define    RXMSQPLL 1                 /* Pull a line from queue      */
  6105. #define    RXMSQPSH 2                 /* Place a line on queue       */
  6106. #define    RXMSQSIZ 3                 /* Return num of lines on queue*/
  6107. #define    RXMSQNAM 20                /* Set active queue name       */
  6108. #define RXSIO    5                    /* Session I/O.                */
  6109. #define    RXSIOSAY 1                 /* SAY a line to STDOUT        */
  6110. #define    RXSIOTRC 2                 /* Trace output                */
  6111. #define    RXSIOTRD 3                 /* Read from char stream       */
  6112. #define    RXSIODTR 4                 /* DEBUG read from char stream */
  6113. #define    RXSIOTLL 5                 /* Return linelength(N/A OS/2) */
  6114. #define RXHLT    7                    /* Halt processing.            */
  6115. #define    RXHLTCLR 1                 /* Clear HALT indicator        */
  6116. #define    RXHLTTST 2                 /* Test HALT indicator         */
  6117. #define RXTRC    8                    /* Test ext trace indicator.   */
  6118. #define    RXTRCTST 1                 /* subcode value.              */
  6119. #define RXINI    9                    /* Initialization processing.  */
  6120. #define    RXINIEXT 1                 /* subcode value.              */
  6121. #define RXTER   10                    /* Termination processing.     */
  6122. #define    RXTEREXT 1                 /* subcode value.              */
  6123. #define RXNOOFEXITS 11                /* 1 + largest exit number.    */
  6124.  
  6125. RXFNC 
  6126.  
  6127. Process External Functions. This function supports only one subfunction. 
  6128.  
  6129.           RXFNCCAL - Process external function. 
  6130.  
  6131.           When called: When the REXX interpreter is about to call an external 
  6132.           function. 
  6133.  
  6134.           Default action: Call the routine. 
  6135.  
  6136.           Action: Call the routine, if possible. 
  6137.  
  6138.           Continuation: If indicated by the exit function return code, raise 
  6139.           error 40, 43 or 44. Resume interpretation. 
  6140.  
  6141.           Parameters: 
  6142.  
  6143.                     /***    Subfunction RXFNCCAL - External Function Calls */
  6144.  
  6145.                     typedef struct {
  6146.                        struct {
  6147.                           unsigned rxfferr  : 1;           /* Invalid call to routine.   */
  6148.                           unsigned rxffnfnd : 1;           /* Function not found.        */
  6149.                           unsigned rxffsub  : 1;           /* Called as a subroutine if  */
  6150.                                                            /* set.  Return values are    */
  6151.                                                            /* optional for subroutines,  */
  6152.                                                            /* required for functions.    */
  6153.                           } rxfnc_flags ;
  6154.                        PUCHAR            rxfnc_name;       /* Pointer to function name.  */
  6155.                        USHORT            rxfnc_namel;      /* Length of function name.   */
  6156.                        PUCHAR            rxfnc_que;        /* Current queue name.        */
  6157.                        USHORT            rxfnc_quel;       /* Length of queue name.      */
  6158.                        USHORT            rxfnc_argc;       /* Number of args in list.    */
  6159.                        PRXSTRING         rxfnc_argv;       /* Pointer to argument list.  */
  6160.                                                            /* List mimics argv list in   */
  6161.                                                            /* REXXSAA -- array of        */
  6162.                                                            /* RXSTRINGs.                 */
  6163.                        RXSTRING          rxfnc_retc;       /* Return value.              */
  6164.                        } RXFNCCAL_PARM;
  6165.  
  6166.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6167.  details on this exit function. 
  6168.  
  6169.  RXCMD 
  6170.  
  6171.  Process Host Commands. This function supports only one subfunction. 
  6172.  
  6173.           RXCMDHST - Process host commands. 
  6174.  
  6175.           When called: When the REXX interpreter is about to process a host 
  6176.           environment command. 
  6177.  
  6178.           Default action: Pass the command to the environment. 
  6179.  
  6180.           Action: Pass the command to the environment, if possible. 
  6181.  
  6182.           Continuation: If indicated by the results, raise the ERROR or FAILURE 
  6183.           condition. Resume interpretation. 
  6184.  
  6185.           Parameters: 
  6186.  
  6187.                     /***    Subfunction RXCMDHST -- Process Host Commands     */
  6188.  
  6189.                     typedef struct {
  6190.                        struct {                            /* Condition flags            */
  6191.                           unsigned rxfcfail : 1;           /* Command failed.  Trap with */
  6192.                                                            /* CALL or SIGNAL on FAILURE. */
  6193.                           unsigned rxfcerr  : 1;           /* Command ERROR occurred.    */
  6194.                                                            /* Trap with CALL or SIGNAL on*/
  6195.                                                            /* ERROR.                     */
  6196.                           } rxcmd_flags;
  6197.                        PUCHAR            rxcmd_address;    /* Pointer to address name.   */
  6198.                        USHORT            rxcmd_addressl;   /* Length of address name.    */
  6199.                        PUCHAR            rxcmd_dll;        /* dll name for command.      */
  6200.                        USHORT            rxcmd_dll_len;    /* Length of dll name.  0 ==> */
  6201.                                                            /* .EXE file.                 */
  6202.                        RXSTRING          rxcmd_command;    /* The command string.        */
  6203.                        RXSTRING          rxcmd_retc;       /* Pointer to return code     */
  6204.                                                            /* buffer.  User allocated.   */
  6205.                        } RXCMDHST_PARM;
  6206.  
  6207.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6208.  details on this exit function. 
  6209.  
  6210.  RXMSQ 
  6211.  
  6212.  Manipulate queue. This function supports four subfunctions. 
  6213.  
  6214.           RXMSQPLL - Pull a line from the queue. 
  6215.  
  6216.           When called: Used in interpret the PULL statement. 
  6217.  
  6218.           Default action: Pull from the current default queue. 
  6219.  
  6220.           Action: Provide a result line. 
  6221.  
  6222.           Continuation: Resume interpretation using the result. 
  6223.  
  6224.           Parameters: 
  6225.  
  6226.                     /***     Subfunction RXMSQPLL -- Pull Entry from Queue */
  6227.  
  6228.                     typedef struct {
  6229.                        RXSTRING          rxmsq_retc;       /* Pointer to dequeued entry  */
  6230.                                                            /* buffer.  User allocated.   */
  6231.                        } RXMSQPLL_PARM;
  6232.  
  6233.           RXMSQPSH - Push a line on the queue. 
  6234.  
  6235.           When called: Used in interpret the PUSH and QUEUE statements. 
  6236.  
  6237.           Default action: Push to the current default queue. 
  6238.  
  6239.           Action: Push the value on some queue where RXMSQPLL can subsequently 
  6240.           fetch it. 
  6241.  
  6242.           Continuation: Resume interpretation. 
  6243.  
  6244.           Parameters: 
  6245.  
  6246.                     /***    Subfunction RXMSQPSH -- Push Entry on Queue */
  6247.  
  6248.                     typedef struct {
  6249.                        struct {                            /* Operation flag             */
  6250.                           unsigned rxfmlifo : 1;           /* Stack entry LIFO if set,   */
  6251.                                                            /* FIFO if reset.             */
  6252.                           } rxmsq_flags;
  6253.                        RXSTRING          rxmsq_value;      /* The entry to be pushed.    */
  6254.                        } RXMSQPSH_PARM;
  6255.  
  6256.           RXMSQSIZ - Return number of lines in the queue. 
  6257.  
  6258.           When called: Used in interpret the QUEUED builtin function. 
  6259.  
  6260.           Default action: Find the size of the default queue. 
  6261.  
  6262.           Action: Return the size. 
  6263.  
  6264.           Continuation: Return the size and resume interpretation. 
  6265.  
  6266.           Parameters: 
  6267.  
  6268.                     /***    Subfunction RXMSQSIZ -- Return the Current Queue Size */
  6269.  
  6270.                     typedef struct {
  6271.                        ULONG             rxmsq_size;       /* Number of Lines in Queue   */
  6272.                        } RXMSQSIZ_PARM;
  6273.  
  6274.           RXMSQNAM - Set the name of the active queue. 
  6275.  
  6276.           When called: Used in interpret the RXQUEUE("SET", newname) builtin 
  6277.           function. 
  6278.  
  6279.           Default action: Chane the default queue to the specified name. 
  6280.  
  6281.           Action: Change the default queue. 
  6282.  
  6283.           Continuation: Resume interpretation. 
  6284.  
  6285.           Parameters: 
  6286.  
  6287.                     /***    Subfunction RXMXQNAM -- Set Current Queue Name */
  6288.  
  6289.                     typedef struct {
  6290.                        SEL               rxmsq_name;       /* Selector containing ASCIIZ */
  6291.                                                            /* queue name.  Change length */
  6292.                                                            /* with DosReallocSeg if      */
  6293.                                                            /* required.                  */
  6294.                        } RXMSQNAM_PARM;
  6295.  
  6296.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6297.  details on this exit function. 
  6298.  
  6299.  RXSIO 
  6300.  
  6301.  Session I/O.  This function supports four subfunctions. 
  6302.  
  6303.           RXSIOSAY - Output result of the SAY statement. 
  6304.  
  6305.           When called: Used in interpret the SAY statement. 
  6306.  
  6307.           Default action: Write to the session standard output device. 
  6308.  
  6309.           Action: Send the line. 
  6310.  
  6311.           Continuation: Resume interpretation. 
  6312.  
  6313.           Parameters: 
  6314.  
  6315.                     /***    Subfunction RXSIOSAY -- Perform SAY Clause */
  6316.  
  6317.                     typedef struct {
  6318.                        RXSTRING          rxsio_string;     /* String to display.         */
  6319.                        } RXSIOSAY_PARM;
  6320.  
  6321.           RXSIOTRC - TRACE output processing. 
  6322.  
  6323.           When called: To output the result of each line of trace processing. 
  6324.  
  6325.           Default action: Write to the session standard error device. 
  6326.  
  6327.           Action: Send the line. 
  6328.  
  6329.           Continuation: Resume interpretation. 
  6330.  
  6331.           Parameters: 
  6332.  
  6333.                     /***    Subfunction RXSIOTRC -- Write Trace Output */
  6334.  
  6335.                     typedef struct {
  6336.                       RXSTRING           rxsio_string;     /* Trace line to display.     */
  6337.                       } RXSIOTRC_PARM;
  6338.  
  6339.           RXSIOTRD - Read from the STDIN stream. 
  6340.  
  6341.           When called: Read from the standard input stream. Note that if PULL 
  6342.           may not call this function if its request can be satisfied by 
  6343.           something from the stack. 
  6344.  
  6345.           Default action: Read from the default input device. 
  6346.  
  6347.           Action: Read the line. 
  6348.  
  6349.           Continuation: Resume interpretation. 
  6350.  
  6351.           Parameters: 
  6352.  
  6353.                     /***    Subfunction RXSIOTRD -- Read Input from the Terminal */
  6354.  
  6355.                     typedef struct {
  6356.                        RXSTRING          rxsiotrd_retc;    /* RXSTRING for output.  Note:*/
  6357.                                                            /* user allocates output      */
  6358.                                                            /* buffer with DosAllocSeg()  */
  6359.                                                            /* or DosAllocHuge().         */
  6360.                        } RXSIOTRD_PARM;
  6361.  
  6362.           RXSIODTR - Debug read. 
  6363.  
  6364.           When called: Read from the standard input stream for interactive 
  6365.           debug. The stack is not used by the subfunction to satisfy requests. 
  6366.  
  6367.           Default action: Read from the default input device. 
  6368.  
  6369.           Action: Read the line. 
  6370.  
  6371.           Continuation: Resume interpretation. 
  6372.  
  6373.           Parameters: 
  6374.  
  6375.                     /***    Subfunction RXSIODTR -- Read Debug Input from the Terminal */
  6376.  
  6377.                     typedef struct {
  6378.                        RXSTRING          rxsiodtr_retc;    /* RXSTRING for output.  Note:*/
  6379.                                                            /* user allocates output      */
  6380.                                                            /* buffer with DosAllocSeg()  */
  6381.                                                            /* or DosAllocHuge().         */
  6382.                        } RXSIODTR_PARM;
  6383.  
  6384.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6385.  details on this exit function. 
  6386.  
  6387.  RXHLT 
  6388.  
  6389.  Halt processing. This function supports two subfunctions. 
  6390.  
  6391.           RXHLTCLR - Clear Halt indicator. This function has no inputs or 
  6392.           outputs. 
  6393.  
  6394.           When called: After raising the HALT and before the next (potential) 
  6395.           call of RXHLTTST . 
  6396.  
  6397.           Default action: Resets the polling of external interrupts. 
  6398.  
  6399.           Action: Rest the polling of the external interrupt. 
  6400.  
  6401.           Continuation: Continue interpretation. 
  6402.  
  6403.           Parameters: None. 
  6404.  
  6405.           RXHLTTST - Test Halt indicator. 
  6406.  
  6407.           When called: The interpreter makes sufficient calls to poll whether 
  6408.           an external attempt has been made to interrupt execution. 
  6409.  
  6410.           Default action: Polls for external interrupts. 
  6411.  
  6412.           Action: Set the result to indicate whether an external interrupt has 
  6413.           occurred. 
  6414.  
  6415.           Continuation: Raise HALT condition if an interrupt has occurred. 
  6416.           Continue interpretation. 
  6417.  
  6418.           Parameters: 
  6419.  
  6420.                     /***    Subfunction RXHSTTST -- Test for HALT Condition */
  6421.  
  6422.                     typedef struct {
  6423.                        struct {                            /* Halt flag                  */
  6424.                           unsigned rxfhhalt : 1;           /* Set if HALT occurred.      */
  6425.                           } rxhlt_flags;
  6426.                        } RXHLTTST_PARM;
  6427.  
  6428.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6429.  details on this exit function. 
  6430.  
  6431.  RXTRC 
  6432.  
  6433.  Test external trace indicator. This function supports one subfunction. 
  6434.  
  6435.           RXTRCTST - Test external trace indicator. 
  6436.  
  6437.           When called: Used to test the trace indicator by the interpreter from 
  6438.           an external program request. 
  6439.  
  6440.           Default action: Returns the trace indicator. 
  6441.  
  6442.           Action: Returns the trace indicator. 
  6443.  
  6444.           Continuation: Continue interpretation, with or without tracing. 
  6445.  
  6446.           Parameters: 
  6447.  
  6448.                     /***    Subfunction RXTRCTST -- Test for TRACE Condition */
  6449.  
  6450.                     typedef struct {
  6451.                        struct {                            /* Trace flags                */
  6452.                           unsigned rxftrace : 1;           /* Set to run external trace. */
  6453.                           } rxtrc_flags;
  6454.                        } RXTRCTST_PARM;
  6455.  
  6456.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6457.  details on this exit function. 
  6458.  
  6459.  RXINI 
  6460.  
  6461.  Initialization processing. This function supports one subfunction. 
  6462.  
  6463.           RXINIEXT - Initialization processing. 
  6464.  
  6465.           When called: Just prior to beginning interpretation. 
  6466.  
  6467.           Default action: None. 
  6468.  
  6469.           Action: Initialize all other system exits. 
  6470.  
  6471.           Continuation: Resume interpretation. 
  6472.  
  6473.           Parameters: None. 
  6474.  
  6475.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6476.  details on this exit function. 
  6477.  
  6478.  RXTER 
  6479.  
  6480.  Termination processing. This function supports one subfunction. 
  6481.  
  6482.           RXTEREXT - Termination processing. 
  6483.  
  6484.           When called: Just prior to returning control to the calling process. 
  6485.  
  6486.           Default action: None. 
  6487.  
  6488.           Action: Terminate all other system exits. 
  6489.  
  6490.           Continuation: Resume, leaving interpreter. 
  6491.  
  6492.           Parameters: None. 
  6493.  
  6494.  Refer to the IBM Procedures Language 2/REXX Reference manual for further 
  6495.  details on this exit function. 
  6496.  
  6497.  
  6498. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6499.  
  6500. BookMark 
  6501.  
  6502. When you place a bookmark on a topic, it is added to a list of bookmarks you 
  6503. have previously set. You can view the list, and you can remove one or all 
  6504. bookmarks from the list. If you have not set any bookmarks, the list is empty. 
  6505.  
  6506. To set a bookmark, do the following: 
  6507.  
  6508.   1. Select a topic from the Contents. 
  6509.  
  6510.   2. When that topic appears, choose the Bookmark option from the Services 
  6511.      pull-down. 
  6512.  
  6513.   3. If you want to change the name used for the bookmark, type the new name in 
  6514.      the field. 
  6515.  
  6516.   4. Click on the Place radio button (or press the Up or Down Arrow key to 
  6517.      select it). 
  6518.  
  6519.   5. Click on OK (or select it and press Enter). The bookmark is then added to 
  6520.      the bookmark list. 
  6521.  
  6522.  
  6523. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6524.  
  6525. Search 
  6526.  
  6527. You can specify a word or phrase to be searched. You can also limit the search 
  6528. to a set of topics by first marking the topics on the Contentes list. 
  6529.  
  6530. To search for a word or phrase in all topics, do the following: 
  6531.  
  6532.   1. Choose the Search option from the Services pull-down. 
  6533.  
  6534.   2. Type the word or words to be searched. 
  6535.  
  6536.   3. Click on All sections (or press the Up or Down Arrow keys to select it). 
  6537.  
  6538.   4. Click on Search (or select it and press Enter) to begin the search. 
  6539.  
  6540.   5. The list of topics where the word or phrase appears is displayed. If only 
  6541.      one topic contains the word or phrase, a window containing that topic 
  6542.      appears. 
  6543.  
  6544.  
  6545. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6546.  
  6547. Print 
  6548.  
  6549. You can print one or more topics. You can also print a set of topics by first 
  6550. marking the topics on the Contents list. 
  6551.  
  6552. To print the document Contents list, do the following: 
  6553.  
  6554.   1. Choose Print from the Services pull-down. 
  6555.  
  6556.   2. Click on Contents (or press the Up or Down Arrow to select it). 
  6557.  
  6558.   3. Click on Print (or select it and press Enter). 
  6559.  
  6560.   4. The Contents list is printed on your printer. 
  6561.  
  6562.  
  6563. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6564.  
  6565. Copy 
  6566.  
  6567. You can copy a topic you are viewing into a temporary file named TEXT.TMP. You 
  6568. can later edit that file by using the editor of your choice. 
  6569.  
  6570. To copy a topic, do the following: 
  6571.  
  6572.   1. Expand the Contents list and select a topic. 
  6573.  
  6574.   2. When a topic appears, choose Copy to file from the Services pull-down. 
  6575.  
  6576.   3. The system puts the text pertaining to that topic in the temporary 
  6577.      TEXT.TMP file. 
  6578.  
  6579.  For information on one of the other choices in the Services pull-down, 
  6580.  highlight the choice and press the F1 key. 
  6581.  
  6582.  
  6583. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6584.  
  6585. Options 
  6586.  
  6587. You can control the appearance of the Contents list. 
  6588.  
  6589. To expand the Contents and show all levels for all topics, choose Expand all 
  6590. from the Options pull-down. You can also press the Ctrl and * keys together. 
  6591.  
  6592. For information on one of the other choices in the Services pull-down, 
  6593. highlight the choice and press the F1 key. 
  6594.  
  6595.  
  6596. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6597.  
  6598.  environment 
  6599.            a literal string or a single symbol denoting the "host" command 
  6600.            environment or particular program to which a command will be 
  6601.            directed. 
  6602.  
  6603.  In all operating systems it is possible for users and programs to define new 
  6604.  "environments". The most commonly used ones are shown below: 
  6605.  
  6606.            TSO MVS LINK ATTACH ISPEXEC ISREDIT 
  6607.            CMS COMMAND ISPEXEC ISREDIT 
  6608.            CMD ISPCIR 
  6609.  
  6610.  
  6611. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6612.  
  6613.  template 
  6614.            a list of symbols that are separated by blanks and/or patterns. 
  6615.  
  6616.  More formally: 
  6617.  
  6618.        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  6619.        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  6620.                                    Γöé
  6621.    ΓöÇΓöÇΓö┤ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÇ
  6622.           Γö£ΓöÇΓöÇvariableΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  6623.           Γö£ΓöÇΓöÇ(variable)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  6624.           Γö£ΓöÇΓöÇliteralstringΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  6625.           Γö£ΓöÇΓöÇ . ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  6626.           ΓööΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇwholenumberΓöÇΓöÇΓöÿ
  6627.              Γö£ΓöÇ + ΓöÇΓöñ
  6628.              ΓööΓöÇ - ΓöÇΓöÿ
  6629.  
  6630.  variable          name of a variable to receive part of the parsed string 
  6631.  
  6632.  (variable)        name of a variable whose value is used to match in the 
  6633.                    parsed string 
  6634.  
  6635.  literalstring     a character, hexadecimal, or binary (OS/2 only) string 
  6636.                    literal used to match in the parsed string 
  6637.  
  6638.  . (period)        a placeholder; just like matching to a dummy variable 
  6639.  
  6640.  wholenumber       move match position in parsed string to specified column 
  6641.  
  6642.  + wholenumber     move match position in parsed string ahead by specified 
  6643.                    number of columns 
  6644.  
  6645.  - wholenumber     move match position in parsed string back by specified 
  6646.                    number of columns 
  6647.  
  6648.  , (comma)         used to separate multiple patterns; available only in the 
  6649.                    ARG and PARSE ARG statements 
  6650.  
  6651.  
  6652. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6653.  
  6654.  name 
  6655.            a symbol or literal string that identifies a routine. This must be a 
  6656.            valid symbol. 
  6657.  
  6658.  
  6659. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6660.  
  6661.  trapname 
  6662.            a symbol or literal string that identifies a routine to be called 
  6663.            when the associated condition is trapped. 
  6664.  
  6665.  
  6666. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6667.  
  6668. Symbol 
  6669.  
  6670. A symbol can be a number, REXX keyword, or a name used for variables, labels, 
  6671. functions, etc.  Names can't begin with digits or a period. All implementations 
  6672. allow names to include: a-z A_Z 0-9 underscore(_) exclamation(!) and 
  6673. question(?).  The period can also be used, but it has a special meaning 
  6674. concerned with compound symbols. Symbols are not case sensitive, i.e., 
  6675. lower-case letters in symbols are translated to upper-case. The VM and TSO 
  6676. environments also support the characters @#$╨½ in symbols.  Avoid them for the 
  6677. sake of portability. 
  6678.  
  6679.  
  6680. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6681.  
  6682. Name expression 
  6683.  
  6684. An variable whose value is a list of variable names. This is a form of 
  6685. indirection. 
  6686.  
  6687.  
  6688. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6689.  
  6690. Labelname 
  6691.  
  6692. A labelname must be a valid REXX symbol and must reference a known internal or 
  6693. external procedure. 
  6694.  
  6695.  
  6696. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6697.  
  6698. Variable 
  6699.  
  6700. The name of a legal REXX variable.