|
Caché Programming Orientation Guide
Namespaces and Databases
|
|
This chapter describes how Caché organizes data and code. It discusses the following:
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.
-
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.
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.
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.
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.
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.
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.
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).
-
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.
-
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.
-
Caution:
InterSystems does not support moving, replacing, or deleting this database.
-
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.
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.
-
-
USER — This namespace provides access to the
USER database.
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
-
-
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
Because of the standard mappings in any namespace, these items are written to
CACHESYS.
MAC code and include files are not affected by upgrade.
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.
-
-
Any additional code or data that is made available via mappings defined in this namespace.
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 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 on the topics covered in this chapter, see the following: