Namespaces and Databases

This chapter describes how Caché organizes data and code. It discusses the following:

The chapter “Useful Skills to Learn” includes information on configuring namespaces, defining mappings, moving code and data, and so on.

Introduction to Namespaces and Databases

In Caché, any code runs in a namespace, which is a logical entity. A namespace provides access to data and to code, which is stored (typically) in multiple databases. A database is a file — a CACHE.DAT file. Caché provides a set of namespaces and databases for your use, and you can define additional ones.

In a namespace, the following options are available:

A namespace has a default database in which it stores code; this is the routine database for this namespace.
When you write code in a namespace, the code is stored in its routine database unless other considerations apply. Similarly, when you invoke code, Caché looks for it in this database unless other considerations apply.
A namespace also has a default database to contain data for persistent classes and any globals you create; this is the global database for this namespace.
So, for example, when you access data (in any manner), Caché retrieves it from this database unless other considerations apply.
The global database can be the same as the routine database, but it is often desirable to separate them for maintainability.
A namespace has a default database for temporary storage.
A namespace can include mappings that provide access to additional data and code that is stored in other databases. Specifically, you can define mappings that refer to routines, class packages, entire globals, and specific global nodes in non-default databases. (These kinds of mappings are called, respectively, routine mappings, package mappings, global mappings, and subscript-level mappings. )
When you provide access to a database via a mapping, you provide access to only a part of that database. The namespace cannot access the non-mapped parts of that database, not even in a read-only manner.
Also, it is important to understand that when you define a mapping, that affects only the configuration of the namespace. It does not change the current location of any code or data. Thus when you define a mapping, it is also necessary to move the code or data (if any exists) from its current location to the one expected by the namespace.
Defining mappings is a database administration task and requires no change to class/table definitions or application logic.
The chapter “Useful Skills to Learn” provides further details.
Any namespace you create has access to most of the Caché code library. This code is available because Caché automatically establishes specific mappings for any namespace you create.
This book has mentioned some of these classes; to find tools for a particular purpose, see the InterSystems Programming Tools Index.

Mappings provide a convenient and powerful way to share data and code. Any given database can be used by multiple namespaces. For example, there are several system databases that all customer namespaces can access, as discussed later in this chapter.

You can change the configuration of a namespace after defining it, and Caché provides tools for moving code and data from one database to another. Thus you can reorganize your code and data during development, if you discover the need to do so. This makes it possible to reconfigure Caché applications (such as for scaling) with little effort.

Locks, Globals, and Namespaces

Because a global can be accessed from multiple namespaces, Caché provides automatic cross-namespace support for its locking mechanism. A lock on a given global applies automatically to all namespaces that use the database that stores the global.

For an introduction to locking, see “Locking and Concurrency Control,” earlier in this book.

Database Basics

A Caché database is a CACHE.DAT file. You create a database via the Management Portal. Or if you have an existing Caché database, you can configure Caché to become aware of it.

Database Configuration

For any database, Caché requires the following configuration details:

Logical name for the database.
Directory in which the CACHE.DAT file resides. When you create a database in the Management Portal, you are prompted to choose or create a subdirectory within the system manager’s directory (cache-install/Mgr), but you can store the database file in any convenient directory.

Tip:

It is convenient to use the same string for the logical name and for the directory that contains the CACHE.DAT file. The system-provided Caché databases follow this convention.

Additional options include the following:

Default directory to use for file streams used by this database.
This is important because your users will need write access to this directory; if not, your code will not be able to create file streams.
Collation of new globals.
Initial size and other physical characteristics.
Option to enable or disable journaling. Journaling tracks changes made to a Caché database, for up-to-the-minute recovery after a crash or restoring your data during system recovery.
In most cases, it is best to enable journaling. However, you might want to disable journaling for designated temporary work spaces; for example, the CACHETEMP database is not journaled.
Option to mount this database for read-only use.
If a user tries to set a global in a read-only database, Caché returns a <PROTECT> error.

In most cases, you can create, delete, or modify database attributes while the system is running.

Database Features

With each database, Caché provides physical integrity guarantees for both the actual data and the metadata that organizes it. This integrity is guaranteed even if an error occurs during writes to the database.

The databases are automatically extended as needed, without manual intervention. If you expect a particular database to grow and you can determine how large it will become, you can “pre-expand” it by setting its initial size to be near the expected eventual size. If you do so, the performance is better.

Caché provides a number of strategies that allow high availability and recoverability. These include:

Journaling — Introduced earlier.
Mirroring — Provides rapid, reliable, robust, automatic failover between two Caché systems, making mirroring the ideal automatic failover high-availability solution for the enterprise.
Shadowing — Using this facility, one Caché database server “shadows” another by reading the primary server’s journal and applying database changes to its own copy of the database. Note that this is not true replication, but allows for emergency failover where a small amount of latency is permissible.
Clustering — There is full support of clustering on operating systems that provide it.

Caché has a technology for distributing data and application logic and processing among multiple systems. It is called the Enterprise Cache Protocol (ECP). On a multiserver system, a network of Caché database servers can be configured as a common resource, sharing data storage and application processing, with the data distributed seamlessly among them. This provides increased scalability as well as automatic failover and recovery.

Database Portability

Caché databases are portable across platforms and across versions, with the following caveats:

On different platforms, any file is either big-endian (that is, most-significant byte first) or little-endian (least-significant byte first).
Caché provides a utility to convert the byte order of a Caché database; it is called cvendian. This is useful when moving a database among platforms of the two types. For details, see the section “Using cvendian to Convert Between Big-endian and Little-endian Systems” in Caché Specialized System Tools and Utilities.
If you use a Unicode version of Caché to create a database, you might lose data if you try to use that database with an 8-bit Caché installation, because that installation cannot retrieve 16-bit character data.
You can use an 8-bit database with a Unicode installation, however.
If you use an 8-bit version of Caché, your data is not portable to an 8-bit locale that uses a different character set.
If a database contains code from an earlier release of Caché, you can use that code with a later version of Caché.
In some cases, it is necessary to make changes. InterSystems strives to assure that applications written for a version of Caché will run without change on subsequent versions, but there are exceptions.
If a database contains code or data that was created when long strings were enabled, then you might not be able to use that database with a Caché system in which long strings are not enabled. See the chapter “Server Configuration Options,” later in this book.

System-Supplied Databases

Caché provides the following databases:

CACHELIB — This is a read-only database that includes the object, data type, stream, and collection classes and many other class definitions. It also includes the system include files, generated INT code (for most classes), and generated OBJ code.
CACHESYS (the system manager’s database) — This database includes utilities and data related to system management. It is intended to contain specific custom code and data of yours and to preserve that code and data upon upgrades.
This database contains or can contain:
- Users, roles, and other security elements (both predefined items and ones that you add).
  For reasons of security, the Management Portal handles this data differently than other data; for example, you cannot display a table of users and their passwords.
- Data for use by the NLS (National Language Support) classes: number formats, the sort order of characters, and other such details. You can load additional data.
- Your own code and data. To ensure that these items are preserved upon upgrades, use the naming conventions in “Custom Items in CACHESYS,” later in this chapter.
Caution:

InterSystems does not support moving, replacing, or deleting this database.

The directory that contains this database is the system manager’s directory. The console log (cconsole.log) is written to this directory, as are other log files.
CACHE — Contains items such as cached SQL queries and CSP session information.

Note:

No customer application should directly interact with the CACHE database.
CACHEAUDIT — When you enable event logging, Caché writes the audit data to this database.
CACHETEMP — Caché uses this for temporary storage, and you can use it as well for the same purpose. This database is reinitialized each time the system restarts; see also the MaxCacheTempSizeAtStart CPF keyword. Note that this database is not journaled.
DOCBOOK — This database contains the documentation that the DocBook application serves up to viewers.
SAMPLES — This database contains code samples.
USER — This database is empty and is reserved for your use. Unlike the other databases, this database is entirely untouched by the installer, after the initial installation.

For additional detail on CACHESYS and SAMPLES, see the chapter “Assets and Resources” in the Caché Security Administration Guide.

System-Supplied Namespaces

Caché provides the following namespaces for your direct use:

%SYS — This namespace provides access to code that should not be available in all namespaces — code that manipulates security elements, the server configuration, and so on.
For this namespace, the default routine database and default global database is CACHESYS. If you follow certain naming conventions, you can create your own code and globals in this namespace and store it in that database. See the next section.
DOCBOOK — The DocBook application uses this namespace.
SAMPLES — This namespace provides access to the SAMPLES database.
USER — This namespace provides access to the USER database.

Caché uses other namespaces for its own purposes; see “Configuring Namespaces” in the Caché System Administration Guide.

Custom Items in CACHESYS

You can create items in the CACHESYS database. When you install a Caché upgrade, this database is upgraded. During this upgrade, some items are deleted unless they follow the naming conventions for custom items.

To add code or data to this database so that your items are not overwritten, do one of the following:

Go to the %SYS namespace and create the item. For this namespace, the default routine database and default global database are both CACHESYS. Use the following naming conventions to prevent your items from being affected by the upgrade installation:
- Classes: start the package with Z or z
- Routines: start the name with Z, z, %Z, or %z
- Globals: start the name with ^Z, ^z, ^%Z, or ^%z
In any namespace, create items with the following names:
- Routines: start the name with %Z or %z
- Globals: start the name with ^%Z or ^%z
Note:

InterSystems reserves the use of some %Z* routine names, including: %ZEN*, %ZHSLIB*.

Because of the standard mappings in any namespace, these items are written to CACHESYS.

MAC code and include files are not affected by upgrade.

What Is Accessible in Your Namespaces

When you create a namespace, the system automatically defines mappings for that namespace. As a result, in that namespace, you can use the following items (provided you are logged in as a user with suitable permissions for these items):

Any class whose package name starts with a percent sign (%). This includes most, but not all, classes provided by Caché.
All the code stored in the routine database for this namespace.
All the data stored in the global database for this namespace.
Any routine whose name starts with a percent sign.
Any include file whose name starts with a percent sign.
Any global whose name starts with a caret and a percent sign (^%). These globals are generally referred to as percent globals. Note that via global mappings or subscript level mappings, it is possible to change where percent globals are stored, but that has no effect on their visibility. Percent globals are always visible in all namespaces.
Your own globals with names that start ^CacheTempUser — for example, ^CacheTempUser.MyApp. If you create such globals, these globals are written to the CACHETEMP database.
Any additional code or data that is made available via mappings defined in this namespace.

Via extended global references, your code can access globals that are defined in other namespaces. For information, see “Global Structure” in Using Caché Globals.

The Caché security model controls which data and which code any user can access; see the chapter “Caché Security” for an introduction.

System Globals in Your Namespaces

Your namespaces contain additional system globals, which fall into two rough categories:

System globals that are in all namespaces. These include the globals in which Caché stores your routines, class definitions, include files, INT code, and OBJ code.
System globals that are created when you use specific Caché features. For example, if you use DeepSee in a namespace, the system creates a set of globals for DeepSee to use.

In most cases, you should not manually write to or delete any of these globals. See “Global Naming Conventions,” in Using Caché Globals.

Stream Directory

In any given namespace, when you create a file stream, Caché writes a file to a default directory and then later deletes it.

This is important because your users will need write access to this directory; if not, your code will not be able to create file streams.

The default directory is the stream subdirectory of the global database for this namespace.

For More Information

For more information on the topics covered in this chapter, see the following:

“Useful Skills to Learn,” later in this book, includes information on defining namespaces and databases.
Using Caché Globals has information on working with globals, including using extended references.
“Using cvendian to Convert Between Big-endian and Little-endian Systems” in Caché Specialized System Tools and Utilities has information on cvendian.
Caché High Availability Guide has information on high availability and recoverability.
Caché Distributed Data Management Guide has information on Enterprise Cache Protocol (ECP).