Macrospace Interface

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.

Search Order

When RexxAddMacro loads a Rexx procedure into the macrospace, the position in the external function search order is specified. Possible values are:

RXMACRO_SEARCH_BEFORE

The Rexx interpreter locates a function registered with RXMACRO_SEARCH_BEFORE before any registered functions or external Rexx files.

RXMACRO_SEARCH_AFTER

The Rexx interpreter locates a function registered with RXMACRO_SEARCH_AFTER after any registered functions or external Rexx files.

Storage of Macrospace Libraries

The Rexx macrospace is stored in separate process using a daemon process. Macrospace routines are retrieved using interprocess call (IPC) mechanisms. A package file that is loaded in the local process might be preferable to loading routines in the macrospace.

Macrospace Interface Functions

The functions to manipulate macrospaces are:

RexxAddMacro

RexxAddMacro loads a Rexx procedure into the macrospace.

retc = RexxAddMacro(FuncName, SourceFile, Position);

Parameters

FuncName (const char *) - input

is the address of the ASCII function name. Rexx procedures in the macrospace are called using the assigned function name.

SourceFile (const char *) - input

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.

Position (size_t) - input

is the position in the Rexx external function search order. Possible values are:

RXMACRO_SEARCH_BEFORE

The Rexx interpreter locates the function before any registered functions or external Rexx files.

RXMACRO_SEARCH_AFTER

The Rexx interpreter locates the function after any registered functions or external Rexx files.

Return Codes

RXMACRO_OK0The call to the function completed successfully.
RXMACRO_NO_STORAGE1There was not enough memory to complete the requested function.
RXMACRO_SOURCE_NOT_FOUND7The requested file was not found.
RXMACRO_INVALID_POSITION8An invalid search-order position request flag was used.

RexxDropMacro

RexxDropMacro removes a Rexx procedure from the macrospace.

retc = RexxDropMacro(FuncName);

Parameter

FuncName (const char *) - input

is the address of the ASCII function name.

Return Codes

RXMACRO_OK0The call to the function completed successfully.
RXMACRO_NOT_FOUND2The requested function was not found in the macrospace.

RexxClearMacroSpace

RexxClearMacroSpace removes all loaded Rexx procedures from the macrospace.

retc = RexxClearMacroSpace();

Return Codes

RXMACRO_OK0The call to the function completed successfully.
RXMACRO_NOT_FOUND2The requested function was not found in the macrospace.

Remarks

RexxClearMacroSpace must be used with care. This function removes all functions from the macrospace, including functions loaded by other processes.

RexxSaveMacroSpace

RexxSaveMacroSpace saves all or part of the macrospace Rexx procedures to a disk file.

retc = RexxSaveMacroSpace(FuncCount, FuncNames, MacroLibFile);

Parameters

FuncCount (size_t) - input

Number of Rexx procedures to be saved.

FuncNames (const char **) - input

is the address of a list of ASCII function names. FuncCount gives the size of the function list.

MacroLibFile (const char *) - input

is the address of the ASCII macrospace file name. If MacroLibFile already exists, it is replaced with the new file.

Return Codes

RXMACRO_OK0The call to the function completed successfully.
RXMACRO_NOT_FOUND2The requested function was not found in the macrospace.
RXMACRO_EXTENSION_REQUIRED3An extension is required for the macrospace file name.
RXMACRO_FILE_ERROR5An error occurred accessing a macrospace file.

Remarks

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

RexxLoadMacroSpace loads all or part of the Rexx procedures from a saved macrospace file.

retc = RexxLoadMacroSpace(FuncCount, FuncNames, MacroLibFile);

Parameters

FuncCount (size_t) - input

is the number of Rexx procedures to load from the saved macrospace.

FuncNames (const char **) - input

is the address of a list of Rexx function names. FuncCount gives the size of the function list.

MacroLibFile (const char *) - input

is the address of the saved macrospace file name.

Return Codes

RXMACRO_OK0The call to the function completed successfully.
RXMACRO_NO_STORAGE1There was not enough memory to complete the requested function.
RXMACRO_NOT_FOUND2The requested function was not found in the macrospace.
RXMACRO_ALREADY_EXISTS4Duplicate functions cannot be loaded from a macrospace file.
RXMACRO_FILE_ERROR5An error occurred accessing a macrospace file.
RXMACRO_SIGNATURE_ERROR6A macrospace save file does not contain valid function images.

Remarks

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

RexxQueryMacro searches the macrospace for a specified function.

retc = RexxQueryMacro(FuncName, Position)

Parameters

FuncName (const char *) - input

is the address of an ASCII function name.

Position (unsigned short *) - output

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.

Return Codes

RXMACRO_OK0The call to the function completed successfully.
RXMACRO_NOT_FOUND2The requested function was not found in the macrospace.

RexxReorderMacro

RexxReorderMacro changes the search order position of a loaded macrospace function.

retc = RexxReorderMacro(FuncName, Position)

Parameters

FuncName (const char *) - input

is the address of an ASCII macrospace function name.

Position (ULONG) - input

is the new search-order position of the macrospace function. Possible values are:

RXMACRO_SEARCH_BEFORE

The Rexx interpreter locates the function before any registered functions or external Rexx files.

RXMACRO_SEARCH_AFTER

The Rexx interpreter locates the function after any registered functions or external Rexx files.

Return Codes

RXMACRO_OK0The call to the function completed successfully.
RXMACRO_NOT_FOUND2The requested function was not found in the macrospace.
RXMACRO_INVALID_POSITION8An invalid search-order position request flag was used.