home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / VSCPPv4.zip / VACPP / IBMCPP / HELP / REXXAPI.INF (.txt) < prev    next >
OS/2 Help File  |  1995-03-10  |  117KB  |  4,457 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Notices ΓòÉΓòÉΓòÉ
  3.  
  4. First Edition (December 1991) 
  5.  
  6. The following paragraph does not apply to the United Kingdom or any country 
  7. where such provisions are inconsistent with local law:  INTERNATIONAL BUSINESS 
  8. MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY 
  9. KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
  10. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states 
  11. do not allow disclaimer of express or implied warranties in certain 
  12. transactions, therefore, this statement may not apply to you. 
  13.  
  14. This publication could include technical inaccuracies or typographical errors. 
  15. Changes are periodically made to the information herein; these changes will be 
  16. incorporated in new editions of the publication. IBM may make improvements 
  17. and/or changes in the product(s) and/or the program(s) described in this 
  18. publication at any time. 
  19.  
  20. It is possible that this publication may contain reference to, or information 
  21. about, IBM products (machines and programs), programming, or services that are 
  22. not announced in your country.  Such references or information must not be 
  23. construed to mean that IBM intends to announce such IBM products, programming, 
  24. or services in your country. 
  25.  
  26. Requests for technical information about IBM products should be made to your 
  27. IBM authorized reseller or IBM marketing representative. 
  28.  
  29.  
  30. ΓòÉΓòÉΓòÉ 1.1. Copyright Notices ΓòÉΓòÉΓòÉ
  31.  
  32. COPYRIGHT LICENSE: This publication contains printed sample application 
  33. programs in source language, which illustrate OS/2 programming techniques. You 
  34. may copy, modify, and distribute these sample programs in any form without 
  35. payment to IBM, for the purposes of developing, using, marketing or 
  36. distributing application programs conforming to the OS/2 application 
  37. programming interface. 
  38.  
  39. Each copy of any portion of these sample programs or any derivative work, which 
  40. is distributed to others, must include a copyright notice as follows: "(C) 
  41. (your company name) (year).  All rights reserved." 
  42.  
  43. (C) Copyright International Business Machines Corporation 1994. All rights 
  44. reserved. 
  45. Note to U.S. Government Users - Documentation related to restricted rights - 
  46. Use, duplication or disclosure is subject to restrictions set forth in GSA ADP 
  47. Schedule Contract with IBM Corp. 
  48.  
  49.  
  50. ΓòÉΓòÉΓòÉ 1.2. Disclaimers ΓòÉΓòÉΓòÉ
  51.  
  52. References in this publication to IBM products, programs, or services do not 
  53. imply that IBM intends to make these available in all countries in which IBM 
  54. operates. Any reference to an IBM product, program or service is not intended 
  55. to state or imply that only IBM's product, program, or service may be used. Any 
  56. functionally equivalent product, program, or service that does not infringe any 
  57. of IBM's intellectual property rights or other legally protectable rights may 
  58. be used instead of the IBM product, program, or service. Evaluation and 
  59. verification of operation in conjunction with other products, programs, or 
  60. services, except those expressly designated by IBM, are the user's 
  61. responsibility. 
  62.  
  63. IBM may have patents or pending patent applications covering subject matter in 
  64. this document. The furnishing of this document does not give you any license to 
  65. these patents. You can send license inquiries, in writing, to the IBM Director 
  66. of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. 
  67.  
  68.  
  69. ΓòÉΓòÉΓòÉ 1.3. Trademarks ΓòÉΓòÉΓòÉ
  70.  
  71. The following terms, denoted by an asterisk (*) in this publication, are 
  72. trademarks of the IBM Corporation in the United States or other countries: 
  73.  
  74. IBM
  75. PM
  76. Presentation Manager
  77. OS/2
  78. SAA
  79. System Application Architecture
  80. Workplace Shell
  81.  
  82. The following terms, denoted by a double asterisk (**) in this publication, are 
  83. trademarks of other companies as follows. Other trademarks are trademarks of 
  84. their respective companies. 
  85.  
  86.  C++                 AT&T, Inc. 
  87.  Helvetica           Linotype 
  88.  
  89.  
  90. ΓòÉΓòÉΓòÉ 2. How to Use the Program Reference ΓòÉΓòÉΓòÉ
  91.  
  92. The REXX Program Reference is a detailed technical reference for application 
  93. programmers.  It gives reference information and code examples to enable you to 
  94. write source code using REXX Program functions. 
  95.  
  96. Before you begin to use this information, it would be helpful to understand how 
  97. you can: 
  98.  
  99.    o  Expand the Contents to see all available topics 
  100.    o  Obtain additional information for a highlighted word or phrase 
  101.    o  Use action bar choices 
  102.    o  Use the programming information. 
  103.  
  104.  How to Use the Contents 
  105.  
  106.  When the Contents window first appears, some topics have a plus (+) sign 
  107.  beside them. The plus sign indicates that additional topics are available. 
  108.  
  109.  To expand the Contents if you are using a mouse, click on the plus sign.  If 
  110.  you are using the keyboard, use the Up or Down Arrow key to highlight the 
  111.  topic, and press the plus (+) key. For example, File System has a plus sign 
  112.  beside it. To see additional topics for that heading, click on the plus sign 
  113.  or highlight that topic and press the plus (+) key. 
  114.  
  115.  To view a topic, double-click on the topic (or press the Up or Down Arrow key 
  116.  to highlight the topic, and then press the Enter key). 
  117.  
  118.  How to Obtain Additional Information 
  119.  
  120.  After you select a topic, the information for that topic appears in a window. 
  121.  Highlighted words or phrases indicate that additional information is 
  122.  available. You will notice that certain words and phrases are highlighted in 
  123.  green letters, or in white letters on a black background.  These are called 
  124.  hypertext terms. If you are using a mouse, double-click on the highlighted 
  125.  word.  If you are using a keyboard, press the Tab key to move to the 
  126.  highlighted word, and then press the Enter key.  Additional information then 
  127.  appears in a window. 
  128.  
  129.  How to Use Action Bar Choices 
  130.  
  131.  Several choices are available for managing information presented in the OS/2* 
  132.  2.0 Control Program Reference.  There are three pull-down menus on the action 
  133.  bar:  the Services menu, the Options menu, and the Help menu. 
  134.  
  135.  The actions that are selectable from the Services menu operate on the active 
  136.  window currently displayed on the screen. These actions include the following: 
  137.  
  138.  Bookmark 
  139.     Allows you to set a placeholder so you can retrieve information of interest 
  140.     to you. 
  141.  
  142.     When you place a bookmark on a topic, it is added to a list of bookmarks 
  143.     you have previously set.  You can view the list, and you can remove one or 
  144.     all bookmarks from the list.  If you have not set any bookmarks, the list 
  145.     is empty. 
  146.  
  147.     To set a bookmark, do the following: 
  148.  
  149.    1. Select a topic from the Contents. 
  150.  
  151.    2. When that topic appears, choose the Bookmark option from the Services 
  152.       pull-down. 
  153.  
  154.    3. If you want to change the name used for the bookmark, type the new name 
  155.       in the field. 
  156.  
  157.    4. Click on the Place radio button (or press the Up or Down Arrow key to 
  158.       select it). 
  159.  
  160.    5. Click on OK (or select it and press Enter). The bookmark is then added to 
  161.       the bookmark list. 
  162.  
  163.  Search 
  164.     Allows you to find occurrences of a word or phrase in the current topic, 
  165.     selected topics, or all topics. 
  166.  
  167.     You can specify a word or phrase to be searched.  You can also limit the 
  168.     search to a set of topics by first marking the topics in the Contents list. 
  169.  
  170.     To search for a word or phrase in all topics, do the following: 
  171.  
  172.    1. Choose the Search option from the Services pull-down. 
  173.  
  174.    2. Type the word or words to be searched for. 
  175.  
  176.    3. Click on All sections (or press the Up or Down Arrow keys to select it). 
  177.  
  178.    4. Click on Search (or select it and press Enter) to begin the search. 
  179.  
  180.    5. The list of topics where the word or phrase appears is displayed. 
  181.  
  182.  Print 
  183.     Allows you to print one or more topics.  You can also print a set of topics 
  184.     by first marking the topics in the Contents list. 
  185.  
  186.     To print the document Contents list, do the following: 
  187.  
  188.    1. Choose Print from the Services pull-down. 
  189.  
  190.    2. Click on Contents (or press the Up or Down Arrow key to select it). 
  191.  
  192.    3. Click on Print (or select it and press Enter). 
  193.  
  194.    4. The Contents list is printed on your printer. 
  195.  
  196.  Copy 
  197.     Allows you to copy a topic that you are viewing to the System Clipboard or 
  198.     to a file that you can edit. You will find this particularly useful for 
  199.     copying syntax definitions and program samples into the application that 
  200.     you are developing. 
  201.  
  202.     You can copy a topic that you are viewing in two ways: 
  203.  
  204.    o  Copy copies the topic that you are viewing into the System Clipboard.  If 
  205.       you are using a Presentation Manager* (PM) editor (for example, the 
  206.       System Editor) that copies or cuts (or both) to the System Clipboard, and 
  207.       pastes to the System Clipboard, you can easily add the copied information 
  208.       to your program source module. 
  209.  
  210.    o  Copy to file copies the topic that you are viewing into a temporary file 
  211.       named TEXT.TMP.  You can later edit that file by using any editor.  You 
  212.       will find TEXT.TMP in the directory where your viewable document resides. 
  213.  
  214.       To copy a topic, do the following: 
  215.  
  216.         1. Expand the Contents list and select a topic. 
  217.  
  218.         2. When the topic appears, choose Copy to file from the Services 
  219.            pull-down. 
  220.  
  221.         3. The system puts the text pertaining to that topic into the temporary 
  222.            file named TEXT.TMP. 
  223.  
  224.     For information on one of the other choices in the Services pull-down, 
  225.     highlight the choice and press the F1 key. 
  226.  
  227.  The actions that are selectable from the Options menu allow you to change the 
  228.  way your Contents list is displayed. To expand the Contents and show all 
  229.  levels for all topics, choose Expand all from the Options pull-down. You can 
  230.  also press the Ctrl and * keys together. For information on one of the other 
  231.  choices in the Options pull-down, highlight the choice and press the F1 key. 
  232.  
  233.  The actions that are selectable from the Help menu allow you to select 
  234.  different types of help information.  You can also press the F1 key for help 
  235.  information about the Information Presentation Facility (IPF). 
  236.  
  237.  How to Use the Programming Information 
  238.  
  239.  The REXX Program Reference consists of reference information that provides a 
  240.  detailed description of each REXX function. 
  241.  
  242.  REXX Program programming information is presented by component, such as 
  243.  Subcommmand Interface Functions, System Exit Functions and Macrospace 
  244.  Functions, for example: 
  245.  
  246.        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  247.        Γöé            Contents                     Γöé
  248.        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  249.        Γöé                                         Γöé
  250.        Γöé  + Subcommand Interface Functions       Γöé
  251.        Γöé  + System Exit Functions                Γöé
  252.        Γöé  + Macrospace Functions                 Γöé
  253.        Γöé                                         Γöé
  254.        ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  255.  
  256.  By clicking on the plus sign beside 'Subcommand Interface Functions', you see 
  257.  an alphabetic list of the REXX functions for the subcommand interface. 
  258.  Selecting a function takes you directly into the reference information for 
  259.  that function. 
  260.  
  261.  Units of reference information are presented in selectable multiple windows or 
  262.  viewports. A viewport is a Presentation Manager window that can be sized, 
  263.  moved, minimized, maximized, or closed.  By selecting a unit (in this case, an 
  264.  entry on the Contents list), you will see two windows displayed: 
  265.  
  266.       ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  267.       Γöé Unit Title    Γöé   Selection Title           Γöé
  268.       Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  269.       Γöé Select one:   Γöé                             Γöé
  270.       Γöé    .          Γöé                             Γöé
  271.       Γöé    .          Γöé                             Γöé
  272.       Γöé    .          Γöé                             Γöé
  273.       Γöé Return Values Γöé                             Γöé
  274.       Γöé Errors        Γöé                             Γöé
  275.       Γöé Notes         Γöé                             Γöé
  276.       Γöé               Γöé                             Γöé
  277.       Γöé               Γöé                             Γöé
  278.       ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  279.  
  280.  The window on the left is the primary window.  It contains a list of items 
  281.  that are always available to you.  The window on the right is the secondary 
  282.  window.  It contains a 'snapshot' of the unit information. For reference units 
  283.  (that is, function descriptions), this window contains the Call Syntax. 
  284.  
  285.  All of the information needed to understand a reference unit (or topic) is 
  286.  readily available to you through the primary window. The information is 
  287.  divided into discrete information groups, and only the appropriate information 
  288.  group appears for the topic that you are viewing. 
  289.  
  290.  The information groups for a reference unit (that is, a function description) 
  291.  can include the following: 
  292.  
  293.    o  Call Syntax 
  294.    o  Uses 
  295.    o  Parameters 
  296.    o  Data Structures 
  297.    o  Return Values 
  298.    o  Errors 
  299.    o  Notes 
  300.    o  Related Functions 
  301.    o  Examples 
  302.    o  Sample Programs 
  303.  
  304.  This list may vary.  Uses, Data Structures, Notes, Related Functions, 
  305.  Examples, and Sample Programs may be omitted when they do not apply. In other 
  306.  instances, information may be added when appropriate. For example, when 
  307.  viewing the RexxStart function, you will see the Data Structures topic and the 
  308.  Examples topic in the primary window. 
  309.  
  310.  Information groups are displayed in separate viewports that are stacked in a 
  311.  third window location that overlaps the secondary window. By selecting an item 
  312.  (information group) in the primary window, the item is displayed in the third 
  313.  window location: 
  314.  
  315.     ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  316.     Γöé Unit Title   Γöé   Selection TiΓöé   Data Types  Γöé
  317.     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  318.     Γöé Select one:  Γöé               Γöé  BOOL         Γöé
  319.     Γöé              Γöé               Γöé  BYTE         Γöé
  320.     Γöé    .         Γöé               Γöé  CHAR         Γöé
  321.     Γöé    .         Γöé               Γöé    .          Γöé
  322.     Γöé    .         Γöé               Γöé    .          Γöé
  323.     Γöé Data Types   Γöé               Γöé    .          Γöé
  324.     Γöé Errors       Γöé               Γöé               Γöé
  325.     Γöé              Γöé               Γöé               Γöé
  326.     Γöé              Γöé               Γöé               Γöé
  327.     Γöé              Γöé               Γöé               Γöé
  328.     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  329.  
  330.  By selecting successive items from the primary window, additional windows are 
  331.  displayed on top of the previous windows displayed in the third window 
  332.  location.  For example, in a function description, Parameters and Return 
  333.  Values are items listed in the primary window.  When selected, they appear one 
  334.  on top of the other in the third window location. Because of this, you may 
  335.  move the first selected (topmost) window to the left before selecting the next 
  336.  item. This allows simultaneous display of two related pieces of information 
  337.  from the 'stack' of windows in the third window location: 
  338.  
  339.     ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  340.     Γöé Unit Title    Γöé  Parameters   Γöé Return Values Γöé
  341.     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  342.     Γöé Select one:   Γöé               Γöé  RXSUBCOM_NOERΓöé
  343.     Γöé    .          Γöé               Γöé  RXSUBCOM_NOTRΓöé
  344.     Γöé    .          Γöé               Γöé  RXSUBCOM_NOEMΓöé
  345.     Γöé    .          Γöé               Γöé  RXSUBCOM_BADTΓöé
  346.     Γöé Parameters    Γöé               Γöé    .          Γöé
  347.     Γöé Return Values Γöé               Γöé    .          Γöé
  348.     Γöé Errors        Γöé               Γöé    .          Γöé
  349.     Γöé Examples      Γöé               Γöé               Γöé
  350.     Γöé               Γöé               Γöé               Γöé
  351.     Γöé               Γöé               Γöé               Γöé
  352.     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  353.  
  354.  Each window can be individually closed from its system menu.  All windows are 
  355.  closed when you close the primary window. 
  356.  
  357.  Some secondary windows may have the appearance of a split screen. For example, 
  358.  an illustration may appear in the left half of the window, and scrollable, 
  359.  explanatory information may appear in the right half of the window.  Because 
  360.  illustrations may not necessarily fit into the small window size on your 
  361.  screen, you may maximize the secondary window for better readability. 
  362.  
  363.  
  364. ΓòÉΓòÉΓòÉ <hidden> IBM Trademark ΓòÉΓòÉΓòÉ
  365.  
  366. Trademark of the IBM Corporation. 
  367.  
  368.  
  369. ΓòÉΓòÉΓòÉ 3. REXX Functions ΓòÉΓòÉΓòÉ
  370.  
  371. The following functions can interface with the REXX interpreter: 
  372.  
  373.       RexxAddMacro 
  374.       RexxClearMacroSpace 
  375.       RexxDeregisterExit 
  376.       RexxDeregisterFunction 
  377.       RexxDeregisterSubcom 
  378.       RexxDropMacro 
  379.       RexxLoadMacroSpace 
  380.       RexxQueryExit 
  381.       RexxQueryFunction 
  382.       RexxQueryMacro 
  383.       RexxQuerySubcom 
  384.       RexxRegisterExitExe 
  385.       RexxRegisterExitDll 
  386.       RexxRegisterFunctionExe 
  387.       RexxRegisterFunctionDll 
  388.       RexxRegisterSubcomExe 
  389.       RexxRegisterSubcomDll 
  390.       RexxReorderMacro 
  391.       RexxResetTrace 
  392.       RexxSaveMacroSpace 
  393.       RexxSetHalt 
  394.       RexxSetTrace 
  395.       RexxStart 
  396.       RexxVariablePool 
  397.  
  398.  
  399. ΓòÉΓòÉΓòÉ 4. Using REXX Interfaces ΓòÉΓòÉΓòÉ
  400.  
  401. This chapter is addressed mainly to professional systems and application 
  402. programmers. It describes: 
  403.  
  404.    o  RXSTRINGs 
  405.    o  Invoking the REXX Interpreter 
  406.    o  Subcommand Handlers 
  407.    o  External Functions 
  408.    o  System Exits 
  409.    o  Variable Pool Interface 
  410.    o  Macrospace Interface 
  411.    o  Halt and Trace Functions 
  412.  
  413.  In this chapter, the term application refers to programs written in languages 
  414.  other than REXX. The features described here allow an application to extend 
  415.  many parts of the REXX language or extend an application with REXX. This 
  416.  includes creating handlers for subcommands, external functions and system 
  417.  exits. 
  418.  
  419.  Subcommands Commands issued from a REXX program. A REXX expression is 
  420.             evaluated and the result is passed as a command to the currently 
  421.             "addressed" subcommand handler. Subcommands are used in REXX 
  422.             programs running as application macros. 
  423.  
  424.  Functions  Direct extensions of the REXX language. An application can create 
  425.             functions that extend the native REXX function set. Functions may 
  426.             be general purpose extensions or specific to an application. 
  427.  
  428.  System Exits Create programmer-defined variations of the operating system. The 
  429.             application programmer can tailor the REXX interpreter behavior by 
  430.             replacing the OS/2* operating system for REXX system requests. 
  431.  
  432.  Subcommand, function and exit handlers have similar coding, compilation and 
  433.  packaging characteristics. 
  434.  
  435.  In addition, applications can manipulate the variables in REXX programs (the 
  436.  Variable Pool Interface), and execute REXX routines directly from memory (the 
  437.  Macrospace Interface). 
  438.  
  439.  
  440. ΓòÉΓòÉΓòÉ 4.1. General Characteristics ΓòÉΓòÉΓòÉ
  441.  
  442. The basic requirements for subcommand, function and system exit handlers are: 
  443.  
  444.    o  REXX handlers must use the system linkage convention. Handler functions 
  445.       must be declared with the appropriate type definition from the REXXSAA.H 
  446.       include file: 
  447.  
  448.         -  RexxSubcomHandler 
  449.         -  RexxFunctionHandler 
  450.         -  RexxExitHandler 
  451.  
  452.    o  A REXX handler must be packaged as either: 
  453.  
  454.         -  An exported routine within a Dynamic Link Library (a dynalink or 
  455.            DLL) 
  456.         -  An entry point within an executable (EXE) module. 
  457.  
  458.    o  A handler must be registered with REXX before it can be used. REXX uses 
  459.       the registration information to locate and call the handler. For example, 
  460.       external function registration of a dynamic link library external 
  461.       function identifies both the dynamic link library and routine that 
  462.       contains the external function. Also note: 
  463.  
  464.         -  Dynamic link library handlers are global to the OS/2* operating 
  465.            system; they can be used by any REXX program. 
  466.  
  467.         -  EXE file handlers are local to the registering process; handlers 
  468.            packaged within an EXE module can only be used by a REXX program 
  469.            running in the same process as the EXE module. 
  470.  
  471.  
  472. ΓòÉΓòÉΓòÉ 5. RXSTRINGs ΓòÉΓòÉΓòÉ
  473.  
  474. Many of the REXX interfaces pass REXX character strings to and from a REXX 
  475. procedure. The RXSTRING data structure is used to describe REXX character 
  476. strings. An RXSTRING is a content-insensitive, flat model character string with 
  477. a theoretical maximum length of 4 gigabytes. The following structure defines an 
  478. RXSTRING: 
  479.  
  480.  
  481. RXSTRING Data Structure
  482.  
  483. typedef struct {
  484.    ULONG           strlength;          /*   length of string          */
  485.    PCH             strptr;             /*   pointer to string         */
  486. } RXSTRING;
  487.  
  488. typedef RXSTRING *PRXSTRING;           /* pointer to an RXSTRING       */
  489.  
  490.    1. The REXXSAA.H include file contains a number of convenient macros for 
  491.       setting and testing RXSTRING values. 
  492.  
  493.    2. An RXSTRING can have a value (including the null string, "") or it can be 
  494.       empty. 
  495.  
  496.         o  If an RXSTRING has a value, the strptr field will be non-NULL. The 
  497.            RXSTRING macro RXVALIDSTRING(string) will return TRUE. 
  498.  
  499.         o  If an RXSTRING is the REXX null string (""), the strptr field will 
  500.            be non-NULL and the strlength field will be 0. The RXSTRING macro 
  501.            RXZEROLENSTRING(string) will return TRUE. 
  502.  
  503.         o  If an RXSTRING is empty, the field strptr will be NULL. The RXSTRING 
  504.            macro RXNULLSTRING(string) will return TRUE. 
  505.  
  506.    3. When the REXX interpreter passes an RXSTRING to a subcommand handler, 
  507.       external function, or exit handler, the interpreter adds a null character 
  508.       (hexadecimal zero) at the end of the RXSTRING data. The C string library 
  509.       functions can be used on these strings. However, the RXSTRING data can 
  510.       also contain null characters. There is no guarantee that the first null 
  511.       character encountered in an RXSTRING marks the end of the string. The C 
  512.       string functions should only be used when null characters are not 
  513.       expected in the RXSTRINGs (such a file names passed to external 
  514.       functions). The strlength field in the RXSTRING does not include the 
  515.       terminating null character. 
  516.  
  517.    4. When the REXX interpreter calls subcommand handlers, external functions, 
  518.       and some exit handlers, the interpreter expects an RXSTRING value 
  519.       returned. The interpreter provides a default RXSTRING with a strlength of 
  520.       256 for the returned information. If the returned data is shorter than 
  521.       256 characters, the handler can copy the data into the default RXSTRING 
  522.       and set the strlength field to the length returned. 
  523.  
  524.       If the returned data is longer than 256 characters, a new RXSTRING can be 
  525.       allocated using "DosAllocMem". The strptr field must point to the new 
  526.       storage and the strlength must be set to the string length. The REXX 
  527.       interpreter will return the newly allocated storage to the system for the 
  528.       handler routine. 
  529.  
  530.  
  531. ΓòÉΓòÉΓòÉ 6. Invoking the REXX Interpreter ΓòÉΓòÉΓòÉ
  532.  
  533. A REXX program can be executed directly by the operating system or from within 
  534. an application program. 
  535.  
  536.  
  537. ΓòÉΓòÉΓòÉ 6.1. From the Operating System ΓòÉΓòÉΓòÉ
  538.  
  539. The CMD.EXE command shell calls the REXX interpreter for the user: 
  540.  
  541.    o  at command prompts 
  542.  
  543.    o  in calls from CMD (batch) files 
  544.  
  545.       Note:  Use the OS/2* operating system CALL command to invoke a REXX 
  546.              program in a batch file if you want control to return to the 
  547.              caller. 
  548.  
  549.    o  from the object that represents the program on the OS/2 operating system 
  550.       Desktop. 
  551.  
  552.  
  553. ΓòÉΓòÉΓòÉ 6.2. From Within an Application ΓòÉΓòÉΓòÉ
  554.  
  555. The REXX interpreter is a dynamic link library (DLL) routine. Any application 
  556. can call the REXX interpreter to execute a REXX program. The interpreter is 
  557. fully re-entrant and supports REXX procedures running on multiple threads 
  558. within the same process. 
  559.  
  560. A C-language prototype for the RexxStart function in the Developer's Toolkit 
  561. REXXSAA.H include file. 
  562.  
  563.  
  564. ΓòÉΓòÉΓòÉ 6.3. RexxStart ΓòÉΓòÉΓòÉ
  565.  
  566.  
  567. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  568.  
  569. Topics: 
  570.  
  571.       Call Syntax 
  572.       Uses 
  573.       Parameters 
  574.       Data Structures 
  575.       Return Values 
  576.       Notes 
  577.       Related Functions 
  578.       Examples 
  579.  
  580.  
  581. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxStart ΓòÉΓòÉΓòÉ
  582.  
  583. /*******************************************/
  584. /* RexxStart invokes the REXX interpreter */
  585. /*  to execute a REXX procedure.           */
  586. /*******************************************/
  587.  
  588. LONG      return_code;  /* interpreter return code    */
  589. RXSTRING  argv[1];      /* program argument string    */
  590. RXSTRING  retstr;       /* program return value       */
  591. LONG      rc;           /* converted return code      */
  592.  
  593. return_code = RexxStart(1,
  594.                        argv,
  595.                        "CHANGE.ED",
  596.                        NULL,
  597.                        "Editor",
  598.                        RXCOMMAND,
  599.                        NULL,
  600.                        &rc,
  601.                        &retstr);
  602.  
  603.  
  604. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxStart ΓòÉΓòÉΓòÉ
  605.  
  606. RexxStart invokes the REXX interpreter to execute a REXX procedure. 
  607.  
  608.  
  609. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxStart ΓòÉΓòÉΓòÉ
  610.  
  611. RexxStart  (ArgCount, ArgList, ProgramName, Instore, EnvName, CallType, Exits, 
  612. ReturnCode, Result) 
  613.  
  614. Parameters: 
  615.  
  616.  ArgCount (LONG) - input 
  617.     The number of elements in the ArgList array. This is the value that will be 
  618.     returned by the ARG() built-in function in the REXX program. ArgCount 
  619.     includes RXSTRINGs which represent omitted arguments. Omitted arguments 
  620.     will be empty RXSTRINGs (strptr will be NULL). 
  621.  
  622.  ArgList (PRXSTRING) - input 
  623.     An array of RXSTRING structures that are the REXX program arguments. 
  624.  
  625.  ProgramName (PSZ) - input 
  626.     Address of the ASCIIZ name of the REXX procedure. If Instore is NULL, 
  627.     string must contain at least the file name of the REXX procedure. An 
  628.     extension, drive, and path specification can also be provided. If a file 
  629.     extension is not specified, a default of ".CMD" is supplied. A REXX program 
  630.     can use any extension. If the path and drive are not provided, the REXX 
  631.     interpreter uses the normal OS/2* operating system file search (current 
  632.     directory, then environment path). 
  633.  
  634.     If Instore is not NULL, ProgramName is the name used in the PARSE SOURCE 
  635.     instruction. If Instore requests a REXX procedure from the macrospace, 
  636.     ProgramName is the macrospace function name. (see Macrospace Interface). 
  637.  
  638.  Instore (PRXSTRING) - input 
  639.     An array of two RXSTRING descriptors for in-storage REXX procedures. If the 
  640.     strptr fields of both RXSTRINGs are NULL, the interpreter searches for REXX 
  641.     procedure ProgramName in the REXX macrospace (see Macrospace Interface). If 
  642.     the procedure is not in the macrospace, the RexxStart function terminates 
  643.     with an error return code. 
  644.  
  645.     If either Instore strptr field is not NULL, Instore is used to execute a 
  646.     REXX procedure directly from storage. 
  647.  
  648.       Instore[0] 
  649.          An RXSTRING describing a memory buffer containing the REXX procedure 
  650.          source. The source must be an exact image of a REXX procedure disk 
  651.          file (complete with carriage returns, line feeds, and end-of-file 
  652.          characters). 
  653.  
  654.       Instore[1] 
  655.          An RXSTRING containing the tokenized image of the REXX procedure. If 
  656.          Instore[1] is empty, the REXX interpreter will return the tokenized 
  657.          image in Instore[1] when the REXX procedure finishes executing. The 
  658.          tokenized image can be used in Instore[1] on subsequent RexxStart 
  659.          function calls. 
  660.  
  661.          If Instore[1] is not empty, interpreter will execute the tokenized 
  662.          image directly. The program source provided in Instore[0] is only used 
  663.          if the REXX procedure uses the SOURCELINE built-in function. 
  664.          Instore[0] can be empty if SOURCELINE is not used. If Instore[0] is 
  665.          empty and the SOURCELINE built-in function is used, SOURCELINE will 
  666.          return null strings for the REXX procedure source lines. 
  667.  
  668.          If Instore[1] is not empty, but does not contain a valid REXX 
  669.          tokenized image, unpredictable results can occur. The REXX interpreter 
  670.          might be able to determine that the tokenized image is incorrect and 
  671.          retokenize the source. 
  672.  
  673.          Instore[1] is both an input and an output parameter. 
  674.  
  675.     If the procedure is executed from disk, the Instore pointer must be NULL. 
  676.     If the first argument string in Arglist contains the string "//T" and the 
  677.     CallType is RXCOMMAND, the interpreter will tokenize the procedure source 
  678.     and return the tokenized image without running the program. 
  679.  
  680.     The program using the RexxStart function must release Instore[1] using 
  681.     "DosFreeMem" when the tokenized image is no longer needed. 
  682.  
  683.     The format of the tokenized image of a REXX program is not a programming 
  684.     interface. The tokenized image can only be executed by the same interpreter 
  685.     version used to create the image. Therefore, a tokenized image must not be 
  686.     moved to other systems or saved for later use. The tokenized image can, 
  687.     however, be used multiple times during a single application instance. 
  688.  
  689.  EnvName (PSZ) - input 
  690.     Address of the ASCIIZ initial ADDRESS environment name. The ADDRESS 
  691.     environment is a subcommand handler registered using RexxRegisterSubcomExe 
  692.     or RexxRegisterSubcomDll, EnvName is used as the initial setting for the 
  693.     REXX ADDRESS instruction. 
  694.  
  695.     If EnvName is NULL, the file extension is used as the initial ADDRESS 
  696.     environment. The environment name cannot be longer than 250 characters. 
  697.  
  698.  CallType (LONG) - input 
  699.     The type of REXX procedure execution. Allowed execution types are: 
  700.  
  701.       RXCOMMAND 
  702.          The REXX procedure is an OS/2 operating system command or application 
  703.          command. REXX commands normally have a single argument string. The 
  704.          REXX PARSE SOURCE instruction will return COMMAND as the second token. 
  705.  
  706.       RXSUBROUTINE 
  707.          The REXX procedure is a subroutine of another program. The subroutine 
  708.          can have multiple arguments and does not need to return a result. The 
  709.          REXX PARSE SOURCE instruction will return SUBROUTINE as the second 
  710.          token. 
  711.  
  712.       RXFUNCTION 
  713.          The REXX procedure is a function called from another program. The 
  714.          subroutine can have multiple arguments and must return a result. The 
  715.          REXX PARSE SOURCE instruction will return FUNCTION as the second 
  716.          token. 
  717.  
  718.  Exits (PRXSYSEXIT) - input 
  719.     An array of RXSYSEXIT structures defining exits the REXX interpreter will 
  720.     use. The RXSYSEXIT structures have the following form: 
  721.  
  722.  
  723.         RXSYSEXIT Data Structure
  724.  
  725.         typedef struct {
  726.            PSZ             sysexit_name;       /* name of exit handler        */
  727.            LONG            sysexit_code;       /* system exit function code   */
  728.         } RXSYSEXIT;
  729.  
  730.     The sysexit_name is the address of an ASCIIZ exit handler name registered 
  731.     with RexxRegisterExitExe or RexxRegisterExitDll. sysexit_code is a code 
  732.     identifying the handler exit type. See System Exits for exit code 
  733.     definitions. The system exit list end is identified by an RXENDLST entry. 
  734.     Exits must be NULL if exits are not used. 
  735.  
  736.  ReturnCode (PLONG) - output 
  737.     The integer form of the Result string. If the Result string is a whole 
  738.     number in the range -(2**15) to 2**15-1, it will be converted to an integer 
  739.     and and also returned in ReturnCode. 
  740.  
  741.  Result (PRXSTRING) - output 
  742.     The string returned from the REXX procedure with the REXX RETURN or EXIT 
  743.     instruction. A default RXSTRING can be provided for the returned result. If 
  744.     a default RXSTRING is not provided or the default is too small for the 
  745.     returned result, the REXX interpreter will allocate an RXSTRING using 
  746.     "DosAllocMem". The caller of the RexxStart function must release the 
  747.     RXSTRING storage with "DosFreeMem". 
  748.  
  749.     The REXX interpreter does not add a terminating null to Result. 
  750.  
  751.  
  752. ΓòÉΓòÉΓòÉ <hidden> Data Structures - RexxStart ΓòÉΓòÉΓòÉ
  753.  
  754. RexxStart uses the following data structures: 
  755.  
  756. typedef struct {
  757.    ULONG           strlength;          /*   length of string         */
  758.    PCH             strptr;             /*   pointer to string        */
  759. } RXSTRING;
  760.  
  761. typedef RXSTRING *PRXSTRING;           /* pointer to an RXSTRING     */
  762.  
  763. typedef struct {
  764.    PSZ             sysexit_name;       /* name of exit handler        */
  765.    LONG            sysexit_code;       /* system exit function code   */
  766. } RXSYSEXIT;
  767.  
  768.  
  769. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxStart ΓòÉΓòÉΓòÉ
  770.  
  771. RexxStart returns the following values: 
  772.  
  773.  negative 
  774.     Interpreter errors. 
  775.  
  776.  0 
  777.     No errors occurred.  The REXX procedure executed normally. 
  778.  
  779.  When a macrospace REXX procedure is not loaded in the macrospace, the return 
  780.  code is -3 ("Program is unreadable"). 
  781.  
  782.  
  783. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxStart ΓòÉΓòÉΓòÉ
  784.  
  785. The REXX interpreter is a dynamic link library (DLL) routine. Any application 
  786. can use the REXX interpreter to execute a REXX program. The interpreter is 
  787. fully re-entrant and supports REXX procedures running on multiple threads 
  788. within the same process. 
  789.  
  790.  
  791. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxStart ΓòÉΓòÉΓòÉ
  792.  
  793. The following functions are related to RexxStart: 
  794.  
  795.       RexxAddMacro 
  796.       RexxRegisterSubcomExe 
  797.       RexxRegisterFunctionExe 
  798.  
  799.  
  800. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxStart ΓòÉΓòÉΓòÉ
  801.  
  802. The following example shows the use of RexxStart: 
  803.  
  804. LONG      return_code;                 /* interpreter return code    */
  805. RXSTRING  argv[1];                     /* program argument string    */
  806. RXSTRING  retstr;                      /* program return value       */
  807. LONG      rc;                          /* converted return code      */
  808. CHAR      return_buffer[250];          /* returned buffer            */
  809.  
  810.                                        /* build the argument string  */
  811.   MAKERXSTRING(argv[0], macro_argument,
  812.       strlen(macro_argument));
  813.                                        /* set up default return      */
  814.   MAKERXSTRING(retstr, return_buffer, sizeof(return_buffer));
  815.  
  816.   return_code = RexxStart(1,           /* one argument               */
  817.                           argv,        /* argument array             */
  818.                           "CHANGE.ED", /* REXX procedure name        */
  819.                           NULL,        /* use disk version           */
  820.                           "Editor",    /* default address name       */
  821.                           RXCOMMAND,   /* calling as a subcommand    */
  822.                           NULL,        /* no exits used              */
  823.                           &rc,         /* converted return code      */
  824.                           &retstr);    /* returned result            */
  825.  
  826.                                        /* process return value       */
  827.            .
  828.            .
  829.            .
  830.                                        /* need to return storage?    */
  831.   if (RXSTRPTR(retval) != return_buffer)
  832.     DosFreeMem(RXSTRPTR(retval));      /* release the RXSTRING       */
  833.  
  834.  
  835. ΓòÉΓòÉΓòÉ 7. Subcommand Interfaces ΓòÉΓòÉΓòÉ
  836.  
  837. An application can create named handlers to process commands from a REXX 
  838. programs. Once created, the subcommand handler name can be used with the 
  839. RexxStart function or the REXX ADDRESS instruction. Subcommand handlers must be 
  840. registered with the RexxRegisterSubcomExe or RexxRegisterSubcomDll function 
  841. before use. 
  842.  
  843.  
  844. ΓòÉΓòÉΓòÉ 7.1. Registering Subcommand Handlers ΓòÉΓòÉΓòÉ
  845.  
  846. A subcommand handler can reside in the same module (EXE or DLL) as an 
  847. application, or it can reside in a separate dynamic link library. An 
  848. application that executes REXX procedures with RexxStart should use 
  849. RexxRegisterSubcomExe to register subcommand handlers. The REXX interpreter 
  850. passes commands to the application subcommand handler entry point. Subcommand 
  851. handlers created using RexxRegisterSubcomExe are available only to REXX 
  852. programs invoked from the registering application. 
  853.  
  854. The RexxRegisterSubcomDll function creates subcommand handlers which reside in 
  855. a dynamic link library. A dynamic link library subcommand handler can be 
  856. accessed by any REXX program using the REXX ADDRESS instruction. A dynamic link 
  857. library subcommand handler can also be registered directly from a REXX program 
  858. using the RXSUBCOM command. 
  859.  
  860.  
  861. ΓòÉΓòÉΓòÉ 7.2. Creating Subcommand Handlers ΓòÉΓòÉΓòÉ
  862.  
  863. The following example is a sample subcommand handler definition. 
  864.  
  865.  
  866. Sample Definition of a Subcommand Handler
  867.  
  868. ULONG command_handler(
  869.   PRXSTRING Command,    /* Command string from REXX                 */
  870.   PUSHORT   Flags,      /* Returned Error/Failure flags             */
  871.   PRXSTRING Retstr)     /* Returned RC string                       */
  872.  
  873. Where: 
  874.  
  875.  Command   The command string created by REXX. 
  876.  
  877.            Command is a null-terminated RXSTRING containing the issued command. 
  878.  
  879.  Flags     Subcommand completion status. The subcommand handler can indicate 
  880.            success, error, or failure status. The subcommand handler can set 
  881.            Flags to one of the following value: 
  882.  
  883.       RXSUBCOM_OK 
  884.          The subcommand completed normally. No errors occurred during 
  885.          subcommand processing and the REXX procedure will continue when the 
  886.          subcommand handler returns. 
  887.  
  888.       RXSUBCOM_ERROR 
  889.          A subcommand error occurred. RXSUBCOM_ERROR indicates a subcommand 
  890.          error occurred, for example, incorrect command options or syntax. 
  891.  
  892.          If the subcommand handler sets Flags to RXSUBCOM_ERROR, the REXX 
  893.          interpreter will raise an ERROR condition if SIGNAL ON ERROR or CALL 
  894.          ON ERROR traps have been created. If TRACE ERRORS has been issued, 
  895.          REXX will trace the command when the subcommand handler returns. 
  896.  
  897.       RXSUBCOM_FAILURE 
  898.          A subcommand failure occurred. RXSUBCOM_FAILURE indicates that general 
  899.          subcommand processing errors have occurred. For example, unknown 
  900.          commands normally return RXSUBCOM_FAILURE. 
  901.  
  902.          If the subcommand handler sets Flags to RXSUBCOM_FAILURE, the REXX 
  903.          interpreter will raise a FAILUREcondition if SIGNAL ON FAILURE or CALL 
  904.          ON FAILURE traps have been created. If TRACE FAILURES has been issued, 
  905.          REXX will trace the command when the subcommand handler returns. 
  906.  
  907.  Retstr    Address of an RXSTRING for the return code. Retstr is a character 
  908.            string return code that will be assigned to the REXX special 
  909.            variable RC when the subcommand handler returns to REXX. The REXX 
  910.            interpreter provides a default 256-byte RXSTRING in Retstr. A longer 
  911.            RXSTRING can allocated with "DosAllocMem" if the return string is 
  912.            longer than the default RXSTRING. If the subcommand handler sets 
  913.            Retval to an empty RXSTRING (a NULL strptr), REXX will assign the 
  914.            string "0" to RC. 
  915.  
  916.  
  917. ΓòÉΓòÉΓòÉ <hidden> Sample Sucommand Handler ΓòÉΓòÉΓòÉ
  918.  
  919. ULONG Edit_Commands(
  920.   PRXSTRING Command,    /* Command string passed from the caller    */
  921.   PUSHORT   Flags,      /* pointer to short for return of flags     */
  922.   PRXSTRING Retstr)     /* pointer to RXSTRING for RC return        */
  923. {
  924.   LONG      command_id;                /* command to process         */
  925.   LONG      rc;                        /* return code                */
  926.   PSZ       scan_pointer;              /* current command scan       */
  927.   PSZ       target;                    /* general editor target      */
  928.  
  929.   scan_pointer = command->strptr;      /* point to the command       */
  930.                                        /* resolve command            */
  931.   command_id = resolve_command(&scan_pointer);
  932.  
  933.   switch (command_id) {                /* process based on command   */
  934.  
  935.     case   LOCATE:                     /* locate command             */
  936.  
  937.                                        /* validate rest of command   */
  938.       if (rc = get_target(&scan_pointer, &target)) {
  939.         *Flags = RXSUBCOM_ERROR;       /* raise an error condition   */
  940.         break;                         /* return to REXX             */
  941.       }
  942.       rc = locate(target);             /* look target in the file    */
  943.       *Flags = RXSUBCOM_OK;            /* not found is not an error  */
  944.       break;                           /* go finish up               */
  945.  
  946.        .
  947.        .
  948.        .
  949.  
  950.     default:                           /* unknown command            */
  951.       rc = 1;                          /* return code for unknown    */
  952.       *Flags = RXSUBCOM_FAILURE;       /* this is a command failure  */
  953.       break;
  954.   }
  955.  
  956.   sprintf(Retstr->strptr, "%d", rc);   /* format return code string  */
  957.                                        /* and set the correct length */
  958.   Retstr->strlength = strlen(Retstr->strptr);
  959.   return 0;                            /* processing completed       */
  960. }
  961.  
  962.  
  963. ΓòÉΓòÉΓòÉ 8. Subcommand Interface Functions ΓòÉΓòÉΓòÉ
  964.  
  965.    o  RexxRegisterSubcomDll registers a subcommand handler that resides in a 
  966.       dynamic link library routine. 
  967.  
  968.    o  RexxRegisterSubcomExe registers a subcommand handler that resides within 
  969.       application code. 
  970.  
  971.    o  RexxDeregisterSubcom deregisters a subcommand handler. 
  972.  
  973.    o  RexxQuerySubcom queries a subcommand handler and retrieves saved user 
  974.       information. 
  975.  
  976.  
  977. ΓòÉΓòÉΓòÉ 8.1. RexxRegisterSubcomDll ΓòÉΓòÉΓòÉ
  978.  
  979.  
  980. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  981.  
  982. Topics: 
  983.  
  984.       Call Syntax 
  985.       Uses 
  986.       Parameters 
  987.       Return Values 
  988.       Errors 
  989.       Notes 
  990.       Related Functions 
  991.       Sample Programs 
  992.  
  993.  
  994. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxRegisterSubcomDll ΓòÉΓòÉΓòÉ
  995.  
  996. /*******************************************/
  997. /* RexxRegisterSubcomDll registers a      */
  998. /*  subcommand handler that resides in a   */
  999. /*  dynamic link library routine.          */
  1000. /*******************************************/
  1001.  
  1002. #define INCL_RXSUBCOM       /* Subcommand handler values */
  1003.  
  1004. PSZ     name;         /* handler name */
  1005. PSZ     library;      /* DLL name     */
  1006. PSZ     routine;      /* routine name */
  1007. ULONG   rc;           /* Return code  */
  1008. ULONG   userdata[2];  /* save userdata*/
  1009.  
  1010. rc = RexxRegisterSubcomDll(name, library, routine,
  1011.      userdata, RXSUBCOM_DROPPABLE);
  1012.  
  1013.  
  1014. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxRegisterSubcomDll ΓòÉΓòÉΓòÉ
  1015.  
  1016. RexxRegisterSubcomDll registers a subcommand handler that resides in a dynamic 
  1017. link library routine. 
  1018.  
  1019.  
  1020. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxRegisterSubcomDll ΓòÉΓòÉΓòÉ
  1021.  
  1022. RexxRegisterSubcomDll (EnvName, ModuleName, EntryPoint, UserArea, DropAuth) 
  1023.  
  1024. Parameters: 
  1025.  
  1026.  EnvName (PSZ) - input 
  1027.     Address of an ASCIIZ subcommand handler name. 
  1028.  
  1029.  ModuleName (PSZ) - input 
  1030.     Address of an ASCIIZ dynamic link library name. ModuleName is the DLL file 
  1031.     containing the subcommand handler routine. 
  1032.  
  1033.  EntryPoint (PSZ) - input 
  1034.     Address of an ASCIIZ dynamic link library procedure name. EntryPoint is the 
  1035.     name of the exported routine within ModuleName that is the REXX subcommand 
  1036.     handler. 
  1037.  
  1038.  UserArea (PUCHAR) - input 
  1039.     Address of an 8-byte area of user defined information. The 8 bytes 
  1040.     addressed by UserArea will be saved with the subcommand handler 
  1041.     registration. UserArea can be NULL if there is no user information to save. 
  1042.     The saved user information can be retrieved with the RexxQuerySubcom 
  1043.     function. 
  1044.  
  1045.  DropAuth (ULONG) - input 
  1046.     The drop authority. DropAuth identifies the processes that can deregister 
  1047.     the subcommand handler. The possible DropAuth values are: 
  1048.  
  1049.       RXSUBCOM_DROPPABLE 
  1050.          Any process can deregister the subcommand handler with 
  1051.          RexxDeregisterSubcom. 
  1052.  
  1053.       RXSUBCOM_NONDROP 
  1054.          Only a thread within the same process as the thread that registered 
  1055.          the handler can deregister the handler with RexxDeregisterSubcom. 
  1056.  
  1057.  
  1058. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxRegisterSubcomDll ΓòÉΓòÉΓòÉ
  1059.  
  1060. RexxRegisterSubcomDll returns the following values: 
  1061.  
  1062.  0         RXSUBCOM_OK 
  1063.  10        RXSUBCOM_DUP 
  1064.  1002      RXSUBCOM_NOEMEM 
  1065.  1003      RXSUBCOM_BADTYPE 
  1066.  
  1067.  
  1068. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxRegisterSubcomDll ΓòÉΓòÉΓòÉ
  1069.  
  1070. EntryPoint can be either a 16-bit or a 32-bit routine. REXX will invoke the 
  1071. handler in the correct addressing mode. 
  1072.  
  1073. A REXX procedure can register dynamic link library subcommand handlers with the 
  1074. RXSUBCOM command. For example: 
  1075.  
  1076.                                  /* register Dialog Manager       */
  1077.                                  /* subcommand handler            */
  1078.   'RXSUBCOM REGISTER ISPCIR ISPCIR ISPCIR'
  1079.   Address ispcir                 /* send commands to dialog mgr   */
  1080.  
  1081. The RXSUBCOM command registers the Dialog Manager subcommand handler ISPCIR as 
  1082. routine ISPCIR in the ISPCIR dynamic link library. 
  1083.  
  1084.  
  1085. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxRegisterSubcomDll ΓòÉΓòÉΓòÉ
  1086.  
  1087. The following functions are related to RexxRegisterSubcomDll: 
  1088.  
  1089.       RexxRegisterSubcomExe 
  1090.       RexxDeregisterSubcom 
  1091.       RexxQuerySubcom 
  1092.       RexxStart 
  1093.  
  1094.  
  1095. ΓòÉΓòÉΓòÉ 8.2. RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1096.  
  1097.  
  1098. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  1099.  
  1100. Topics: 
  1101.  
  1102.       Call Syntax 
  1103.       Uses 
  1104.       Parameters 
  1105.       Return Values 
  1106.       Errors 
  1107.       Notes 
  1108.       Related Functions 
  1109.       Examples 
  1110.       Sample Programs 
  1111.  
  1112.  
  1113. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1114.  
  1115. /*******************************************/
  1116. /* RexxRegisterSubcomExe registers a      */
  1117. /*  subcommand handler that resides within */
  1118. /*  application code .                     */
  1119. /*******************************************/
  1120.  
  1121. #define INCL_RXSUBCOM       /* Subcommand handler values */
  1122.  
  1123. PSZ     name;         /* handler name */
  1124. ULONG   rc;           /* Return code  */
  1125. ULONG   userdata[2];  /* save userdata*/
  1126.  
  1127. rc = RexxRegisterSubcomExe(name, &handler_routine,
  1128.      userdata);
  1129.  
  1130.  
  1131. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1132.  
  1133. RexxRegisterSubcomExe registers a subcommand handler that resides within 
  1134. application code. 
  1135.  
  1136.  
  1137. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1138.  
  1139. RexxRegisterSubcomExe (EnvName, EntryPoint, UserArea) 
  1140.  
  1141. Parameters: 
  1142.  
  1143.  EnvName (PSZ) - input 
  1144.     Address of an ASCIIZ subcommand handler name. 
  1145.  
  1146.  EntryPoint (PFN) - input 
  1147.     Address of the subcommand handler entry point within the application EXE 
  1148.     code. pt.UserArea (PUCHAR) - input pd. Address of an 8-byte area of user 
  1149.     defined information. The 8 bytes addressed by UserArea will be saved with 
  1150.     the subcommand handler registration. UserArea can be NULL if there is no 
  1151.     user information to save. The user information can be retrieved with the 
  1152.     RexxQuerySubcom function. 
  1153.  
  1154.  
  1155. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1156.  
  1157. RexxRegisterSubcomExe returns the following values: 
  1158.  
  1159.  0         RXSUBCOM_OK 
  1160.  10        RXSUBCOM_DUP 
  1161.  30        RXSUBCOM_NOTREG 
  1162.  1002      RXSUBCOM_NOEMEM 
  1163.  1003      RXSUBCOM_BADTYPE 
  1164.  
  1165.  
  1166. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1167.  
  1168. If EnvName is same as a subcommand handler already registered with 
  1169. RexxRegisterSubcomDll, RexxRegisterSubcomExe will return RXSUBCOM_DUP. This is 
  1170. not an error condition. RexxRegisterSubcomExe has successfully registered the 
  1171. new subcommand handler. 
  1172.  
  1173.  
  1174. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1175.  
  1176. The following functions are related to RexxRegisterSubcomExe: 
  1177.  
  1178.       RexxRegisterSubcomDll 
  1179.       RexxDeregisterSubcom 
  1180.       RexxQuerySubcom 
  1181.       RexxStart 
  1182.  
  1183.  
  1184. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxRegisterSubcomExe ΓòÉΓòÉΓòÉ
  1185.  
  1186. The following example shows the use of RexxRegisterSubcomExe: 
  1187.  
  1188.   WORKAREARECORD  *user_info[2];       /* saved user information     */
  1189.  
  1190.   user_info[0] = global_workarea;      /* save global work area for  */
  1191.   user_info[1] = NULL;                 /* re-entrancy                */
  1192.  
  1193.   rc = RexxRegisterSubcomExe("Editor", /* register editor handler    */
  1194.       &Edit_Commands,                  /* located at this address    */
  1195.       user_info);                      /* save global pointer        */
  1196.  
  1197.  
  1198. ΓòÉΓòÉΓòÉ 8.3. RexxDeregisterSubcom ΓòÉΓòÉΓòÉ
  1199.  
  1200.  
  1201. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  1202.  
  1203. Topics: 
  1204.  
  1205.       Call Syntax 
  1206.       Uses 
  1207.       Parameters 
  1208.       Return Values 
  1209.       Errors 
  1210.       Notes 
  1211.       Related Functions 
  1212.  
  1213.  
  1214. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxDeregisterSubcom ΓòÉΓòÉΓòÉ
  1215.  
  1216. /*******************************************/
  1217. /* RexxDeregisterSubcom deregisters a      */
  1218. /*  subcommand handler.                    */
  1219. /*******************************************/
  1220.  
  1221. #define INCL_RXSUBCOM       /* Subcommand handler values */
  1222.  
  1223. PSZ     name;       /* handler name       */
  1224. PSZ     library     /* handler dll        */
  1225. ULONG   rc;         /* Return code */
  1226.  
  1227. rc = RexxDeregisterSubcom(name, library);
  1228.  
  1229.  
  1230. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxDeregisterSubcom ΓòÉΓòÉΓòÉ
  1231.  
  1232. RexxDeregisterSubcom deregisters a subcommand handler. 
  1233.  
  1234.  
  1235. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxDeregisterSubcom ΓòÉΓòÉΓòÉ
  1236.  
  1237. RexxDeregisterSubcom (EnvName, ModuleName) 
  1238.  
  1239. Parameters: 
  1240.  
  1241.  EnvName (PSZ) - input 
  1242.     Address of an ASCIIZ subcommand handler name. 
  1243.  
  1244.  ModuleName (PSZ) - input 
  1245.     Address of an ASCIIZ dynalink library name. ModuleName is the name of the 
  1246.     dynalink library containing the registered subcommand handler. When 
  1247.     ModuleName is NULL, RexxDeregisterSubcom searches the RexxRegisterSubcomExe 
  1248.     subcommand handler list for a handler within the current process. If 
  1249.     RexxDeregisterSubcom does not find a RexxRegisterSubcomExe handler, it will 
  1250.     search the RexxRegisterSubcomDll subcommand handler list. 
  1251.  
  1252.  
  1253. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxDeregisterSubcom ΓòÉΓòÉΓòÉ
  1254.  
  1255. RexxDeregisterSubcom returns the following values: 
  1256.  
  1257.  0         RXSUBCOM_OK 
  1258.  30        RXSUBCOM_NOTREG 
  1259.  40        RXSUBCOM_NOCANDROP 
  1260.  1003      RXSUBCOM_BADTYPE 
  1261.  
  1262.  
  1263. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxDeregisterSubcom ΓòÉΓòÉΓòÉ
  1264.  
  1265. The handler is removed from the active subcommand handler list. 
  1266.  
  1267.  
  1268. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxDeregisterSubcom ΓòÉΓòÉΓòÉ
  1269.  
  1270. The following functions are related to RexxDeregisterSubcom: 
  1271.  
  1272.       RexxRegisterSubcomDll 
  1273.       RexxRegisterSubcomExe 
  1274.       RexxQuerySubcom 
  1275.  
  1276.  
  1277. ΓòÉΓòÉΓòÉ 8.4. RexxQuerySubcom ΓòÉΓòÉΓòÉ
  1278.  
  1279.  
  1280. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  1281.  
  1282. Topics: 
  1283.  
  1284.       Call Syntax 
  1285.       Uses 
  1286.       Parameters 
  1287.       Return Values 
  1288.       Errors 
  1289.       Related Functions 
  1290.       Examples 
  1291.  
  1292.  
  1293. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxQuerySubcom ΓòÉΓòÉΓòÉ
  1294.  
  1295. /*******************************************/
  1296. /* RexxQuerySubcom queries a subcommand   */
  1297. /*  handler and retrieves saved user       */
  1298. /*  information.                           */
  1299. /*******************************************/
  1300.  
  1301. #define INCL_RXSUBCOM       /* subcommand handler values */
  1302.  
  1303. PSZ     name;         /* handler name */
  1304. PSZ     library;      /* DLL name     */
  1305. ULONG   userdata[2];  /* saved information */
  1306. ULONG   rc;         /* Return code */
  1307.  
  1308. rc = RexxQuerySubcom(name, library, userdata);
  1309.  
  1310.  
  1311. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxQuerySubcom ΓòÉΓòÉΓòÉ
  1312.  
  1313. RexxQuerySubcom queries a subcommand handler and retrieves saved user 
  1314. information. 
  1315.  
  1316.  
  1317. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxQuerySubcom ΓòÉΓòÉΓòÉ
  1318.  
  1319. RexxQuerySubcom (EnvName, ModuleName, Flag, UserWord) 
  1320.  
  1321. Parameters: 
  1322.  
  1323.  EnvName (PSZ) - input 
  1324.     Address of an ASCIIZ subcommand handler name. 
  1325.  
  1326.  ModuleName (PSZ) - input 
  1327.     Address of an ASCIIZ dynamic link library name. ModuleName restricts the 
  1328.     query to a subcommand handler within the ModuleName dynamic link library. 
  1329.     When ModuleName is NULL, RexxQuerySubcom searches the RexxRegisterSubcomExe 
  1330.     subcommand handler list for a handler within the current process. If 
  1331.     RexxQuerySubcom does not find a RexxRegisterSubcomExe handler, it will 
  1332.     search the RexxRegisterSubcomDll subcommand handler list. 
  1333.  
  1334.  Flag (PUSHORT) - output 
  1335.     Subcommand handler registration flag. Flag is the EnvName subcommand 
  1336.     handler registration status. When RexxQuerySubcom returns RXSUBCOM_OK, the 
  1337.     EnvName subcommand handler is currently registered. When RexxQuerySubcom 
  1338.     returns RXSUBCOM_NOTREG, the EnvName subcommand handler is not registered. 
  1339.  
  1340.  UserWord (PUCHAR) - output 
  1341.     Address of an 8-byte area to receive the user information saved with 
  1342.     RexxRegisterSubcomExe or RexxRegisterSubcomDll. UserWord can be NULL if the 
  1343.     saved user information is not required. 
  1344.  
  1345.  
  1346. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxQuerySubcom ΓòÉΓòÉΓòÉ
  1347.  
  1348. RexxQuerySubcom returns the following values: 
  1349.  
  1350.  0         RXSUBCOM_OK 
  1351.  30        RXSUBCOM_NOTREG 
  1352.  1003      RXSUBCOM_BADTYPE 
  1353.  
  1354.  
  1355. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxQuerySubcom ΓòÉΓòÉΓòÉ
  1356.  
  1357. The following functions are related to RexxQuerySubcom: 
  1358.  
  1359.       RexxRegisterSubcomDll 
  1360.       RexxRegisterSubcomExe 
  1361.       RexxDeregisterSubcom 
  1362.  
  1363.  
  1364. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxQuerySubcom ΓòÉΓòÉΓòÉ
  1365.  
  1366. The following examples show the use of RexxQuerySubcom: 
  1367.  
  1368. ULONG Edit_Commands(
  1369.   PRXSTRING Command,    /* Command string passed from the caller    */
  1370.   PUSHORT   Flags,      /* pointer to short for return of flags     */
  1371.   PRXSTRING Retstr)     /* pointer to RXSTRING for RC return        */
  1372. {
  1373.   WORKAREARECORD  *user_info[2];       /* saved user information     */
  1374.   WORKAREARECORD   global_workarea;    /* application data anchor    */
  1375.   USHORT           query_flag;         /* flag for handler query     */
  1376.  
  1377.  
  1378.   rc = RexxQuerySubcom("Editor",       /* retrieve application work  */
  1379.       NULL,                            /* area anchor from REXX.     */
  1380.       &query_flag,
  1381.       user_info);
  1382.  
  1383.   global_workarea = user_info[0];      /* set the global anchor      */
  1384.  
  1385.  
  1386. ΓòÉΓòÉΓòÉ <hidden> Subcommand Interface Errors ΓòÉΓòÉΓòÉ
  1387.  
  1388. The following are the subcommand handler function errors.: 
  1389.  
  1390.  RXSUBCOM_NOEMEM 
  1391.     There is insufficient memory available to complete this request. 
  1392.  
  1393.  RXSUBCOM_OK 
  1394.     A subcommand function has executed successfully. 
  1395.  
  1396.  RXSUBCOM_DUP 
  1397.     A duplicate handler name has been successfully registered; there is either: 
  1398.  
  1399.    o  an EXE handler with the same name registered in another process, or 
  1400.  
  1401.    o  a DLL handler with the same name registered in another DLL; to address 
  1402.       this subcommand, its library name must be specified. 
  1403.  
  1404.  RXSUBCOM_NOTREG 
  1405.     This indicates: 
  1406.  
  1407.    o  registration was unsuccessful due to duplicate handler and dynalink names 
  1408.       (RexxRegisterSubcomExe or RexxRegisterSubcomDll) 
  1409.  
  1410.    o  the subcommand handler is not registered (other REXX subcommand 
  1411.       functions). 
  1412.  
  1413.  RXSUBCOM_NOCANDROP 
  1414.     The subcommand handler has been registered as "not droppable". 
  1415.  
  1416.  
  1417. ΓòÉΓòÉΓòÉ 9. External Functions ΓòÉΓòÉΓòÉ
  1418.  
  1419. There are two types of REXX external functions: 
  1420.  
  1421.    1. Routines written in REXX 
  1422.  
  1423.    2. Routines written in other OS/2* operating system supported languages. 
  1424.  External functions written in the REXX language are not registered with REXX. 
  1425.  the REXX functions are found by a disk search for a REXX procedure file that 
  1426.  matches the function name. Functions written in other languages, however, must 
  1427.  be registered with the REXX interpeter. 
  1428.  
  1429.  
  1430. ΓòÉΓòÉΓòÉ 9.1. Registering External Functions ΓòÉΓòÉΓòÉ
  1431.  
  1432. An external function can reside in the same module (EXE or DLL) as an 
  1433. application, or it can reside in a separate dynamic link library. 
  1434. RexxRegisterFunctionExe registers external functions within an application 
  1435. module. External functions registered with RexxRegisterFunctionExe 
  1436.  
  1437. The RexxRegisterFunctionDll function registers external functions that reside 
  1438. in a dynamic link library. Once registered, a dynamic link library external 
  1439. function can be accessed by any REXX program. A dynamic link library external 
  1440. function can also be registered directly from a REXX program using the REXX 
  1441. RxFuncAdd built-in function. 
  1442.  
  1443.  
  1444. ΓòÉΓòÉΓòÉ 9.2. Creating External Functions ΓòÉΓòÉΓòÉ
  1445.  
  1446. The following is a sample external function definition: 
  1447.  
  1448.  
  1449. Sample External Function Definition
  1450.  
  1451. ULONG SysLoadFuncs(
  1452.      PSZ       Name,                   /* name of the function       */
  1453.      LONG      Argc,                   /* number of arguments        */
  1454.      RXSTRING  Argv[],                 /* list of argument strings   */
  1455.      PSZ       Queuename,              /* current queue name         */
  1456.      PRXSTRING Retstr)                 /* returned result string     */
  1457.  
  1458. Where 
  1459.  
  1460.  Name        Address of ASCIIZ external function name. 
  1461.  
  1462.  Argc        The size of the argument list. Argv will contain Argc RXSTRINGs. 
  1463.  
  1464.  Argv        An array of null-terminated RXSTRINGs for the function arguments. 
  1465.  
  1466.  Queue       The name of the currently defined REXX external data queue. 
  1467.  
  1468.  Retstr      Address of an RXSTRING for the returned value. Retstr is a 
  1469.              character string function or subroutine return value. When a REXX 
  1470.              program calls an external function with the REXX CALL instruction, 
  1471.              Retstr is assigned to the REXX special variable RESULT. When the 
  1472.              REXX program calls an external function as a function, Retstr is 
  1473.              used directly within the REXX expression. 
  1474.  
  1475.              The REXX interpreter provides a default 256-byte RXSTRING in 
  1476.              Retstr. A longer RXSTRING can allocated with "DosAllocMem" if the 
  1477.              returned string is longer name 256 bytes. The REXX interpreter 
  1478.              releases Retstr with "DosFreeMem" when the external function 
  1479.              completes. 
  1480.  
  1481.  Returns     An integer return code from the function. When the external 
  1482.              function returns 0, the function completed successfully. Retstr 
  1483.              contains the function return value. When external function return 
  1484.              code is not 0, the REXX interpreter raises REXX error 40 ("Invalid 
  1485.              call to routine").  The Retstr value is ignored. 
  1486.  
  1487.              If the external function does not have a return value, the 
  1488.              function must set Retstr to an an empty RXSTRING (NULL strptr). 
  1489.              When a function does not return a value, the interpreter raises 
  1490.              error 44, "Function did not return data". When an external 
  1491.              function invoked with the REXX CALL instruction does not return a 
  1492.              value, the REXX interpreter drops (unassigns) the special variable 
  1493.              RESULT. 
  1494.  
  1495.  
  1496. ΓòÉΓòÉΓòÉ 9.3. Calling External Functions ΓòÉΓòÉΓòÉ
  1497.  
  1498. RexxRegisterFunctionExe Only REXX procedures running in the same process can 
  1499. use the registered external function. It is possible to register functions with 
  1500. the same external function name if they are registered from different 
  1501. processes. However, RexxRegisterFunctionDll functions are available from all 
  1502. processes. The function names cannot be duplicated. 
  1503.  
  1504.  
  1505. ΓòÉΓòÉΓòÉ 9.4. Sample External Function ΓòÉΓòÉΓòÉ
  1506.  
  1507. ULONG SysMkDir(
  1508.      PSZ       Name,                   /* name of the function       */
  1509.      LONG      Argc,                   /* number of arguments        */
  1510.      RXSTRING  Argv[],                 /* list of argument strings   */
  1511.      PSZ       Queuename,              /* current queue name         */
  1512.      PRXSTRING Retstr)                 /* returned result string     */
  1513. {
  1514.   ULONG  rc;                           /* Return code of function    */
  1515.  
  1516.   if (Argc != 1)                       /* must be 1 argument         */
  1517.     return 40;                         /* incorrect call if not      */
  1518.  
  1519.                                        /* make the directory using   */
  1520.                                        /* the null-terminated        */
  1521.   rc = DosMkDir(Argv[0].strptr, 0L);   /* directly                   */
  1522.  
  1523.   sprintf(Retstr->strptr, "%d", rc);   /* result is return code      */
  1524.                                        /* set proper string length   */
  1525.   Retstr->strlength = strlen(Retstr->strptr);
  1526.   return 0;                            /* successful completion      */
  1527. }
  1528.  
  1529.  
  1530. ΓòÉΓòÉΓòÉ 10. External Function Interface Functions ΓòÉΓòÉΓòÉ
  1531.  
  1532.    o  RexxRegisterFunctionDll registers an external function that resides in a 
  1533.       dynamic link library routine. 
  1534.  
  1535.    o  RexxRegisterFunctionExe registers an external function that resides 
  1536.       within application code. 
  1537.  
  1538.    o  RexxDeregisterFunction deregisters an external function. 
  1539.  
  1540.    o  RexxQueryFunction queries the existence of a registered external 
  1541.       function. 
  1542.  
  1543.  
  1544. ΓòÉΓòÉΓòÉ 10.1. RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1545.  
  1546.  
  1547. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  1548.  
  1549. Topics: 
  1550.  
  1551.       Call Syntax 
  1552.       Uses 
  1553.       Parameters 
  1554.       Return Values 
  1555.       Errors 
  1556.       Notes 
  1557.       Related Functions 
  1558.       Examples 
  1559.  
  1560.  
  1561. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1562.  
  1563. /*******************************************/
  1564. /* RexxRegisterFunctionDll registers an   */
  1565. /*  external function that resides in a    */
  1566. /*  dynamic link library routine.          */
  1567. /*******************************************/
  1568.  
  1569. #define INCL_RXFUNC       /* External function values */
  1570.  
  1571. PSZ     name;         /* function name */
  1572. PSZ     library;      /* DLL name      */
  1573. PSZ     routine;      /* routine name  */
  1574. ULONG   rc;           /* Return code   */
  1575.  
  1576. rc = RexxRegisterFunctionDll(name, library, routine);
  1577.  
  1578.  
  1579. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1580.  
  1581. RexxRegisterFunctionDll registers an external function that resides in a 
  1582. dynamic link library routine. 
  1583.  
  1584.  
  1585. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1586.  
  1587. RexxRegisterFunctionDll (FuncName, ModuleName, EntryPoint) 
  1588.  
  1589. Parameters: 
  1590.  
  1591.  FuncName (PSZ) - input 
  1592.     Address of an ASCIIZ external function name. 
  1593.  
  1594.  ModuleName (PSZ) - input 
  1595.     Address of an ASCIIZ dynamic link library name. ModuleName is the DLL file 
  1596.     containing the external function routine. 
  1597.  
  1598.  EntryPoint (PSZ) - input 
  1599.     Address of an ASCIIZ dynamic link procedure name. EntryPoint is exported 
  1600.     external function routine within ModuleName. 
  1601.  
  1602.  
  1603. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1604.  
  1605. RexxRegisterFunctionDll returns the following values: 
  1606.  
  1607.  0         RXFUNC_OK 
  1608.  10        RXFUNC_DEFINED 
  1609.  20        RXFUNC_NOMEM 
  1610.  
  1611.  
  1612. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1613.  
  1614. EntryPoint can be either a 16-bit or 32-bit routine. REXX will invoke the 
  1615. function in the correct addressing mode. 
  1616.  
  1617. A REXX procedure can register dynamic link library subcommand handlers with the 
  1618. RxFuncAdd built-in function. For example: 
  1619.  
  1620.                                  /* register function SysLoadFuncs*/
  1621.                                  /* in dynalink library REXXUTIL  */
  1622.   Call RxFuncAdd 'SysLoadFuncs', 'REXXUTIL', 'SysLoadFuncs'
  1623.   Call SysLoadFuncs              /* call to load other functions  */
  1624.  
  1625. The RxFuncAdd registers the external function SysLoadFuncs as routine 
  1626. SysLoadFuncs in the REXXUTIL dynamic link library. SysLoadFuncs registers 
  1627. additional functions in REXXUTIL.DLL with RexxRegisterFunctionDll. 
  1628.  
  1629.  
  1630. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1631.  
  1632. The following functions are related to RexxRegisterFunctionDll: 
  1633.  
  1634.       RexxRegisterFunctionExe 
  1635.       RexxDeregisterFunction 
  1636.       RexxQueryFunction 
  1637.  
  1638.  
  1639. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxRegisterFunctionDll ΓòÉΓòÉΓòÉ
  1640.  
  1641. The following example shows the use of RexxRegisterFunctionDll: 
  1642.  
  1643. static PSZ  RxFncTable[] =             /* function package list      */
  1644. {
  1645.       "SysCls",
  1646.       "SysCurpos",
  1647.       "SysCurState",
  1648.       "SysDriveInfo",
  1649. }
  1650.  
  1651.  
  1652. ULONG SysLoadFuncs(
  1653.      PSZ       Name,                   /* name of the function       */
  1654.      LONG      Argc,                   /* number of arguments        */
  1655.      RXSTRING  Argv[],                 /* list of argument strings   */
  1656.      PSZ       Queuename,              /* current queue name         */
  1657.      PRXSTRING Retstr)                 /* returned result string     */
  1658. {
  1659.   INT    entries;                      /* Num of entries             */
  1660.   INT    j;                            /* Counter                    */
  1661.  
  1662.   Retstr->strlength = 0;               /* set null string return     */
  1663.  
  1664.   if (Argc > 0)                        /* check arguments            */
  1665.     return 40;                         /* too many, raise an error   */
  1666.  
  1667.                                        /* get count of arguments     */
  1668.   entries = sizeof(RxFncTable)/sizeof(PSZ);
  1669.                                        /* register each function in  */
  1670.   for (j = 0; j < entries; j++) {      /* the table                  */
  1671.     RexxRegisterFunctionDll(RxFncTable[j],
  1672.           "REXXUTIL", RxFncTable[j]);
  1673.   }
  1674.   return 0;                            /* successful completion      */
  1675. }
  1676.  
  1677.  
  1678. ΓòÉΓòÉΓòÉ 10.2. RexxRegisterFunctionExe ΓòÉΓòÉΓòÉ
  1679.  
  1680.  
  1681. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  1682.  
  1683. Topics: 
  1684.  
  1685.       Call Syntax 
  1686.       Uses 
  1687.       Parameters 
  1688.       Return Values 
  1689.       Errors 
  1690.       Related Functions 
  1691.  
  1692.  
  1693. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxRegisterFunctionExe ΓòÉΓòÉΓòÉ
  1694.  
  1695. /*******************************************/
  1696. /* RexxRegisterFunctionExe registers an   */
  1697. /*  external function that resides within  */
  1698. /*  application code.                      */
  1699. /*******************************************/
  1700.  
  1701. #define INCL_RXFUNC       /* external function values */
  1702.  
  1703. PSZ     name;         /* handler name */
  1704. ULONG   rc;           /* Return code  */
  1705.  
  1706. rc = RexxRegisterFunctionExe(name, &external_function);
  1707.  
  1708.  
  1709. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxRegisterFunctionExe ΓòÉΓòÉΓòÉ
  1710.  
  1711. RexxRegisterFunctionExe registers an external function that resides within 
  1712. application code. 
  1713.  
  1714.  
  1715. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxRegisterFunctionExe ΓòÉΓòÉΓòÉ
  1716.  
  1717. RexxRegisterFunctionExe (FuncName, EntryPoint) 
  1718.  
  1719. Parameters: 
  1720.  
  1721.  FuncName (PSZ) - input 
  1722.     Address of an ASCIIZ external function name. 
  1723.  
  1724.  EntryPoint (PFN) - input 
  1725.     Address of the external function entry point within the application EXE 
  1726.     file. Functions registered with RexxRegisterFunctionExe are local to the 
  1727.     current process. REXX procedures in the same process as the 
  1728.     RexxRegisterFunctionExe function caller can use local external functions. 
  1729.  
  1730.  
  1731. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxRegisterFunctionExe ΓòÉΓòÉΓòÉ
  1732.  
  1733. RexxRegisterFunctionExe returns the following values: 
  1734.  
  1735.  0         RXFUNC_OK 
  1736.  10        RXFUNC_DEFINED 
  1737.  20        RXFUNC_NOMEM 
  1738.  
  1739.  
  1740. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxRegisterFunctionExe ΓòÉΓòÉΓòÉ
  1741.  
  1742. The following functions are related to RexxRegisterFunctionExe: 
  1743.  
  1744.       RexxRegisterFunctionDll 
  1745.       RexxDeregisterFunction 
  1746.       RexxQueryFunction 
  1747.  
  1748.  
  1749. ΓòÉΓòÉΓòÉ 10.3. RexxDeregisterFunction ΓòÉΓòÉΓòÉ
  1750.  
  1751.  
  1752. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  1753.  
  1754. Topics: 
  1755.  
  1756.       Call Syntax 
  1757.       Uses 
  1758.       Parameters 
  1759.       Return Values 
  1760.       Errors 
  1761.       Related Functions 
  1762.  
  1763.  
  1764. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxDeregisterFunction ΓòÉΓòÉΓòÉ
  1765.  
  1766. /*******************************************/
  1767. /* RexxDeregisterFunction deregisters an   */
  1768. /*  external function.                     */
  1769. /*******************************************/
  1770.  
  1771. #define INCL_RXFUNC       /* External Function values */
  1772.  
  1773. PSZ     name;       /* function name      */
  1774. ULONG   rc;         /* Return code        */
  1775.  
  1776. rc = RexxDeregisterFunction(name);
  1777.  
  1778.  
  1779. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxDeregisterFunction ΓòÉΓòÉΓòÉ
  1780.  
  1781. RexxDeregisterFunction deregisters an external function. 
  1782.  
  1783.  
  1784. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxDeregisterFunction ΓòÉΓòÉΓòÉ
  1785.  
  1786. RexxDeregisterFunction (FuncName) 
  1787.  
  1788. Parameters: 
  1789.  
  1790.  FuncName (PSZ) - input 
  1791.     Address of an ASCIIZ external function name to deregister. 
  1792.  
  1793.  
  1794. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxDeregisterFunction ΓòÉΓòÉΓòÉ
  1795.  
  1796. RexxDeregisterFunction returns the following values: 
  1797.  
  1798.  0         RXFUNC_OK 
  1799.  30        RXFUNC_NOTREG 
  1800.  
  1801.  
  1802. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxDeregisterFunction ΓòÉΓòÉΓòÉ
  1803.  
  1804. The following functions are related to RexxDeregisterFunction: 
  1805.  
  1806.       RexxRegisterFunctionDll 
  1807.       RexxRegisterFunctionExe 
  1808.       RexxQueryFunction 
  1809.  
  1810.  
  1811. ΓòÉΓòÉΓòÉ 10.4. RexxQueryFunction ΓòÉΓòÉΓòÉ
  1812.  
  1813.  
  1814. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  1815.  
  1816. Topics: 
  1817.  
  1818.       Call Syntax 
  1819.       Uses 
  1820.       Parameters 
  1821.       Return Values 
  1822.       Errors 
  1823.       Notes 
  1824.       Related Functions 
  1825.  
  1826.  
  1827. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxQueryFunction ΓòÉΓòÉΓòÉ
  1828.  
  1829. /*******************************************/
  1830. /* RexxQueryFunction queries the          */
  1831. /*  existence of a registered external     */
  1832. /*  function.                              */
  1833. /*******************************************/
  1834.  
  1835. #define INCL_RXFUNC      /* External function values */
  1836.  
  1837. PSZ     name;       /* function name */
  1838. ULONG   rc;         /* Return code */
  1839.  
  1840. rc = RexxQueryFunction(name);
  1841.  
  1842.  
  1843. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxQueryFunction ΓòÉΓòÉΓòÉ
  1844.  
  1845. RexxQueryFunction queries the existence of a registered external function. 
  1846.  
  1847.  
  1848. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxQueryFunction ΓòÉΓòÉΓòÉ
  1849.  
  1850. RexxQueryFunction (FuncName) 
  1851.  
  1852. Parameters: 
  1853.  
  1854.  FuncName (PSZ) - input 
  1855.     Address of an ASCIIZ external function name to query. 
  1856.  
  1857.  
  1858. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxQueryFunction ΓòÉΓòÉΓòÉ
  1859.  
  1860. RexxQueryFunction returns the following values: 
  1861.  
  1862.  0         RXFUNC_OK 
  1863.  30        RXFUNC_NOTREG 
  1864.  
  1865.  
  1866. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxQueryFunction ΓòÉΓòÉΓòÉ
  1867.  
  1868. RexxQueryFunction will only return RXFUNC_OK if the requested function is 
  1869. available to the current process. If a function is not available to the current 
  1870. process, RexxQueryFunction search will search the RexxRegisterFunctionDll 
  1871. external function list. 
  1872.  
  1873.  
  1874. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxQueryFunction ΓòÉΓòÉΓòÉ
  1875.  
  1876. The following functions are related to RexxQueryFunction: 
  1877.  
  1878.       RexxRegisterFunctionDll 
  1879.       RexxRegisterFunctionExe 
  1880.       RexxDeregisterFunction 
  1881.  
  1882.  
  1883. ΓòÉΓòÉΓòÉ <hidden> External Function Interface Errors ΓòÉΓòÉΓòÉ
  1884.  
  1885. The following are the external function interface errors.: 
  1886.  
  1887.  RXFUNC_OK 
  1888.     The function call completed successfully. 
  1889.  
  1890.  RXFUNC_DEFINED 
  1891.     The requested function is already registered. 
  1892.  
  1893.  RXFUNC_NOMEM 
  1894.     There is not enough memory to register a new function. 
  1895.  
  1896.  RXFUNC_NOTREG 
  1897.     The requested function is not registered. 
  1898.  
  1899.  
  1900. ΓòÉΓòÉΓòÉ 11. System Exits ΓòÉΓòÉΓòÉ
  1901.  
  1902. The REXX System Exits create user-define REXX interpreter operating 
  1903. environment. Application defined exit handlers process specified REXX 
  1904. interpreter activities. 
  1905.  
  1906. Applications can create exits for: 
  1907.  
  1908.    o  The administration of resources at the beginning and end of 
  1909.       interpretation. 
  1910.  
  1911.    o  Linkages to external functions and subcommand handlers. 
  1912.  
  1913.    o  Special language features. For example, input and output to standard 
  1914.       resources. 
  1915.  
  1916.    o  Polling for halt and external trace events. 
  1917.  
  1918.  Exit handlers are similar to subcommand handlers and external functions: 
  1919.  
  1920.    o  Applications must registers named exit handlers with the REXX 
  1921.       interpreter. 
  1922.  
  1923.    o  Exit handlers can reside in dynamic link libraries or within an 
  1924.       application EXE module. 
  1925.  
  1926.  
  1927. ΓòÉΓòÉΓòÉ 11.1. Writing System Exit Handlers ΓòÉΓòÉΓòÉ
  1928.  
  1929. The following is a sample exit handler definition: 
  1930.  
  1931.  
  1932. Sample System Exit Handler Definition
  1933.  
  1934. LONG Rexx_IO_exit(
  1935.      LONG  ExitNumber,    /* code defining the exit function    */
  1936.      LONG  Subfunction,   /* code defining the exit subfunction */
  1937.      PEXIT ParmBlock)     /* function dependent control block   */
  1938.  
  1939. Where: 
  1940.  
  1941.  ExitNumber  The major function code defining the type of exit. 
  1942.  
  1943.  Subfunction The subfunction code defining the exit event. 
  1944.  
  1945.  ParmBlock   A pointer to the exit parameter list. 
  1946.  
  1947.              The exit parameter list contains exit specific information. See 
  1948.              the exit descriptions below parameter list formats. 
  1949.  
  1950.              Note:  Some exit subfunctions do not have parameters. ParmBlock 
  1951.                     for exit subfunctions without parameters. 
  1952.  
  1953.  
  1954. ΓòÉΓòÉΓòÉ 11.1.1. Exit Return Codes ΓòÉΓòÉΓòÉ
  1955.  
  1956. Exit handlers return an integer value that signals one of three actions: 
  1957.  
  1958.  RXEXIT_HANDLED 
  1959.     The exit handler processed the exit subfunction and updated the subfunction 
  1960.     parameter list as required. The REXX interpreter continues with normal 
  1961.     processing. 
  1962.  
  1963.  RXEXIT_NOT_HANDLED 
  1964.     The exit handler did not process the exit subfunction. The REXX interpreter 
  1965.     processes the subfunction as if the exit handler was not called. 
  1966.  
  1967.  RXEXIT_RAISE_ERROR 
  1968.     A fatal error occurred in the exit handler. The REXX interpreter raises 
  1969.     REXX error 48 ("Failure in system service"). 
  1970.  
  1971.  For example, if an application creates an input/output exit handler: 
  1972.  
  1973.    o  When the exit handler returns RXEXIT_NOT_HANDLED for an RXSIOSAY 
  1974.       subfunction, the REXX interpreter writes the output line to STDOUT. 
  1975.  
  1976.    o  When the exit handler returns RXEXIT_HANDLED for an RXSIOSAY subfunction, 
  1977.       the REXX interpreter assumes the exit handler has performed all required 
  1978.       output. The interpreter will not write the output line to STDOUT. 
  1979.  
  1980.    o  When the exit handler returns RXEXIT_RAISE_ERROR for an RXSIOSAY 
  1981.       subfunction, the interpreter raise REXX error 48, "Failure in system 
  1982.       service". 
  1983.  
  1984.  
  1985. ΓòÉΓòÉΓòÉ 11.1.2. Exit Parameters ΓòÉΓòÉΓòÉ
  1986.  
  1987. Each exit subfunction has a different parameter list. All RXSTRING exit 
  1988. subfunction parameters are passed as null-terminated RXSTRINGs. It is possible 
  1989. that the RXSTRING value will contain null characters also. 
  1990.  
  1991. For some exit subfunctions, the exit handler can return an RXSTRING character 
  1992. result in the parameter list. The interpreter provides a default 256-byte for 
  1993. RXSTRING result strings. If the result is longer than 256 bytes, a new RXSTRING 
  1994. can be allocated using "DosAllocMem". The REXX interpreter will return the 
  1995. RXSTRING storage for the exit handler. 
  1996.  
  1997.  
  1998. ΓòÉΓòÉΓòÉ 11.1.3. Identifying Exit Handlers to REXX ΓòÉΓòÉΓòÉ
  1999.  
  2000. System exit handlers must be registered with RexxRegisterExitDll or 
  2001. RexxRegisterExitExe The system exit handler registration is similar to 
  2002. subcommand handler registration. 
  2003.  
  2004. The REXX system exits are enabled with the RexxStart function parameter Exits. 
  2005. Exits is a pointer to an array of RXSYSEXIT structures. Each RXSYSEXIT 
  2006. structure in the array contains a REXX exit code and the address of an ASCIIZ 
  2007. exit handler name. The RXENDLST exit code marks the exit list end. 
  2008.  
  2009. The REXX interpreter calls the registered exit handler in sysexit_name for all 
  2010. sysexit_code subfunctions. 
  2011. Example 
  2012.  
  2013.  
  2014. Sample System Exit Usage
  2015.  
  2016. WORKAREARECORD  *user_info[2];         /* saved user information     */
  2017. RXSYSEXIT exit_list[2];                /* system exit list           */
  2018.  
  2019.   user_info[0] = global_workarea;      /* save global work area for  */
  2020.   user_info[1] = NULL;                 /* re-entrancy                */
  2021.  
  2022.   rc = RexxRegisterExitExe("EditInit", /* register exit handler      */
  2023.       &Init_exit,                      /* located at this address    */
  2024.       user_info);                      /* save global pointer        */
  2025.  
  2026.                                        /* set up for RXINI exit      */
  2027.   exit_list[0].sysexit_name = "EditInit";
  2028.   exit_list[0].sysexit_code = RXINI;
  2029.   exit_list[1].sysexit_code = RXENDLST;
  2030.  
  2031.   return_code = RexxStart(1,           /* one argument               */
  2032.                           argv,        /* argument array             */
  2033.                           "CHANGE.ED", /* REXX procedure name        */
  2034.                           NULL,        /* use disk version           */
  2035.                           "Editor",    /* default address name       */
  2036.                           RXCOMMAND,   /* calling as a subcommand    */
  2037.                           exit_list,   /* no exits used              */
  2038.                           &rc,         /* converted return code      */
  2039.                           &retstr);    /* returned result            */
  2040.  
  2041.                                        /* process return value       */
  2042.            .
  2043.            .
  2044.            .
  2045. }
  2046.  
  2047. LONG Init_exit(
  2048.      LONG  ExitNumber,    /* code defining the exit function    */
  2049.      LONG  Subfunction,   /* code defining the exit subfunction */
  2050.      PEXIT ParmBlock)     /* function dependent control block   */
  2051. {
  2052.   WORKAREARECORD  *user_info[2];       /* saved user information     */
  2053.   WORKAREARECORD   global_workarea;    /* application data anchor    */
  2054.   USHORT           query_flag;         /* flag for handler query     */
  2055.  
  2056.  
  2057.   rc = RexxQueryExit("EditInit",       /* retrieve application work  */
  2058.       NULL,                            /* area anchor from REXX.     */
  2059.       &query_flag,
  2060.       user_info);
  2061.  
  2062.   global_workarea = user_info[0];      /* set the global anchor      */
  2063.  
  2064.   if (global_workarea->rexx_trace)     /* trace at start?            */
  2065.                                        /* turn on macro tracing      */
  2066.     RexxSetTrace(global_workarea->rexx_pid, global_workarea->rexx_tid);
  2067.   return RXEXIT_HANDLED;               /* successfully handled       */
  2068. }
  2069.  
  2070.  
  2071. ΓòÉΓòÉΓòÉ 11.2. System Exit Definitions ΓòÉΓòÉΓòÉ
  2072.  
  2073. The REXX interpreter supports the following system exits: 
  2074.  
  2075.  RXFNC     External function call exit 
  2076.  
  2077.       RXFNCCAL    Call an external function 
  2078.  
  2079.  RXCMD     Subcommand call exit 
  2080.  
  2081.       RXCMDHST    Call a subcommand handler 
  2082.  
  2083.  RXMSQ     External data queue exit 
  2084.  
  2085.       RXMSQPLL    Pull a line from the external data queue. 
  2086.       RXMSQPSH    Place a line on the external data queue. 
  2087.       RXMSQSIZ    Return number of lines on the external data queue. 
  2088.       RXMSQNAM    Set active external data queue name. 
  2089.  
  2090.  RXSIO     Standard input and output exit. 
  2091.  
  2092.       RXSIOSAY    Write a line to the standard output stream for the SAY 
  2093.                   instruction. 
  2094.       RXSIOTRC    Write a line to the standard error stream for REXX trace or 
  2095.                   REXX error messages. 
  2096.       RXSIOTRD    Read a line from the standard input stream for PULL or PARSE 
  2097.                   PULL. 
  2098.       RXSIODTR    Read a line from the standard input stream for interactive 
  2099.                   debug. 
  2100.  
  2101.  RXHLT     Halt processing exit 
  2102.  
  2103.       RXHLTTST    Test for a HALT condition. 
  2104.       RXHLTCLR    Clear a HALT condition. 
  2105.  
  2106.  RXTRC     External trace exit 
  2107.  
  2108.       RXTRCTST    Test for an external trace event. 
  2109.  
  2110.  RXINI     Initialization exit 
  2111.  
  2112.       RXINIEXT    Allow additional REXX procedure initialization. 
  2113.  
  2114.  RXTER     Termination exit 
  2115.  
  2116.       RXTEREXT    Process REXX procedure termination. 
  2117.  
  2118.  Each exit subfunction has the following characteristics: 
  2119.  
  2120.    o  When REXX calls the exit handler. 
  2121.  
  2122.    o  The default action when the exit is not provided or the exit handler does 
  2123.       not process the subfunction. 
  2124.  
  2125.    o  The subfunction parameter list. 
  2126.  
  2127.    o  The service the subfunction provides. 
  2128.  
  2129.    o  The state of the variable pool interface during the exit handler call. 
  2130.       The variable pool interface is fully enabled for the RXCMD, RXFNC, RXINT, 
  2131.       and RXTER exit handler calls. The variable pool interface is enabled for 
  2132.       RXSHV_EXIT requests for RXHLT, RXCMD, RXFNC, RXSIO, and RXMSQ exit 
  2133.       handler calls. 
  2134.  
  2135.  
  2136. ΓòÉΓòÉΓòÉ 11.3. RXFNC ΓòÉΓòÉΓòÉ
  2137.  
  2138. Process external function calls. 
  2139.  
  2140. The RXFNC exit has the following subfunction: 
  2141.  
  2142.  RXFNCCAL    Process external function calls. 
  2143.  
  2144.  
  2145. ΓòÉΓòÉΓòÉ 11.3.1. RXFNCCAL ΓòÉΓòÉΓòÉ
  2146.  
  2147.  
  2148. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXFNCCAL ΓòÉΓòÉΓòÉ
  2149.  
  2150. Process external function calls. 
  2151.  
  2152.       When called: When a REXX program calls an external subroutine or 
  2153.       function. 
  2154.  
  2155.       Default action: Call the external routine using the normal external 
  2156.       function search order. 
  2157.  
  2158.       Exit Action: Call the external routine, if possible. 
  2159.  
  2160.       Continuation: If necessary, raise REXX error 40 ("Invalid call to 
  2161.       routine"), 43 ("Routine not found"), or 44 ("Function did not return 
  2162.       data"). 
  2163.  
  2164.  Note:  The variable pool interface is fully enabled during RXFNC exit handler 
  2165.         calls. 
  2166.  
  2167.  
  2168. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXFNCCAL ΓòÉΓòÉΓòÉ
  2169.  
  2170. typedef struct {
  2171.    struct {
  2172.       unsigned rxfferr  : 1;           /* Invalid call to routine.    */
  2173.       unsigned rxffnfnd : 1;           /* Function not found.         */
  2174.       unsigned rxffsub  : 1;           /* Called as a subroutine if   */
  2175.                                        /* TRUE.  Return values are    */
  2176.                                        /* optional for subroutines,   */
  2177.                                        /* required for functions.     */
  2178.    } rxfnc_flags ;
  2179.  
  2180.    PUCHAR            rxfnc_name;       /* Pointer to function name.   */
  2181.    USHORT            rxfnc_namel;      /* Length of function name.    */
  2182.    PUCHAR            rxfnc_que;        /* Current queue name.         */
  2183.    USHORT            rxfnc_quel;       /* Length of queue name.       */
  2184.    USHORT            rxfnc_argc;       /* Number of args in list.     */
  2185.    PRXSTRING         rxfnc_argv;       /* Pointer to argument list.   */
  2186.                                        /* List mimics argv list for   */
  2187.                                        /* function calls, an array of */
  2188.                                        /* RXSTRINGs.                  */
  2189.    RXSTRING          rxfnc_retc;       /* Return value.               */
  2190. } RXFNCCAL_PARM;
  2191.  
  2192. The name of the external function is defined by rxfnc_name and rxfnc_namel. The 
  2193. arguments to the function are in rxfnc_argc and rxfnc_argv. If the named 
  2194. external function is invoked by the REXX CALL instruction (rather than as a 
  2195. function call), the flag rxffsub is TRUE. 
  2196.  
  2197. The exit handler can set rxfnc_flags to indicate the external function success. 
  2198. If neither rxfferr or rxffnfnd is TRUE, the exit hander successfully called the 
  2199. external function. The error flags are checked only when the exit handler 
  2200. handles the the request. 
  2201.  
  2202. The exit handler sets rxffnfnd to TRUE when the exit handler could not locate 
  2203. the external function. The interpreter raises REXX error 43, "Routine not 
  2204. found". The exit handler sets rxfferr to TRUE when the exit handler located the 
  2205. external function, but the external function returned an error return code. The 
  2206. REXX interpreter raises error 40, "Invalid call to routine". 
  2207.  
  2208. The exit handler returns the external function result in the rxfnc_retc 
  2209. RXSTRING. The REXX interpreter will raise error 44, "Function did not return 
  2210. data" when the external routine is invoked as a function and the exit handler 
  2211. does not return a result. When the external routine is invoked by the REXX CALL 
  2212. instruction, the exit handler a result is not required. 
  2213.  
  2214.  
  2215. ΓòÉΓòÉΓòÉ 11.4. RXCMD ΓòÉΓòÉΓòÉ
  2216.  
  2217. Process subcommand handler calls. 
  2218.  
  2219. The RXCMD exit has the following subfunction: 
  2220.  
  2221.  RXCMDHST    Call a named subcommand handler. 
  2222.  
  2223.  
  2224. ΓòÉΓòÉΓòÉ 11.4.1. RXCMDHST ΓòÉΓòÉΓòÉ
  2225.  
  2226.  
  2227. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXCMDHST ΓòÉΓòÉΓòÉ
  2228.  
  2229. Call a named subcommand handler. 
  2230.  
  2231.       When called: When a REXX procedure issues a command. 
  2232.  
  2233.       Default action: Call the named subcommand handler specified by the 
  2234.       current REXX ADDRESS setting. 
  2235.  
  2236.       Exit Action: Process the call to a named subcommand handler. 
  2237.  
  2238.       Continuation: Raise the ERROR or FAILURE condition when indicated by the 
  2239.       parameter list flags, 
  2240.  
  2241.  Note:  The variable pool interface function is fully enabled during RXCMD exit 
  2242.         handler calls. 
  2243.  
  2244.  
  2245. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXCMDHST ΓòÉΓòÉΓòÉ
  2246.  
  2247. typedef struct {
  2248.    struct {                            /* Condition flags             */
  2249.       unsigned rxfcfail : 1;           /* Command failed.  Trap with  */
  2250.                                        /* CALL or SIGNAL on FAILURE.  */
  2251.       unsigned rxfcerr  : 1;           /* Command ERROR occurred.     */
  2252.                                        /* Trap with CALL or SIGNAL on */
  2253.                                        /* ERROR.                      */
  2254.    } rxcmd_flags;
  2255.    PUCHAR            rxcmd_address;    /* Pointer to address name.    */
  2256.    USHORT            rxcmd_addressl;   /* Length of address name.     */
  2257.    PUCHAR            rxcmd_dll;        /* dll name for command.       */
  2258.    USHORT            rxcmd_dll_len;    /* Length of dll name.  0 ==>  */
  2259.                                        /* .EXE file.                  */
  2260.    RXSTRING          rxcmd_command;    /* The command string.         */
  2261.    RXSTRING          rxcmd_retc;       /* Pointer to return code      */
  2262.                                        /* buffer.  User allocated.    */
  2263. } RXCMDHST_PARM;
  2264.  
  2265. The rxcmd_command field contains the issued command. rxcmd_address, 
  2266. rxcmd_addressl, rxcmd_dll, and rxcmd_dll_len fully define the current ADDRESS 
  2267. setting. rxcmd_retc is an RXSTRING for the return code value assigned to REXX 
  2268. special variable RC. 
  2269.  
  2270. The exit handler can set rxfcfail or rxfcerr to TRUE to raise an ERROR or 
  2271. FAILURE condition. 
  2272.  
  2273.  
  2274. ΓòÉΓòÉΓòÉ 11.5. RXMSQ ΓòÉΓòÉΓòÉ
  2275.  
  2276. External data queue exit. 
  2277.  
  2278. The RXMSQ exit has the following subfunctions: 
  2279.  
  2280.  RXMSQPLL    Pull a line from the external data queue. 
  2281.  RXMSQPSH    Place a line on the external data queue. 
  2282.  RXMSQSIZ    Return the number of lines in the external data queue. 
  2283.  RXMSQNAM    Set the name of the active external data queue. 
  2284.  
  2285.  
  2286. ΓòÉΓòÉΓòÉ 11.5.1. RXMSQPLL ΓòÉΓòÉΓòÉ
  2287.  
  2288.  
  2289. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXMSQPLL ΓòÉΓòÉΓòÉ
  2290.  
  2291. Pull a line from the external data queue. 
  2292.  
  2293.       When called: When a REXX PULL instruction, PARSE PULL instruction, or 
  2294.       LINEIN() built-in function reads a line from the external data queue. 
  2295.  
  2296.       Default action: Remove a line from the current REXX data queue. 
  2297.  
  2298.       Exit Action: Return a line from the exit handler provided data queue. 
  2299.  
  2300.  
  2301. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXMSQPLL ΓòÉΓòÉΓòÉ
  2302.  
  2303. typedef struct {
  2304.    RXSTRING          rxmsq_retc;       /* Pointer to dequeued entry   */
  2305.                                        /* buffer.  User allocated.    */
  2306. } RXMSQPLL_PARM;
  2307.  
  2308. The exit handler returns the queue line in the rxmsq_retc RXSTRING. 
  2309.  
  2310.  
  2311. ΓòÉΓòÉΓòÉ 11.5.2. RXMSQPSH ΓòÉΓòÉΓòÉ
  2312.  
  2313.  
  2314. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXMSQPSH ΓòÉΓòÉΓòÉ
  2315.  
  2316. Place a line on the external data queue. 
  2317.  
  2318.       When called: Called by the REXX PUSH instruction, QUEUE instruction, or 
  2319.       LINEOUT() built-in function to add a line to the data queue. 
  2320.  
  2321.       Default action: Add the line to the current REXX data queue. 
  2322.  
  2323.       Exit Action: Add the line to the exit handler provided data queue. 
  2324.  
  2325.  
  2326. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXMSQPSH ΓòÉΓòÉΓòÉ
  2327.  
  2328. typedef struct {
  2329.    struct {                            /* Operation flag              */
  2330.       unsigned rxfmlifo : 1;           /* Stack entry LIFO when TRUE, */
  2331.                                        /* FIFO when FALSE.            */
  2332.    } rxmsq_flags;
  2333.    RXSTRING          rxmsq_value;      /* The entry to be pushed.     */
  2334. } RXMSQPSH_PARM;
  2335.  
  2336. The rxmsq_value RXSTRING contains the line added to the queue. It is the 
  2337. responsibility of the exit handler to truncate the string if the exit handler 
  2338. data queue has a maximum length restriction. rxfmlifo is the stacking order 
  2339. (LIFO or FIFO). 
  2340.  
  2341.  
  2342. ΓòÉΓòÉΓòÉ 11.5.3. RXMSQSIZ ΓòÉΓòÉΓòÉ
  2343.  
  2344.  
  2345. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXMSQSIZ ΓòÉΓòÉΓòÉ
  2346.  
  2347. Return the number of lines in the external data queue. 
  2348.  
  2349.       When called: When the REXX QUEUED() built-in function requests the size 
  2350.       of the external data queue. 
  2351.  
  2352.       Default action: Request the size from the current REXX data queue. 
  2353.  
  2354.       Exit Action: Return the size of the exit handler provided data queue. 
  2355.  
  2356.  
  2357. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXMSQSIZ ΓòÉΓòÉΓòÉ
  2358.  
  2359. typedef struct {
  2360.    ULONG             rxmsq_size;       /* Number of Lines in Queue    */
  2361. } RXMSQSIZ_PARM;
  2362.  
  2363. The exit handler returns the number of queue lines in rxmsq_size. 
  2364.  
  2365.  
  2366. ΓòÉΓòÉΓòÉ 11.5.4. RXMSQNAM ΓòÉΓòÉΓòÉ
  2367.  
  2368.  
  2369. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXMSQNAM ΓòÉΓòÉΓòÉ
  2370.  
  2371. Set the name of the active external data queue. 
  2372.  
  2373.       When called: Called by the RXQUEUE("Set",newname) built-in function. 
  2374.  
  2375.       Default action: Change the current default queue to newname. 
  2376.  
  2377.       Exit Action: Change the default queue name for the exit handler provided 
  2378.       data queue. 
  2379.  
  2380.  
  2381. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXMSQNAM ΓòÉΓòÉΓòÉ
  2382.  
  2383. typedef struct {
  2384.    RXSTRING          rxmsq_name;       /* RXSTRING containing         */
  2385.                                        /* queue name.                 */
  2386. } RXMSQNAM_PARM;
  2387.  
  2388. rxmsq_name contains the new queue name. 
  2389.  
  2390.  
  2391. ΓòÉΓòÉΓòÉ 11.6. RXSIO ΓòÉΓòÉΓòÉ
  2392.  
  2393. Standard input and output. 
  2394.  
  2395. The RXMSQ exit has the following subfunctions: 
  2396.  
  2397.  RXSIOSAY    Write a line to the standard output stream (STDOUT). 
  2398.  RXSIOTRC    Write trace and error message output to the standard error stream. 
  2399.  RXSIOTRD    Read from standard input stream. 
  2400.  RXSIODTR    Interactive debug input. 
  2401.  
  2402.  Note:  The PARSE LINEIN instruction and the LINEIN, LINEOUT, LINES, CHARIN, 
  2403.         CHAROUT, and CHARS built-in functions do not call the RXSIO exit 
  2404.         handler. 
  2405.  
  2406.  
  2407. ΓòÉΓòÉΓòÉ 11.6.1. RXSIOSAY ΓòÉΓòÉΓòÉ
  2408.  
  2409.  
  2410. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXSIOSAY ΓòÉΓòÉΓòÉ
  2411.  
  2412. Write a line to the standard output stream (STDOUT). 
  2413.  
  2414.       When called: By the SAY instruction to write a line to the standard 
  2415.       output stream. 
  2416.  
  2417.       Default action: Write to the standard output stream. 
  2418.  
  2419.       Exit Action: Write the line to the exit handler provided output stream. 
  2420.  
  2421.  
  2422. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXSIOSAY ΓòÉΓòÉΓòÉ
  2423.  
  2424. typedef struct {
  2425.    RXSTRING          rxsio_string;     /* String to display.          */
  2426. } RXSIOSAY_PARM;
  2427.  
  2428. The output line is contained in rxsio_string. The output line can be any 
  2429. length. It is the responsibility of the exit handler to truncate or split the 
  2430. line if necessary. 
  2431.  
  2432.  
  2433. ΓòÉΓòÉΓòÉ 11.6.2. RXSIOTRC ΓòÉΓòÉΓòÉ
  2434.  
  2435.  
  2436. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXSIOTRC ΓòÉΓòÉΓòÉ
  2437.  
  2438. Write trace and error message output to the standard error stream. 
  2439.  
  2440.       When called: To output lines of trace output and REXX error messages. 
  2441.  
  2442.       Default action: Write the line to the standard error stream (STDERR). 
  2443.  
  2444.       Exit Action: Write tine to the exit handler provided error output stream. 
  2445.  
  2446.  
  2447. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXSIOTRC ΓòÉΓòÉΓòÉ
  2448.  
  2449. typedef struct {
  2450.   RXSTRING           rxsio_string;     /* Trace line to display.      */
  2451. } RXSIOTRC_PARM;
  2452.  
  2453. The output line is contained in rxsio_string. The output line can be of any 
  2454. length. It is the responsibility of the exit handler to truncate or split the 
  2455. line if necessary. 
  2456.  
  2457.  
  2458. ΓòÉΓòÉΓòÉ 11.6.3. RXSIOTRD ΓòÉΓòÉΓòÉ
  2459.  
  2460.  
  2461. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXSIOTRD ΓòÉΓòÉΓòÉ
  2462.  
  2463. Read from standard input stream. 
  2464.  
  2465.       When called: To read from the standard input stream for the REXX PULL and 
  2466.       PARSE PULL instructions. 
  2467.  
  2468.       Default action: Read a line from the standard input stream (STDIN). 
  2469.  
  2470.       Exit Action: Return a line from the exit handler provided standard input 
  2471.       stream. 
  2472.  
  2473.  
  2474. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXSIOTRD ΓòÉΓòÉΓòÉ
  2475.  
  2476. typedef struct {
  2477.    RXSTRING          rxsiotrd_retc;    /* RXSTRING for output.        */
  2478. } RXSIOTRD_PARM;
  2479.  
  2480. The input stream line is returned in the rxsiotrd_retc RXSTRING. 
  2481.  
  2482.  
  2483. ΓòÉΓòÉΓòÉ 11.6.4. RXSIODTR ΓòÉΓòÉΓòÉ
  2484.  
  2485.  
  2486. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXSIODTR ΓòÉΓòÉΓòÉ
  2487.  
  2488. Interactive debug input. 
  2489.  
  2490.       When called: To read from the debug input stream for interactive debug 
  2491.       prompts. 
  2492.  
  2493.       Default action: Read a line from the standard input stream (STDIN). 
  2494.  
  2495.       Exit Action: Return a line from the exit handler provided standard debug 
  2496.       stream. 
  2497.  
  2498.  
  2499. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXSIODTR ΓòÉΓòÉΓòÉ
  2500.  
  2501. typedef struct {
  2502.    RXSTRING          rxsiodtr_retc;    /* RXSTRING for output.        */
  2503. } RXSIODTR_PARM;
  2504.  
  2505. The input stream line is returned in the rxsiodtr_retc RXSTRING. 
  2506.  
  2507.  
  2508. ΓòÉΓòÉΓòÉ 11.7. RXHLT ΓòÉΓòÉΓòÉ
  2509.  
  2510. HALT condition processing. 
  2511.  
  2512. The RXHLT exit has the following subfunctions: 
  2513.  
  2514.  RXHLTTST    Test HALT indicator. 
  2515.  RXHLTCLR    Clear HALT condition. 
  2516.  
  2517.  Note:  Since the RXHLT exit handler is called after every REXX instruction, 
  2518.         this exit will slow REXX program execution. The RexxSetHalt function 
  2519.         can halt a REXX program without between-instruction polling. 
  2520.  
  2521.  
  2522. ΓòÉΓòÉΓòÉ 11.7.1. RXHLTTST ΓòÉΓòÉΓòÉ
  2523.  
  2524.  
  2525. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXHLTTST ΓòÉΓòÉΓòÉ
  2526.  
  2527. Test HALT indicator. 
  2528.  
  2529.       When called: When the interpreter polls externally raised HALT 
  2530.       conditions. The exit is called after completion of every REXX 
  2531.       instruction. 
  2532.  
  2533.       Default action: The interpreter uses the system facilities for trapping 
  2534.       Cntrl-Break signals. 
  2535.  
  2536.       Exit Action: Return the current state of the HALT condition (either TRUE 
  2537.       or FALSE). 
  2538.  
  2539.       Continuation: Raise the REXX HALT condition if the exit handler returns 
  2540.       TRUE. 
  2541.  
  2542.  
  2543. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXHLTTST ΓòÉΓòÉΓòÉ
  2544.  
  2545. typedef struct {
  2546.    struct {                            /* Halt flag                   */
  2547.       unsigned rxfhhalt : 1;           /* Set if HALT occurred.       */
  2548.    } rxhlt_flags;
  2549. } RXHLTTST_PARM;
  2550.  
  2551. If the exit handler sets rxfhhalt to TRUE, the HALT condition will be raised in 
  2552. the REXX program. 
  2553.  
  2554. When the exit handler has set rxfhhalt to TRUE, it can also use the RXSHV_EXIT 
  2555. operation of RexxVariablePool to return a string describing the HALT condition 
  2556. reason. The REXX program can retrieve the reason string using the 
  2557. CONDITION("D") built-in function. 
  2558.  
  2559.  
  2560. ΓòÉΓòÉΓòÉ 11.7.2. RXHLTCLR ΓòÉΓòÉΓòÉ
  2561.  
  2562.  
  2563. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXHLTCLR ΓòÉΓòÉΓòÉ
  2564.  
  2565. Clear HALT condition. 
  2566.  
  2567.       When called: To acknowledge processing of the HALT condition when the 
  2568.       interpreter has recognized and raised a HALT condition 
  2569.  
  2570.       Default action: The interpreter resets the Cntrl-Break signal handlers. 
  2571.  
  2572.       Exit Action: Reset exit handler HALT state to FALSE. 
  2573.  
  2574.  
  2575. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXHLTCLR ΓòÉΓòÉΓòÉ
  2576.  
  2577. (None) 
  2578.  
  2579.  
  2580. ΓòÉΓòÉΓòÉ 11.8. RXTRC ΓòÉΓòÉΓòÉ
  2581.  
  2582. Test external trace indicator. 
  2583.  
  2584. The RXTRC exit has the following subfunction: 
  2585.  
  2586.  RXTRCTST    Test external trace indicator. 
  2587.  
  2588.  Note:  Since the RXTST exit is called after every REXX instruction, these 
  2589.         exits will slow REXX procedure execution. The RexxSetTrace function can 
  2590.         turn on REXX tracing without between-instruction polling. 
  2591.  
  2592.  
  2593. ΓòÉΓòÉΓòÉ 11.8.1. RXTRCTST ΓòÉΓòÉΓòÉ
  2594.  
  2595.  
  2596. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXTRCTST ΓòÉΓòÉΓòÉ
  2597.  
  2598. Test external trace indicator. 
  2599.  
  2600.       When called: When the interpreter polls poll for an external trace event. 
  2601.       The exit is called after completion of every REXX instruction. 
  2602.  
  2603.       Default action: None. 
  2604.  
  2605.       Exit Action: Return the current state of external tracing (either TRUE or 
  2606.       FALSE). 
  2607.  
  2608.       Continuation: When the exit handler switches from FALSE to TRUE, the REXX 
  2609.       interpreter enters REXX interactive debug mode using TRACE ?R level of 
  2610.       tracing. When the exit handler switches from TRUE to FALSE, the REXX 
  2611.       interpreter will exit interactived debug mode. 
  2612.  
  2613.  
  2614. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXTRCTST ΓòÉΓòÉΓòÉ
  2615.  
  2616. struct rxtrc_parm {
  2617.   struct {
  2618.     unsigned rxftrace : 1;        /* External trace setting        */
  2619.   } rxtrc_flags;
  2620. }
  2621.  
  2622. If the exit handler switches rxftrace to TRUE, REXX will switch on interactive 
  2623. debug mode. It the exit handler switches rxftrace to FALSE, REXX will switch 
  2624. off interactive debug mode. 
  2625.  
  2626.  
  2627. ΓòÉΓòÉΓòÉ 11.9. RXINI ΓòÉΓòÉΓòÉ
  2628.  
  2629. Initialization processing. 
  2630.  
  2631. The RXINT exit has the following subfunction: 
  2632.  
  2633.  RXINIEXT    Initialization exit. 
  2634.  
  2635.  
  2636. ΓòÉΓòÉΓòÉ 11.9.1. RXINIEXT ΓòÉΓòÉΓòÉ
  2637.  
  2638.  
  2639. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXINIEXT ΓòÉΓòÉΓòÉ
  2640.  
  2641. Initialization exit. 
  2642.  
  2643. The RXINI exit is called as the last step of REXX program initialization. The 
  2644. exit handler can perform additional initialization. For example: 
  2645.  
  2646.    o  Use RexxVariablePool to initialize application specific variables 
  2647.  
  2648.    o  Use RexxSetTrace to switch on REXX interactive debug mode. 
  2649.  
  2650.       When called: Before the first instruction of the REXX procedure is 
  2651.       interpreted. 
  2652.  
  2653.       Default action: None. 
  2654.  
  2655.       Exit Action: The exit handler can perform additional initialization. For 
  2656.       example: 
  2657.  
  2658.         o  Use RexxVariablePool to initialize application specific variables 
  2659.  
  2660.         o  Use RexxSetTrace to switch on REXX interactive debug mode. 
  2661.  
  2662.       Note:  The variable pool interface is fully enabled for this exit. 
  2663.  
  2664.  
  2665. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXINIEXT ΓòÉΓòÉΓòÉ
  2666.  
  2667. (None) 
  2668.  
  2669.  
  2670. ΓòÉΓòÉΓòÉ 11.10. RXTER ΓòÉΓòÉΓòÉ
  2671.  
  2672. Termination processing. 
  2673.  
  2674. The RXTER exit has the following subfunction: 
  2675.  
  2676.  RXTEREXT    Termination exit 
  2677.  
  2678.  
  2679. ΓòÉΓòÉΓòÉ 11.10.1. RXTEREXT ΓòÉΓòÉΓòÉ
  2680.  
  2681.  
  2682. ΓòÉΓòÉΓòÉ <hidden> Characteristics - RXTEREXT ΓòÉΓòÉΓòÉ
  2683.  
  2684. Termination exit 
  2685.  
  2686. the RXTER exit is called as the first step of REXX program termination. 
  2687.  
  2688.       When called: After the last instruction of the REXX procedure has been 
  2689.       interpreted. 
  2690.  
  2691.       Default action: None. 
  2692.  
  2693.       Exit Action: The exit handler can perform additional termination 
  2694.       activities For example, the exit handler can use RexxVariablePool to 
  2695.       retrieve REXX variables values. 
  2696.  
  2697.       Note:  The variable pool interface is fully enabled for this exit. 
  2698.  
  2699.  
  2700. ΓòÉΓòÉΓòÉ <hidden> Parameters - RXTEREXT ΓòÉΓòÉΓòÉ
  2701.  
  2702. (None) 
  2703.  
  2704.  
  2705. ΓòÉΓòÉΓòÉ 12. System Exit Functions ΓòÉΓòÉΓòÉ
  2706.  
  2707.    o  RexxRegisterExitDll registers an exit handler that resides in a dynalink 
  2708.       library routine. 
  2709.  
  2710.    o  RexxRegisterExitExe registers an exit handler that resides within 
  2711.       application code. 
  2712.  
  2713.    o  RexxDeregisterExit deregisters an exit handler. 
  2714.  
  2715.    o  RexxQueryExit queries an exit handler and retrieves saved user 
  2716.       information. 
  2717.  
  2718.  
  2719. ΓòÉΓòÉΓòÉ 12.1. RexxRegisterExitDll ΓòÉΓòÉΓòÉ
  2720.  
  2721.  
  2722. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  2723.  
  2724. Topics: 
  2725.  
  2726.       Call Syntax 
  2727.       Uses 
  2728.       Parameters 
  2729.       Return Values 
  2730.       Errors 
  2731.       Notes 
  2732.       Related Functions 
  2733.  
  2734.  
  2735. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxRegisterExitDll ΓòÉΓòÉΓòÉ
  2736.  
  2737. /*******************************************/
  2738. /* RexxRegisterExitDll registers an       */
  2739. /*  exit handler that resides in a         */
  2740. /*  dynamic link library routine.          */
  2741. /*******************************************/
  2742.  
  2743. #define INCL_RXSYSEXIT      /* Exit handler values */
  2744.  
  2745. PSZ     name;         /* handler name */
  2746. PSZ     library;      /* DLL name     */
  2747. PSZ     routine;      /* routine name */
  2748. ULONG   rc;           /* Return code  */
  2749. ULONG   userdata[2];  /* save userdata*/
  2750.  
  2751. rc = RexxRegisterExitDll(name, library, routine,
  2752.      userdata, RXEXIT_DROPPABLE);
  2753.  
  2754.  
  2755. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxRegisterExitDll ΓòÉΓòÉΓòÉ
  2756.  
  2757. RexxRegisterExitDll registers an exit handler that resides in a dynalink 
  2758. library routine. 
  2759.  
  2760.  
  2761. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxRegisterExitDll ΓòÉΓòÉΓòÉ
  2762.  
  2763. RexxRegisterExitDll (ExitName, ModuleName, EntryPoint, UserArea, DropAuth) 
  2764.  
  2765. Parameters: 
  2766.  
  2767.  EnvName (PSZ) - input 
  2768.     Address of an ASCIIZ exit handler name. 
  2769.  
  2770.  ModuleName (PSZ) - input 
  2771.     Address of an ASCIIZ dynamic link library name. ModuleName is the DLL file 
  2772.     containing the exit handler routine. 
  2773.  
  2774.  EntryPoint (PSZ) - input 
  2775.     Address of an ASCIIZ dynalink procedure name. EntryPoint is the exit 
  2776.     handler routine within ModuleName. 
  2777.  
  2778.  UserArea (PUCHAR) - input 
  2779.     Address of an 8-byte area of user defined information. The 8 bytes 
  2780.     addressed by UserArea will be saved with the exit handler registration. 
  2781.     UserArea can be NULL if there is no user information to save. The saved 
  2782.     user information can be retrieved with the RexxQueryExit function. 
  2783.  
  2784.  DropAuth (ULONG) - input 
  2785.     The drop authority. DropAuth identifies the processes that can deregister 
  2786.     the exit handler. The possible DropAuth values are: 
  2787.  
  2788.       RXEXIT_DROPPABLE 
  2789.          Any process can deregister the exit handler with RexxDeregisterExit. 
  2790.  
  2791.       RXEXIT_NONDROP 
  2792.          Only a thread within the same process as the thread that registered 
  2793.          the handler can deregister the handler with RexxDeregisterExit. 
  2794.  
  2795.  
  2796. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxRegisterExitDll ΓòÉΓòÉΓòÉ
  2797.  
  2798. RexxRegisterExitDll returns the following values: 
  2799.  
  2800.  0         RXEXIT_OK 
  2801.  10        RXEXIT_DUP 
  2802.  1002      RXEXIT_NOEMEM 
  2803.  1003      RXEXIT_BADTYPE 
  2804.  
  2805.  
  2806. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxRegisterExitDll ΓòÉΓòÉΓòÉ
  2807.  
  2808. EntryPoint can be either a 16-bit or a 32-bit routine. REXX will invoke the 
  2809. exit handler in the correct addressing mode. 
  2810.  
  2811.  
  2812. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxRegisterExitDll ΓòÉΓòÉΓòÉ
  2813.  
  2814. The following functions are related to RexxRegisterExitDll: 
  2815.  
  2816.       RexxRegisterExitExe 
  2817.       RexxDeregisterExit 
  2818.       RexxQueryExit 
  2819.  
  2820.  
  2821. ΓòÉΓòÉΓòÉ 12.2. RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2822.  
  2823.  
  2824. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  2825.  
  2826. Topics: 
  2827.  
  2828.       Call Syntax 
  2829.       Uses 
  2830.       Parameters 
  2831.       Return Values 
  2832.       Errors 
  2833.       Notes 
  2834.       Related Functions 
  2835.       Examples 
  2836.  
  2837.  
  2838. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2839.  
  2840. /*******************************************/
  2841. /* RexxRegisterExitDll registers an       */
  2842. /*  exit handler that resides in a         */
  2843. /*  dynamic link library routine.          */
  2844. /*******************************************/
  2845.  
  2846. #define INCL_RXSYSEXITS     /* Exit handler values */
  2847.  
  2848. PSZ     name;         /* handler name */
  2849. PSZ     library;      /* DLL name     */
  2850. PSZ     routine;      /* routine name */
  2851. ULONG   rc;           /* Return code  */
  2852. ULONG   userdata[2];  /* save userdata*/
  2853.  
  2854. rc = RexxRegisterExitDll(name, library, routine,
  2855.      userdata, RXEXIT_DROPPABLE);
  2856.  
  2857.  
  2858. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2859.  
  2860. RexxRegisterExitExe registers an exit handler that resides within application 
  2861. code. 
  2862.  
  2863.  
  2864. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2865.  
  2866. RexxRegisterExitExe (EnvName, EntryPoint, UserArea) 
  2867.  
  2868. Parameters: 
  2869.  
  2870.  EnvName (PSZ) - input 
  2871.     Address of an ASCIIZ exit handler name. 
  2872.  
  2873.  EntryPoint (PFN) - input 
  2874.     Address of the exit handler entry point within the application EXE file. 
  2875.  
  2876.  UserArea (PUCHAR) - input 
  2877.     Address of an 8-byte area of user defined information. The 8 bytes 
  2878.     addressed by UserArea will be saved with the exit handler registration. 
  2879.     UserArea can be NULL if there is no user information to save. The user 
  2880.     information can be retrieved with the RexxQueryExit function. 
  2881.  
  2882.  
  2883. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2884.  
  2885. RexxRegisterExitExe returns the following values: 
  2886.  
  2887.  0         RXEXIT_OK 
  2888.  10        RXEXIT_DUP 
  2889.  30        RXEXIT_NOTREG 
  2890.  1002      RXEXIT_NOEMEM 
  2891.  1003      RXEXIT_BADTYPE 
  2892.  
  2893.  
  2894. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2895.  
  2896. If EnvName has the same name as a handler registered with RexxRegisterExitDll, 
  2897. RexxRegisterExitExe will return RXEXIT_DUP. This is not an error and the new 
  2898. exit handler has been properly registered. 
  2899.  
  2900.  
  2901. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2902.  
  2903. The following functions are related to RexxRegisterExitExe: 
  2904.  
  2905.       RexxRegisterExitDll 
  2906.       RexxDeregisterExit 
  2907.       RexxQueryExit 
  2908.  
  2909.  
  2910. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxRegisterExitExe ΓòÉΓòÉΓòÉ
  2911.  
  2912. The following example shows the use of RexxRegisterExitExe: 
  2913.  
  2914.   WORKAREARECORD  *user_info[2];       /* saved user information     */
  2915.  
  2916.   user_info[0] = global_workarea;      /* save global work area for  */
  2917.   user_info[1] = NULL;                 /* re-entrancy                */
  2918.  
  2919.   rc = RexxRegisterExitExe("IO_Exit",  /* register editor handler    */
  2920.       &Edit_IO_Exit,                   /* located at this address    */
  2921.       user_info);                      /* save global pointer        */
  2922.  
  2923.  
  2924. ΓòÉΓòÉΓòÉ 12.3. RexxDeregisterExit ΓòÉΓòÉΓòÉ
  2925.  
  2926.  
  2927. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  2928.  
  2929. Topics: 
  2930.  
  2931.       Call Syntax 
  2932.       Uses 
  2933.       Parameters 
  2934.       Return Values 
  2935.       Errors 
  2936.       Notes 
  2937.       Related Functions 
  2938.  
  2939.  
  2940. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxDeregisterExit ΓòÉΓòÉΓòÉ
  2941.  
  2942. /*******************************************/
  2943. /* RexxDeregisterExit deregisters an       */
  2944. /*  exit handler.                          */
  2945. /*******************************************/
  2946.  
  2947. #define INCL_RXSYSEXIT      /* Exit handler values */
  2948.  
  2949. PSZ     name;       /* handler name       */
  2950. PSZ     library     /* handler dll        */
  2951. ULONG   rc;         /* Return code */
  2952.  
  2953. rc = RexxDeregisterExit(name, library);
  2954.  
  2955.  
  2956. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxDeregisterExit ΓòÉΓòÉΓòÉ
  2957.  
  2958. RexxDeregisterExit deregisters an exit handler. 
  2959.  
  2960.  
  2961. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxDeregisterExit ΓòÉΓòÉΓòÉ
  2962.  
  2963. RexxDeregisterExit (EnvName, ModuleName) 
  2964.  
  2965. Parameters: 
  2966.  
  2967.  EnvName (PSZ) - input 
  2968.     Address of an ASCIIZ exit handler name. 
  2969.  
  2970.  ModuleName (PSZ) - input 
  2971.     Address of an ASCIIZ dynamic link library name. ModuleName restricts the 
  2972.     query to an exit handler within the ModuleName dynamic link library. When 
  2973.     ModuleName is NULL, RexxDeregisterExit searches the RexxRegisterExitExe 
  2974.     exit handler list for a handler within the current process. If 
  2975.     RexxDeregisterExit does not find a RexxRegisterExitExe handler, it will 
  2976.     search the RexxRegisterExitDll exit handler list. 
  2977.  
  2978.  
  2979. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxDeregisterExit ΓòÉΓòÉΓòÉ
  2980.  
  2981. RexxDeregisterExit returns the following values: 
  2982.  
  2983.  0         RXEXIT_OK 
  2984.  30        RXEXIT_NOTREG 
  2985.  40        RXEXIT_NOCANDROP 
  2986.  1003      RXEXIT_BADTYPE 
  2987.  
  2988.  
  2989. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxDeregisterExit ΓòÉΓòÉΓòÉ
  2990.  
  2991. The handler is removed from the exit handler list. 
  2992.  
  2993.  
  2994. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxDeregisterExit ΓòÉΓòÉΓòÉ
  2995.  
  2996. The following functions are related to RexxDeregisterExit: 
  2997.  
  2998.       RexxRegisterExitDll 
  2999.       RexxRegisterExitExe 
  3000.       RexxQueryExit 
  3001.  
  3002.  
  3003. ΓòÉΓòÉΓòÉ 12.4. RexxQueryExit ΓòÉΓòÉΓòÉ
  3004.  
  3005.  
  3006. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3007.  
  3008. Topics: 
  3009.  
  3010.       Call Syntax 
  3011.       Uses 
  3012.       Parameters 
  3013.       Return Values 
  3014.       Errors 
  3015.       Related Functions 
  3016.       Examples 
  3017.  
  3018.  
  3019. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxQueryExit ΓòÉΓòÉΓòÉ
  3020.  
  3021. /*******************************************/
  3022. /* RexxQueryExit queries an exit          */
  3023. /*  handler and retrieves saved user       */
  3024. /*  information.                           */
  3025. /*******************************************/
  3026.  
  3027. #define INCL_RXSYSEXIT      /* subcommand handler values */
  3028.  
  3029. PSZ     name;         /* handler name */
  3030. PSZ     library;      /* DLL name     */
  3031. ULONG   userdata[2];  /* saved information */
  3032. ULONG   rc;         /* Return code */
  3033.  
  3034. rc = RexxQueryExit(name, library, userdata);
  3035.  
  3036.  
  3037. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxQueryExit ΓòÉΓòÉΓòÉ
  3038.  
  3039. RexxQueryExit queries an exit handler and retrieves saved user information. 
  3040.  
  3041.  
  3042. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxQueryExit ΓòÉΓòÉΓòÉ
  3043.  
  3044. RexxQueryExit (EnvName, ModuleName, Flag, UserWord) 
  3045.  
  3046. Parameters: 
  3047.  
  3048.  EnvName (PSZ) - input 
  3049.     Address of an ASCIIZ exit handler name. 
  3050.  
  3051.  ModuleName (PSZ) - input 
  3052.     ModuleName restricts the query to an exit handler within the ModuleName 
  3053.     dynamic link library. When ModuleName is NULL, RexxQueryExit searches the 
  3054.     RexxRegisterExitExe exit handler list for a handler within the current 
  3055.     process. If RexxQueryExit does not find a RexxRegisterExitExe handler, it 
  3056.     will search the RexxRegisterExitDll exit handler list. 
  3057.  
  3058.  Flag (PUSHORT) - output 
  3059.     Exit handler registration flag. Flag is the EnvName exit handler 
  3060.     registration status. When RexxQueryExit returns RXEXIT_OK, the EnvName exit 
  3061.     handler is currently registered. When RexxQueryExit returns RXEXIT_NOTREG, 
  3062.     the EnvName exit handler is not registered. 
  3063.  
  3064.  Flag (PUSHORT) - output 
  3065.     Exit handler registration flag. Flag indicates if the EnvName exit handler 
  3066.     is registered. If Flag is RXEXIT_OK, the EnvName exit handler is not 
  3067.     registered. If Flag is RXEXIT_NOTREG, the EnvName exit handler is 
  3068.     registered. 
  3069.  
  3070.  UserWord (PUCHAR) - output 
  3071.     Address of an 8-byte area to receive the user information saved with 
  3072.     RexxRegisterExitExe or RexxRegisterExitDll. UserWord can be NULL if the 
  3073.     saved user information is not required. 
  3074.  
  3075.  
  3076. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxQueryExit ΓòÉΓòÉΓòÉ
  3077.  
  3078. RexxQueryExit returns the following values: 
  3079.  
  3080.  0         RXEXIT_OK 
  3081.  30        RXEXIT_NOTREG 
  3082.  1003      RXEXIT_BADTYPE 
  3083.  
  3084.  
  3085. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxQueryExit ΓòÉΓòÉΓòÉ
  3086.  
  3087. The following functions are related to RexxQueryExit: 
  3088.  
  3089.       RexxRegisterExitDll 
  3090.       RexxRegisterExitExe 
  3091.       RexxDeregisterExit 
  3092.  
  3093.  
  3094. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxQueryExit ΓòÉΓòÉΓòÉ
  3095.  
  3096. The following example shows the use of RexxQueryExit: 
  3097.  
  3098. ULONG Edit_IO_Exit(
  3099.   PRXSTRING Command,    /* Command string passed from the caller    */
  3100.   PUSHORT   Flags,      /* pointer to short for return of flags     */
  3101.   PRXSTRING Retstr)     /* pointer to RXSTRING for RC return        */
  3102. {
  3103.   WORKAREARECORD  *user_info[2];       /* saved user information     */
  3104.   WORKAREARECORD   global_workarea;    /* application data anchor    */
  3105.   USHORT           query_flag;         /* flag for handler query     */
  3106.  
  3107.  
  3108.   rc = RexxQueryExit("IO_Exit",        /* retrieve application work  */
  3109.       NULL,                            /* area anchor from REXX.     */
  3110.       &query_flag,
  3111.       user_info);
  3112.  
  3113.   global_workarea = user_info[0];      /* set the global anchor      */
  3114.  
  3115.  
  3116. ΓòÉΓòÉΓòÉ <hidden> System Exit Interface Errors ΓòÉΓòÉΓòÉ
  3117.  
  3118. The following are the exit handler function errors.: 
  3119.  
  3120.  RXEXIT_NOEMEM 
  3121.     There is insufficient memory available to complete this request. 
  3122.  
  3123.  RXEXIT_OK 
  3124.     An exit function has executed successfully. 
  3125.  
  3126.  RXEXIT_DUP 
  3127.     A duplicate exit handler name has been successfully registered; there is 
  3128.     either: 
  3129.  
  3130.    o  an EXE handler with the same name registered in another process, or 
  3131.  
  3132.    o  a DLL handler with the same name registered in another DLL; to address 
  3133.       this exit, its library name must be specified. 
  3134.  
  3135.  RXEXIT_NOTREG 
  3136.     This indicates: 
  3137.  
  3138.    o  registration was unsuccessful due to duplicate handler and dynalink names 
  3139.       (RexxRegisterExitExe or RexxRegisterExitDll) 
  3140.  
  3141.    o  the exit handler is not registered (other REXX exit functions). 
  3142.  
  3143.  RXEXIT_NOCANDROP 
  3144.     The exit handler has been registered as "not droppable". 
  3145.  
  3146.  
  3147. ΓòÉΓòÉΓòÉ 13. Variable Pool Interface ΓòÉΓòÉΓòÉ
  3148.  
  3149. Application programs can use the REXX Variable Pool Interface to manipulate the 
  3150. variables of a currently active REXX procedure. 
  3151.  
  3152.  
  3153. ΓòÉΓòÉΓòÉ 13.1. Interface Types ΓòÉΓòÉΓòÉ
  3154.  
  3155. Three of the Variable Pool Interface functions (set, fetch and drop) have dual 
  3156. interfaces. 
  3157.  
  3158.  
  3159. ΓòÉΓòÉΓòÉ 13.1.1. Symbolic Interface ΓòÉΓòÉΓòÉ
  3160.  
  3161. The symbolic interface uses normal REXX variable rules when interpreting 
  3162. variables. Variable names are valid REXX symbols (in mixed case if desired) 
  3163. including compound symbols. Compound symbols will be referenced with tail 
  3164. substitution. The functions that use the symbolic interface are RXSHV_SYSET, 
  3165. RXSHV_SYFET, and RXSHV_SYDRO. 
  3166.  
  3167.  
  3168. ΓòÉΓòÉΓòÉ 13.1.2. Direct Interface ΓòÉΓòÉΓòÉ
  3169.  
  3170. The direct interface uses no substitution or case translation. Simple symbols 
  3171. must be valid REXX variable names. A valid REXX variable name: 
  3172.  
  3173.    o  Does not begin with a digit or period 
  3174.  
  3175.    o  Contains only uppercase A to Z, the digits 0 - 9, or the characters _, ! 
  3176.       or ? before the first period of the name. 
  3177.  
  3178.    o  Can contain any characters after the first period of the name. 
  3179.  
  3180.  Compound variables are specified using the derived name of the variable.  Any 
  3181.  characters (including blanks) can appear after the first period of the name. 
  3182.  No additional variable sustitution is used. The direct interface is used by 
  3183.  RXSHV_SET, RXSHV_FETCH, and RXSHV_DROP. 
  3184.  
  3185.  
  3186. ΓòÉΓòÉΓòÉ 13.2. RexxVariablePool Restrictions ΓòÉΓòÉΓòÉ
  3187.  
  3188. Only the main thread of an application can access the REXX variable pool. 
  3189. Applications can create and use new threads, but only the original thread that 
  3190. called the RexxStart function can use RexxVariablePool. 
  3191.  
  3192. OS/2* operating system EXE modules invoked from a REXX procedure execute in a 
  3193. new process. Because the modules are not using the same process and thread as 
  3194. the REXX procedure, the modules cannot use RexxVariablePool to access REXX 
  3195. variables. RexxVariablePool can be used from subcommand handlers, external 
  3196. functions and exit handlers. 
  3197.  
  3198.  
  3199. ΓòÉΓòÉΓòÉ 14. RexxVariablePool Interface Function ΓòÉΓòÉΓòÉ
  3200.  
  3201. REXX procedure variables are accessed using the RexxVariablePool function. 
  3202.  
  3203.  
  3204. ΓòÉΓòÉΓòÉ 14.1. RexxVariablePool ΓòÉΓòÉΓòÉ
  3205.  
  3206.  
  3207. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3208.  
  3209. Topics: 
  3210.  
  3211.       Call Syntax 
  3212.       Uses 
  3213.       Parameters 
  3214.       Data Structures 
  3215.       Return Values 
  3216.       Notes 
  3217.       Examples 
  3218.  
  3219.  
  3220. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxVariablePool ΓòÉΓòÉΓòÉ
  3221.  
  3222. /*******************************************/
  3223. /* RexxVariablePool accesses variables   */
  3224. /*  of a currently active REXX procedure.  */
  3225. /*******************************************/
  3226.  
  3227. #define INCL_RXSHV    /* Shared variable values */
  3228.  
  3229. SHVBLOCK  request;    /* request block */
  3230. ULONG     rc;         /* Return code */
  3231.  
  3232. rc = RexxVariablePool(&request);
  3233.  
  3234.  
  3235. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxVariablePool ΓòÉΓòÉΓòÉ
  3236.  
  3237. RexxVariablePool accesses variables of a currently active REXX procedure. 
  3238.  
  3239.  
  3240. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxVariablePool ΓòÉΓòÉΓòÉ
  3241.  
  3242. RexxVariablePool (RequestBlockList) 
  3243.  
  3244. Parameters: 
  3245.  
  3246.  RequestBlockList (PSHVBLOCK) - input 
  3247.     A linked list of shared variable request blocks (SHVBLOCK). Each shared 
  3248.     variable request block in the linked list is a separate variable access 
  3249.     request. 
  3250.  
  3251.  
  3252. ΓòÉΓòÉΓòÉ <hidden> Data Structures - RexxVariablePool ΓòÉΓòÉΓòÉ
  3253.  
  3254. typedef struct shvnode {
  3255.     struct shvnode    *shvnext;
  3256.     RXSTRING           shvname;
  3257.     RXSTRING           shvvalue;
  3258.     ULONG              shvnamelen;
  3259.     ULONG              shvvaluelen;
  3260.     UCHAR              shvcode;
  3261.     UCHAR              shvret;
  3262. }   SHVBLOCK;
  3263.  
  3264. Where: 
  3265.  
  3266.  shvnext 
  3267.     The address of the next SHVBLOCK in the request list. shvnext is NULL for 
  3268.     the last request block. 
  3269.  
  3270.  shvcode 
  3271.     The shared variable block request code. The request codes are: 
  3272.  
  3273.       RXSHV_SET 
  3274.  
  3275.       RXSHV_SYSET 
  3276.          Assign a new value to a REXX procedure variable. 
  3277.  
  3278.       RXSHV_FETCH 
  3279.  
  3280.       RXSHV_SYFETCH 
  3281.          Retrieve the value of a REXX procedure variable. 
  3282.  
  3283.       RXSHV_DROPV 
  3284.  
  3285.       RXSHV_SYDRO 
  3286.          Drop (unassign) a REXX procedure variable. 
  3287.  
  3288.       RXSHV_PRIV 
  3289.          Fetch REXX procedure private information. The following information 
  3290.          items can be retrieved by name: 
  3291.  
  3292.            PARM 
  3293.               The number of arguments supplied to the REXX procedure. The 
  3294.               number will be formatted as a character string. 
  3295.  
  3296.            PARM.n 
  3297.               The Nth argument string to the REXX procedure. If the Nth 
  3298.               argument was not supplied to the procedure (either omitted or 
  3299.               fewer than N parameters were specified), a null string will be 
  3300.               returned. 
  3301.  
  3302.            QUENAME 
  3303.               The current REXX data queue name. 
  3304.  
  3305.            SOURCE 
  3306.               The REXX procedure source string used for the PARSE SOURCE 
  3307.               instruction. 
  3308.  
  3309.            VERSION 
  3310.               The REXX interpreter version string used for the PARSE SOURCE 
  3311.               instruction. 
  3312.  
  3313.       RXSHV_NEXTV 
  3314.          Fetch next variable. RXSHV_NEXTV traverses the variables in the 
  3315.          current generation of REXX variables, excluding variables hidden by 
  3316.          PROCEDURE instructions. The variables will not be returned in any 
  3317.          specified order. 
  3318.  
  3319.          The REXX interpreter maintains an internal pointer to its list of 
  3320.          variables. The variable pointers is reset to the first REXX variable 
  3321.          whenever: c. 
  3322.  
  3323.         1. An external program returns control to the interpreter 
  3324.  
  3325.         2. A set, fetch or drop RexxVariablePool function is used. 
  3326.  
  3327.          RXSHV_NEXTV returns both the name and the value of REXX variables 
  3328.          until the end of the variable list is reached. If no REXX variables 
  3329.          are left to return, RexxVariablePool will set the RXSHV_LVAR bit in 
  3330.          shvret. 
  3331.  
  3332.       RXSHV_EXIT 
  3333.          Set a return value for an external function or exit handler. 
  3334.          RXSHV_EXIT is only valid from external functions or exit events that 
  3335.          return a string value. RXSHV_EXIT can only be used once by an external 
  3336.          function or exit handler. 
  3337.  
  3338.  shvret 
  3339.     Individual shared variable request return code. shvret is a 1-byte field of 
  3340.     status flags for the individual shared variable request. The shvret fields 
  3341.     for all request blocks in the list are ORed together to form the 
  3342.     RexxVariablePool return code. The individual status conditions are: 
  3343.  
  3344.       RXSHV_OK 
  3345.          The request was processed with out error (all flag bits are FALSE). 
  3346.  
  3347.       RXSHV_NEWV 
  3348.          The named variable was uninitialized. 
  3349.  
  3350.       RXSHV_LVAR 
  3351.          No more variables are available for an RXSHV_NEXTV operation. 
  3352.  
  3353.       RXSHV_TRUNC 
  3354.          A variable value or variable name was truncated because the supplied 
  3355.          RXSTRING was too small for the copied value. 
  3356.  
  3357.       RXSHV_BADN 
  3358.          The variable name specified in shvname was invalid for the requested 
  3359.          operation. 
  3360.  
  3361.       RXSHV_MEMFL 
  3362.          The REXX interpreter was unable to obtain the storage required to 
  3363.          complete the request. 
  3364.  
  3365.       RXSHV_BADF 
  3366.          The shared variable request block contains an invalid function code. 
  3367.  
  3368.  shvname 
  3369.     An RXSTRING containing a REXX variable name. shvname usage varies for the 
  3370.     different SHVBLOCK request codes: 
  3371.  
  3372.       RXSHV_SET 
  3373.  
  3374.       RXSHV_SYSET 
  3375.  
  3376.       RXSHV_FETCH 
  3377.  
  3378.       RXSHV_SYFET 
  3379.  
  3380.       RXSHV_DROPV 
  3381.  
  3382.       RXSHV_SYDRO 
  3383.  
  3384.       RXSHV_PRIV 
  3385.          shvname is an RXSTRING pointing to the name of the REXX variable 
  3386.          accessed by the shared variable request block. 
  3387.  
  3388.       RXSHV_NEXTV 
  3389.          shvname is an RXSTRING defining an area of storage to receive the name 
  3390.          of the next variable. shvnamelen is the length of the RXSTRING area. 
  3391.          If the variable name is longer than shvnamelen characters, the name 
  3392.          will be truncated and the RXSHV_TRUNC bit of shvret will be set. On 
  3393.          return, shvname.strlength will contain the length of the variable 
  3394.          name; shvnamelen will be unchanged. 
  3395.  
  3396.          If shvname is an empty RXSTRING (strptr is NULL), the REXX interpreter 
  3397.          will allocate and return an RXSTRING to hold the variable name. If the 
  3398.          REXX interpreter allocates the RXSTRING, an RXSHV_TRUNC condition 
  3399.          cannot occur. However, RXSHV_MEMFL errors are possible for these 
  3400.          operations. If an RXSHV_MEMFL condition occurs, memory will not be 
  3401.          allocated for that request block. The RexxVariablePool function caller 
  3402.          must release the storage with "DosFreeMem". 
  3403.  
  3404.          Note:  The RexxVariablePool does not add a terminating null character 
  3405.                 to the variable name. 
  3406.  
  3407.       RXSHV_EXIT 
  3408.          shvname is unused for the RXSHV_EXIT function. 
  3409.  
  3410.  shvvalue 
  3411.     An RXSTRING containing a REXX variable value. shvvalue meaning varies for 
  3412.     the different SHVBLOCK request codes: 
  3413.  
  3414.       RXSHV_SET 
  3415.  
  3416.       RXSHV_SYSET 
  3417.          shvvalue is the value assigned to the REXX variable in shvname. 
  3418.          shvvaluelen contains the length of the variable value. 
  3419.  
  3420.       RXSHV_EXIT 
  3421.          shvvalue is the value assigned to the exit handler return value. 
  3422.          shvvaluelen contains the length of the variable value. 
  3423.  
  3424.       RXSHV_FETCH 
  3425.  
  3426.       RXSHV_SYFET 
  3427.  
  3428.       RXSHV_PRIV 
  3429.  
  3430.       RXSHV_NEXT 
  3431.          shvvalue is a buffer the REXX interpreter uses to return a copy of 
  3432.          REXX variable shvname. shvvaluelen contains the length of the value 
  3433.          buffer. On return, shvvalue.strlength will be set to the length of the 
  3434.          returned value and shvvaluelen will be unchanged. If the variable 
  3435.          value is longer than shvvaluelen characters, the value will be 
  3436.          truncated and the RXSHV_TRUNC bit of shvret will be set. On return, 
  3437.          shvvalue.strlength will be set to the length of the returned value; 
  3438.          shvvaluelen will be unchanged. 
  3439.  
  3440.          If shvvalue is an empty RXSTRING (strptr is NULL), the REXX 
  3441.          interpreter will allocate and return an RXSTRING to hold the variable 
  3442.          value. If the REXX interpreter allocates the RXSTRING, an RXSHV_TRUNC 
  3443.          condition cannot occur. However, RXSHV_MEMFL errors are possible for 
  3444.          these operations. If an RXSHV_MEMFL condition occurs, memory will not 
  3445.          be allocated for that request block. The RexxVariablePool function 
  3446.          caller must release the storage with "DosFreeMem". 
  3447.  
  3448.          Note:  RexxVariablePool does not add a terminating null character to 
  3449.                 the variable value. 
  3450.  
  3451.       RXSHV_DROPV 
  3452.  
  3453.       RXSHV_SYDRO 
  3454.          shvvalue is not used. 
  3455.  
  3456.  
  3457. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxVariablePool ΓòÉΓòÉΓòÉ
  3458.  
  3459. RexxVariablePool returns the following values: 
  3460.  
  3461.  0 to 127 
  3462.     RexxVariablePool has processed the entire shared variable request block 
  3463.     list. 
  3464.  
  3465.     The RexxVariablePool function return code is a composite return code for 
  3466.     the entire set of shared variable requests. The low-order 6 bits of the the 
  3467.     shvret fields for all request blocks are ORed together to form the 
  3468.     composite return code. Individual shared variable request status flags are 
  3469.     returned in the shared variable request block shvret field. 
  3470.  
  3471.  RXSHV_NOAVL 
  3472.     The variable pool interface was not enabled. 
  3473.  
  3474.  
  3475. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxVariablePool ΓòÉΓòÉΓòÉ
  3476.  
  3477. The REXX interpreter processes each request block in the order provided; the 
  3478. RexxVariablePool function returns when the last block is processed or after a 
  3479. severe error (such as an out-of-memory condition). 
  3480.  
  3481. The RexxVariablePool function return code is a composite return code for the 
  3482. entire set of shared variable requests. The return codes for all of the 
  3483. individual requests are ORed together to form the composite return code. 
  3484. Individual shared variable request return code are returned in the request 
  3485. shared variable blocks. 
  3486.  
  3487.  
  3488. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxVariablePool ΓòÉΓòÉΓòÉ
  3489.  
  3490. /*********************************************************************/
  3491. /*                                                                   */
  3492. /* SetRexxVariable - Set the value of a REXX variable                */
  3493. /*                                                                   */
  3494. /*********************************************************************/
  3495.  
  3496. INT SetRexxVariable(
  3497.   PSZ        name,                     /* REXX variable to set       */
  3498.   PSZ        value);                   /* value to assign            */
  3499. {
  3500.   SHVBLOCK   block;                    /* variable pool control block*/
  3501.  
  3502.   block.shvcode = RXSHV_SYSET;         /* do a symbolic set operation*/
  3503.   block.shvret=(UCHAR)0;               /* clear return code field    */
  3504.   block.shvnext=(PSHVBLOCK)0;          /* no next block              */
  3505.                                        /* set variable name string   */
  3506.   MAKERXSTRING(block.shvname, name, strlen(name));
  3507.                                        /* set value string           */
  3508.   MAKERXSTRING(block.shvvalue, value, strlen(value));
  3509.   block.shvvaluelen=strlen(value);     /* set value length           */
  3510.   return RexxVariablePool(&block);     /* set the variable           */
  3511. }
  3512.  
  3513.  
  3514. ΓòÉΓòÉΓòÉ 15. Halt and Trace Interface ΓòÉΓòÉΓòÉ
  3515.  
  3516. The halt and trace functions raise a REXX HALT condition or change the REXX 
  3517. interactive debug mode while a REXX procedure is running. These interfaces may 
  3518. be preferred over the RXHLT and RXTRC system exits. The REXX calls the RXTRC 
  3519. exit handler after each REXX instruction completes. This might cause a 
  3520. noticable performance degradation. The Halt and Trace functions are a single 
  3521. request to change the halt or trace state, and do not degrade the REXX 
  3522. procedure performance. 
  3523.  
  3524.    o  RexxSetHalt raises a HALT condition in a running REXX program. 
  3525.  
  3526.    o  RexxSetTrace turns on interactive debug mode for a REXX procedure. 
  3527.  
  3528.    o  RexxResetTrace turns off interactive debug mode for a REXX procedure. 
  3529.  
  3530.  
  3531. ΓòÉΓòÉΓòÉ 16. Halt and Trace Functions ΓòÉΓòÉΓòÉ
  3532.  
  3533.    o  RexxSetHalt raises a HALT condition in a running REXX program. 
  3534.  
  3535.    o  RexxSetTrace turns on interactive debug mode for a REXX procedure. 
  3536.  
  3537.    o  RexxResetTrace turns off interactive debug mode for a REXX procedure. 
  3538.  
  3539.  
  3540. ΓòÉΓòÉΓòÉ 16.1. RexxSetHalt ΓòÉΓòÉΓòÉ
  3541.  
  3542.  
  3543. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3544.  
  3545. Topics: 
  3546.  
  3547.       Call Syntax 
  3548.       Uses 
  3549.       Parameters 
  3550.       Return Values 
  3551.       Notes 
  3552.  
  3553.  
  3554. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxSetHalt ΓòÉΓòÉΓòÉ
  3555.  
  3556. /*******************************************/
  3557. /* RexxSetHalt raises a HALT condition    */
  3558. /*  in a running REXX program.             */
  3559. /*******************************************/
  3560.  
  3561. #define INCL_RXARI     /* Halt and Trace values */
  3562.  
  3563. TID     ThreadId;   /* Thread of REXX program  */
  3564. PID     ProcessId;  /* Process of REXX program */
  3565. ULONG   rc;         /* Return code             */
  3566.  
  3567. rc = RexxSetHalt(ProcessId, ThreadId);
  3568.  
  3569.  
  3570. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxSetHalt ΓòÉΓòÉΓòÉ
  3571.  
  3572. RexxSetHalt raises a HALT condition in a running REXX program. 
  3573.  
  3574.  
  3575. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxSetHalt ΓòÉΓòÉΓòÉ
  3576.  
  3577. RexxSetHalt (ProcessId, ThreadId) 
  3578.  
  3579. Parameters: 
  3580.  
  3581.  ProcessId (PID) - input 
  3582.     The process ID of the target REXX procedure. ProcessId is the application 
  3583.     process that called the RexxStart function. 
  3584.  
  3585.  ThreadId (TID) - input 
  3586.     The thread ID of the target REXX procedure. ThreadId is the application 
  3587.     thread that called the RexxStart function. 
  3588.  
  3589.  
  3590. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxSetHalt ΓòÉΓòÉΓòÉ
  3591.  
  3592. RexxSetHalt returns the following values: 
  3593.  
  3594.  0         RXARI_OK 
  3595.  1         RXARI_PID_TID_NOT_FOUND 
  3596.  2         RXARI_PROCESSING_ERROR 
  3597.  
  3598.  
  3599. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxSetHalt ΓòÉΓòÉΓòÉ
  3600.  
  3601. This function will not be processed if the target REXX program is executing 
  3602. with the RXHLT exit enabled. 
  3603.  
  3604.  
  3605. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxSetHalt ΓòÉΓòÉΓòÉ
  3606.  
  3607. The following functions are related to RexxSetHalt: 
  3608.  
  3609.       RexxSetTrace 
  3610.       RexxResetTrace 
  3611.  
  3612.  
  3613. ΓòÉΓòÉΓòÉ 16.2. RexxSetTrace ΓòÉΓòÉΓòÉ
  3614.  
  3615.  
  3616. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3617.  
  3618. Topics: 
  3619.  
  3620.       Call Syntax 
  3621.       Uses 
  3622.       Parameters 
  3623.       Return Values 
  3624.       Notes 
  3625.  
  3626.  
  3627. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxSetTrace ΓòÉΓòÉΓòÉ
  3628.  
  3629. /*******************************************/
  3630. /* RexxSetTrace turns on interactive      */
  3631. /*  debug mode for REXX procedure.         */
  3632. /*******************************************/
  3633.  
  3634. #define INCL_RXARI     /* Halt and Trace values */
  3635.  
  3636. TID     ThreadId;   /* Thread of REXX program  */
  3637. PID     ProcessId;  /* Process of REXX program */
  3638. ULONG   rc;         /* Return code             */
  3639.  
  3640. rc = RexxSetTrace(ProcessId, ThreadId);
  3641.  
  3642.  
  3643. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxSetTrace ΓòÉΓòÉΓòÉ
  3644.  
  3645. RexxSetTrace turns on interactive debug mode for a REXX procedure. 
  3646.  
  3647.  
  3648. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxSetTrace ΓòÉΓòÉΓòÉ
  3649.  
  3650. RexxSetTrace (ProcessId, ThreadId) 
  3651.  
  3652. Parameters: 
  3653.  
  3654.  ProcessId (PID) - input 
  3655.     The process ID of the target REXX procedure. ProcessId is the application 
  3656.     process that called the RexxStart function. 
  3657.  
  3658.  ThreadId (TID) - input 
  3659.     The thread ID of the target REXX procedure. ThreadId is the application 
  3660.     thread that called the RexxStart function. 
  3661.  
  3662.  
  3663. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxSetTrace ΓòÉΓòÉΓòÉ
  3664.  
  3665. RexxSetTrace returns the following values: 
  3666.  
  3667.  0         RXARI_OK 
  3668.  1         RXARI_PID_TID_NOT_FOUND 
  3669.  2         RXARI_PROCESSING_ERROR 
  3670.  
  3671.  
  3672. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxSetTrace ΓòÉΓòÉΓòÉ
  3673.  
  3674. The RexxSetTrace function is not processed if the REXX procedure is using the 
  3675. RXTRC exit. 
  3676.  
  3677.  
  3678. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxSetTrace ΓòÉΓòÉΓòÉ
  3679.  
  3680. The following functions are related to RexxSetTrace: 
  3681.  
  3682.       RexxSetHalt 
  3683.       RexxResetTrace 
  3684.  
  3685.  
  3686. ΓòÉΓòÉΓòÉ 16.3. RexxResetTrace ΓòÉΓòÉΓòÉ
  3687.  
  3688.  
  3689. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3690.  
  3691. Topics: 
  3692.  
  3693.       Call Syntax 
  3694.       Uses 
  3695.       Parameters 
  3696.       Return Values 
  3697.       Notes 
  3698.  
  3699.  
  3700. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxResetTrace ΓòÉΓòÉΓòÉ
  3701.  
  3702. /*******************************************/
  3703. /* RexxResetTrace turns off interactive   */
  3704. /*  debug mode for REXX procedure.         */
  3705. /*******************************************/
  3706.  
  3707. #define INCL_RXARI     /* Halt and Trace values */
  3708.  
  3709. TID     ThreadId;   /* Thread of REXX program  */
  3710. PID     ProcessId;  /* Process of REXX program */
  3711. ULONG   rc;         /* Return code             */
  3712.  
  3713. rc = RexxResetTrace(ProcessId, ThreadId);
  3714.  
  3715.  
  3716. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxResetTrace ΓòÉΓòÉΓòÉ
  3717.  
  3718. RexxResetTrace turns off interactive debug mode for a REXX procedure. 
  3719.  
  3720.  
  3721. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxResetTrace ΓòÉΓòÉΓòÉ
  3722.  
  3723. RexxResetTrace (ProcessId,ThreadId) 
  3724.  
  3725. Parameters: 
  3726.  
  3727.  ProcessId (PID) - input 
  3728.     The process ID of the target REXX procedure. ProcessId is the application 
  3729.     process that called the RexxStart function. 
  3730.  
  3731.  ThreadId (TID) - input 
  3732.     The thread ID of the target REXX procedure. The thread ID of the target 
  3733.     REXX procedure. ThreadId is the application thread that called the 
  3734.     RexxStart function. 
  3735.  
  3736.  
  3737. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxResetTrace ΓòÉΓòÉΓòÉ
  3738.  
  3739. RexxResetTrace returns the following values: 
  3740.  
  3741.  0         RXARI_OK 
  3742.  1         RXARI_PID_TID_NOT_FOUND 
  3743.  2         RXARI_PROCESSING_ERROR 
  3744.  
  3745.  
  3746. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxResetTrace ΓòÉΓòÉΓòÉ
  3747.  
  3748. The RexxResetTrace function is not processed if the REXX procedure is using the 
  3749. RXTRC exit. 
  3750.  
  3751. Interactive debug will not be turned off unless interactive debug mode was 
  3752. originally started with RexxSetTrace. 
  3753.  
  3754.  
  3755. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxResetTrace ΓòÉΓòÉΓòÉ
  3756.  
  3757. The following functions are related to RexxResetTrace: 
  3758.  
  3759.       RexxSetHalt 
  3760.       RexxSetTrace 
  3761.  
  3762.  
  3763. ΓòÉΓòÉΓòÉ 17. Macrospace Interface ΓòÉΓòÉΓòÉ
  3764.  
  3765. The macrospace can improve the performance of REXX procedures by maintaining 
  3766. REXX procecure images in memory for immediate load and execution. This is 
  3767. useful for frequently used procedures and functions such as editor macros. 
  3768.  
  3769. Programs registered in the REXX macrospace are available to all processes. They 
  3770. can be executed using the RexxStart function or called as functions or 
  3771. subroutines from other REXX procedures. 
  3772.  
  3773. Macrospace procedures are called as other REXX external functions are called. 
  3774. However, the macrospace REXX procedures can be placed at the front or at the 
  3775. end of the external function search order. 
  3776.  
  3777. REXX procedures in the macrospace can be saved to a disk file. A saved 
  3778. macrospace file can be reloaded with the RexxLoadMacroSpace function. An 
  3779. application, such as an editor, can create a library of frequently-used 
  3780. functions and load the library into the macrospace for fast access. Multiple 
  3781. macrospace libraries can be created and loaded. 
  3782. Search Order 
  3783.  
  3784. When RexxAddMacro loads a REXX procecure into the macrospace, the position in 
  3785. the external function search order is specified. The REXX procedure can be 
  3786. placed before all other forms of external function or after all other external 
  3787. functions. 
  3788.  
  3789.  RXMACRO_SEARCH_BEFORE A function registered with RXMACRO_SEARCH_BEFORE will be 
  3790.            located by the REXX interpreter before any registered functions or 
  3791.            external REXX files. 
  3792.  
  3793.  SEARCH_AFTER Function Registration A function registered with 
  3794.            RXMACRO_SEARCH_AFTER will be located by the REXX interpreter after 
  3795.            any registered functions or external REXX files. 
  3796.  
  3797.  Storage of Macrospace Libraries 
  3798.  
  3799.  Note:  The REXX macrospace is placed in shared memory. The size of the 
  3800.         macrospace is only limited by the amount of memory and swap space 
  3801.         available to the system. However, as the macrospace grows, it limits 
  3802.         the memory available to other processes in the system. Allowing the 
  3803.         macrospace to grow too large might degrade overall system performance 
  3804.         due to increased system swap file access. It is recommended that only 
  3805.         the most frequently used functions be placed in the macrospace. 
  3806.  
  3807.  
  3808. ΓòÉΓòÉΓòÉ 18. Macrospace Interface Functions ΓòÉΓòÉΓòÉ
  3809.  
  3810.    o  RexxAddMacro loads a REXX procedure into the macrospace. 
  3811.  
  3812.    o  RexxDropMacro removes a REXX procedure from the macrospace. 
  3813.  
  3814.    o  RexxClearMacroSpace removes all loaded REXX procedures from the 
  3815.       macrospace. 
  3816.  
  3817.    o  RexxSaveMacroSpace saves all or part of the macrospace REXX procedures 
  3818.  
  3819.    o  RexxLoadMacroSpace loads all or part of the REXX procedures from a saved 
  3820.       macrospace file. 
  3821.  
  3822.    o  RexxQueryMacro searches the macrospace for a specified function. 
  3823.  
  3824.    o  RexxReorderMacro changes the search order position of a loaded macrospace 
  3825.  
  3826.  
  3827. ΓòÉΓòÉΓòÉ 18.1. RexxAddMacro ΓòÉΓòÉΓòÉ
  3828.  
  3829.  
  3830. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3831.  
  3832. Topics: 
  3833.  
  3834.       Call Syntax 
  3835.       Uses 
  3836.       Parameters 
  3837.       Return Values 
  3838.       Errors 
  3839.       Related Functions 
  3840.       Examples 
  3841.  
  3842.  
  3843. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxAddMacro ΓòÉΓòÉΓòÉ
  3844.  
  3845. /*******************************************/
  3846. /* RexxAddMacro loads a REXX procedure    */
  3847. /*  into the macrospace.                   */
  3848. /*******************************************/
  3849.  
  3850. #define INCL_RXMACRO    /* Macrospace values */
  3851.  
  3852. PSZ     name;       /* function name      */
  3853. PSZ     file;       /* REXX source file   */
  3854. ULONG   rc;         /* Return code        */
  3855.  
  3856. rc = RexxAddMacro(name, file, RXMACRO_SEARCH_BEFORE);
  3857.  
  3858.  
  3859. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxAddMacro ΓòÉΓòÉΓòÉ
  3860.  
  3861. RexxAddMacro loads a REXX procedure into the macrospace. 
  3862.  
  3863.  
  3864. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxAddMacro ΓòÉΓòÉΓòÉ
  3865.  
  3866. RexxAddMacro (FuncName, SourceFile, Position) 
  3867.  
  3868. Parameters: 
  3869.  
  3870.  FuncName (PSZ) - input 
  3871.  
  3872.     Address of the ASCIIZ function name. Macrospace REXX procedures are called 
  3873.     using FuncName. 
  3874.  
  3875.  SourceFile (PSZ) - input 
  3876.     Address of the ASCIIZ file specification for the REXX procedure source 
  3877.     file. When a file extension is not supplied, .CMD is used. When the full 
  3878.     path is not specified, the current directory and path is searched. 
  3879.  
  3880.  Position (ULONG) - input 
  3881.     Position in the REXX external function search order. Possible values are: 
  3882.  
  3883.       RXMACRO_SEARCH_BEFORE 
  3884.          The function will be located by the REXX interpreter before any 
  3885.          registered functions or external REXX files. 
  3886.  
  3887.       RXMACRO_SEARCH_AFTER 
  3888.          The function will be located by the REXX interpreter after any 
  3889.          registered functions or external REXX files. 
  3890.  
  3891.  
  3892. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxAddMacro ΓòÉΓòÉΓòÉ
  3893.  
  3894. RexxAddMacro returns the following values: 
  3895.  
  3896.  0         RXMACRO_OK 
  3897.  1         RXMACRO_NO_STORAGE 
  3898.  7         RXMACRO_SOURCE_NOT_FOUND 
  3899.  8         RXMACRO_INVALID_POSITION 
  3900.  
  3901.  
  3902. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxAddMacro ΓòÉΓòÉΓòÉ
  3903.  
  3904. The following functions are related to RexxAddMacro: 
  3905.  
  3906.       RexxDropMacro 
  3907.       RexxClearMacroSpace 
  3908.       RexxSaveMacroSpace 
  3909.       RexxLoadMacroSpace 
  3910.       RexxQueryMacro 
  3911.       RexxReorderMacro 
  3912.  
  3913.  
  3914. ΓòÉΓòÉΓòÉ 18.2. RexxDropMacro ΓòÉΓòÉΓòÉ
  3915.  
  3916.  
  3917. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3918.  
  3919. Topics: 
  3920.  
  3921.       Call Syntax 
  3922.       Uses 
  3923.       Parameters 
  3924.       Return Values 
  3925.       Errors 
  3926.       Related Functions 
  3927.  
  3928.  
  3929. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxDropMacro ΓòÉΓòÉΓòÉ
  3930.  
  3931. /*******************************************/
  3932. /* RexxDropMacro removes a REXX           */
  3933. /*  procedure from the macrospace.         */
  3934. /*******************************************/
  3935.  
  3936. #define INCL_RXMACRO    /* Macrospace values */
  3937.  
  3938. PSZ     name;       /* function name      */
  3939. ULONG   rc;         /* Return code        */
  3940.  
  3941. rc = RexxDropMacro(name);
  3942.  
  3943.  
  3944. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxDropMacro ΓòÉΓòÉΓòÉ
  3945.  
  3946. RexxDropMacro removes a REXX procedure from the macrospace. 
  3947.  
  3948.  
  3949. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxDropMacro ΓòÉΓòÉΓòÉ
  3950.  
  3951. RexxDropMacro (FuncName) 
  3952.  
  3953. Parameters: 
  3954.  
  3955.  FuncName (PSZ) - input 
  3956.     Address of the ASCIIZ function name. 
  3957.  
  3958.  
  3959. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxDropMacro ΓòÉΓòÉΓòÉ
  3960.  
  3961. RexxDropMacro returns the following values: 
  3962.  
  3963.  0         RXMACRO_OK 
  3964.  2         RXMACRO_NOT_FOUND 
  3965.  
  3966.  
  3967. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxDropMacro ΓòÉΓòÉΓòÉ
  3968.  
  3969. The following functions are related to RexxDropMacro: 
  3970.  
  3971.       RexxAddMacro 
  3972.       RexxClearMacroSpace 
  3973.       RexxSaveMacroSpace 
  3974.       RexxLoadMacroSpace 
  3975.       RexxQueryMacro 
  3976.       RexxReorderMacro 
  3977.  
  3978.  
  3979. ΓòÉΓòÉΓòÉ 18.3. RexxClearMacroSpace ΓòÉΓòÉΓòÉ
  3980.  
  3981.  
  3982. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  3983.  
  3984. Topics: 
  3985.  
  3986.       Call Syntax 
  3987.       Uses 
  3988.       Parameters 
  3989.       Return Values 
  3990.       Errors 
  3991.       Notes 
  3992.       Related Functions 
  3993.  
  3994.  
  3995. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxClearMacroSpace ΓòÉΓòÉΓòÉ
  3996.  
  3997. /*******************************************/
  3998. /* RexxClearMacroSpace removes all        */
  3999. /*  REXX procedures from the macrospace    */
  4000. /*******************************************/
  4001.  
  4002. #define INCL_RXMACRO    /* Macrospace values */
  4003.  
  4004. ULONG   rc;         /* Return code        */
  4005.  
  4006. rc = RexxClearMacroSpace();
  4007.  
  4008.  
  4009. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxClearMacroSpace ΓòÉΓòÉΓòÉ
  4010.  
  4011. RexxClearMacroSpace removes all loaded REXX procedures from the macrospace. 
  4012.  
  4013.  
  4014. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxClearMacroSpace ΓòÉΓòÉΓòÉ
  4015.  
  4016. RexxClearMacroSpace () 
  4017.  
  4018. Parameters: 
  4019.  
  4020. (None) 
  4021.  
  4022.  
  4023. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxClearMacroSpace ΓòÉΓòÉΓòÉ
  4024.  
  4025. RexxClearMacroSpace returns the following values: 
  4026.  
  4027.  0         RXMACRO_OK 
  4028.  2         RXMACRO_NOT_FOUND 
  4029.  
  4030.  
  4031. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxClearMacroSpace ΓòÉΓòÉΓòÉ
  4032.  
  4033. RexxClearMacroSpace must be used with care. This function will remove all 
  4034. functions from the macrospace, including functions loaded by other processes. 
  4035.  
  4036.  
  4037. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxClearMacroSpace ΓòÉΓòÉΓòÉ
  4038.  
  4039. The following functions are related to RexxClearMacroSpace: 
  4040.  
  4041.       RexxAddMacro 
  4042.       RexxDropMacro 
  4043.       RexxSaveMacroSpace 
  4044.       RexxLoadMacroSpace 
  4045.       RexxQueryMacro 
  4046.       RexxReorderMacro 
  4047.  
  4048.  
  4049. ΓòÉΓòÉΓòÉ 18.4. RexxSaveMacroSpace ΓòÉΓòÉΓòÉ
  4050.  
  4051.  
  4052. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  4053.  
  4054. Topics: 
  4055.  
  4056.       Call Syntax 
  4057.       Uses 
  4058.       Parameters 
  4059.       Return Values 
  4060.       Errors 
  4061.       Notes 
  4062.       Related Functions 
  4063.       Examples 
  4064.  
  4065.  
  4066. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxSaveMacroSpace ΓòÉΓòÉΓòÉ
  4067.  
  4068. /*******************************************/
  4069. /* RexxSaveMacroSpace saves all or part   */
  4070. /*  of the macrospace REXX procedures      */
  4071. /*******************************************/
  4072.  
  4073. #define INCL_RXMACRO    /* Macrospace values */
  4074.  
  4075. PSZ     macrolist;  /* list of macros     */
  4076. ULONG   count;      /* size of macrolist  */
  4077. PSZ     file;       /* name of savefile   */
  4078. ULONG   rc;         /* Return code        */
  4079.  
  4080. rc = RexxSaveMacroSpace(count, macrolist, file);
  4081.  
  4082.  
  4083. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxSaveMacroSpace ΓòÉΓòÉΓòÉ
  4084.  
  4085. RexxSaveMacroSpace saves all or part of the macrospace REXX procedures to a 
  4086. disk file. 
  4087.  
  4088.  
  4089. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxSaveMacroSpace ΓòÉΓòÉΓòÉ
  4090.  
  4091. RexxSaveMacroSpace (FuncCount, FuncNames, MacroLibFile) 
  4092.  
  4093. Parameters: 
  4094.  
  4095.  FuncCount (ULONG) - input 
  4096.     Number of REXX procedures to save. 
  4097.  
  4098.  FuncNames (PSZ *) - input 
  4099.     Address of a list of ASCIIZ function names. FuncCount gives the size of the 
  4100.     function list. 
  4101.  
  4102.  MacroLibFile (PSZ) - input 
  4103.     Address of the ASCIIZ macrospace file name. If MacroLibFile already exists, 
  4104.     it is replaced with the new file. 
  4105.  
  4106.  
  4107. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxSaveMacroSpace ΓòÉΓòÉΓòÉ
  4108.  
  4109. RexxSaveMacroSpace returns the following values: 
  4110.  
  4111.  0         RXMACRO_OK 
  4112.  2         RXMACRO_NOT_FOUND 
  4113.  3         RXMACRO_EXTENSION_REQUIRED 
  4114.  5         RXMACRO_FILE_ERROR 
  4115.  
  4116.  
  4117. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxSaveMacroSpace ΓòÉΓòÉΓòÉ
  4118.  
  4119. When FuncCount is 0 or FuncNames is NULL, RexxSaveMacroSpace saves all 
  4120. functions in the macrospace. 
  4121.  
  4122. Saved macrospace files can only be used with the same interpreter version that 
  4123. created the images. If the RexxLoadMacroSpace function is called to load a 
  4124. saved macrospace, and the release level or service level is incorrect, the 
  4125. RexxLoadMacroSpace function will fail. If RexxLoadMacroSpace fails, the REXX 
  4126. procedures must be reloaded individually from the original source programs. 
  4127.  
  4128.  
  4129. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxSaveMacroSpace ΓòÉΓòÉΓòÉ
  4130.  
  4131. The following functions are related to RexxSaveMacroSpace: 
  4132.  
  4133.       RexxAddMacro 
  4134.       RexxDropMacro 
  4135.       RexxClearMacroSpace 
  4136.       RexxLoadMacroSpace 
  4137.       RexxQueryMacro 
  4138.       RexxReorderMacro 
  4139.  
  4140.  
  4141. ΓòÉΓòÉΓòÉ 18.5. RexxLoadMacroSpace ΓòÉΓòÉΓòÉ
  4142.  
  4143.  
  4144. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  4145.  
  4146. Topics: 
  4147.  
  4148.       Call Syntax 
  4149.       Uses 
  4150.       Parameters 
  4151.       Return Values 
  4152.       Errors 
  4153.       Notes 
  4154.       Related Functions 
  4155.       Examples 
  4156.  
  4157.  
  4158. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxLoadMacroSpace ΓòÉΓòÉΓòÉ
  4159.  
  4160. /*******************************************/
  4161. /* RexxLoadMacroSpace loads all or part   */
  4162. /*  of the REXX procedures from a saved    */
  4163. /*  macrospace file.                       */
  4164. /*******************************************/
  4165.  
  4166. #define INCL_RXMACRO    /* Macrospace values */
  4167.  
  4168. PSZ     macrolist;  /* list of macros     */
  4169. ULONG   count;      /* size of macrolist  */
  4170. PSZ     file;       /* name of savefile   */
  4171. ULONG   rc;         /* Return code        */
  4172.  
  4173. rc = RexxLoadMacroSpace(count, macrolist, file);
  4174.  
  4175.  
  4176. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxLoadMacroSpace ΓòÉΓòÉΓòÉ
  4177.  
  4178. RexxLoadMacroSpace loads all or part of the REXX procedures from a saved 
  4179. macrospace file. 
  4180.  
  4181.  
  4182. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxLoadMacroSpace ΓòÉΓòÉΓòÉ
  4183.  
  4184. RexxLoadMacroSpace (FuncCount, FuncNames, MacroLibFile) 
  4185.  
  4186. Parameters: 
  4187.  
  4188.  FuncCount (ULONG) - input 
  4189.     Number of REXX procedures to load from the saved macrospace. 
  4190.  
  4191.  FuncNames (PSZ *) - input 
  4192.     Address of a list of ASCIIZ REXX function names. FuncCount gives the size 
  4193.     of the function list. 
  4194.  
  4195.  MacroLibFile (PSZ) - input 
  4196.     Address of the ASCIIZ saved macrospace file name. 
  4197.  
  4198.  
  4199. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxLoadMacroSpace ΓòÉΓòÉΓòÉ
  4200.  
  4201. RexxLoadMacroSpace returns the following values: 
  4202.  
  4203.  0         RXMACRO_OK 
  4204.  1         RXMACRO_NO_STORAGE 
  4205.  2         RXMACRO_NOT_FOUND 
  4206.  4         RXMACRO_ALREADY_EXISTS 
  4207.  5         RXMACRO_FILE_ERROR 
  4208.  6         RXMACRO_SIGNATURE_ERROR 
  4209.  
  4210.  
  4211. ΓòÉΓòÉΓòÉ <hidden> Notes - RexxLoadMacroSpace ΓòÉΓòÉΓòÉ
  4212.  
  4213. When FuncCount is 0 or FuncNames is NULL, RexxLoadMacroSpace loads all REXX 
  4214. procedures from the saved file. 
  4215.  
  4216. If the RexxLoadMacroSpace function must replace an existing macrospace REXX 
  4217. procedure, the entire load request is discarded and the macrospace remains 
  4218. unchanged. 
  4219.  
  4220.  
  4221. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxLoadMacroSpace ΓòÉΓòÉΓòÉ
  4222.  
  4223. The following functions are related to RexxLoadMacroSpace: 
  4224.  
  4225.       RexxAddMacro 
  4226.       RexxDropMacro 
  4227.       RexxClearMacroSpace 
  4228.       RexxSaveMacroSpace 
  4229.       RexxQueryMacro 
  4230.       RexxReorderMacro 
  4231.  
  4232.  
  4233. ΓòÉΓòÉΓòÉ 18.6. RexxQueryMacro ΓòÉΓòÉΓòÉ
  4234.  
  4235.  
  4236. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  4237.  
  4238. Topics: 
  4239.  
  4240.       Call Syntax 
  4241.       Uses 
  4242.       Parameters 
  4243.       Return Values 
  4244.       Errors 
  4245.       Related Functions 
  4246.       Examples 
  4247.  
  4248.  
  4249. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxQueryMacro ΓòÉΓòÉΓòÉ
  4250.  
  4251. /*******************************************/
  4252. /* RexxQueryMacro searches the            */
  4253. /*  macrospace for a specified function.   */
  4254. /*******************************************/
  4255.  
  4256. #define INCL_RXMACRO    /* Macrospace values */
  4257.  
  4258. PSZ     name;       /* function name         */
  4259. USHORT  position;   /* search order position */
  4260. ULONG   rc;         /* Return code           */
  4261.  
  4262. rc = RexxQueryMacro(name, &position);
  4263.  
  4264.  
  4265. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxQueryMacro ΓòÉΓòÉΓòÉ
  4266.  
  4267. RexxQueryMacro searches the macrospace for a specified function. 
  4268.  
  4269.  
  4270. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxQueryMacro ΓòÉΓòÉΓòÉ
  4271.  
  4272. RexxQueryMacro (FuncName, Position) 
  4273.  
  4274. Parameters: 
  4275.  
  4276.  FuncName (PSZ) - input 
  4277.     Address of an ASCIIZ function name. 
  4278.  
  4279.  Position (PUSHORT) - output 
  4280.     Address of an unsigned short integer flag. If the function is loaded in the 
  4281.     macrospace, Position is set to the current function search-order position. 
  4282.  
  4283.  
  4284. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxQueryMacro ΓòÉΓòÉΓòÉ
  4285.  
  4286. RexxQueryMacro returns the following values: 
  4287.  
  4288.  0         RXMACRO_OK 
  4289.  2         RXMACRO_NOT_FOUND 
  4290.  
  4291.  
  4292. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxQueryMacro ΓòÉΓòÉΓòÉ
  4293.  
  4294. The following functions are related to RexxQueryMacro: 
  4295.  
  4296.       RexxAddMacro 
  4297.       RexxDropMacro 
  4298.       RexxClearMacroSpace 
  4299.       RexxSaveMacroSpace 
  4300.       RexxLoadMacroSpace 
  4301.       RexxReorderMacro 
  4302.  
  4303.  
  4304. ΓòÉΓòÉΓòÉ 18.7. RexxReorderMacro ΓòÉΓòÉΓòÉ
  4305.  
  4306.  
  4307. ΓòÉΓòÉΓòÉ <hidden> Instructions ΓòÉΓòÉΓòÉ
  4308.  
  4309. Topics: 
  4310.  
  4311.       Call Syntax 
  4312.       Uses 
  4313.       Parameters 
  4314.       Return Values 
  4315.       Errors 
  4316.       Related Functions 
  4317.  
  4318.  
  4319. ΓòÉΓòÉΓòÉ <hidden> Call Syntax - RexxReorderMacro ΓòÉΓòÉΓòÉ
  4320.  
  4321. /*******************************************/
  4322. /* RexxReorderMacro changes the search    */
  4323. /*  order position of a loaded macrospace  */
  4324. /*  function.                              */
  4325. /*******************************************/
  4326.  
  4327. #define INCL_RXMACRO    /* Macrospace values */
  4328.  
  4329. PSZ     name;       /* function name         */
  4330. ULONG   rc;         /* Return code           */
  4331.  
  4332. rc = RexxReorderMacro(name, RXMACRO_SEARCH_AFTER);
  4333.  
  4334.  
  4335. ΓòÉΓòÉΓòÉ <hidden> Uses - RexxReorderMacro ΓòÉΓòÉΓòÉ
  4336.  
  4337. RexxReorderMacro changes the search order position of a loaded macrospace 
  4338. function. 
  4339.  
  4340.  
  4341. ΓòÉΓòÉΓòÉ <hidden> Parameters - RexxReorderMacro ΓòÉΓòÉΓòÉ
  4342.  
  4343. RexxReorderMacro (FuncName, Position) 
  4344.  
  4345. Parameters: 
  4346.  
  4347.  FuncName (PSZ) - input 
  4348.     Address of an ASCIIZ macrospace function name. 
  4349.  
  4350.  Position (ULONG) - input 
  4351.  
  4352.     New search-order position of the macrospace function. Possible values are: 
  4353.  
  4354.       RXMACRO_SEARCH_BEFORE 
  4355.          The function will be located by the REXX interpreter before any 
  4356.          registered functions or external REXX files. 
  4357.  
  4358.       RXMACRO_SEARCH_AFTER 
  4359.          The function will be located by the REXX interpreter after any 
  4360.          registered functions or external REXX files. 
  4361.  
  4362.  
  4363. ΓòÉΓòÉΓòÉ <hidden> Return Values - RexxReorderMacro ΓòÉΓòÉΓòÉ
  4364.  
  4365. RexxReorderMacro returns the following values: 
  4366.  
  4367.  0         RXMACRO_OK 
  4368.  2         RXMACRO_NOT_FOUND 
  4369.  8         RXMACRO_INVALID_POSITION 
  4370.  
  4371.  
  4372. ΓòÉΓòÉΓòÉ <hidden> Related Functions - RexxReorderMacro ΓòÉΓòÉΓòÉ
  4373.  
  4374. The following functions are related to RexxReorderMacro: 
  4375.  
  4376.       RexxAddMacro 
  4377.       RexxDropMacro 
  4378.       RexxClearMacroSpace 
  4379.       RexxSaveMacroSpace 
  4380.       RexxLoadMacroSpace 
  4381.       RexxQueryMacro 
  4382.  
  4383.  
  4384. ΓòÉΓòÉΓòÉ <hidden> Macrospace Interface Errors ΓòÉΓòÉΓòÉ
  4385.  
  4386. The follow return codes can be returned from the macrospace functions.  These 
  4387. values signify the causes for a failure, in these functions. 
  4388.  
  4389.  RXMACRO_OK 
  4390.     The function completed successfully 
  4391.  
  4392.  RXMACRO_NO_STORAGE 
  4393.     There was not enough memory to complete the requested function. 
  4394.  
  4395.  RXMACRO_NOT_FOUND 
  4396.     The requested procedure was not found in the macrospace. 
  4397.  
  4398.  RXMACRO_EXTENSION_REQUIRED 
  4399.     An extension is required for the macrospace file name. 
  4400.  
  4401.  RXMACRO_ALREADY_EXISTS 
  4402.     Duplicate functions cannot be loaded from a macrospace file. 
  4403.  
  4404.  RXMACRO_FILE_ERROR 
  4405.     An error occurred accessing a macro space file. 
  4406.  
  4407.  RXMACRO_SIGNATURE_ERROR 
  4408.     A macrospace save file does not contain valid function images. 
  4409.  
  4410.  RXMACRO_SOURCE_NOT_FOUND 
  4411.     The requested file was not found. 
  4412.  
  4413.  RXMACRO_INVALID_POSITION 
  4414.     An invalid search-order position request flag was used. 
  4415.  
  4416.  
  4417. ΓòÉΓòÉΓòÉ <hidden> Examples - RexxReorderMacro ΓòÉΓòÉΓòÉ
  4418.  
  4419. The following example shows the use of RexxAddMacro, RexxQueryMacro, 
  4420. RexxLoadMacroSpace, and RexxSaveMacroSpace. 
  4421.  
  4422.                                        /* first load entire package  */
  4423.   RexxLoadMacroSpace(0, NULL, "EDITOR.MAC");
  4424.  
  4425.   for (i = 0; i < MACRO_COUNT; i++) {  /* verify each macro          */
  4426.                                        /* if not there               */
  4427.     if (RexxQueryMacro(macro[i], &position))
  4428.                                        /* add to list                */
  4429.       RexxAddMacro(macro[i], macro_files[i],
  4430.           RXMACRO_SEARCH_BEFORE);
  4431.   }
  4432.                                        /* rebuild the macrospace     */
  4433.   RexxSaveMacroSpace(0, NULL, "EDITOR.MAC");
  4434.  
  4435. .
  4436. .
  4437. .
  4438.  
  4439.                                        /* build the argument string  */
  4440.   MAKERXSTRING(argv[0], macro_argument,
  4441.       strlen(macro_argument));
  4442.                                        /* set up default return      */
  4443.   MAKERXSTRING(retstr, return_buffer, sizeof(return_buffer));
  4444.                                        /* set up for macrospace call */
  4445.   MAKERXSTRING(macrospace[0],NULL, 0);
  4446.   MAKERXSTRING(macrospace[1],NULL, 0);
  4447.  
  4448.   return_code = RexxStart(1,           /* one argument               */
  4449.                           argv,        /* argument array             */
  4450.                           macro[pos],  /* REXX procedure name        */
  4451.                           macrospace,  /* use macrospace version     */
  4452.                           "Editor",    /* default address name       */
  4453.                           RXCOMMAND,   /* calling as a subcommand    */
  4454.                           NULL,        /* no exits used              */
  4455.                           &rc,         /* converted return code      */
  4456.                           &retstr);    /* returned result            */
  4457.