Caché ObjectScript Reference
$NAMESPACE
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Contains the namespace for the current stack level.
Synopsis
$NAMESPACE
SET $NAMESPACE=namespace
NEW $NAMESPACE
Description
$NAMESPACE contains the name of the current namespace for the current stack level. You can use $NAMESPACE to:
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() method of %SYSTEM.SYS class, as follows:
   WRITE $SYSTEM.SYS.NameSpace()
 
You can obtain the full pathname of the current namespace by using the NormalizeDirectory() method of %Library.File class, as follows:
   WRITE $NAMESPACE,!
   WRITE ##class(%Library.File).NormalizeDirectory("")
 
You can test whether a namespace is defined by using the Exists() method of the %SYS.Namespace 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 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. If you create an object instance in the changed namespace, Caché closes the object in that namespace before reverting to the stacked namespace. This is shown in the following Terminal example:
USER>NEW $NAMESPACE
USER 1S1>NEW myoref
USER 2N1>SET $NAMESPACE="SAMPLES"
SAMPLES 2N1>SET myoref=##class(%SQL.Statement).%New()
SAMPLES 2N1>QUIT
  /* Cache closes myoref in the SAMPLES namespace
     Then reverts to the USER namespace */
USER>
In more complex stacked namespace situations, it is the programmer’s responsibility to explicitly close objects in the proper namespace.
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