Skip to main content

ZNSPACE

Sets the current namespace.

Synopsis

ZNSPACE:pc nspace
ZN:pc nspace

Arguments

Argument Description
pc Optional — A postconditional expression.
nspace A string expression that evaluates to the name of an existing namespace.

Description

ZNSPACE nspace changes the current namespace to the nspace value. nspace can be an explicit namespace name or an implied namespace.

If nspace does not exist, the system 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\.

You can change the current namespace by using the ZNSPACE command, the %CD utility (DO ^%CD), or by setting the $NAMESPACE or $ZNSPACE special variables. Use of ZNSPACE or %CD is preferable, because these provide more extensive error checking.

When you wish to temporarily change the current namespace, perform some operation, then revert to the prior namespace, use SET $NAMESPACE. Because $NAMESPACE permits you to NEW $NAMESPACE, it reverts to the original namespace when either the subroutine completes or an unexpected error occurs. See $NAMESPACE special variable for details.

The following methods may assist you when using ZNSPACE:

  • To return the name of the current namespace: return the $NAMESPACE or $ZNSPACE special variable value, or invoke the NameSpace()Opens in a new tab method of the %SYSTEM.SYSOpens in a new tab class, as follows:

       WRITE $SYSTEM.SYS.NameSpace()
  • To list all namespaces (explicit and implicit) available to the current process: invoke the ListAll()Opens in a new tab method of the %SYS.NamespaceOpens in a new tab class, as follows:

       DO ##class(%SYS.Namespace).ListAll(.result)
       ZWRITE result

    When ListAll() lists an implied namespace, it delimits the system name using caret (^) delimiters.

    To list all local and (optionally) remotely-mapped namespaces, invoke the ListOpens in a new tab query of the %SYS.NamespaceOpens in a new tab class, as follows:

      SET ListRemote=1
      SET stmt=##class(%SQL.Statement).%New()
      SET status=stmt.%PrepareClassQuery("%SYS.Namespace","List")
         IF status'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(status) QUIT}
      SET rset= stmt.%Execute(ListRemote)
      DO rset.%Display()

    This query returns each namespace name, its status (available or not), and whether it is mapped to a remote system.

    Note that both of these listings list all namespaces, including those for which the user does not have access privileges.

  • To test whether a namespace is defined: use the Exists()Opens in a new tab method of %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.

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

For namespace naming conventions and namespace name translation, see Namespaces in the “Syntax Rules” chapter of Using Caché ObjectScript. For information on using namespaces, see Namespaces and Databases in the Caché Programming Orientation Guide. For information on creating and modifying namespaces, see Configuring Namespaces in the Caché System Administration Guide.

Changing the Current Namespace

You can change the current namespace by using the ZNSPACE command, the %CD utility (DO ^%CD), or by setting the $NAMESPACE or $ZNSPACE special variables. From the Terminal prompt use of ZNSPACE or %CD is preferable, because these provide more extensive error checking.

When you wish to temporarily change the current namespace, perform some operation, then revert to the prior namespace, use NEW $NAMESPACE then SET $NAMESPACE. By using NEW $NAMESPACE and SET $NAMESPACE you establish a namespace context that automatically reverts to the prior namespace when the routine concludes or an unexpected error occurs.

Implied Namespace

An implied namespace specifies the namespace by system name and directory path. There are three forms:

  • "^^." for the current namespace. This can be used to change the namespace prompt from an explicit namespace to the corresponding implied namespace.

  • "^^dir" specifying the namespace directory path dir on the current system.

  • "^system^dir" specifying the namespace directory path dir on a specified remote system.

For dir, specify a directory path. This is shown in the following examples:

Windows example:

  ZNSPACE "^^c:\InterSystems\Cache\mgr\user\"
  WRITE $NAMESPACE

Linux example:

  ZNSPACE "^RemoteLinuxSystem^/usr/Cache/mgr/user/"
  WRITE $NAMESPACE

To return the full pathname of the current namespace, you can invoke the NormalizeDirectory()Opens in a new tab method, as shown in the following example:

   WRITE ##class(%Library.File).NormalizeDirectory("")

Arguments

pc

Optional — An optional postconditional expression. Caché executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). Caché does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions in Using Caché ObjectScript.

nspace

Any valid string expression that evaluates to the name of the new namespace. nspace can be an explicit namespace name or an implied namespace.

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

Examples

The following example uses NEW $NAMESPACE to stack the current namespace. It then uses ZNSPACE to change the namespace. The QUIT reverts to the stacked namespace:

   WRITE "before: ",$NAMESPACE,!
   DO Test
   WRITE "after: ",$NAMESPACE,!
   QUIT
Test
   NEW $NAMESPACE
   ZNSPACE "%SYS"
   WRITE "testing: ",$NAMESPACE,!
   QUIT

The following example assumes that a namespace called "accounting" already exists. Otherwise, you receive a <NAMESPACE> error.

From the programmer prompt:

USER>ZNSPACE "Accounting"
ACCOUNTING>

By default, as shown in this example, the Terminal prompt displays the current namespace name. Namespace names are always displayed in uppercase letters.

The following example tests for the existence of a namespace, then uses ZNSPACE to set the current namespace and uses the TerminalPrompt()Opens in a new tab method to set the Terminal prompt either to the specified namespace or to USER:

   WRITE !,"Current namespace is ",$NAMESPACE
   SET ns="ACCOUNTING"
   IF 1=##class(%SYS.Namespace).Exists(ns) {
     WRITE !,"Changing namespace to: ",ns
     ZNSPACE ns
     DO ##class(%SYSTEM.Process).TerminalPrompt(2)
     WRITE !,"and ",$NAMESPACE," will display at the prompt"
     }
   ELSE {
     WRITE !,"Namespace ",ns," does not exist"
     SET ns="USER"
     WRITE !,"Changing namespace to: ",ns
     ZNSPACE ns
     DO ##class(%SYSTEM.Process).TerminalPrompt(2)
     WRITE !,"and ",$NAMESPACE," will display at the prompt"
     }

Notes

Namespaces with Default Directories

If the namespace you select has a default directory on a remote machine, ZNSPACE does not change the current directory of your process to that namespace’s directory. Thus, your current namespace becomes the namespace you selected, but your current directory remains the directory that was current before you issued the ZNSPACE command.

Implied Namespace Mapping

ZNSPACE creates additional default mappings from an implied namespace. These mappings are the same as for a normal (explicit) namespace. They allow a process to find and execute the % routines and % globals that are physically located in the CACHESYS and CACHELIB databases (the cache\mgr\ and cache\mgr\cachelib directories).

Setting the $NAMESPACE or $ZNSPACE special variable or running the %CD routine with an implied namespace is the same as issuing a ZNSPACE command.

% Routine Mapping

When a process switches namespaces using the ZNSPACE command, the system routines path mapping is normally reset. This is true for both a normal (explicit) namespace and an implied namespace. The only exception to this is when the process switches from an implied namespace to an implied namespace, in which case the existing mapping is preserved. For further information on implied namespaces, see Global Structure in Using Caché Globals.

You can override this remapping of system routines by using the SysRoutinePath()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. This can be used to override an existing system routine. Commonly, this is used to create an additional mapping when debugging a % routine. The process must have Write permission for the CACHESYS database. This method should be used with extreme caution.

Caution:

Changing the mapping of a system routine supplied by InterSystems is strongly discouraged. Doing so could break current or future library routines and methods supplied by InterSystems.

% Global Mapping

The first time a user uses ZNSPACE (or its equivalent) to go to an implied namespace, the system creates a mapping for that implied namespace, as follows: Caché first maps to existing % globals in that implied namespace. Caché then maps all other % globals to CACHESYS.

Once this mapping has been created for an implied namespace, the mapping is stored in shared memory. This means that when any subsequent user goes to that implied namespace, Caché uses this pre-existing global mapping.

To update an implied namespace global mapping you must clear this shared memory storage. A system restart is one way to clear shared memory.

The deprecated $ZUTIL(5) function does not create additional default mappings from an implied namespace. Thus a process cannot find and execute % routines and % globals that are physically located in the CACHELIB database. For this reason, ZNSPACE or $NAMESPACE are strongly preferred; existing uses of $ZUTIL(5) should be phased out wherever possible.

Controlling Namespace Display

Terminal Prompt

By default, the Terminal prompt displays the current namespace name. This default is configurable:

Go to the Management Portal, select System, Configuration, Startup Settings. View and edit the current setting of TerminalPrompt. This also sets the prompt for Telnet windows.

To set this behavior for the current process, use the TerminalPrompt()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. The system-wide default behavior can be established by setting the TerminalPromptOpens in a new tab property of the Config.StartupOpens in a new tab class.

The Terminal prompt can represent the current namespace as the explicit namespace name or the implied namespace. If the implied namespace path is longer than 27 characters, the prompt is truncated to display an ellipsis, followed by the last 24 characters of the implied namespace path. For example: ...rsystems\cache\mgr\user\>

$NAME and $QUERY Functions

The $NAME and $QUERY functions can return the extended global reference form of a global variable, which includes the namespace name. You can control whether these functions return namespace names as part of the global variable name. You can set this extended global reference switch for the current process using the RefInKind()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. The system-wide default behavior can be established by setting the RefInKindOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class. For further information on extended global references, see Global Structure in Using Caché Globals.

Changing Namespaces within Application Code

Object and SQL code assumes that it is running in a single namespace; hence, changing namespaces with open object instances or SQL cursors can lead to code running incorrectly. Typically, there is no need to explicitly change namespaces, as the various Object, SQL, and CSP servers automatically ensure that application code is run in the correct namespace.

Also, changing namespaces demands a relatively high amount of computing power compared to other commands; if possible, application code should avoid it.

See Also

FeedbackOpens in a new tab