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