Skip to main content

Adding Mappings to a Namespace

As part of configuring a namespace, you can also map globals, routines, and class packages from other databases on the same or different systems.

This allows simple references to data which can exist anywhere and is the primary feature of a namespace. You can map whole globals or pieces of globals; this feature allows data to easily span disks.

Note:

Mappings are sorted alphabetically; if subscripts are specified, they are sorted by name and subscript. For more information, see Formal Rules about Globals.

Important:

If there is mapped content with the same identifier as local content (such as a package, class, global, or routine name), the mapped content will be visible, rather than the local content. As such, you should be as specific with your mappings as possible, to prevent mapping away from existing content.

Be sure to follow Rules and Guidelines for Identifiers when naming content and creating mappings, to avoid any unwanted conflicts.

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.

  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 Up Global Mappings.

  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 Configuration 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.

Important:

While it is possible to add a mapping that changes the database location of an existing global, this does not actually move the global. As a consequence, the global becomes inaccessible, as it remains in the original database while the namespace expects to find it in the newly mapped database. For a new mapping for an existing global to be successful, you must relocate the global manually, for example using the Terminal or the Management Portal, by creating it on the new database and removing it from the original database.

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.

  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 Test 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:

Important:

When you map one or more routines, be sure to identify all the code and data needed by those routines, and ensure that all that code and data is available in all the target namespaces. The mapped routines could depend on the following items:

  • Include files

  • Other routines

  • Classes

  • Tables

  • Globals

Use additional routine, package, and global mappings as needed to ensure that these items are available in the target namespaces.

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 Package Mapping for a description of packages and the procedure for mapping them.

Important:

When you map a package, be sure to identify all the code and data needed by the classes in that package, and ensure that all that code and data is available in all the target namespaces. The mapped classes could depend on the following items:

  • Include files

  • Routines

  • Other classes

  • Tables

  • Globals

Use additional routine, package, and global mappings as needed to ensure that these items are available in the target namespaces.

InterSystems IRIS also provides functionality to make a package available in all namespaces through a single action.

Mapping 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 Create/Modify a Namespace.

    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.

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

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.

Caution:

%ALL mappings apply to every namespace, including %SYS. It is possible to break certain features by creating a mapping that overrides a routine or global the instance relies on.

You should create mappings as narrowly as possible when using %ALL. Additionally, closely follow the Rules and Guidelines for Identifiers; in particular, do not create %ALL mappings for any globals listed in Global Names to Avoid.

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.

See Also

FeedbackOpens in a new tab