Skip to main content
Previous section   Next section

$NAMESPACE

Contains the namespace for the current stack level.

Synopsis

$NAMESPACE
SET $NAMESPACE=namespace
NEW $NAMESPACE

Parameter

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

Previous section   Next section