Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

$NAMESPACE (ObjectScript)

Contains the namespace for the current stack level.


SET $NAMESPACE=namespace


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.


$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() 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. 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.


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. This is shown in the following Terminal example:

SAMPLES 1S1>SET myoref=##class(%SQL.Statement).%New()
  /* The QUIT reverts to the USER 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; 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,!
   WRITE "testing: ",$NAMESPACE,!
   ; routine code

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,!
   . WRITE "testing: ",$NAMESPACE,!
   . ; routine code
   WRITE "after: ",$NAMESPACE,!

See Also