Managing Caché

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:

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

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

Displaying Free Space Information

To get free space information, you can display the Database Freespace page 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 ^%FREECNT

Caché 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:\MyCache\mgr\
c:\MyCache\mgr\cacheaudit\
c:\MyCache\mgr\cachelib\
c:\MyCache\mgr\cache\
c:\MyCache\mgr\cachetemp\
c:\MyCache\mgr\docbook\
c:\MyCache\mgr\samples\
c:\MyCache\mgr\user\
Device:
Right margin: 80 =>
 
 
                           Cache Database Free Space
                              Feb 15 2012  7:25 PM
Database                           Max Size  Size    Available %Free   Disk Free
c:\MyCache\mgr\                    Unlimited 191MB   19MB      9.94    60.79GB
c:\MyCache\mgr\cacheaudit\         Unlimited 1MB     0.43MB    43      60.79GB
c:\MyCache\mgr\cachelib\           Unlimited 319MB   27MB      8.46    60.79GB
c:\MyCache\mgr\cache\              Unlimited 1MB     0.55MB    55      60.79GB
c:\MyCache\mgr\cachetemp\          Unlimited 4MB     1.5MB     37.5    60.79GB
c:\MyCache\mgr\docbook\            Unlimited 144MB   11MB      7.63    60.79GB
c:\MyCache\mgr\samples\            Unlimited 114MB   52MB      45.61   60.79GB
c:\MyCache\mgr\user\               Unlimited 1MB     0.43MB    43      60.79GB

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:\MyCache\mgr\user\
Device:
Right margin: 80 =>
 
 
                           Cache Database Free Space
                              Feb 15 2012  7:28 PM
Database                           Max Size  Size    Available %Free   Disk Free
c:\MyCache\mgr\user\               Unlimited 1MB     0.52MB    52      42.72GB

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 filesystem to handle database expansion.

You may choose the device to which to send the information and choose the line length of the display.

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 moves enough global blocks from the end to the beginning 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) and click Freespace to display the Database Freespace page.

2. Click Compact in the row of the database you want to compact. This displays the Compact Database page, 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.

   Note:

   If a database is mounted read only and the Caché instance is not a backup or async mirror member (see the “Mirroring” chapter of the Caché High Availability Guide), the Compact link does not appear in its row on the Database Freespace page.

3. The Target freespace (in MB) at end of file prompt allows you to specify the amount of free space you want at the end of the file following the operation. 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.

4. When the Compact dialog box displays a message that the background job has started, click the Click here to view the background tasks page link near the top of the page to view the status of Compact Database Space background tasks on the Background Tasks page (System Operation > Background Tasks).

5. In the Compact dialog box, click Done to redisplay the Database Freespace page. If >> is displayed in the first column of the database row, refresh the page to see the new size displayed in the Size column.

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

To truncate a database:

1. Navigate to the Databases page (System Operation > Databases) and click Freespace to display the Database Freespace page.

   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.

2. Click Truncate in the row of the database you want to truncate. This displays the Truncate Database page (System Operation > Databases > Freespace > Truncate), which shows the name, location, and current size in megabytes (MB) of the selected database.

   Note:

   If a database is mounted read only and the Caché instance is not a backup or async mirror member (see the “Mirroring” chapter of the Caché High Availability Guide), the Truncate link does not appear in its row on the Database Freespace page.

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

4. When the page displays a message that the background job has started, click the Click here to view the background tasks page link near the top of the page to view the status of background tasks on the Background Tasks page (System Operation > Background Tasks).

5. In the Truncate dialog box, click Done to redisplay the Database Freespace page. If >> is displayed in the first column of the database row, refresh the page to see the new size displayed in the Size column.

Compacting Globals in a Database

The Compact globals in a database option of the ^DATABASE routine consolidates global data into fewer blocks, increasing the amount of free space in a database.

When globals are created and updated, Caché 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 Caché to manage global block density automatically is sufficient. However, some nonsequential patterns of data deletion may reduce average global block density considerably.

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 for a numbered list, and then a list of numbers, for example 1,4,7-10.

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

5. Specify the target average global block density, indicate whether you want to display the results of the compacting operation for each global, specify the output device, and confirm.

Defragmenting Globals in a Database

The Defragment globals in a database option of the ^DATABASE routine 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 globals in 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.)

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 so you can first compact the database and then choose the Defragment globals in a database option again, reducing the amount of expansion required to complete the defragmentation operation.

To defragment 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 14) Defragment globals in a database from the menu.

3. Specify the directory of the database on which you want to run the operation.

4. Indicate that want to allow expansion, if required, and complete.

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:

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

• + Process is in Caché

• – Process is not in Caché

The Callin API is a Caché 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.)

3. The portal displays the Process Details page for the process you selected.

Each category is described in one of the tables that follow:

• General information

• Client application details

• Execution details

In most cases, you can click any of the indicators to display a description of the item in the bottom detail box at the lower left corner of the page of the Process Details page.

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

• Suspend a process with the intention of resuming the process later.

• Terminate a process, which entirely cancels the process.

Broadcast Messages to the 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 Caché 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.

Manage Refresh Interval

You can control whether or not to auto-refresh the process information and, if you want to refresh the information, you can specify how frequently it is refreshed. The minimum interval for auto-refreshing the data is 5 seconds; the default interval is 10 seconds.

To turn on auto-refresh for all active processes, do the following in the Management Portal:

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

2. Click the on (on the options bar) and enter the interval (minimum: 5 seconds) in the text box.

3. To turn on auto-refresh for process details, do the following in 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 the on (on the options bar) and enter the interval (minimum: 5 seconds) in the text box.

New Task

The New Task option starts the Task Scheduler Wizard.

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

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

   • 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 Caché username you select; see License Login Special Considerations in the “Managing Caché Licensing” chapter of this guide for more information.

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

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

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

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

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

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

     • run on primary failover member only

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

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

     Important:

     This setting must be set for all tasks on the mirror member, the task will not run on a mirror member if not. Adding an instance to a mirror member does not automatically update this setting 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.

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

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:

• taskname — 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 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.

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.TaskOpens in a new tab class documentation in the InterSystems Class Reference.