Skip to main content

Online Backup Utilities

Online Backup Utilities

InterSystems IRIS provides utilities to perform backup tasks. The ^BACKUP routine provides menu choices to run common backup procedures, which you can also run independently and in some cases non-interactively using scripts.

The utility names are case-sensitive. Run all these utilities from the %SYS namespace:

InterSystems IRIS maintains a bitmap list of database blocks modified since the last backup; you can use this list to keep track of database updates during backup stages. The ^DBSIZE utility, which inspects these bitmaps, helps you calculate the size of a backup. The InterSystems IRIS ^BACKUP utility uses a multipass scan of these lists to back up only the blocks modified since the last pass.

Estimate Backup Size Using ^DBSIZE

Immediately before performing an InterSystems IRIS backup, you can estimate the size of its output using the ^DBSIZE utility. It is only an estimate, since there is no way of knowing how many blocks will be modified once the backup starts. You can obtain a more accurate estimate by preventing global updates while running ^DBSIZE, and then running your backup before resuming global updates.

You can estimate the size of backups in two ways:

Note:

A database must be in the database backup list before you can evaluate it with ^DBSIZE. See Define Database Backup List for details.

Run ^DBSIZE Interactively

The following procedure describes the steps necessary to run ^DBSIZE interactively:

  1. Open the Terminal and run the utility from the %SYS namespace:

    %SYS>Do ^DBSIZE

  2. InterSystems IRIS displays the ^DBSIZE main menu:

                   Incremental Backup Size Estimator
 
 
What kind of backup:
   1. Full backup of all in-use blocks
   2. Incremental since last backup
   3. Cumulative incremental since last full backup
   4. Exit the backup program
1 =>

  3. Enter the appropriate menu option to select the type of backup for which you want an estimate: full, incremental, or cumulative. The prompts are the same for each type.

  4. At the following prompt either press Enter to suspend updates so that you get a more accurate estimate or enter No to allow updates:

    Suspend Updates?  Yes=>

    If you choose to suspend updates, you receive the following message:

    WARNING: Switch is set and may affect production for up to 30 seconds.
Waiting for disk cleanup to finish... ready.

  5. The output first shows you how many InterSystems IRIS blocks you need to do the type of backup you selected. It shows an estimate for each directory in the backup list and a total. The following is an example of the display for a full backup:

    
                                                     In-Use    Block
Directory                                            Blocks    Size

c:\iris-install\mgr\                                  19,963   (8KB)
c:\iris-install\mgr\irisaudit\                           189   (8KB)
c:\iris-install\mgr\user\                                 61   (8KB)
                                                      --------------
 Total number of database blocks:                     36,228

    The display for an incremental and cumulative backup looks similar to this:

    
                                                     Modified  Block
Directory                                            Blocks    Size
 
c:\iris-install\mgr\                                       5   (8KB)
c:\iris-install\mgr\irisaudit\                             3   (8KB)
c:\iris-install\mgr\user\                                  1   (8KB)
                                                    - --------------
Total number of database blocks:                          10

  6. The utility then displays information about backup disk file space:

    Total backup size, including overhead of volume and pass labels:
 
     For a disk file:
          Number of 512-byte blocks:  598,092  (306,223,104 bytes)

Use the ^DBSIZE Function

You can also call ^DBSIZE from a routine. To do so, you use the following function:

$$INT^DBSIZE(backup_type)
Important:

The values of backup_type differ from the menu option numbers when running ^DBSIZE interactively.

backup_type Description
1 Incremental backup
2 Full backup
3 Cumulative incremental backup

For example, to see the size estimate for running a full backup:

%SYS>w $$INT^DBSIZE(2)
18950^5^160952320^2710^160309248^313104^313104

The returned value is seven numbers separated by a caret (^). In this example, the returned value 18950 is the total estimated size of the backup, in blocks; the returned value 5 indicates the number of database directories to back up. The following table shows what is contained in each piece of the output.

Position of output Description
Piece 1 Number of database blocks for backup

(-1 if error during processing or invalid parameter)
Piece 2 Number of directories to back up
Piece 3 Number of bytes for media (not including inter-record gaps)
Piece 4 Number of blocks for media
Piece 5 Number of bytes for a disk file
Piece 6 Number of 512-byte blocks for a disk file

The following shows the output of calling the ^DBSIZE function for each type of backup:

%SYS>w $$INT^DBSIZE(1)
466^5^4157440^70^4122624^8052^8052

%SYS>w $$INT^DBSIZE(2)
18950^5^160952320^2710^160309248^313104^313104

%SYS>w $$INT^DBSIZE(3)
466^5^4157440^70^4122624^8052^8052

Perform Backup and Restore Tasks Using ^BACKUP

The InterSystems IRIS ^BACKUP utility allows you to perform InterSystems IRIS backup and restore tasks from a central menu as shown in the following example:

%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
5) Abort Backup

6) Display Backup volume information
7) Monitor progress of backup or restore

Option?

Enter the appropriate menu option number to start the corresponding routine. Press Enter without entering an option number to exit the utility.

Subsequent sections in this document describe the utilities started by choosing the corresponding option:

  1. Back Up Databases Using ^DBACK

  2. Restore All Databases Using ^DBREST

  3. Restore Selected Databases Using ^DBREST

  4. Edit/Display List of Directories for Backup Using ^BACKUP

  5. Abort a Backup Using ^BACKUP

  6. Display Information About a Backup Volume Using ^BACKUP

  7. Monitor Backup or Restore Progress Using ^BACKUP

Back Up Databases Using ^DBACK

The InterSystems ^DBACK utility allows you to backup InterSystems IRIS databases. Running the ^DBACK utility is equivalent to choosing option 1 from the ^BACKUP utility menu. The following is an example of running the utility from the Terminal:

  1. First, make sure you have defined your database backup list and choose your output device for the backup file.

  2. From the %SYS namespace run the ^DBACK routine:

    %SYS>Do ^DBACK
 
 
                      Backup Utility
              --------------------------
What kind of backup:
   1. Full backup of all in-use blocks
   2. Incremental since last backup
   3. Cumulative incremental since last full backup
   4. Exit the backup program

  3. Select which backup type (full, incremental, or cumulative) to run by entering the appropriate menu option number. The procedure for running the backup is the same regardless of what type you run.

  4. Enter the output device and a description of the backup:

    Specify output device (type STOP to exit)
Device: c:\iris-install\mgr\backup\FullDBList_20081201_003.cbk =>

Backing up to device: c:\iris-install\mgr\backup\FullDBList_20081201_003.cbk
Description: Full Backup using ^DBACK

    The device defaults to that of the last backup. This example uses the format of the online backup device.

  5. The utility then displays a list of the database directories to back up (those in your database backup list). For example:

     Backing up the following directories:
 c:\iris-install\mgr\
 c:\iris-install\mgr\irisaudit
 c:\iris-install\mgr\user\

  6. Answer Y to start the backup. The journal file switches and you see a display of the backup progress:

    Start the Backup =>  [answer Y or N] => y
Journal file switched to:
c:\iris-install\mgr\journal\20081201.004
. 
Starting backup pass 1

  7. At the beginning of the third and final pass, the utility displays information about the oldest journal file that will be required for transaction rollback when the backup is restored, for example:

    Starting backup pass 3
 
Journal file 'c:\intersystems\test62\mgr\journal\20180919.003' and the subsequent ones
are required for recovery purposes if the backup were to be restored
 
Journal marker set at
offset 197180 of c:\intersystems\test62\mgr\journal\20180919.003

    This information is available in the backup log.

  8. When the backup finishes successfully, you see the following:

    ***FINISHED BACKUP***
 
Global references are enabled.
 
Backup complete.
 
%SYS>
    Note:

    Following successful completion of the backup, ^DBACK writes your description of the backup to the backup history (see View Backup History). Note that this can trigger a journal purge, depending on the When to purge journal files > After this many successive backups setting on the Journal Settings page (the default is 2); for more information, see Configuring Journal Settings.

External Entry Points for ^DBACK explains how to call this utility from your external backup procedures using the provided entry points.

External Entry Points for ^DBACK

The entry points provided for the ^DBACK utility are for you to use in your external backup procedures. You must use them as described to ensure the integrity of the backup. All of the entry points return 1 if they are successful or 0 if they fail. The following external entry points are available for the ^DBACK routine:

BACKUP^DBACK

This procedure invokes a backup using the passed arguments to satisfy the questions that are asked during the interactive execution of ^DBACK.

BACKUP^DBACK(argfile,TYPE,DESC,OUTDEV,kiljrn,LOGFILE,MODE,clrjrn,swjrn,
nwjrnfil,quietimeout,taskname)

The capitalized arguments are the ones most important to the backup procedure in this release of InterSystems IRIS. Due to changes in the journaling mechanism, you can no longer delete the current journal file, clear the current journal file, or specify a new journal file name in the backup utilities. As a result, this version of InterSystems IRIS ignores many of the arguments as described in the following tables.

Argument Description
argfile No longer used; always use a null value.
TYPE Type of backup (required)

Values:

I — Incremental

C — Cumulative

F — Full

E — External full backup using a third-party or operating system backup utility
DESC Description stored in the backup label and in the backup history global. Free form text string that can be empty.

External (type E) backups ignore the arguments in the following table. Whether they are ignored or required for other backup types is also indicated in the table.

Argument Description
OUTDEV Output filename for the backup (required).
kiljrn Indicates whether to switch the journal file:

Y — switch the journal file (recommended)

N — do not switch

(No longer allows deletion of the current journal file)
LOGFILE Indicates whether or not to log and where to write the output of the function:

File name — writes all messages that would be sent to the terminal to this file (recommended)

Null value — no log file
MODE Indicates what output to write to the terminal during the procedure; this does not control what is written to the log file.

Values:

“NOISY” — write all text on terminal (default)

“QUIET” — only write text related to abnormal conditions

“NOINPUT” — do not send any output as no terminal is attached to this process; if a read is required, the backup aborts
clrjrn Indicates whether to switch the journal file:

Y — switch the journal file (recommended)

N — do not switch

(No longer allows clearing of the current journal file)
swjrn Indicates whether or not to switch the journal file:

Y — switch the journal file (recommended)

N — do not switch (If the clrjrn or kiljrn arguments have a value of Y, swjrn converts to Y and the journal file is switched)
nwjrnfil (Ignored)

The following are two optional arguments:

Argument Description
quietimeout Number of seconds to wait for the system to quiesce before aborting the backup. A zero (0) or negative value indicates waiting indefinitely (default = 60).
taskname Task name used internally for backup types F, I, and C.

Using these external entry points requires read/write access to the ^SYS global for all modes. An external (type E) backup deletes the .IND, .INE, and .INF files in the directories in the ^SYS global. The routine also records this backup with the description in the backup history global as being the LASTFULL backup.

If you set switch 10 when you call this routine, it remains set throughout the backup. If you set switch 13, then the procedure converts it into a switch 10 while the backup performs necessary Set and Kill commands and then restores it to switch 13 upon exit.

The routine performs the New command on variables defined by this entry point, but does not on those defined within the body of the ^DBACK procedure. As a result, you must be careful to protect all other variables in any calling routine prior to calling ^DBACK.

Return values:

  • 0 — failed; check log file if specified.

  • 1 — success

  • 1,warning message string — success, but with warnings. The warnings are separated by a tilde character (~) in the string.

LISTDIRS^DBACK

This procedure opens an output file and writes a list to it of database directories included in a backup. If the list is empty, the procedure backs up all database directories (except IRISTEMP, IRISLIB, and IRISLOCALDATA). The format of the function is as follows:

LISTDIRS^DBACK(file,mode)
Argument Description
file Name of the output file name to which the function writes the list of database directories in the backup list.
mode Indicates what output to write to the terminal during the procedure.

“QUIET” — Only display return value and text related to abnormal conditions.

Any other value — Display the directory list at the terminal.

The following is an example of the output displayed on the terminal:

%SYS>w $$LISTDIRS^DBACK("c:\temp\listdirs.txt","NOISY")
 
List of directories to be backed up
     c:\iris-install\mgr\irisaudit\
     c:\iris-install\mgr\irislib\
     c:\iris-install\mgr\
     c:\iris-install\mgr\user\
1
%SYS>

Notes for this procedure:

  • Requires read access to the ^SYS global.

  • Does not set or clear any switches.

  • Issues a New command on all local variables.

CLRINC^DBACK (concurrent external backup Only)

This procedure is called to clear the incremental backup bitmaps that mark blocks as modified for the databases in the backup list. At the same time it also deletes the backup history as it is no longer possible to do any sort of a backup without first performing a full backup. This procedure is designed to be used prior to doing an external full backup with InterSystems IRIS running. If you perform an external backup with InterSystems IRIS down, then before shutting down the system, call this entry point. The format of the function is as follows:

CLRINC^DBACK(mode)
Argument Description
mode Indicates what output to write to the terminal during the procedure.

“QUIET” — Only display return value and text related to abnormal conditions.

Any other value — Display the directory names as they are processed.

For example:

%SYS>w $$CLRINC^DBACK("QUIET")
1
%SYS> 


%SYS>Do CLRINC^DBACK("NOISY")
 
     Cleared incremental backup bitmap in c:\iris-install\mgr\
     Cleared incremental backup bitmap in c:\iris-install\mgr\irisaudit\
     Cleared incremental backup bitmap in c:\iris-install\mgr\user\
%SYS>

Notes for this procedure:

  • Requires read and write access to the ^SYS global.

  • Records the state of switch 13, sets it if it is not already, and restores it to its original state upon exit.

  • Issues a New command on all local variables except those defined in the main backup procedure.

  • Leaves directories dismounted if they are dismounted when you call this routine.

Edit/Display List of Directories for Backup Using ^BACKUP

Important:

When editing the database list use the database name, not the directory name. This is consistent with the way the backup configuration works in the Management Portal.

Options of the InterSystems IRIS ^BACKUP utility allow you to backup InterSystems IRIS databases or to restore an already created backup. If you have not created a list of databases, then the utility includes all databases in the backup. When you create a list, it applies to all aspects of the InterSystems IRIS backup system including calls to the entry points of the ^DBACK utility in scripted backups.

The following examples show sample output from each option on the menu:

  1. From the ^BACKUP menu, choose option 4 to display the database backup list maintenance menu:

    %SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
5) Abort Backup
6) Display Backup volume information
7) Monitor progress of backup or restore
 
Option? 4
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information

  2. To add a database to the list choose option 1. This example also uses option 3 to show that the database is added to the current list.

    1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 1
Enter database to add? DATA
Enter database to add?
You've selected DATA to be added to the backups
Are you sure you want to do this (yes/no)? y
Completed.
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 3
The following 3 databases are included in backups
     IRISAUDIT               C:\iris-install\Mgr\irisaudit\
     IRISSYS                 C:\iris-install\Mgr\
     USER                    C:\iris-install\Mgr\User\

  3. To remove a database to the list choose option 2. This example also uses option 3 to show that the database is removed from the current list.

    1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 2
Enter database to remove (^ when done)?  DATA
Enter database to remove (^ when done)?
You've removed DATA from the backups
Are you sure you want to do this? y
Completed.
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information

Option? 3
The following 3 databases are included in backups
     IRISAUDIT          C:\iris-install\Mgr\irisaudit\
     IRISSYS            C:\iris-install\Mgr\
     USER               C:\iris-install\Mgr\User\

  4. To display a list of all databases in this instance choose option 4:

    1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 4
The following is a list of all databases in the configuration.
Databases which are part of the backup are marked with (*)
     (*) IRISAUDIT           c:\iris-install\mgr\irisaudit\
         IRISLIB (Read Only) c:\iris-install\mgr\irislib\
         IRISLOCALDATA       c:\iris-install\mgr\irislocaldata\
     (*) IRISSYS             c:\iris-install\mgr\
     (*) USER                c:\iris-install\mgr\user\

  5. To display information about the last full backup choose option 5:

    1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 5
 
=====Last Full Backup Information=====
 
Date: 19 Jan 2018
Description: Full backup of all databases that are in the backup database list.
Device: c:\iris-install\mgr\backup\FullDBList_20180119_001.cbk

Abort a Running Backup Using ^BACKUP

You can abort a running backup using menu option 5 of the ^BACKUP utility.

%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
5) Abort Backup
6) Display Backup volume information
7) Monitor progress of backup or restore
 
Option? 5
Are you sure you want to abort the backup operation ? <No> Yes
Backup abortion succeed.

If no backup is running when you choose this option, you receive the following message:

No Backup operation is currently running.

Display Information About a Backup Volume Using ^BACKUP

When you select option 6 from the ^BACKUP menu, you are prompted for the pathname of a backup file, as shown in the following:

Enter the backup volume you want to display information from
 (Type STOP to exit)
Device: c:\131u1\mgr\backup\FullAllDatabases_20180802_001.cbk =>
 
This backup volume was created by:
InterSystems IRIS for Windows (x86-64) 2018.1.1 (Build 257U) Sun Jul 1 2018 23:35:31 EDT
 
The volume label contains:
   Volume number       1
   Volume backup       AUG 2 2018 12:27PM Full
   Previous backup     AUG 2 2018 11:35AM Cumulative Incremental
   Last FULL backup    AUG 2 2018 11:24AM
   Description         Full backup of ALL databases
   Buffer Count        0
   Mirror name         MIRROR122
   Failover member     NONNIE20/TEST2A   
   Journal File        c:\131u1\mgr\journal\20180802.005
   Log file            c:\131u1\mgr\Backup\FullAllDatabases_20180802_001.log
   Backup Status       Completed
 
Database                                Size(mb)  Mirror DB Name 
--------                                --------  --------------
c:\131u1\mgr\                                191
c:\131u1\mgr\irisaudit\                      11
c:\131u1\mgr\user\                          2113  MUSER
Total of 3 databases, totaling 2315 mb
Backup volume size is 2365 mb

Monitor Backup or Restore Progress Using ^BACKUP

To monitor the progress of a running backup or restore job started using ^BACKUP, select option 7 from the ^BACKUP menu. You can start the monitor in a separate Terminal window before starting the backup or restore job.

For a running backup job, the following information is displayed:

                                 Backup Status
                                 -------------
 
Status:                       Running
Backup process pid:           13052
Backup file:                  c:\132u1\mgr\stcfull.bck
Description:
Log file:                     c:\132u1\mgr\irisbackup.log
Type:                         Full
Start time:                   2018-09-05 14:09:02
Estimated finish time:        2018-09-05 14:09:45
Total time (hh:mm:ss):        00:00:18
Time remaining (hh:mm:ss):    00:00:25
Estimated backup size:        7.68GB
Current backup size:          3.12GB
Current Backup rate:          184MB/sec
% Completed                   41

For a running restore job, the following information is displayed:

                                 Restor Status
                                 -------------
 
Status:                       Running
Restore process pid:          13052
Restore file:                 c:\132u1\mgr\stcfull.bck
Description:
Type:                         Full
Start time:                   2018-09-05 14:10:49
Estimated finish time:        2018-09-05 14:12:07
Total time (hh:mm:ss):        00:00:34
Time remaining (hh:mm:ss):    00:00:44
Restore file size:            7.68GB
Restore size completed:       3.28GB
Current restore rate:         103MB/sec
% Completed                   43
Note:

When doing an incremental backup, some of the fields are not available and are displayed as N/A. This includes Time remaining, Estimated backup size, and % Completed.

A restore job cannot be monitored if switch 10 was set when starting the restore.

Next sectionOnline Backup Restore Utility
Previous sectionManaging Online Backups
FeedbackOpens in a new tab