The macrospace can improve the performance of Rexx procedures by maintaining Rexx procedure images in memory for immediate load and execution. This is useful for frequently-used procedures and functions such as editor macros.
Programs registered in the Rexx macrospace are available to all processes. You can run them by using the RexxStart function or calling them as functions or subroutines from other Rexx procedures.
Procedures in the macrospace are called in the same way as other Rexx external functions. However, the macrospace Rexx procedures can be placed at the front or at the very end of the external function search order.
Procedures in the macrospace are stored without source code information and therefore cannot be traced.
Rexx procedures in the macrospace can be saved to a disk file. A saved macrospace file can be reloaded with a single call to RexxLoadMacroSpace. An application, such as an editor, can create its own library of frequently-used functions and load the entire library into memory for fast access. Several macrospace libraries can be created and loaded.
Note: The TRACE keyword instruction cannot be used in the Rexx macrospace. Since macrospace uses the tokenized format, it is not possible to get the source code from macrospace to trace a function.
When RexxAddMacro loads a Rexx procedure into the macrospace, the position in the external function search order is specified. Possible values are:
The Rexx interpreter locates a function registered with RXMACRO_SEARCH_BEFORE before any registered functions or external Rexx files.
The Rexx interpreter locates a function registered with RXMACRO_SEARCH_AFTER after any registered functions or external Rexx files.
The Rexx macrospace is placed in shared memory. Only the amount of memory and swap space available to the system limits the size of the macrospace. However, as the macrospace grows, it limits the memory available to other processes in the system. Allowing the macrospace to grow too large can degrade overall system performance due to increased system swap file access. Try to place only the most frequently-used functions in the macrospace.
The functions to manipulate macrospaces are:
RexxAddMacro loads a Rexx procedure into the macrospace.
retc = RexxAddMacro(FuncName, SourceFile, Position);
is the address of the ASCII function name. Rexx procedures in the macrospace are called using the assigned function name.
is the address of the ASCII file specification for the Rexx procedure source file. When a file extension is not supplied, .CMD is used. When the full path is not specified, the current directory and path are searched.
is the position in the Rexx external function search order. Possible values are:
The Rexx interpreter locates the function before any registered functions or external Rexx files.
The Rexx interpreter locates the function after any registered functions or external Rexx files.
RexxDropMacro removes a Rexx procedure from the macrospace.
retc = RexxDropMacro(FuncName);
is the address of the ASCII function name.
RexxClearMacroSpace removes all loaded Rexx procedures from the macrospace.
retc = RexxClearMacroSpace();
RexxClearMacroSpace must be used with care. This function removes all functions from the macrospace, including functions loaded by other processes.
RexxSaveMacroSpace saves all or part of the macrospace Rexx procedures to a disk file.
retc = RexxSaveMacroSpace(FuncCount, FuncNames, MacroLibFile);
Number of Rexx procedures to be saved.
is the address of a list of ASCII function names. FuncCount gives the size of the function list.
is the address of the ASCII macrospace file name. If MacroLibFile already exists, it is replaced with the new file.
When FuncCount is 0 or FuncNames is null, RexxSaveMacroSpace saves all functions in the macrospace.
Saved macrospace files can be used only with the same interpreter version that created the images. If RexxLoadMacroSpace is called to load a saved macrospace and the release level or service level is incorrect, RexxLoadMacroSpace fails. The Rexx procedures must then be reloaded individually from the original source programs.
RexxLoadMacroSpace loads all or part of the Rexx procedures from a saved macrospace file.
retc = RexxLoadMacroSpace(FuncCount, FuncNames, MacroLibFile);
is the number of Rexx procedures to load from the saved macrospace.
is the address of a list of Rexx function names. FuncCount gives the size of the function list.
is the address of the saved macrospace file name.
| RXMACRO_OK | 0 | The call to the function completed successfully. |
| RXMACRO_NO_STORAGE | 1 | There was not enough memory to complete the requested function. |
| RXMACRO_NOT_FOUND | 2 | The requested function was not found in the macrospace. |
| RXMACRO_ALREADY_EXISTS | 4 | Duplicate functions cannot be loaded from a macrospace file. |
| RXMACRO_FILE_ERROR | 5 | An error occurred accessing a macrospace file. |
| RXMACRO_SIGNATURE_ERROR | 6 | A macrospace save file does not contain valid function images. |
When FuncCount is 0 or FuncNames is null, RexxLoadMacroSpace loads all Rexx procedures from the saved file.
If a RexxLoadMacroSpace call replaces an existing macrospace Rexx procedure, the entire load request is discarded and the macrospace remains unchanged.
RexxQueryMacro searches the macrospace for a specified function.
retc = RexxQueryMacro(FuncName, Position)
is the address of an ASCII function name.
is the address of an unsigned short integer flag. If the function is loaded in the macrospace, Position is set to the search-order position of the current function.
RexxReorderMacro changes the search order position of a loaded macrospace function.
retc = RexxReorderMacro(FuncName, Position)
is the address of an ASCII macrospace function name.
is the new search-order position of the macrospace function. Possible values are:
The Rexx interpreter locates the function before any registered functions or external Rexx files.
The Rexx interpreter locates the function after any registered functions or external Rexx files.