Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.4 / All Documentation / Using Globals / Managing Globals
Previous section   Next section

Managing Globals

The Management Portal provides tools for managing globals, and the system classes provide methods to perform some of the same tasks. This chapter describes how to use these tools. It includes the following topics:
For information on defining global mappings, see the chapter “Configuring InterSystems IRIS®” in the System Administration Guide.

General Advice

As with the ObjectScript commands SET, MERGE, KILL, and others, the tools described here provide direct access to manipulate globals. If you delete or modify via global access, you bypass all object and SQL integrity checking and there is no undo option. It is therefore important to be very careful when doing these tasks. (Viewing and exporting do not affect the database and are safe activities.)
When using the tools described in this chapter, make sure of the following:
  • Be sure that you know which globals InterSystems IRIS uses. Not all of these are treated as “system” globals — that is, some of them are visible even when you do not select the System check box. Some of these globals store code, including your code.
    See the section “Global Variable Names to Avoid” in the “Rules and Guidelines for Identifiers” appendix of the Orientation Guide for Server-Side Programming.
  • Be sure that you know which globals your application uses.
    Even if your application never performs any direct global access, your application uses globals. Remember that if you create persistent classes, their data and any indices are stored in globals, whose names are based on the class names (by default). See “Data,” in the previous chapter.

Introduction to the Globals Page

The Management Portal includes the Globals page, which allows you to manage globals. On this page, you can:
This page also includes options for viewing routines and classes; these options are not discussed here.
To access this page from the Management Portal home page:
  1. Select System Explorer > Globals.
  2. Select the namespace or database of interest:
    • Select either Namespaces or Databases from the Lookin list.
    • Select the desired namespace or database from the displayed list.
    Selecting a namespace or database updates the page to display its globals.
  3. If you are looking for a particular global and do not initially see its name:
    • Optionally specify a search mask. To do so, enter a value into the Globals field. If you end the string with an asterisk “*”, the asterisk is treated as a wildcard, and the page displays each global whose name begins with the string before the asterisk.
      After entering a value, press Enter.
    • Optionally select System items to include all system globals in the search.
    • Optionally select a value from Page size, which controls the number of globals to list on any page.

Viewing Global Data

The View Global Data page lists nodes of the given global. In the table, the first column displays the row number, the next column lists the nodes, and the right column shows the values. This page initially shows the first hundred nodes in the global.
To access this page, display the Globals page and select the View link next to the name of a global. Or click the View button.
On this page, you can do the following:
  • Specify a search mask. To do so, edit the value in Global Search Mask as follows:
    • To display a single node, use a complete global reference. For example: ^Sample.PersonD(9)
    • To display a subtree, use a partial global reference without the right parenthesis. For example: ^%SYS("JOURNAL"
    • To display all nodes that match a given subscript, include the desired subscript and leave other subscript fields empty. For example: ^IRIS.Msg(,"en")
    • To display all subtrees that match a given subscript, use a value as in the previous option but also omit the right parenthesis. For example: ^IRIS.Msg(,"en"
    • To display nodes that match a range of subscripts, use subscriptvalue1:subscriptvalue2 in the place of a subscript. For example: ^Sample.PersonD(50:60)
      As with the previous option, if you omit the right parenthesis, the system displays the subtrees.
    Then click Display or press Enter.
  • Specify a different number of nodes to display. To do so, enter an integer into Maximum Rows.
  • Repeat a previous search. To do so, select the search mask in the Search History drop-down.
  • Select Allow Edit to make the data editable; see the next topic.
To close this page, click Cancel.

Editing Globals

Caution:
Before making any edits, be sure that you know which globals InterSystems IRIS uses and which globals your application uses; see “General Advice.” There is no undo option. A modified global cannot be restored.
The Edit Global Data page enables you to edit globals. In the table, the first column displays the row number, the next column lists the nodes, and the right column shows the values (with a blue underline to indicate that the value can be edited). This page initially shows the first hundred nodes in the global.
To access and use this page:
  1. Display the Globals page.
  2. Select the Edit link next to the name of a global.
  3. Optionally use the Global Search Mask field to refine what is displayed. See “Viewing Global Data.”
  4. Optionally specify a different number of nodes to display. To do so, enter an integer into Maximum Rows.
  5. If necessary, navigate to the value you want to edit by selecting the subscripts that correspond to it.
  6. Select the value that you want to edit.
    The page then displays two editable fields:
    • The top field contains the full global reference for the node you are editing. For example: ^Sample.PersonD("18")
      You can edit this to refer to a different global node. If you do so, your action affects the newly specified global node.
    • The bottom field contains the current value of this node. For example:
      $lb("",43144,$lb("White","Orange"),$lb("8262 Elm Avenue","Islip","RI",57581),"Rogers,Emilio L.",
      $lb("7430 Washington Street","Albany","GA",66833),"650-37-4263","")
      
    Edit the values as needed.
  7. If you make edits, click Save to save your changes, or click Cancel.
Or, to delete a node:
  1. Optionally select Delete global subnodes during deletion
  2. Click Delete.
  3. Click OK to confirm this action.
Also see “Performing Wholesale Replacements,” later in this chapter.

Finding Values in Globals

The Find Global String page enables you to find a given string in the subscripts or in the values of selected globals.
To access and use this page:
  1. Display the Globals page.
  2. Select the globals to work with. To do so, see steps 2 and 3 in the section “Introduction to the Globals Page.”
  3. Click the Find button.
  4. For Find What, enter the string to search for.
  5. Optionally clear Match Case. By default, the search is case-sensitive.
  6. Click either Find First or Find All.
    The page then displays either the first node or all nodes whose subscripts or values contain the given string, within the selected globals. The table shows the node subscripts on the left and the corresponding values on the right.
  7. If you used Find First, click Find Next to see the next node, as needed.
  8. When you are done, click Close Window.

Performing Wholesale Replacements

Caution:
Before making any edits, be sure that you know which globals InterSystems IRIS uses and which globals your application uses; see “General Advice.” This option changes the data permanently. It is not recommended for use in production systems.
For development purposes, the Find Global String page also provides an option to make wholesale changes to values in global nodes. To use this option:
  1. Display the Globals page.
  2. Select the globals to work with. To do so, see steps 2 and 3 in the section “Introduction to the Globals Page.”
  3. Click the Replace button.
  4. Use this page to find values as described in the previous section.
  5. Specify a value for Replace With.
  6. Click Replace All.
  7. Click OK to confirm this action.
    The page then displays a preview of the change.
  8. If the results are acceptable, click Save.
  9. Click OK to confirm this action.

Exporting Globals

Caution:
Because of how easy it is to import globals (which is an irreversible change), it is good practice to export only the globals you need to import. Note that if you export all globals, the export includes all the globals that contain code. Be sure that you know which globals InterSystems IRIS uses and which globals your application uses; see “General Advice.”
The Export Globals page enables you to export globals.
To access and use this page:
  1. Display the Globals page.
  2. Specify the globals to work with. To do so, see steps 2 and 3 in the section “Introduction to the Globals Page.”
  3. Click the Export button.
  4. Specify the file into which you wish to export the globals. To do this, either enter a file name (including its absolute or relative pathname) in the Enter the path and name of the export on server <hostname> field or click Browse and navigate to the file.
  5. Select the export file’s character set with the Character set list.
  6. In the page’s central box:
    • Choose an Output format
    • Choose a Record format
  7. Select or clear Check here to run export in the background...
  8. Click Export.
  9. If the file already exists, click OK to overwrite it with a new version.
The export creates a .gof file.

Importing Globals

Caution:
Before importing any globals, be sure that you know which globals InterSystems IRIS uses and which globals your application uses; see “General Advice.” There is no undo option. After you import a global into an existing global (thus merging the data), there is no way to restore the global to its previous state.
The Import Globals page enables you to import globals. To access and use this page:
  1. Display the Globals page.
  2. Click the Import button.
  3. Specify the import file. To do this, either enter a file (including its absolute or relative pathname) in the Enter the path and name of the import file field or click Browse and navigate to the file.
  4. Select the import file’s character set with the Character set list.
  5. Select Next.
  6. Choose the globals to import using the check boxes in the table.
  7. Optionally select Run import in the background. If you select this, the task is run in the background.
  8. Click Import.

Deleting Globals

Caution:
Before deleting any globals, be sure that you know which globals InterSystems IRIS uses and which globals your application uses; see “General Advice.” There is no undo option. A deleted global cannot be restored.
The Delete Globals page enables you to delete globals. To access and use this page:
  1. Display the Globals page.
  2. Select the globals to work with. To do so, see steps 2 and 3 in the section “Introduction to the Globals Page.”
  3. Click the Delete button.
  4. Click OK to confirm this action.

APIs for Management Tasks

InterSystems IRIS also provides the following APIs to perform some of the tasks described in this chapter:
  • The class %SYSTEM.OBJ provides the following methods:
    • Export() enables you to export globals to an XML file.
    • Load() and LoadDir() enable you to import globals contained in XML files.
    These are both available via the $SYSTEM variable, for example: $SYSTEM.OBJ.Export
  • The class %Library.Global provides the following methods:
    • Export() enables you to export globals to .gof and other file formats (not including XML).
    • Import() enables you to import globals to .gof and other file formats (not including XML).
    %Library.Global also provides the Get() class query, which you can use to find globals, given search criteria.
For pointers to additional APIs, see “Globals” in the InterSystems Programming Tools Index.
Previous section   Next section