$NAMESPACE

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 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.