ZNSPACE (ObjectScript)
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.
-
From the Terminal command prompt ZNSPACE is the preferred way to change namespaces.
-
Within a code routine NEW $NAMESPACE followed by SET $NAMESPACE=namespace is the preferred way to change the current namespace. 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("TESTNAMESPACE1") ; 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 For information on using namespaces, see Namespaces and Databases. For information on creating and modifying namespaces, see Configuring Namespaces.
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\IRIS\mgr\user\"
WRITE $NAMESPACE
Linux example:
ZNSPACE "^RemoteLinuxSystem^/usr/IRIS/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. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions.
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. InterSystems IRIS always displays explicit namespace names in all uppercase letters, and implied namespace names in all lowercase letters.
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, InterSystems IRIS issues the following error (on a Windows system): <PROTECT> *c:\intersystems\iris\mgr\.
Examples
The following example assumes that a namespace called "accounting" already exists. Otherwise, you receive a <NAMESPACE> error.
From the Terminal:
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"
}
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 IRISSYS and IRISLIB databases (the IRIS\mgr\ and IRIS\mgr\irislib 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 Extended Global References.
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 IRISSYS database. This method should be used with extreme 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: InterSystems IRIS first maps to existing % globals in that implied namespace. InterSystems IRIS then maps all other % globals to IRISSYS.
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, InterSystems IRIS 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.
Terminal Prompt
By default, the Terminal prompt displays the current namespace name. This default is configurable:
Go to the Management Portal, select System Administration, Configuration, Additional Settings, Startup. 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: ...ersystems\iris\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 Extended Global References.
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
-
JOB command
-
$NAMESPACE special variable
-
$ZNSPACE special variable