Skip to main content

$ZNSPACE (ObjectScript)

Contains the current namespace name.




$ZNSPACE contains the name of the current namespace. By setting $ZNSPACE, you can change the current namespace.

To obtain the current namespace name:

   WRITE ns

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:

   SET ns=$SYSTEM.SYS.NameSpace()

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.

For UNIX® systems, the default namespace is established as a System Configuration option. For Windows systems, it is set using a command line start-up option.

Namespace names are not case-sensitive. InterSystems IRIS always displays explicit namespace names in all uppercase letters, and implied namespace names in all lowercase letters.

To obtain the namespace name of a specified process, use a method of the %SYS.ProcessQueryOpens in a new tab class, as shown in the following example:

    WRITE ##class(%SYS.ProcessQuery).%OpenId($JOB).NameSpaceGet()

Setting the Current Namespace

You can change the current namespace using the ZNSPACE command, SET $NAMESPACE, SET $ZNSPACE, or the %CD utility.

  • From the Terminal command prompt the ZNSPACE command is the preferred way to change namespaces. SET $ZNSPACE is functionally identical to the ZNSPACE command.

  • Within a code routine NEW $NAMESPACE followed by SET $NAMESPACE=namespace is the preferred way to change the current namespace. 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. See $NAMESPACE special variable for details.

You can use SET $ZNSPACE to change the current namespace for the process. Specify the new namespace as a string literal or a variable or expression that evaluates to a quoted string. You can specify an explicit namespace ("namespace") or an implied namespace ("^system^dir" or "^^dir").

If you specify the current namespace, SET $ZNSPACE performs no operation and returns no error. If you specify an undefined namespace, SET $ZNSPACE generates a <NAMESPACE> error.

You cannot NEW the $ZNSPACE special variable.


In the following example, if the current namespace is not USER, a SET $ZNSPACE command changes the current namespace to USER. Note that because of the IF test, the namespace must be specified in all uppercase letters.

   SET ns="USER"
   IF $ZNSPACE=ns {
     WRITE !,"Namespace already was ",$ZNSPACE }
   ELSEIF 1=##class(%SYS.Namespace).Exists(ns) {
     WRITE !,"Namespace was ",$ZNSPACE
     SET $ZNSPACE=ns
     WRITE !,"Set namespace to ",$ZNSPACE }
   ELSE { WRITE !,ns," is not a defined namespace" }

This example requires that UnknownUser have assigned the %DB_IRISSYS and the %DB_USER roles.

See Also

FeedbackOpens in a new tab