Skip to main content

Back Up Databases Using ^DBACK

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.

Next sectionEdit/Display List of Directories for Backup Using ^BACKUP
Previous sectionPerform Backup and Restore Tasks Using ^BACKUP
FeedbackOpens in a new tab