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
LISTDIRS^DBACK
CLRINC^DBACK (concurrent external backup Only)

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.

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.

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.