$NAMESPACE
Synopsis
$NAMESPACE
SET $NAMESPACE=namespace
NEW $NAMESPACE
Parameter
Parameter | Values |
---|---|
namespace | The name of an existing namespace, specified as a literal quoted string or an expression that resolves to a quoted string. Namespace names are not case-sensitive. |
Description
$NAMESPACE contains the name of the current namespace for the current stack level. You can use $NAMESPACE to:
-
Return the name of the current namespace.
-
Change the current namespace with SET.
-
Establish a new temporary namespace context with NEW and SET.
Return the Current Namespace Name
The $NAMESPACE special variable contains the current namespace name.
You can also obtain the name of the current namespace by invoking the NameSpace()Opens in a new tab method of %SYSTEM.SYSOpens in a new tab class, as follows:
WRITE $SYSTEM.SYS.NameSpace()
You can obtain the full pathname of the current namespace by using the NormalizeDirectory()Opens in a new tab method of %Library.FileOpens in a new tab class, as follows:
WRITE $NAMESPACE,!
WRITE ##class(%Library.File).NormalizeDirectory("")
You can test whether a namespace is defined by using the Exists()Opens in a new tab method of the %SYS.NamespaceOpens in a new tab class, as follows:
WRITE ##class(%SYS.Namespace).Exists("USER"),! ; an existing namespace
WRITE ##class(%SYS.Namespace).Exists("LOSER") ; a non-existent namespace
These methods are described in the InterSystems Class Reference.
SET $NAMESPACE
You can set $NAMESPACE to an existing namespace using the SET command. In SET $NAMESPACE=namespace, specify namespace as a quoted string literal or a variable or expression that evaluates to a quoted string; namespace is not case-sensitive. However, Caché always displays explicit namespace names in all uppercase letters, and implied namespace names in all lowercase letters. A namespace name can contain Unicode letter characters; Caché converts accented lowercase letters to their corresponding accented uppercase letters.
The namespace name can be an explicit namespace name ("USER") or an implied namespace ("^^c:\InterSystems\Cache\mgr\user\"). For further details on implied namespaces, refer to the ZNSPACE command.
If the specified namespace does not exist, SET $NAMESPACE generates a <NAMESPACE> error. If you do not have access privileges to a namespace, the system generates a <PROTECT> error, followed by the database path. For example, the %Developer role does not have access privileges to the %SYS namespace. If you have this role and attempt to access this namespace, Caché issues the following error (on a Windows system): <PROTECT> *c:\intersystems\cache\mgr\.
When you wish to temporarily change the current namespace, perform some operation, then revert to the prior namespace, use SET $NAMESPACE, rather than the SET $ZNSPACE or the ZNSPACE command. This is because $NAMESPACE permits you to NEW $NAMESPACE.
NEW $NAMESPACE
By setting $NAMESPACE you can change the current namespace. This is the preferred way to change a namespace in a method or other routine. By using NEW $NAMESPACE and SET $NAMESPACE you establish a namespace context that automatically reverts to the prior namespace when the method concludes or an unexpected error occurs:
TRY {
WRITE "before the method: ",$NAMESPACE,!
DO MyNSMethod("DocBook")
WRITE "after the method: ",$NAMESPACE
RETURN
MyNSMethod(ns)
NEW $NAMESPACE
IF ##class(%SYS.Namespace).Exists(ns) {
SET $NAMESPACE=ns }
ELSE {SET $NAMESPACE="User" }
WRITE "namespace changed in method: ",$NAMESPACE,!
SET num=5/$RANDOM(2)
QUIT
NextMethod()
WRITE "This should not write",!
}
CATCH exp {
WRITE "namespace after error in method: ",$NAMESPACE,!
IF 1=exp.%IsA("%Exception.SystemException") {
WRITE "System exception: ",$ZCVT(exp.Name,"O","HTML"),! }
}
Quitting a routine or branching to an error trap reverts to this stacked namespace. This is shown in the following Terminal example:
USER>NEW $NAMESPACE
USER 1S1>SET $NAMESPACE="SAMPLES"
SAMPLES 1S1>SET myoref=##class(%SQL.Statement).%New()
SAMPLES 1S1>QUIT
/* The QUIT reverts to the USER namespace */
USER>
Examples
The following example calls a routine that executes in a different namespace than the calling program. It uses NEW $NAMESPACE to stack the current namespace. It then uses SET $NAMESPACE to change the namespace for the duration of Test. The QUIT reverts to the stacked namespace:
WRITE "before: ",$NAMESPACE,!
DO Test
WRITE "after: ",$NAMESPACE,!
QUIT
Test
NEW $NAMESPACE
SET $NAMESPACE="USER"
WRITE "testing: ",$NAMESPACE,!
; routine code
QUIT
There is no need to handle an error to switch back to the old namespace; Caché restores the old namespace when you leave the current stack level.
The following example differs from the previous example by omitting NEW $NAMESPACE. Note that upon QUIT the namespace does not revert:
WRITE "before: ",$NAMESPACE,!
DO Test
WRITE "after: ",$NAMESPACE,!
QUIT
Test
NEW
SET $NAMESPACE="USER"
WRITE "testing: ",$NAMESPACE,!
; routine code
QUIT
Calling a separate routine when temporarily changing the current namespace is the preferred programming practice. In situations when calling a separate routine is not practical, you can use the legacy DO command dot syntax. The following example temporarily changes the namespace within a large subroutine by using this DO command syntax to create a stack frame:
WRITE "before: ",$NAMESPACE,!
DO
. NEW $NAMESPACE
. SET $NAMESPACE="USER"
. WRITE "testing: ",$NAMESPACE,!
. ; routine code
WRITE "after: ",$NAMESPACE,!
See Also
-
NEW command
-
SET command
-
ZNSPACE command
-
$ZNSPACE special variable
-
Configuring Namespaces in Caché System Administration Guide