Skip to main content

Configuring Namespaces

A namespace is a collection of data and programs in a virtual work space. In a namespace, you can define the globals that various groups or people need. For example, if your accounting department needs to use certain globals that exist on different systems or in different directories, you can set up a single namespace that references all the accounting globals and databases on your network.

InterSystems IRIS® comes with the following predefined namespaces:

  • %SYS — System management information and utilities.

  • USER — Empty at installation. Typically used for application development.

You can configure namespaces on the Namespace page of the Management Portal, which you can navigate to by selecting System Administration on the home page, then Configuration, then System Configuration, then Namespaces.

Note:

This page describes the process of manually configuring namespaces using the Management Portal. InterSystems IRIS also contains programmatic tools that are useful for automating namespace configuration. You can use the Config.NamespacesOpens in a new tab class to create and configure namespaces; see the InterSystems Class Reference for more information.

You can also create, modify and delete namespaces using the configuration merge action parameters CreateNamespace, ModifyNamespace, and DeleteNamespace. Configuration merge allows you to deploy or reconfigure an InterSystems IRIS instance with the objects and settings you want by applying a declarative merge file. For more information about this feature, see Automating Configuration of InterSystems IRIS with Configuration Merge.

The absolute limit to the number of namespaces within a single InterSystems IRIS instance is 2048. The size of the namespaces table is automatic and not configurable.

For more information about namespaces, see the Namespaces and Databases.

Create/Modify a Namespace

You can create a new namespace at any time, but when you are first setting up the system, create the basic ones that your users need. To create a namespace, click Create New Namespace to display the New Namespace page, then do the following:

  1. Enter a Name for the namespace.

    Namespace names must be at least one character (but not more than 64 characters) long, starting with an alphabetic character or a percent sign (%) followed by an arbitrary number of alphanumeric characters, dashes, or underscores.

    Important:

    Do not specify the following reserved system names: BIN, BROKER, DOCUMATIC, %SYS.

  2. You can Copy from an existing namespace, creating a duplicate of the selected namespace. In this case, all other options will be made unavailable except for the Web application check box described in step 6 below.

  3. Choose whether the default database for globals is local or remote.

  4. Select an existing database for Globals for the default Global mapping of this namespace or click Create New Database, which launches either the database wizard or the remote database wizard.

  5. Optionally, you can choose whether the default database for routines is local or remote, then either use the Select an existing database for Routines drop-down to choose a database for the default Routine mapping of this namespace, or click Create New Database, which launches either the database wizard or the remote database wizard.

  6. Select the Create a default Web application for this namespace check box if you are creating a web application that accesses this namespace.

  7. Optionally, you can clear the Enable namespace for interoperability productions check box. For more information, see Create an Interoperability-Enabled Namespace below.

  8. After entering the required information, click Save to add your namespace to the configuration.

Create an Interoperability-Enabled Namespace

When you create a namespace on an InterSystems IRIS instance, the Enable namespace for interoperability productions check box is displayed at the bottom of the New Namespace page and is automatically selected. To create a namespace that is not interoperability-enabled, clear this check box before clicking Save.

If you do not clear the check box and create an interoperability-enabled namespace, the system automatically performs additional configuration tasks for the new namespace, as follows:

  • If the default globals database for this namespace is an existing database, it upgrades and recompiles some classes in that database.

    Caution:

    If you are also using this database in other namespaces, you might consider this change undesirable. When you create a new namespace in an InterSystems IRIS instance, carefully consider whether it is appropriate for this namespace to reuse an existing database.

  • It defines global mappings, routine mappings, and package mappings that make the InterSystems IRIS system classes and data available to the namespace.

  • It adds nodes to the ^%SYS global.

  • It creates a web application for the namespace, using the application name required by InterSystems IRIS: /csp/namespace.

Create a Foundation Namespace for Healthcare Interoperability

To create a Foundation namespace and production for healthcare interoperability, use the InterSystems IRIS for Health™ Installer Wizard or the HealthShare® HealthConnect Installer Wizard, rather than the New Namespace page. Once you have activated a Foundation namespace in the Installer Wizard, if you later need to modify an option, such as the routine database, you can use the Namespaces page.

Rename a Namespace or Modify Default Mappings

You can rename a namespace, or change the databases to which your namespace is mapped without restarting InterSystems IRIS, using the following procedure:

  1. Go to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces).

  2. On the Namespaces page, click the name of namespace you wish to modify.

  3. Change or replace the existing name to rename the namespace.

    Important:

    If you are renaming an interoperability-enabled namespace, you must take additional steps to complete the process.

    1. Open the InterSystems Terminal from the System Tray.

    2. Enter:

      do ##class(%Library.EnsembleMgr).EnableNamespace("<NewNamespace>",1)

      Where <NewNamespace> is the new name of the existing namespace.

    3. Go to the Web Applications page (System Administration > Security > Applications > Web Applications).

    4. Find the name of the application that corresponds to the old name of the namespace, and click Delete.

    5. Click the name of the application that corresponds to the new name of the namespace.

    6. Select Namespace Default Application and click Save.

    7. In the Terminal, enter:

      do ##class(%EnsembleMgr).DisableNamespace("<OldName>",1)

      Where <OldName> is the original name of the namespace that you are renaming.

  4. Choose the Default Database for Globals, the Default Database for Routines, and the Default Database for Temporary Storage from the list of defined databases.

    Note:

    Selecting a database that is configured not to journal globals (that is, the Journal globals property is set to No) from the Default Database for Temporary Storage drop-down list is not the same as selecting IRISTEMP; for more information, see Using Temporary Globals and IRISTEMP.

  5. Click Save.

Note:

Users directly accessing the database at the time of the change may need to log out of and then back into InterSystems IRIS to update their namespace mappings.

Add Global, Routine, and Package Mapping to a Namespace

In addition to having access to the globals and routines in the mapped database, 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.

Click the appropriate choice to begin mapping:

The following is a schematic diagram of how mapping works in a sample airline reservation application:

Test Namespace Mapping
Namespaces for Travel Agent and Flight Schedule have unique mappings, and are both mapped to the Airline Routes database.

Data and programs are stored in the database databases, the physical storage locations, and referred to by namespaces, the logical references.

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 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 Studio, 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.

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

Delete a Namespace

You can delete a namespace, including all mappings associated with it:

  1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Delete in the row of the namespace you want to delete.

  2. On the Delete Namespaces page, if you want to delete the Web Gateway pages from the physical path, select the check box.

  3. To delete the namespace and associated mappings, click Perform Action Now.

Next sectionConfiguring Databases
Previous sectionConfiguring System Information
FeedbackOpens in a new tab