Home  /  Application Development: Core Topics  /  ObjectScript Reference  /  ObjectScript Special Variables  /  $NAMESPACE

ObjectScript Reference
[Back]  [Next] 
InterSystems: The power behind what matters   

Contains the namespace for the current stack level.
SET $NAMESPACE=namespace
$NAMESPACE contains the name of the current namespace for the current stack level. You can use $NAMESPACE to:
NEW $NAMESPACE followed by SET $NAMESPACE=namespace is the preferred way to change the current namespace within a code module.
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 ##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.
You can set $NAMESPACE to an existing namespace using the SET command.
NEW $NAMESPACE followed by SET $NAMESPACE=namespace is the preferred way to change a namespace within a code module, rather than using SET $ZNSPACE or the ZNSPACE 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, InterSystems IRIS 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; InterSystems IRIS 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\IRIS\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, InterSystems IRIS issues the following error (on a Windows system): <PROTECT> *c:\intersystems\iris\mgr\.
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
  IF ##class(%SYS.Namespace).Exists(ns) {
     SET $NAMESPACE=ns }
  WRITE "namespace changed in method: ",$NAMESPACE,!
  SET num=5/$RANDOM(2)
  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, InterSystems IRIS closes the object in that namespace before reverting to the stacked namespace. This is shown in the following Terminal example:
USER 1S1>NEW myoref
MYNSPACE 2N1>SET myoref=##class(%SQL.Statement).%New()
  /* IRIS closes myoref in the MYNSPACE namespace
     Then reverts to the USER namespace */
In more complex stacked namespace situations, it is the programmer’s responsibility to explicitly close objects in the proper namespace.
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,!
   WRITE "testing: ",$NAMESPACE,!
   ; routine code
There is no need to handle an error to switch back to the old namespace; InterSystems IRIS 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,!
   WRITE "testing: ",$NAMESPACE,!
   ; routine code
Calling a separate routine when temporarily changing the current namespace is the preferred programming practice.
See Also