Thanks for your feedback!
Need to tell us more? Click here or use the Feedback button.

Is this page helpful?

Contents

Synopsis
Description
Return Current Namespace Name
SET $NAMESPACE
NEW $NAMESPACE
Examples
See Also

$NAMESPACE (ObjectScript)

Contains the namespace for the current stack level.

Synopsis

$NAMESPACE
SET $NAMESPACE=namespace
NEW $NAMESPACE

Argument

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

NEW $NAMESPACE followed by SET $NAMESPACE=namespace is the preferred way to change the current namespace within a code module.

Return 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("TESTNAMESPACE1")   ; 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.

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

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; 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,!
   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.