Skip to main content
Previous sectionNext section

Managing InterSystems IRIS

This chapter explains common InterSystems IRIS® data platform operations tasks including displaying process details, broadcasting messages, and monitoring processes.

Maintaining Local Databases

You can review and maintain local databases on the Databases page of the Management Portal (System Operations > Databases). From this page, you can view the following information:

You also have the option to perform an integrity check using the buttons at the top of the page. For more information, see the Verifying Structural Integrity section of the “Introduction to Data Integrity” chapter of Data Integrity Guide.

Databases General Information

The Databases page (System Operation > Databases) contains a list of all local databases. For each local database, you see the following information:

Local Databases Information
Column Heading Definition
Name The database name; click this name to display more details. See Database Details Page.
Directory The system directory in which the database resides.
Max Size (GB) The maximum size allocated to which the database can grow, in gigabytes.
Size (MB) The current allocated size of the database, in megabytes.
Status
The status of the database: mounted (including which permissions it has), unmounted, or dismounted.
  • A mounted database is one for which Mount Required at Startup is selected, as described in Edit Database Properties in the “Configuring InterSystems IRIS” chapter of this guide, and which therefore must be mounted for InterSystems IRIS to start or become primary in a mirror; in this case, it is always mounted and accessible when InterSystems IRIS starts. Alternatively, it is a previously unmounted database that has been mounted dynamically when you accessed it or explicitly mounted it; in this case, it remains mounted until you explicitly dismount it or restart/stop InterSystems IRIS.
  • An unmounted database is one for which Mount Required at Startup is not selected and which therefore does not need to be mounted for InterSystems IRIS to start or become mirror primary, and has been neither accessed nor explicitly mounted; it is mounted dynamically when you access it or explicitly mount it, and remains mounted until you explicitly dismount it or restart/stop InterSystems IRIS.
  • A dismounted database is one that has been explicitly dismounted; it is inaccessible until you explicitly mount it or restart/stop InterSystems IRIS (that is, a dismounted database is not mounted dynamically if you try to access it). To permanently dismount a database you must remove it from the configuration, as described in Local Databases in the “Configuring InterSystems IRIS” chapter of this guide.
Encrypted Indicates whether or not the database is encrypted.
Journal Indicates whether globals in the database are journaled with a Y or an N.

In addition, the page contains a filter bar that you can use to control the number of databases displayed. For example, to list only the system databases, you might enter IRIS* in the Filter: text box; and/or to list only five databases per page, enter 5 in the Page size: text box; and/or to limit the number of rows displayed to three, enter 3 in the Max rows: text box (a + sign displayed with the number in the Results field indicates there are additional databases that meet the specified criteria, but they are not displayed).

Database Free Space Information

Managing the free space (empty blocks) in a database is an important aspect of database maintenance. To see free space information, you can display the Free space view of the Management Portal or use the ^%FREECNT utility. Remember that the size and free space attributes of a database in normal operation change continuously, and that numbers reported by the Portal or the utility at a given point in time are approximations only.

Display Free Space Information Using the Management Portal

To display free space information, which shows information about the amount of free space on each local database, navigate to the Databases page (System Operation > Databases) and click the Free space view radio button. The following table describes the information displayed:

Local Databases Free space Information
Column Heading Definition
Name The database name; click this name to display more details. See Database Details Page.
Directory The system directory in which the primary volume of the database resides.
Max Size The maximum allocated size to which the database can grow, in gigabytes. The default is unlimited when you create a database.
Size The current allocated size of the database, in megabytes.
Expansion Size Size (in MB) by which to expand the database. The default and recommended setting is zero (0) when you create a database, which indicates the use of system defaults (12% of the current size or 10 MB, whichever is larger). Under this setting, the expansion size will not be greater than 1GB.
Available The amount of free space (in MB) available in the database.
% Free The percentage of free space available in the database.
Disk Free Space The amount of space free on the volume.
Status The status of the directory, which indicates if the database is mounted and with what permissions.

For information about performing free space management operations from the Management Portal, see the Database Details Page section of this chapter.

Display Free Space Information Using ^%FREECNT

InterSystems IRIS also provides the ^%FREECNT utility, which you run by entering do ^%FREECNT in the Terminal, to display the free space available in a database.

When using ^%FREECNT in the %SYS namespace, you can choose to display the free space of all databases by entering an asterisk (*) at the prompt, or enter one database directory name. For example:

%SYS>do ^%FREECNT
 
Database directory to show free space for (*=All)? *
 
Databases Selected
------------------
c:\MyIris\mgr\
c:\MyIris\mgr\irisaudit\
c:\MyIris\mgr\irislib\
c:\MyIris\mgr\irislocaldata\
c:\MyIris\mgr\iristemp\
c:\MyIris\mgr\user\
Device:
Right margin: 80 =>
 
 
                            Database Free Space
                              Feb 15 2012  7:25 PM
Database                           Max Size  Size    Available %Free   Disk Free
c:\MyIris\mgr\                    Unlimited 191MB   19MB      9.94    60.79GB
c:\MyIris\mgr\irisaudit\          Unlimited 1MB     0.43MB    43      60.79GB
c:\MyIris\mgr\irislib\            Unlimited 319MB   27MB      8.46    60.79GB
c:\MyIris\mgr\irislocaldata\      Unlimited 1MB     0.55MB    55      60.79GB
c:\MyIris\mgr\iristemp\           Unlimited 4MB     1.5MB     37.5    60.79GB
c:\MyIris\mgr\user\               Unlimited 1MB     0.43MB    43      60.79GB
Copy code to clipboard

In a namespace other than %SYS, the utility shows the free space of the databases in that namespace. For example:

USER>Do ^%FREECNT
 
 
Databases Selected
------------------
c:\MyIris\mgr\user\
Device:
Right margin: 80 =>
 
 
                            Database Free Space
                              Feb 15 2012  7:28 PM
Database                           Max Size  Size    Available %Free   Disk Free
c:\MyIris\mgr\user\                 Unlimited 1MB     0.52MB    52      42.72GB
Copy code to clipboard
Note:

A <- flag (in the %Free column) indicates that the percentage of free space in the specified database has dropped below 5%. Ensure that there is enough space on the file system to handle database expansion.

The ^DATABASE utility is another way to display free space information, as well as perform other database tasks. For example, you can compact globals in a database, or you can recreate a database, which lets you clear the data in an existing database without changing the database’s name or size. See ^DATABASE in the “Using Character-based Security Management Routines” chapter of the Security Administration Guide for information about the utility.

Note:

The data structures used by InterSystems IRIS are self-balancing and suffer no performance degradation over time. It is never necessary to take a database down to rebuild it nor to compress data or indices to regain performance.

Database Details Page

The Database Details page displays detailed information about any database. To access this information from the Management Portal:

  1. Display the Databases page (System Operation > Databases).

  2. Click the name of the database for which you would like to see more details.

Along the top of the Database Details page is a row of buttons, which allow you to perform various database operations:

  • Mount / Dismount — Mount or dismount a database. The new status remains in effect until you explicitly change it or restart/stop InterSystems IRIS; to permanently dismount a database, you must remove it from the configuration.

  • Compact — Move free space distributed throughout a database to its end.

  • Truncate — Return free space at the end of a database to the underlying file system.

  • Defragment — Relocate global blocks so that the blocks representing a given global are in continuous sequence.

The page also includes information specific to the selected database, which is organized into a General Information table and a Database Size table:

General Information
Field Definition
Directory Name of directory where this database resides.
Resource Name Resource name assigned to this database.
Mounted Indicates whether this database is mounted.
Read Only Indicates whether this database is mounted as read-only.
Read Only Reason The reason the database is mounted as read-only.
Encrypted Indicates whether this database is encrypted.
Encryption Key ID Indicates encryption key ID.
Database Size
Field Definition
Block Size Block size (bytes) for this database.
Blocks Current number of blocks within this database.
Max Size Maximum size (MB) allowed for this database.
Size Maximum size (MB) allowed for this database.
Expansion Size: Amount (MB) this database will expand by.
Available Space Available space within this database.
% Free Space % Free space within this database.
Disk Free Space Free space on disk containing this database.
Last Expansion Time Last time this database expanded.
Full Indicates that this database is full.

Compacting a Database

Compacting a database moves free space distributed throughout the database to its end by relocating global blocks. You can then return the free space to the underlying file system by truncating the database. (You can also compact globals; see Compact Globals in a Database.)

When you compact a database, you specify the amount of the available free space to be positioned at its end, and the operation rearranges global blocks to ensure that at least that amount of free space is located at the end. (The operation cannot create more free space, so it can never place more at the end than the total available amount.)

For example, suppose the size of a database is 50 MB, with 15 MB of that being free space, and 5 MB of that free space already positioned at the end of the database. If you compact the database and specify more than 5 MB but less than 15MB, global blocks are moved from the end of the database to the beginning until the free space at the end equals the amount you specified; if you specify 15 MB, all possible global blocks are moved to the beginning.

To compact a database:

  1. Navigate to the Databases page (System Operations > Databases).

  2. Click the name of the database you want to compact. This takes you to its Database Details page.

  3. Click Compact on the ribbon at the top of the page. This displays the Compact Database dialog box, which shows the name and location of the database, its current size, the total available free space, and the amount of free space currently at the end of the file.

  4. Specify the amount of free space you want at the end of the file in the Target free space (in MB) at end of file text box. Your entry must be within the stated range. Once you have entered an amount, click OK. If all of the free space is already at the end, or there is no free space, the prompt does not appear and the OK button is disabled.

    Note:

    For a number of reasons, the operation may move more free space than the amount you specify. Conversely, because the numbers reported are approximations, it is possible that not all of the free space displayed can actually be moved.

  5. When the task is complete, a Background Task Info dialog box appears. Optionally, you can also view the task on the Background Tasks page (System Operation > Background Tasks).

  6. Click Close to redisplay the Database Details page. The page should automatically refresh to show the new database information.

Note:

The compact database operation is designed to run concurrently with normal database activity. The operation does consume some system resources, however, and may not complete if the system is under extremely high load. For these reasons, InterSystems recommends running this and other database reorganization operations (including compacting and defragmenting globals) during off-peak hours, and running only one such operation on a system at a time.

Truncating a Database

Truncating a database returns free space from the end of the database to the underlying file system. A database is often truncated after being compacted, which moves free space to the end of the database.

When you truncate a database, you specify a target size for the database. If there is sufficient free space at the end of database, the operation removes enough to reduce the database to the target size; if not, it removes all that can be removed. (To find out how much of a database’s free space is positioned at the end, compact the database; you do not need to complete the operation to display current total available free space and the amount at the end.)

Note:

This feature is not applicable to databases with raw volumes.

To truncate a database:

  1. Navigate to the Databases page (System Operations > Databases).

  2. Click the name of the database you want to truncate. This takes you to its Database Details page.

  3. Click Truncate on the ribbon at the top of the page. This displays the Truncate Database dialog box, which shows the name, location, and current size in megabytes (MB) of the selected database.

  4. Enter the Target File Size (MB), which must be less than the current size, and click OK. Enter 0 to remove all possible free space from the end of the file.

    Note:

    Free space for truncation purposes is different than free space for storing data. Certain control structures can be deleted during truncation if they are not being used for data storage. This can lead to a difference in reported free space.

Defragmenting a Database

Defragmenting a database rearranges global blocks within the database so that all of the blocks containing data for a given global are in consecutive sequence. The operation does not place big string blocks or pointer blocks from a global in sequence, but it does locate them in a contiguous area. As part of the process, the Defragment a database option compacts all globals in the same manner as the Compact globals in a database option, but with a target density of 70%. (If this is lower than the current global block density of the database, the size of the database does not increase.)

Note:

The IRISTEMP database cannot be defragmented.

In general, it is not necessary to run defragmentation on any regular basis. Some workloads, however, particularly those that read large portions of a database sequentially, can benefit from having global blocks organized sequentially.

The defragmentation process requires a certain amount of free space at the end of the database. For this reason, the following possibilities exist:

  • If there is enough free space at the end to perform the operation, it completes without any changes to the database beyond global defragmentation.

  • If there is not enough free space in the database, the database is expanded as necessary. When defragmentation is complete, you can truncate the database to remove the added free space.

  • If there is not enough free space in the database but there is significant free space that could be moved to the end, you are informed of this. In this case, compacting the database before you choose the Defragment a database option reduces the amount of expansion required to complete the defragmentation operation.

To defragment the globals in a database, use the following procedure:

  1. Navigate to the Databases page (System Operations > Databases).

  2. Click the name of the database you want to defragment. This takes you to its Database Details page.

  3. Click Defragment on the ribbon at the top of the page. This displays the Defragment Database dialog box, which shows the name, location, and current size in megabytes (MB) of the selected database, as well as a message describing the free space needed to defragment.

  4. Click OK.

  5. When the task is complete, a Background Task Info dialog box appears. Optionally, you can also view the task on the Background Tasks page (System Operation > Background Tasks).

  6. Click Close to redisplay the Database Details page. The page should automatically refresh to show the new database information.

Important:

The defragment operation temporarily relocates all of the data in the database, regardless of the degree of global fragmentation in the database prior to running the operation. Subsequent runs of the operation consume similar amounts of resources but do not provide any additional benefit.

Note:

The defragment operation is designed to run concurrently with normal database activity. The operation does consume some system resources, however, and may not complete if the system is under extremely high load. For these reasons, InterSystems recommends running this and other database reorganization operations (including compacting a database and compacting globals) during off-peak hours, and running only one such operation on a system at a time.

Global defragmentation can involve a temporary increase in the size of the database being compacted. If this causes the database to reach its configured maximum size (see Local Databases in the “Configuring InterSystems IRIS” chapter of this guide), or if expansion is not possible because there is insufficient space available on the storage volume, the operation is canceled.

Compacting Globals in a Database

Another way to manage database space is to compact the globals in a database using the ^DATABASE routine. Compacting globals consolidates global data into fewer blocks, increasing the amount of free space in a database.

When globals are created and updated, InterSystems IRIS typically allocates data in a manner that fills global blocks to about 70% of capacity. (Globals that have grown entirely in collation order may be allocated at closer to 90%.) In general, allowing InterSystems IRIS to manage global block density automatically is sufficient. However, some nonsequential patterns of data deletion may reduce average global block density considerably.

Note:

To see the current density of the global blocks in a database on a global by global basis, you can run an integrity check (as described in the Verifying Structural Integrity section of the “Introduction to Data Integrity” chapter in Data Integrity Guide) and examine the Data Level output for each global.

When you compact globals, you specify a desired global block density (90% by default) and the operation attempts to come as close to this as possible by consolidating data—for example, rearranging global data that is spread across three blocks into two. Typically (but not always), compacting globals yields a meaningful increase in available free space within a database. (If you specify a target density that is lower than the current global block density of the database, the size of the database does not increase.)

To compact the globals in a database, use the following procedure:

  1. Open the Terminal and change to the %SYS namespace.

  2. Enter do ^DATABASE, and select 7) Compact globals in a database from the menu.

  3. Specify the directory of the database on which you want to run the operation. You can specify multiple databases by entering ? at the Database directories to compact? prompt and then entering a list of numbers.

  4. Indicate that you awnt to compact all globals, or instead enter a list of individual globals to be compacted.

  5. Specify the target average global block density, respond to the rest of the prompts, and confirm.

Note:

The compact globals operation is designed to run concurrently with normal database activity. The operation does consume some system resources, however, and may not complete if the system is under extremely high load. For these reasons, InterSystems recommends running this and other database reorganization operations (including compacting a database and defragmenting globals) during off-peak hours, and running only one such operation on a system at a time.

Global compaction can involve a temporary increase in the size of the database being compacted. If this causes the database to reach its configured maximum size (see Local Databases in the “Configuring InterSystems IRIS” chapter of this guide), or if expansion is not possible because there is insufficient space available on the storage volume, the operation is canceled.

Controlling InterSystems IRIS Processes

An InterSystems IRIS system runs a number of processes. Application code as well as InterSystems IRIS system code executes within these processes. There are three categories of InterSystems IRIS processes:

  • User processes, created when a user connects to InterSystems IRIS.

  • Background processes, created when a user issues an ObjectScript Job command, or by the Management Portal or a utility (see Using the Background Tasks Page).

  • InterSystems IRIS system processes.

In this chapter, the word “process” by itself refers to both user and background processes.

You can manage and control processes using the Management Portal:

Process Management Functions
Function How to Access Function From The Portal
Display process information
Display the Processes page (System Operation > Processes).
Display process details
Display the Processes page, then click Details in the right hand column of the selected process to display the Process Details page.
Suspend/resume a process
Display the Processes page, then click Details in the right hand column of the selected process to display Process Details page. Then click Suspend or Resume on the operations bar, as desired.
Terminate a process
Display the Processes page, then click Details in the right hand column of the selected process to display the Process Details page. Then click Terminate or Terminate with <RESJOB> Error on the operations bar, as desired.
Display process variables
Display the Processes page, then click Details in the right hand column of the selected process to display the Process Details page. Then click the Variables tab to display the process variables.
Broadcast messages to terminals
Display the Processes page and click the Broadcast button to open the Broadcast dialog.

Display Process Information

To display all the active processes on the system and basic information about each, navigate to the Processes page (System Operation > Processes), which displays a table of the processes with statistics about each in columns.

The following table describes the process information available for display:

Process Column Information
Column Heading Definition
Job # Index of the Processes table.
Process ID Operating system process identification number (PID).*
User Name of the user who owns the process.
Device Current device the process is using. This can be:
  • |TCP|IP_address:Port_number — For an outbound connection from the instance.
  • |TCP|Port_number — For the superserver.
  • //./nul — The null device. This discards any output; if you attempt read from it, there will be no data.
Namespace Namespace in which the process is running.
Routine Name of the routine that the process is currently executing.
Commands Number of commands executed.
Globals Number of global references, including updates, executed (database reads and writes) since the process entered InterSystems IRIS.
State Process state. See the State property of the %SYS.ProcessQuery class documentation in the InterSystems Class Reference for an explanation of each state.
Client Name Name of the client system that connected to, or initiated the connection to, the process.
Client EXE Name of the executable that called the process.
Client IP IP Address of the system that initiated the process.
O/S Username Username assigned to the process by the operating system.
Details Button appears if you have authority to maintain this process. See Display Process Details.

* An asterisk (*) appears next to the process id if the user entered InterSystems IRIS in programmer mode. A plus or minus sign appears next to Callin processes:

  • + Process is in InterSystems IRIS

  • Process is not in InterSystems IRIS

The Callin API is an InterSystems IRIS facility that lets you execute and evaluate ObjectScript commands and expressions from within C programs.

Display Process Details

The Process Details page displays detailed information about any process. To access this information from the Management Portal:

  1. Display the Processes page (System Operation > Processes).

  2. Click Details in the row of the appropriate process. (This option exists only on processes that you have authority to maintain.)

The page also includes information specific to the selected process, which is organized into a General Information table, a Client Application Details table, and a Execution Details table:

General Information
Field Definition
Process ID Process ID (PID) number of this process.
User Name Name of the user currently logged in for this process.
Login Roles Login roles for the process.
Escalated Roles Additional roles granted to the process. These roles plus the Login Roles is the total set of roles granted to the process.
OS User Name Username assigned to the process by the operating system.
NameSpace Namespace in which the process is executing.
Process Priority Priority level of this process.
Global References Number of global references made by this process.
Private Global References Number of private global references made by this process.
Commands Executed Number of commands executed by this process.
Memory Limit Amount of memory (KB) allocated for use by this process.
Memory Peak Peak amount of memory (KB) used by this process.
Memory Used Amount of memory (KB) currently in use by this process.
Private Global Blocks Number of private global data blocks used by this process.
Current Device Name of the I/O device currently in use by this process.
Open Devices List of devices currently opened by this process.
Lock Lock information for this process. Click the link at top of the detail box for additional details (mode, counts, and full reference).
Client Application Details
Field Definition
Client Name Node name of the client that is connected, or initiated the connection, to this process (if any).
EXE Name Name of the executable client application client connected to this process (if any).
Client IP Address IP address of the executable client application client connected to this process (if any).
Info User-defined information (if any).
Execution Details
Field Definition
Process State Current execution state of this process.
In Tranaction Indicates whether or not this process is currently within a transaction.
Last Global Reference Last global referenced by this process.
Routine Name of the routine this process is currently executing.
Source Location Last reported source location (routine name plus offset) of this process.
Source Line Last reported line of source code executed by this process, if available.
Stopping a Process

From this page you can also stop or resume a process. You can stop a process in one of the following ways:

Suspend or Resume a Process

You may want to suspend a process if you are not sure what it is doing and want to investigate, or if a more important process is trying to run and needs the CPU cycles. To access this option from the Management Portal:

  1. Display the Processes page (System Operation > Processes).

  2. Click Details in the row of the appropriate process. This option only exists on processes that you have authority to maintain.

  3. Click Suspend on the options bar.

You may resume a suspended process at any time by clicking Resume from the same page.

Terminate a Process

You may want to terminate a process if it becomes unresponsive or is affecting other processes or users. To access this option from the Management Portal:

  1. Display the Processes page (System Operation > Processes).

  2. Click Details in the row of the appropriate process. (This option exists only on processes that you have authority to maintain. The portal displays the Process Details page for the process you selected.

  3. Click Terminate on the options bar.

    Optionally, to log the status of the process when it terminates, select the Terminate with RESJOB Error check box.

    Note:

    This option is enabled by default.

  4. Click Yes to confirm that you want to terminate the process. There is no way to resume a terminated process.

Display Process Variables

The Process Variables page displays all the variables used in the selected process giving the global name and the value of the global. To access this information from the Management Portal:

  1. Display the Processes page (System Operation > Processes) page.

  2. Click Details in the row of the appropriate process. (This option exists only on processes that you have authority to maintain.) The portal displays the Process Details page for the process you selected.

  3. Click Variables on the options bar.

Broadcast Messages to Terminals

You can broadcast messages to the terminals associated with a selected process or all processes; this utility is useful, for example, to ask people to sign off the system. However, you must use it carefully or you may cause messages to appear in the middle of reports that may be printing at the time.

The utility temporarily takes control of each terminal as it sends the message. Once the terminal receives the message, the previous process continues. The message appears on the terminal screen; it may disrupt the screen display, but it does not affect user input. The message does not appear in windows running ObjectScript utilities.

To broadcast a message to the terminals associated with a selected process, do the following in the Management Portal:

  1. Display the Processes page (System Operation > Processes).

  2. Click Broadcast (on the options bar) to open the Broadcast window.

  3. Enter the message to broadcast in the text box.

    (The dialog box notifies you if there are no active processes that can accept a message; you do not see a message text box or list of processes. Click Close.)

  4. Select the appropriate check boxes for the appropriate processes (PIDs) to receive the broadcast message. Use the Select All and Clear All buttons accordingly to help with the selection.

  5. Click Broadcast.

  6. After the completed message displays, click Close.

Using the Task Manager

To use the Task Manager, navigate to the Task Manager menu (System Operation > Task Manager) to the following options:

You can also interact with the Task Manager using the InterSystems Terminal, as described in the Using ^TASKMGR section.

Note:

The Task Manager polls every 60 seconds to see if there are any Tasks to be run. When you click Perform Action Now to schedule a Task, there may be a delay of up to 60 seconds before the newly scheduled Task actually runs.

New Task

The New Task option starts the Task Scheduler Wizard. This tool allows you to schedule a new task to run.

Note:

You can also use the Task Scheduler Wizard to edit an existing task by selecting the existing task from the Task Schedule page.

  1. On the first page of the Task Scheduler Wizard, provide the following details about the new task:

    • Task name

    • Description

    • Namespace to run task in — Choose from the list of defined namespaces in which to run the task

    • Task type — Choose from among the listed tasks. For details about the available tasks, see Task Types below.

      Note:

      Depending on the task type selected, you may be presented with a form in which to specify additional information; for example, if you are scheduling an IntegrityCheck, the form prompts you for Directory, Filename, and KeepDays (number of days to keep the file).

  2. Task priority — Choose from Priority Normal, Priority Low, or Priority High. For more information about priority, read the Priority section of the “Process Management” chapter in Specialized System Tools and Utilities.

  3. Run task as this user — Choose from the list of defined users. To choose a different user than the one you are logged in as, you must have the %Admin_Secure:Use privilege.

    Note:

    If the chosen user is disabled, the task is suspended until the user is enabled and the task is resumed manually. This does not apply to built-in System tasks, which run even when the chosen user is disabled.

    Each task consumes a license unit, with the license user ID based on the InterSystems IRIS username you select; see License Login Special Considerations in the “Managing InterSystems IRIS Licensing” chapter of this guide for more information.

  4. Open output file when task is running and Output file — If the task creates output, the log file is written to the directory specified.

  5. Suspend task on error? — Specify whether the task will be rescheduled and continue to run after an error, or suspended. The default is No, to reschedule and run the task after an error.

  6. Reschedule task after system restart? — Specify whether you want to reschedule the task when the system restarts (that is, if the system is down when the task is scheduled to run):

    • No specifies that the task should run when the system restarts.

    • Yes specifies that the task should be rescheduled for the next logical time after the system restarts.

  7. Send completion email notification to — If you have configured email settings for the Task Manager (see Configuring Task Manager Email Settings in the “Configuring InterSystems IRIS” chapter of this guide), enter a comma-separated list of email addresses to which a notification should be sent when the task ends successfully.

  8. Send error email notification to — If you have configured email settings for the Task Manager, enter a comma-separated list of email addresses to which a notification should be sent when the task ends in error.

  9. How should task run for Mirror — If this instance is a mirror member, specify the type of member the task can be run on:

    • primary failover member only

    • backup failover member and async members only (all except primary)

    • all mirror members (primary, backup, and asyncs)

    Important:

    For a task to run on a mirror member, this option must be set for all tasks on the mirror member. Adding an instance to a mirror member does not automatically update this option in user-defined tasks. As such, you must either:

    • Define this setting when you create a task even if the instance is not a mirror, so it can run if the instance is added to a mirror.

    • Make sure you review all user-defined tasks when an instance is added to a mirror and set How should task run for mirror.

    Note:

    When the status of a failover member is in transition, for example when the backup is in the process of taking over as primary, the Task Manager does not run any tasks on that member until its status as primary or backup is established.

    After you have filled in all the necessary fields, click Next.

  10. On the second page of the Task Scheduler Wizard, specify when the new task should run. The options are:

    • Daily — A daily interval (for example, every other day, or every third day).

    • Weekly — A weekly interval on specific days of the week.

    • Monthly — A monthly interval on a specific day of the month.

    • Monthly (by day) — A monthly interval on a specified day of the week (for example, first Monday, or third Wednesday).

    • After another task completes — After a specified task runs.

    • On demand — Only when manually executed.

    The Daily, Weekly, Monthly, and Monthly (by day) fields allow you to specify what time during the day the task should run:

    • Start Date — The first day the scheduled task should run.

    • End Date — The last day the scheduled task should run.

    • Task execution details, which specify what happens when a task executes as follows:

      • Run once at this time — At the specified time, the task executes once.

      • Run every ____ — During the specified time range, the task executes repeatedly at the specified interval.

      Note:

      By default, all new tasks expire if they miss their scheduled time for any reason. If you wish to change this behavior, see Changing Task Expiration Behavior below.

    After you have filled in all the necessary fields, click Finish to schedule the task.

Task Types

This section describes the predefined task types you can choose when creating or editing a task. Some tasks are only available from certain namespaces.

Note:

You can define your own task types using the %SYS.Task.Definition API; for details, see the class documentation in the InterSystems Class Reference.

  • CheckLogging — creates an alert or turns off ^ISCSOAP logging and any internal logging if it has been running too long (by default, 2 days)

  • CleanSQLIndex— cleans up stale SQL Statement Index entries

  • CumuIncrDBList — a cumulative backup of databases in the defined list

  • DiagnosticReport — collects and delivers diagnostic reports to the WRC

  • FullAllDatabases — a full backup of all databases

  • FullDBList — a full backup of databases in the defined list

  • IncrementalDBList — an incremental backup of databases in the defined list

  • IntegrityCheck — an integrity check of databases in the namespace. The Integrity Check task only appears when the %SYS namespace is selected

  • InventoryScan — compiles an inventory scan of the instance

  • PurgeAudit — purge the audit database after a specified time following a journal switch

  • PurgeBackupLog — purge the backup log after a specified time following a database backup

  • PurgeErrorsAndLogs — purge error globals and messages.log based on settings in the iris.cpf file (see ErrorPurge and MaxConsoleLogSize parameters in the “[Startup]” section of the Configuration Parameter File Reference)

    Note:

    When System Monitor is running, it monitors and limits the size of the messages log.

  • PurgeJournal — purge journal files that meet the purging criteria

  • PurgeTaskHistory — purge Task Manager history files

  • ResourceCleanup — free up resources registered to jobs that no longer exist

  • RunLegacyTask — run a legacy task, that is, your own programmatic task; the line you enter in the text box, for example do ^MyCode, must be executable in the Terminal

    Note:

    Do not use the local variable Status in RunLegacyTask code. InterSystems IRIS uses this variable, and if it is modified by RunLegacyTask code, the task is likely to end with an error status.

    A legacy task that fails to complete due to an error is marked Suspended due to error and is not scheduled to run until the error is corrected and you resume the task.

  • SecurityScan — disables expired user accounts, and expires user passwords and web session tokens

  • SwitchJournal — switch to a new journal file

  • UpdateSQLStats — updates the information on SQL query statistics

On-demand Task

The On-demand Task page (System Operation > Task Manager > On-demand Task) lists the tasks you have scheduled as on-demand. The list includes the task name, a description, and an option to Run the task from this page. You can sort the information in the table by clicking any column heading. When you click Run, the Run Task Wizard page displays the task name and ID, and the date and time the task will run; click Perform Action Now to confirm the information and schedule the task.

Upcoming Tasks

The Upcoming Tasks page (System Operation > Task Manager > Upcoming Tasks) lists the tasks scheduled to run within a certain interval. To select an interval, click an option in the Scheduled to run: search pane to the left of the task list. If you select the To a date option, you can either enter a date in yyyy-mm-dd format or click the calendar icon to select a date from the calendar.

You can sort the information in the task list by clicking any column heading. You can Suspend or Resume the scheduling of each task by clicking the appropriate option:

  • Suspend — Lets you suspend the task; a Do you want to reschedule task when task is supposed to run? drop-down list lets you specify:

    • No. Upon resuming the task, the Task Manager attempts to run missed instances of the task before returning to the normal schedule.

    • Yes. Upon resuming the task, the Task Manager returns to the normal schedule without attempting to run missed instances.

  • Resume — Lets you resume a suspended task.

Task Schedule

The Task Schedule page (System Operation > Task Manager > Task Schedule) lists all scheduled tasks. You can sort the information in the table by clicking any column heading. You can view Details or History, as well as Run, a scheduled task by clicking the appropriate option:

  • Task Name — Lets you view details about the task and perform operations on it.

  • History — Displays the task’s history.

  • Run — Lets you run the task. A Run Task wizard displays the task name and ID, and the date and time the task will run; click Perform Action Now to confirm the information and schedule the task.

Task Details

To display detailed information about a scheduled task and perform one of several operations on it, click the task’s name in the Task Name column. The Task Details page displays information and execution details about the selected task. You can perform one of the following operations on the task by clicking the appropriate button:

  • Edit — Change the task definition and schedule using the Task Scheduler Wizard.

  • History — View the task’s history.

  • Resume/Suspend — Suspend a task/resume a suspended task, as on the Upcoming Tasks page.

  • Delete — Delete the task permanently.

  • Export — Export a task to a file that can later be imported, including by another InterSystems IRIS instance.

  • Run — Schedule the task. When you click Run, the Run Task Wizard page displays the task name and ID, and the date and time the task will run; click Perform Action Now to confirm the information and schedule the task.

Note:

Some of the actions described are unavailable while a task is running.

Scheduled Task History

To display history information about an individual scheduled task, click the History link in the row of the item. The Task History page displays detailed history for the selected task. The Result column indicates the outcome the last time the task was run, showing either Success or an error message. You can sort the information in the table by clicking any column heading.

The Details link at the top of the page displays the Task Details page for the selected task.

Task History

The Task History page (System Operation > Task Manager > Task History) lists the history of all tasks executed by the Task Manager.

You can sort the information in the table by clicking any column heading. To filter out system tasks, select the Show only user-defined task types check box at the top of the table.

Import Tasks

The Import Tasks page (System Operation > Task Manager > Import Tasks) lets you import and run a task by browsing to a previously-exported task file, then clicking Perform Action Now. For information about exporting tasks to a file, see Task Details in this section.

Using ^TASKMGR

The ^TASKMGR routine allows you to configure the Task Manager using the Terminal. Except when noted otherwise, ^TASKMGR and the Management Portal contain the same options for configuring tasks; the one you use is a matter of preference.

To use ^TASKMGR:

  1. Open the Terminal.

  2. Enter set $namespace = “%SYS” to change to the %SYS namespace.

  3. Enter do ^TASKMGR.

For more details about how to schedule or edit a task programmatically, see the %SYS.TaskSuper class documentation in the InterSystems Class Reference.

Changing Task Expiration Behavior

By default, all tasks are configured to expire if they miss their scheduled time. This could happen for a number of reasons; for example, when InterSystems IRIS is down during the scheduled time, or if the previous run of the task extends beyond the next scheduled time. When a task expires, it does not run until the next scheduled time.

The ^TASKMGR routine (but not the Management Portal) contains the option to change this behavior, such that a scheduled run is never skipped. To do so:

  1. Open the Terminal.

  2. Enter set $namespace = “%SYS” to change to the %SYS namespace.

  3. Enter do ^TASKMGR.

  4. Select option 2.

  5. Enter the task number you want to edit.

  6. Press Enter to save the defaults of each option until you reach Task Expires?

  7. Enter No.

Alternatively, you can specify a grace period, such that the task does not expire immediately after it is missed. Instead, the Task Manager runs the missed task as soon as it is able. To adjust this grace period of when a specific task expires:

  1. Open the Terminal.

  2. Enter set $namespace = “%SYS” to change to the %SYS namespace.

  3. Enter do ^TASKMGR.

  4. Select option 2.

  5. Enter the task number you want to edit.

  6. Press Enter to save the defaults of each option until you reach Task Expires?

  7. Enter Yes.

  8. At the Expires in how many days? prompt, enter the number of days before the task should expire.

  9. At the Expires in how many hours? prompt, enter the number of hours before the task should expire.

  10. At the Expires in how many minutes? prompt, enter the number of minutes before the task should expire.

Using the Background Tasks Page

A background task is an asynchronous job process that runs in the background, independently of the process that created it. A background task is created when a user issues an ObjectScript JOB command, or by the Management Portal or a utility to execute a job without requiring the user to wait for completion. For example, when you use the Portal to truncate a database, as described in Truncating a Database earlier in this chapter, a background task is started.

The Background Tasks page (System Operation > Background Tasks) lists past and active background tasks. You can purge the log of past background tasks at any time.

When a background task is active, the process can also be seen on the Processes page (System Operation > Processes), as described in Controlling InterSystems IRIS Processes in this chapter.