Overview
The namespace utilities (provided by %SYSNSP.m, %SYSNSP0.m, and %SYSGEN.m in $DIST_ROOT/mlib
) are used for the management of namespaces. A namespace is a particular collection of FreeM globals and routines. If you are accustomed to other MUMPS implementations, you might have seen this concept referred to as a UCI or a global directory.
FreeM has something of a "system library" namespace, located in $DIST_ROOT/mlib
which contains the "percent" globals and routines (globals and routines whose names begin with the percent sign %). Routines and globals beginning with the percent sign character must be contained in $DIST_ROOT/mlib
in the current version of FreeM. However, these routines and globals are always accessible, regardless of the currently-active namespace.
Any user-defined namespace may only access globals and routines residing either in the current namespace, or in the system library namespace. For instance, if you have two user-defined namespaces, USER1 and USER2, routines in the USER1 namespace may not access globals in the USER2 namespace, but may access globals in the system library namespace.
At least one user-defined namespace is required for proper FreeM operation, and FreeM will automatically ask you to create one if one does not already exist. The first user-defined namespace you create is automatically chosen as the startup namespace when FreeM first runs. However, the FreeM programmer may easily switch to other namespaces using the utility entry points contained in the ^%SYSNSP
routine.
All namespaces aside from the system library namespace are located in $DIST_ROOT/namespace
, and are laid out as follows:
+---namespace namespace directory
| |
| +---<name> name of the namespace (can have more than one)
| |
| +---routine namespace routines
| |
| +---global namespace globals
Listing Namespaces
From the FreeM REPL, enter the following commands:
USER> d show^%SYSNSP
index namespace
----- ---------------
1 *USER
2 MVTS
In the above display, the USER
namespace is the default, denoted by the asterisk character preceding its name. The index
column is of special importance, as it is the index value (and not the name) that is used when switching namespaces.
Switching Namespaces
To switch namespaces, use the show^%SYSNSP
entry point documented above to determine the index of the desired namespace, and then call switch^%SYSNSP
, passing the index as the sole argument.
For example, to switch from the MVTS namespace (index 2) to the USER namespace, with an index of 1:
MVTS> S RESULT=$$switch^%SYSNSP(1)
USER>
Note that the programmer mode prompt of the FreeM REPL always indicates the name of the currently-selected namespace.
Adding New Namespaces
To add a new namespace, you will use the ^%SYSGEN
routine, which is user-friendly and menu-driven.
In this example, we will add a new namespace, called TESTING:
USER> D ^%SYSGEN
FreeM SYSTEM SETUP UTILITY
2020/02/22 20:28:51
Main Menu
---------
1 - Namespace Settings
2 - Routine-Editor Settings
3 - Configuration Settings
4 - Startup Options
Your choice: 1
Namespace Settings
------------------
1 - List Namespaces
2 - add Namespace
3 - delete Namespace
4 - rename Namespace
5 - repair Namespace
Your choice: 2
Name ..........: TESTING
Ok to create? <Y> y
Done.
Switching to the Default Namespace
To switch to the default namespace, enter the following command in the FreeM REPL:
TESTING> S RESULT=$$switch^%SYSNSP($$dflt^%SYSNSP))
USER>