Caché data is stored in databases and accessed via namespaces.
A database is a file (actually it could be more than one file, but we'll skip that complication for now) that can contain many different sorts of information—data from many classes, in object terms, or from many tables, in relational terms.
A namespace is a logical view of data in one or more databases. In the simplest case, there is a one-to-one correspondence between a namespace and a database, but in the real world it's very powerful to define a namespace which provides access to data in multiple databases.
A given Caché system has multiple “namespaces” each of which provides a different logical view of the data stored within one or more physical databases. This is illustrated in the following diagram:
Caché comes with the following namespaces predefined.
Predefined Namespaces
Namespace Contents Fate when a new Caché version is installed
%CACHELIB Components of the Caché system itself, such as the defintions of built-in classes. Replaced
%SYS System management information and utilities. Preserved
SAMPLES Sample code and applications. Replaced
USER Empty at installation. Typically used for application development. Preserved
Namespaces and the Caché Terminal
When you are using the Caché terminal to interact with a Caché system, the command prompt shows the current namespace you are in:
USER>
From the command line you can switch to a different namespace using the Caché ObjectScript ZNAMESPACE command (short form:ZN):
USER>
USER>ZN "SAMPLES"
SAMPLES>
The ZNAMESPACE command takes a single string as argument that is the name of the namespace you wish to switch to. If you enter an invalid namespace name, ZNAMESPACE will throw a <NAMESPACE> error.
Alternatively, you can use the ^%CD (Change Directory) command line utility which provides a simple user interface that prompts you about which namespace to change to. If you enter “?” at the prompt, ^%CD will give you a list of available namespaces to choose from.
Changing Namespaces within an Application
Within an application you can determine the current namespace using the $ZU(5) system command:
 Write $ZU(5)
You can switch to different namespace from within an application using the ZNAMESPACE command:
 ZN "SAMPLES"
You should take care when changing namespaces within applications. In particular, object and SQL code assumes that it is running in a single namespace; changing namespaces with open object instances or SQL cursors will lead to code running incorrectly. Typically you do not have to worry about this; the various Object, SQL, and CSP servers automatically ensure that application code is run in the correct namespace. Changing namespaces is a fairly expensive operation (as compared to other commands); application code should avoid it as possible.