Configuring Caché

Global Mappings

You can add a mapping for a new global to your namespace at the global and global subscript level that overrides the default database mapping for globals of the namespace:

1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Global Mappings in the row of the namespace where you want to map the global.

2. From the Global Mappings page click New Global Mapping.

3. Select the Global database location database where the global is located.

4. Enter the Global name. You can use the * character as part of the global name to specify multiple globals, for example ABC*.

5. Enter the Global subscripts to be mapped. The subscript reference must begin with an open parenthesis. Some examples follow:

   (1)
   ("A")
   (1):(5)
   ("A"):("Z")
   ("B",23,"m"):("E",5)
   (BEGIN):("X")
   ("Y"):(END)
   

   Note:

   When specifying a range (for example, ("A"):("Z"), the range is “from-to” (not “from-through”) the specified subscripts; that is, the lower end of a defined subscript range is inclusive, while the upper end of the defined subscript range is exclusive. For example, Name (1):(10) includes Name (1) but does not include Name (10); the exclusive upper range allows you to have a defined upper boundary when working with subscripted ranges, such as Name ("a"):("b"), where Name ("aa") and Name ("aaaaa") are equally valid ranges to precede Name ("b").

   You can use the reserved words BEGIN and END to refer to the first and last possible subscripts; however, you cannot use the asterisk (*) wildcard with subscripted globals because global subscripts must be mapped individually.

   For more information about subscript-level mapping (SLM) ranges, see Setting Global Mappings in the “Global Structure” chapter of Using Caché Globals.

6. Click Advanced to display the following:

   1. Select the Collation. Collation applies only to new subscript-level mapping globals.

   2. Select the Lock Database Location. For more information see Global in the “[Map]” section of the Caché Parameter File Reference.

7. Click OK.

   Note:

   >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.

8. To save the mappings in the cpf file, click Save Changes.

Routine Mappings

You can add mappings to your namespace at the routine level that overrides the default database mapping for routines of the namespace:

1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Routine Mappings in the row of the namespace where you want to map the global.

2. From the Routine Mappings page, click New Routine Mapping.

3. Select the Routine database location database where the routine is located.

4. Enter the Routine name. The routine does not have to exist when you map it (that is, it can be the name of a routine you plan to create).

5. Click OK.

   Note:

   >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.

6. To save the mappings in the cpf file, click Save Changes.

For example, using the preceding Sample Namespace Mapping example, if you plan to create a schedule routine (for example, BOSZZairline) in the airports database (in the FlightSchedule namespace) and you want it to be available to users in the TravelAgent namespace, navigate to the Routine Mappings page (in the TravelAgent namespace row), then click New Routine Mapping. Enter the information as shown in the following Routine Mapping dialog box:

Package Mappings

You can add a class package mappings which makes all the classes within a package (and all the generated routines for those classes) in a specific database visible to another namespace:

1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Package Mappings in the row of the namespace where you want to map the package.

2. From the Package Mappings page, click New.

3. Select the Package database location database where the package is located.

4. Select the Package name. The package does not have to exist when you map it (that is, it can be the name of a package you plan to create); you can specify a new package name, as follows:

   1. Click New Package.

   2. In the New package name text box, enter a name.

5. Click OK.

   Note:

   >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.

6. To save the mappings in the cpf file, click Save Changes.

See the Package Mapping section in the “Packages” chapter of Using Caché Objects for a description of packages and the procedure for mapping them.

For example, to make the class definitions in the Cinema package of the SAMPLES database available in the TESTSAMPLES namespace, navigate to the Package Mappings page and click New Package Mapping. Enter the information as shown in the following Package Mapping dialog box:

Mapping Data to All Namespaces

In addition to mapping globals, routines, and packages to specific namespaces, you can map them to all namespaces. To enable this form of mapping:

1. First, create a namespace named %ALL, as described in the Create/Modify a Namespace section.

   Note:

   %ALL is not visible except for the purposes of mapping data; that is, it is not a real namespace, but a mechanism for mapping data to all namespaces (except DOCBOOK and SAMPLES).

2. Then, make the desired mappings in the %ALL namespace, as described in the Add Global, Routine, and Package Mapping to a Namespace section.

   Note:

   For mappings in the DOCKBOOK and SAMPLES namespaces, you must create the mappings separately.

These %ALL mappings apply in all namespaces. You cannot create namespace-specific mappings to resources that are mapped in the %ALL namespace, as %ALL mappings override any namespace-specific mappings to the same resource.

When you create a subscript-level mapping in the %ALL namespace, a mapping for the root global is automatically created to %DEFAULTDB. The %DEFAULTDB variable represents the default database for any given namespace.

Database Configuration Limits

The absolute limit on the number of databases that can be configured within a single Caché instance (given sufficient storage space) is 15,998. However, because database directory information for all databases in an instance is limited to 64KB, the practical maximum depends on the number of bytes used in their database directory paths, and is likely to be much lower. Because mirrored databases (see the Mirroring chapter of the Caché High Availability Guide) require additional database directory information, the precise minimum depends on the number of mirrored databases involved, if any. The different calculations for non-mirrored and mirrored databases are described in the following sections.

The number of databases that can be in use simultaneously is further limited by the operating system’s limit on the number of open files (either per process or system-wide), minus what Caché reserves for its own use and devices, which is approximately half.

Database Configuration Considerations

The following are tips to consider to consider when configuring databases:

• Caché provides a seamless option to spread data across multiple physical database (CACHE.DAT) files. Therefore, you can build applications with multiple databases or splitting data by global or subscript-level mappings, as appropriate.

• Keep database sizes within a manageable value based on the infrastructure available for administration tasks such as backup, restore, integrity checks, etc.

• It is recommended that stream globals (if storing streams within CACHE.DAT database files) be global mapped to a separate database, and that the stream database(s) be configured with a large (64 KB) block size.

• Depending on your workload, it may be beneficial to consider alternate (larger) block sizes than the default 8 KB database block size. For general guidelines, see Large Block Size Considerations below.

Large Block Size Considerations

In addition to the 8 KB (default) block size supported by Caché (which is always enabled), you can also enable the following block sizes:

• 16 KB (16384)

• 32 KB (32768)

• 64 KB (65536)

However, you should exercise caution when creating your database to use large block size because using them can impact the performance of the system. Consider the following before enabling and using large block sizes:

• If your application workload consists primarily of sequential inserts or sequential reads/queries, large block sizes may improve performance.

• If your application workload consists primarily of random inserts or random reads/queries, large block sizes may degrade performance. Since larger block sizes result in fewer blocks being cached for a given total size of database cache, to reduce the impact on random database access, you should also consider making more total memory available as database cache.

• For index-type databases, the default block size (8 KB) ensures optimum performance; larger block sizes potentially degrade performance. If you are considering larger block sizes for your data, you should consider mapping index globals to a separate 8 KB block size database.

To create a database that uses block sizes other than the supported blocks, do the following:

1. Enable the block sizes using the DBSizesAllowed setting on the Startup Settings page (System Administration > Additional Settings > Startup), described in Startup Settings in the Caché Additional Configuration Settings Reference.

2. Configure the database cache for the enabled block size on the Startup Settings page (System Administration > Additional Settings > Startup), as described in Memory and Startup Settings.

3. Restart Caché.

4. Create the database as described in Create Local Databases in this chapter.

Database Compatibility Considerations

As described in the Create a Local Database procedure, you can copy or move a Caché database to an instance other than the one in which it was created by copying or moving its CACHE.DAT file, or temporarily mount a database created in another instance on the same system. You can also restore a backup of a database (see the “Backup and Restore” chapter of the Caché Data Integrity Guide) to an instance other than its original instance. To avoid data incompatibility, however, the following requirements must be met:

• The target (new) instance must use the same character width (8-bit or Unicode; see Caché Character Width in the Caché Installation Guide) and the same locale (see Using the NLS Pages of the Management Portal in this chapter) as the source instance (the one in which the database was created).

  The one exception to this requirement is that an 8-bit instance using a locale based on the ISO 8859 Latin-1 character set is compatible with a Unicode instance using the corresponding wide character locale. For example, a database created in an 8-bit instance using the enu8 locale can be used in a Unicode instance using the enuw locale.

• If the source and target instances are on systems of different endianness, the database must be converted to the endianness of the target instance before being used.

  Depending on the platform (see “Platform Endianness” in the “Supported Technologies” chapter of the online InterSystems Supported PlatformsOpens in a new tab document for this release), multibyte data is stored with either the most significant byte or the least significant byte in the lowest memory address (that is, first): when the most significant byte is stored first, it is referred to as “Big-endian;” when the least significant byte is stored first, it is referred to as “Little-endian.”

  When defining a database using an existing CACHE.DAT created on a system of different endianness, use the cvendian utility (see the Using cvendian to Convert Between Big-endian and Little-endian Systems section of the “Migration and Conversion Utilities” chapter of Caché Specialized System Tools and Utilities) to convert the database before you use it. When restoring a backup of a database to a system of different endianness than the source system, see Considering Endianness in the “Backup and Restore” chapter of the Caché Data Integrity Guide.

Create a Local Database

To create a local database, navigate to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

1. Click Create New Database to open the Database Wizard.

2. Enter a database name in the text box. A database name must

   • not already be in use within the Caché instance

   • be between one and 30 characters long

   • start with an alphabetic character or an underscore; the remainder can include alphanumeric characters, dashes, or underscores

3. The first time you create a local database in a Caché instance using a particular browser, you must either

   • enter the name of the database directory, in which case this directory, containing the CACHE.DAT file, is created in c:\InterSystems\mgr once you confirm it

   • click the folder icon to browse to an existing directory, in which case the CACHE.DAT file is created in that directory

   Thereafter, by default a directory of the same name as the database name you provide, containing the CACHE.DAT file, will be created in the same location as the previous database directory. For example, if you first create database db22 in any directory under c:\InterSystems\mgr, when you click Create New Database again and enter db33 in the Enter the name of your database box, c:\InterSystems\mgr\db33 is automatically filled into the Database directory text box. If you change this to c:\InterSystems\db33 and create db33, the base directory c:\InterSystems will be filled in the next time.

   Note:

   InterSystems does not support the use of symbolic links when configuring database directories.

4. Click Next to continue configuring the database. If a CACHE.DAT file already exists in the directory you specified, you are warned of this and can either

   • Click Finish to use the existing file, in which case all of the databases characteristics are determined by the CACHE.DAT file. You would typically do this when copying or moving a database from another instance, or temporarily mounting a database created in another instance on the same system.

   • Click Back to specify another directory, then click Next again to continue specifying the characteristics of the new database in the next step.

5. In the Initial Size text box, type the number of megabytes for your database size (the default is 1 MB).

   Note:

   You cannot create or edit a database so that its size is larger than the total available disk space. If the size you specify is within 90% of the disk's free space, you are warned and must confirm the action.

6. Select the desired block size from the Block size for this database will be drop-down list. By default, all new databases are created with a Block Size of 8 KB.

   Caution:

   Do not select block sizes other than 8 KB from the drop-down list unless you have read and understand the guidelines described in “Large Block Size Considerations” in the Configuring Databases section of this chapter.

7. Select whether or not you want to journal globals in this database from the Journal globals? drop-down list. See the “Journaling” chapter of the Caché Data Integrity Guide.

   Note:

   If you are configuring the database to store temporary globals, setting the Journal globals property to No is not the same as storing the temporary globals in CACHETEMP; for more information, see Using Temporary Globals and CACHETEMP in the “Journaling” chapter of the Caché Data Integrity Guide.

8. If encryption is activated, you can encrypt this database by selecting Yes for Encrypt Database?.

9. If the instance is part of a mirror, you can add this database to the mirror by selecting Yes for Mirrored Database?. See Add Databases to the Mirror in the “Mirroring” chapter of the Caché High Availability Guide for information about creating mirrored databases.

10. From this panel onward, you can click Next. to continue configuring the database or Finish to accept the remaining defaults

11. Choose the resource to control access to this database:

    • Default — %DB_%DEFAULT

    • Existing — Choose from a list of existing database resources

    • New — Create a new database resource (the new name defaults to %DB_%database name)

12. Click Next to view a list of the database attributes.

13. Click Finish to add your database.

You are now ready to configure and manage your new database.

Edit a Local Database’s Properties

The information displayed varies depending on whether or not the database is mirrored. This section identifies the fields for:

• Edit Non-Mirrored Local Database Properties

• Edit Mirrored Local Database Properties

Delete a Local Database

To delete a local database, click the Delete link in the appropriate row. The Delete Database page displays information about the database you are deleting, and lets you:

• Select the namespaces mapped to this database for deletion. You cannot delete a database if a namespace is mapped to it, so unless you select all of the listed namespaces you cannot delete the database.

  You cannot delete namespaces that are also mapped to other databases. When this is the case, a link is provided to take you to the Namespaces page, where you can modify the database mappings of the namespaces involved. After you delete all mappings to another database, that database will be removed from the list of databases you have to delete.

• You can choose to delete the database’s CACHE.DAT file, if and only if:

  • No other databases use this CACHE.DAT file.

  • You have marked all namespaces mapped to the database for deletion.

  If these conditions are not met, you can still delete the database from the current configuration, but the CACHE.DAT file cannot be deleted.

• Confirm that you want to delete the database after reviewing information about it by clicking Delete Database Now.

If you cannot or chose not to delete the CACHE.DAT file, the database is still removed from the Databases section of the Caché parameters file and therefore from the list of local databases displayed by the Management Portal.

Add a Remote Database

You can define a remote database on the local server if the database’s host is configured on that server as an ECP remote data server. To configure a remote data server:

1. Navigate to the ECP Settings page (System Administration > Configuration > Connectivity > ECP Settings).

2. Click Add Remote Data Server and enter the following information for the ECP remote data server:

   1. Server Name — Enter a logical local name for the remote data server for convenience of the application system administrator.

   2. Host DNS Name or IP Address — Specify the host name either as a raw IP address (in dotted-decimal format or, if IPv6 is enabled, in colon-separated format) or as the Domain Name System (DNS) name of the remote host. If you use the DNS name, it resolves to an actual IP address each time the application server initiates a connection to that ECP data server host. For more information about IPv6 addressing, see the IPv6 Support section in this chapter.

   3. IP Port — The port number defaults to 1972; change it as necessary to the superserver port of the Caché instance on the remote server.

3. Click Save.

4. In the list of remote servers, verify the status is Normal. If it is not, click Change Status and change the status to Normal.

To add a remote database, follow these steps:

1. Navigate to the Remote Databases page (System Administration > Configuration > System Configuration > Remote Databases) and click Add Remote Database to launch the wizard.

2. Select Select databases from a list to let the portal provide you with a drop-down list of remote data servers and then a drop-down list of database directories on the server you select. If a remote data server cannot currently be reached, its database directories are not available for selection.

3. Select Enter your own database specification to enter the remote data server name and database directory directly. (Note that the portal does not validate your entries.)

4. Enter a database name (its name on the local server; it does not need to match its name on the remote server). You have defined a remote database.

   Database names are between 1 and 30 characters long, can start with an alphabetic character or an underscore. The remaining characters can be alphanumeric, a dash, or an underscore.

5. You can optionally specify the directory in which streams associated with this database are stored. By default, the stream location for a remote database is the Caché Temp directory (install-dir\Mgr\Temp).

   Note:

   InterSystems recommends that you use the default location.

6. Click Save to configure the remote database.

You can click the Edit link for a remote database at any time to view and change the database described in the preceding procedure.

Delete a Remote Database

To delete a remote database, click the Delete link in the appropriate row. The Delete Database page displays information about the database you are deleting, and lets you:

• Select the namespaces mapped to this database for deletion. You cannot delete a database if a namespace is mapped to it, so unless you select all of the listed namespaces you cannot delete the database.

  You cannot delete namespaces that are also mapped to other databases. When this is the case, a link is provided to take you to the Namespaces page, where you can modify the database mappings of the namespaces involved. After you delete all mappings to another database, that database will be removed from the list of databases you have to delete.

• Confirm that you want to delete the database after reviewing information about it by clicking Delete Database Now.

This action simply removes the database from the local instance’s remote database configuration; the actual database and its local configuration on its host are not affected.

Configured Defaults

The Configured Defaults page (System Administration > Configuration > National Language Settings > Configured Defaults) displays the locale table currently used by default for each purpose within Caché. When writing ObjectScript code or using some utilities, it is possible to specify a particular table for a given purpose; the default table is used when no table is specified.

Each table name is color-coded to show whether the setting was inherited from the current locale at installation or specified using the NLS class packages, as described in Using System Classes for National Language Support.in the “Customizing the Caché System” chapter of Caché Specialized System Tools and Utilities.

The configuration defaults are a property of the instance, not of the locale. Therefore, when the instance is upgraded, the default selections are preserved.

Locale Definitions

From the Locale Definitions< page (System Administration > Configuration > National Language Settings > Locale Definitions), you can select a locale at the Select a locale drop-down and perform several actions. The drop-down is always set to the current locale when the page first displays.

• Using the Use locale date/time/number formats for [current locale] drop-down, indicate whether or not you want to use the date, time, and number formats specified by the current locale. Note that this always applies to the current locale, not a locale you have selected in the Select a locale drop-down but not yet installed.

• To view the details of a selected locale, click Properties. The next page displays the locale properties grouped into categories. For locales you have added, you can edit the fields and click Save to save these changes. You cannot edit the system locales provided with Caché. The properties are as follows:

  • Basic Properties

  • Date, Time, and Number Formats

  • Internal Tables — You have two options when editing the internal tables:

    • Edit Tables — You may select or delete a table from the list boxes by double clicking an item, or by selecting an item and then clicking > or < to move it from the appropriate list.

      Tables that require at least one entry are indicated by an asterisk (*); the other tables may be left empty.

    • Edit Defaults — You may choose the default from the values you enter in the Edit Tables function of the Internal Tables category.

  • Input/Output Tables — You can edit, add, or remove a table when choosing to edit this category.

    • To edit a table, click the table in the first list. The table name appears in the lower box. You can modify the values and click Save.

    • To remove a table, click the table in the first list. The table name appears in the lower box; click Remove. A confirmation box displays offering you the option to Cancel or OK the delete.

    • To add a table, click Add. The lower box has the Table field enabled and the Remove option disabled. You can enter a table name and enter the Output to and Input from fields.

    Click Save when you have made all your updates. If the save is successful, the updated list appears; otherwise, an appropriate error message displays.

  • Input/Output Defaults

  • Strings

• To take further actions, click the following buttons:

  • Validate — Validates the selected locale, displaying an error message if the locale cannot be validated. This is useful when creating custom locales.

  • Copy — Creates a copy of the selected locale, which you can then customize. The name of the copy must contain four characters beginning with y and ending with 8 or w. The default description is Copy of %locale, where %locale is the selected locale name. When the copy is created, it is added to the Select a locale drop-down.

  • Export — Exports a locale to an .xml file. For example, you might export a custom locale you created and import it on another instance using the Import Locale page. The default name is loc_%locale.xml, where %locale is the selected locale. In addition, you can include the path of the export file; if you do not specify the path, the default location is install-dir\Mgr.

  • Install — Installs the selected locale as the current locale for the instance. An initial validation occurs; if it fails, an error message displays, otherwise you can continue with installation.

  • Load Table — Lets you load a table from the selected locale (the current locale or another) into memory from disk. Select a table type and then a table name from the list populated after you select the type. Click OK to load the table or Cancel to close the dialog box and return to the Locale Definitions page.

  • Delete — Deletes a locale. You can delete only custom locales; the button is disabled when a system locale is selected. You cannot delete the current locale even if it is a custom locale. You must confirm deletion of the locale before proceeding.

Import Locale

From the Import Locale page (System Administration > Configuration > National Language Settings > Import Locales or Tables), you can import locales or tables. For example, you can import a custom locale exported (as described in the previous section) from another instance.

1. Select the Import Type > Locale is the default.

2. Enter a file name and click OK. The only valid file extensions are .xml and .goq.

3. A message displays indicating how many locales, tables, and subtables have been imported.