第三十五章 Caché 命令大全 ZNSPACE 命令

设置当前命名空间。

重点

1. 警告：强烈建议不要更改InterSystems提供的系统例程的映射。这样做可能会破坏InterSystems提供的当前或将来的库例程和方法
2. 强烈建议使用ZNSPACE或$NAMESPACE。 $ZUTIL（5）的现有用法应尽可能淘汰。
3. 与其他命令相比，更改名称空间需要相对较高的计算能力；如果可能，应用程序代码应避免使用它。

大纲

ZNSPACE:pc nspace
ZN:pc nspace

参数

• pc - 可选-后置条件表达式。
• nspace 计算结果为现有命名空间名称的字符串表达式。

描述

ZNSPACE nspace将当前名称空间更改为nspace值。Nspace可以是显式名称空间名称，也可以是隐含的名称空间。

如果nspace不存在，系统将生成<Namespace>错误。如果没有名称空间的访问权限，系统将生成一个<PROTECT>错误，后跟数据库路径。例如，%Developer角色没有访问%SYS命名空间的权限。如果具有此角色并尝试访问此命名空间，则Caché会发出以下错误(在Windows系统上)：<PROTECT> *c:\intersystems\cache\mgr\.

可以使用ZNSPACE命令、%cd实用程序(DO^%cd)或通过设置$NAMESPACE或$ZNSPACE特殊变量来更改当前名称空间。最好使用ZNSPACE或%cd，因为它们可以提供更广泛的错误检查。

临时更改当前名称空间，执行一些操作，然后恢复到以前的名称空间时，可以使用set $NAMESPACE。因为$NAMESPACE允许新建$NAMESPACE，所以当子例程完成或发生意外错误时，它将恢复为原始名称空间。

使用ZNSPACE时，以下方法可能会对有所帮助：

• 要返回当前命名空间的名称：返回$NAMESPACE或$ZNSPACE特殊变量值，或调用%SYSTEM.SYS类的NAMESPACE()方法，如下所示：

   WRITE $SYSTEM.SYS.NameSpace()

DHC-APP>  WRITE $SYSTEM.SYS.NameSpace()
DHC-APP

• 要列出当前进程可用的所有命名空间(显式和隐式)：调用%SYS.Namespace类的ListAll()方法，如下所示：

DHC-APP> DO ##class(%SYS.Namespace).ListAll(.result)
 
DHC-APP>zw result
result("%SYS")=""
result("DHC-APP")=""
result("DHC-CHSSWEB")=""
result("DHC-CSM")=""
result("DHC-DATA")=""
result("DHC-DWR")=""
result("DHC-EKG")=""
result("DHC-HEIS")=""
result("DHC-HR")=""
result("DHC-LISDATA")=""
result("DHC-LISSRC")=""
result("DHC-MEDSRC")=""
result("DHC-MRQ")=""
result("DOCBOOK")=""
result("FDBMS")=""
result("PACS")=""
result("PIS")=""
result("RIS")=""
result("SAMPLES")=""
result("USER")=""

当ListAll()列出隐含的名称空间时，它使用脱字符(^)分隔符分隔系统名称。

/// d ##class(PHA.TEST.Command).TestZnspace()
ClassMethod TestZnspace()
{
    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()
}

DHC-APP>d ##class(PHA.TEST.Command).TestZnspace()
 
 
Dumping result #1
Nsp     Status  Remote
%SYS    1       0
DHC-APP 1       0
DHC-CHSSWEB     1       0
DHC-CSM 1       0
DHC-DATA        1       0
DHC-DWR 1       0
DHC-EKG 1       0
DHC-HEIS        1       0
DHC-HR  1       0
DHC-LISDATA     1       0
DHC-LISSRC      1       0
DHC-MEDSRC      1       0
DHC-MRQ 1       0
DOCBOOK 1       0
FDBMS   1       0
PACS    1       0
PIS     1       0
RIS     1       0
SAMPLES 1       0
USER    1       0
 
20 Rows(s) Affected

此查询返回每个命名空间名称、其状态(可用或不可用)以及它是否映射到远程系统。

请注意，这两个清单都列出了所有名称空间，包括用户没有访问权限的名称空间。

• 要测试是否定义了命名空间：使用%SYS.Namespace类的Existes()方法，如下所示：

DHC-APP>WRITE ##class(%SYS.Namespace).Exists("USER"),!
1
 
DHC-APP>WRITE ##class(%SYS.Namespace).Exists("LOSER")
0

对于UNIX®系统，系统范围内的默认命名空间是作为系统配置选项建立的。对于Windows系统，它是使用命令行启动选项设置的。

更改当前命名空间

可以使用ZNSPACE命令、%cd实用程序(DO^%cd)或通过设置$NAMESPACE或$ZNSPACE特殊变量来更改当前名称空间。在终端提示符下，最好使用ZNSPACE或%CD，因为它们可以提供更广泛的错误检查。

临时更改当前命名空间时，执行一些操作，然后恢复到以前的命名空间，使用新的$NAMESPACE，然后设置$NAMESPACE。通过使用new $NAMESPACE和SET $NAMESPACE，您可以建立一个名称空间上下文，当例程结束或发生意外错误时，该上下文将自动恢复到前一个名称空间。

隐含命名名称

隐含的命名空间通过系统名称和目录路径指定命名空间。有三种形式：

• 当前命名空间的"^^."。这可用于将名称空间提示从显式名称空间更改为相应的隐含名称空间。
• "^^dir " 指定当前系统上的命名空间目录路径dir。
• "^system^dir" 指定指定远程系统上的命名空间目录路径目录。

对于目录，请指定目录路径。以下示例显示了这一点：

Windows示例：

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

DHC-APP>ZNSPACE "^^c:\InterSystems\Cache\mgr\user\"
...rsystems\cache\mgr\user\>WRITE $NAMESPACE
^^c:\intersystems\cache\mgr\user\

Linux示例：

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

若要返回当前命名空间的完整路径名，可以调用NormalizeDirectory()方法，如下例所示：

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

...rsystems\cache\mgr\user\>WRITE ##class(%Library.File).NormalizeDirectory("")
C:\InterSystems\Cache\mgr\user\
DHC-APP>WRITE ##class(%Library.File).NormalizeDirectory("")
E:\DtHealth\db\dthis\data\

参数

pc

可选-可选的后置条件表达式。如果后置条件表达式为TRUE(计算结果为非零数值)，则Caché执行该命令。如果后置条件表达式为假(计算结果为零)，则Caché不执行该命令。

nspace

计算结果为新命名空间名称的任何有效字符串表达式。Nspace可以是显式名称空间名称，也可以是隐含的名称空间。命名空间名称不区分大小写。Caché始终以全部大写字母显示显式名称空间名称，以全部小写字母显示隐含名称空间名称。

示例

下面的示例使用new$NAMESPACE堆栈当前命名空间。然后，它使用ZNSPACE更改名称空间。退出将恢复为堆叠名称空间：

/// d ##class(PHA.TEST.Command).TestZnspaceSwitch()
ClassMethod TestZnspaceSwitch()
{
   WRITE "before: ",$NAMESPACE,!
   DO Test
   WRITE "after: ",$NAMESPACE,!
   QUIT
Test
   NEW $NAMESPACE
   ZNSPACE "%SYS"
   WRITE "testing: ",$NAMESPACE,!
   QUIT
}

DHC-APP>d ##class(PHA.TEST.Command).TestZnspaceSwitch()
before: DHC-APP
testing: %SYS
after: DHC-APP

下面的示例假定一个名为“accounting”的名称空间已经存在。否则，会收到错误。

USER>ZNSPACE "Accounting"
ACCOUNTING>

默认情况下，如本示例所示，终端提示显示当前名称空间名称。命名空间名称始终以大写字母显示。

下面的示例测试名称空间的存在，然后使用ZNSPACE设置当前名称空间，并使用TerminalPrompt（）方法将Terminal终端设置为指定的名称空间或USER：

/// d ##class(PHA.TEST.Command).TestZnspaceTerminal()
ClassMethod TestZnspaceTerminal()
{
    WRITE !,"当前名称空间为 ",$NAMESPACE
    SET ns="ACCOUNTING"
    IF 1=##class(%SYS.Namespace).Exists(ns) {
        WRITE !,"将命名空间更改为: ",ns
        ZNSPACE ns
        DO ##class(%SYSTEM.Process).TerminalPrompt(2)
        WRITE !,"and ",$NAMESPACE," 将在终端下显示"
    } ELSE {
        WRITE !,"Namespace ",ns," 不存在"
        SET ns="USER"
        WRITE !,"将命名空间更改为:: ",ns
        ZNSPACE ns
        DO ##class(%SYSTEM.Process).TerminalPrompt(2)
        WRITE !,"and ",$NAMESPACE," 将在终端下显示"
    }
}

DHC-APP>d ##class(PHA.TEST.Command).TestZnspaceTerminal()
 
当前名称空间为 DHC-APP
Namespace ACCOUNTING 不存在
将命名空间更改为:: USER
and USER 将在终端下显示

注意

具有默认目录的命名空间

如果选择的名称空间在远程计算机上具有默认目录，则ZNSPACE不会将进程的当前目录更改为该名称空间的目录。因此，当前的名称空间将成为选择的名称空间，但是当前目录仍然是发出ZNSPACE命令之前的当前目录。

隐式命名空间映射

ZNSPACE从隐式命名空间创建其他默认映射。这些映射与普通（显式）名称空间的映射相同。它们允许进程查找并执行物理上位于CACHESYS和CACHELIB数据库中的%routines 和%globals( cache\mgr\ 与 cache\mgr\cachelib 目录下).

设置$NAMESPACE或$ZNSPACE特殊变量或使用隐式名称空间运行％CD例程与发出ZNSPACE命令相同。

%Routine 映射

当进程使用ZNSPACE命令切换名称空间时，通常会重置系统例程路径映射。普通（显式）名称空间和隐式名称空间都是如此。唯一的例外是当流程从隐式名称空间切换到隐式名称空间时，在这种情况下，将保留现有映射。

可以使用％SYSTEM.Process类的SysRoutinePath（）方法覆盖此对系统例程的重新映射。这可以用来覆盖现有的系统例程。通常，它用于调试%routine时创建其他映射。该进程必须对CACHESYS数据库具有“写”权限。使用此方法时应格外小心。

警告：强烈建议不要更改InterSystems提供的系统例程的映射。这样做可能会破坏InterSystems提供的当前或将来的库例程和方法。

%Global 映射

用户首次使用ZNSPACE（或其等效项）进入隐式名称空间时，系统将为该隐式名称空间创建映射，如下所示：Caché首先映射至该隐式名称空间中的现有％globals。然后，Caché将所有其他％globals映射到CACHESYS。

为隐式名称空间创建此映射后，该映射将存储在共享内存中。这意味着，当任何后续用户转到该隐含名称空间时，Caché将使用此预先存在的全局映射。

要更新隐式命名空间全局映射，必须清除此共享内存存储。重新启动系统是清除共享内存的一种方法。

不建议使用的$ZUTIL（5）函数不会从隐式命名空间创建其他默认映射。因此，进程无法找到并执行物理上位于CACHELIB数据库中的%routines和``％Globals。**因此，强烈建议使用ZNSPACE或ZUTIL（5）`的现有用法应尽可能淘汰。**

控制命名空间显示

终端提示

默认情况下，终端提示会显示当前的名称空间名称。此默认值是可配置的：

转到管理门户，选择系统，配置，启动设置。查看和编辑TerminalPrompt的当前设置。这还将设置Telnet窗口的提示。

image.png

若要为当前进程设置此行为，请使用％SYSTEM.Process类的TerminalPrompt（）方法。可以通过设置Config.Startup类的TerminalPrompt属性来建立系统范围的默认行为。

终端提示可以将当前名称空间表示为显式名称空间名称或隐式名称空间。如果隐式名称空间路径的长度超过27个字符，则提示会被截断以显示省略号，后跟隐式名称空间路径的最后24个字符。例如： ...rsystems\cache\mgr\user\>

$NAME和$QUERY函数

$NAME和$QUERY函数可以返回扩展的全局引用形式的全局变量，其中包括名称空间名称。可以控制这些函数是否将名称空间名称作为全局变量名称的一部分返回。可以使用％SYSTEM.Process类的RefInKind（）方法为当前进程设置此扩展的全局引用开关。 ese函数将名称空间名称作为全局变量名称的一部分返回。可以通过设置Config.Miscellaneous类的RefInKind属性来建立系统范围的默认行为。

在应用程序代码中更改命名空间

对象和SQL代码假定它在单个名称空间中运行；因此，使用开放对象实例或SQL游标更改名称空间可能导致代码运行不正确。通常，无需显式更改名称空间，因为各种对象，SQL和CSP服务器会自动确保应用程序代码在正确的名称空间中运行。

而且，与其他命令相比，更改名称空间需要相对较高的计算能力；如果可能，应用程序代码应避免使用它。