Skip to main content

Backup.General

abstract class Backup.General extends %SYSTEM.Help

Method Inventory

Parameters

parameter DOMAIN = %Utility;
Default Localization Domain

Methods

classmethod AbortBackup() as %Integer
This method will abort the currently running InterSystems IRIS On-Line Backup operation.
Returns 0 - success, 1 - No Backup is currently running, 2 - Backup is aborted already.
classmethod AddDatabaseToList(newdb As %String) as %Status
Add a database to the list of databases to be included in a backup.
An error is returned if the specified database is the system TEMP database.
classmethod ClearAbortStatus() as %Integer
Clear backup abort flag.
Returns the original backup abort status.
classmethod ClearDatabaseList() as %Status
Remove all databases from the list of databases to be included in a backup
classmethod ExternalFreeze(LogFile As %String = "", Text As %String = "", SwitchJournalFile As %Boolean = 1, TimeOut As %Integer = 10, Hibernate As %Integer = 0, Verbose As %Boolean = 0, ExternalFreezeTimeOut As %Integer = 0, Username As %String = "", Password As %String = "", WDSuspendLimit As %Integer = 0, RequiredFile As %String) as %Status

This method is intended to be called when you perform an external backup as described in External Backup.

ExternalFreeze is used to freeze InterSystems IRIS before starting an operation which will produce a valid full backup of a set of databases using technology external to InterSystems IRIS such as disk mirroring or snapshots. The mechanisms used to freeze InterSystems IRIS are different on clustered and non-clustered systems.

Non-Clustered systems:

WARNING: On non-clustered systems, this entry point should only be used if you are journaling all of your database updates. If databases are not being journalled, and the system should happen to crash while the write daemon is suspended, then all updates to non-journalled databases will be lost from the point in time the write daemon was suspended.

When this entry point is called on non-clustered systems, the write daemon is suspended from writing to the database. Processes will continue to run with updates only being written to the journal file and to the global buffer pool. Updates will not be written to the databases. When the ExternalThaw() method is called, the write daemon will resume and write the updated buffers to the databases. During the period of time that the write daemon is suspended, processes may themselves be suspended when trying to update the database if one of the following occurs:

1) The system runs out of global buffers for processes to write to.
2) The length of the suspension is longer than the system default (currently 600 seconds/10 minutes).

Note that the behavior of #2 can be modified by specifying the ExternalFreezeTimeOut parameter to extend the amount of time user processes can continue to update the database on the system before they are suspended.

Restoring the backup:

Restore the database files using your external restore mechanism. Once the databases are restored and mounted on the system, you will need to restore the journals starting which the one which was switched to during the ExternalFreeze.() You can see what journal file to start with by examining the messages.log.

Clustered systems:

When this entry point is called on a clustered system, switch 13 is set on all the cluster members which will suspend all processes trying to update the database. When this method returns successfully, all the clustered systems have been quiesced, and it is now safe to take a snapshot of the database. When the ExternalThaw() method is called, switch 13 is cleared on all the cluster members, and the suspended processes will resume writing to the database.

Restoring the backup:

Restore the database files using your external restore mechanism. Once the databases are restored and mounted on the system, you will need to use option 4 in CLUMENU^JRNRESTO.

Arguments:
Text Optional text string to store in the journal marker.

LogFile If this is not NULL then this is a filename which is opened for output where messages from the execution of this method are logged. The file is created if it does not exist. If the file exists, new messages are appended to the end of the file. By default, all messages are also logged to the messages.log file. Default="" (no logging).

SwitchJournalFile 0/1 to indicate whether the system should switch to a new journal file and add a journal marker before freezing the system. Default=1 (switch journal).

TimeOut Ignored on non-cluster systems. For clustered systems, how long to wait (in seconds) for the system to quiesce before giving up. Default=10.

Hibernate Ignored on non-cluster systems. For clustered systems, number of times to hibernate (with database updates resuming) and retry the whole process of blocking and waiting, before returning failure. Default=0.

Verbose Ignored on non-cluster systems. 0/1 For clustered systems, whether to print out messages on the screen about what is going on. Default=0.

ExternalFreezeTimeOut Ignored for Clustered systems. Optional parameter which specifies the number of seconds which the write daemon can be suspended before the system blocks processes which are updating the database. The default of 0 should be sufficient for most environments and means that the system will wait for 600 seconds (10 minutes) before suspending processes which are updating the database. Some environments may find that their disk snapshots take more than 10 minutes and that processes are getting suspended. In those situations, an explicit value can be passed. For example, to increase this time to 15 minutes, pass 900 for this parameter. This assumes that there are sufficient buffer space to support the activity for the period. If the buffers become full processes may start to be blocked. NOTE: If the system should crash while the write daemon is suspended, a subsequent startup of the system may take an extended period of time while the databases are updated with information from the journal.

Username Username to pass to the ExternalThaw() method. Default="".

Password Password to pass to the ExternalThaw() method. Default="".

WDSuspendLimit Ignored for Clustered systems. An optional parameter for user to specify the maximum duration, in seconds, for which the write daemon (WD) should remain suspended. Once the limit is reached or exceeded, WD resumes activity (as when ExternalThaw() is called) and any backup that hasn't finished by then should be considered a failure. By default, WD doesn't resume activity until notified so (when backup is finished).

RequiredFile (Return by reference) the oldest journal file required for transaction rollback after the backup is restored.

Returns: On error a descriptive message is included as part of the return code. If an error occurs, the system is not frozen when this method returns.
If this command is used as an argument as part of an O/S script, a Status value of 5 is returned if the system is successfully frozen. If the Freeze fails, then a Status value of 3 is returned.
Here is an example of how to use this on each of the platforms. Make sure your default directory is the "mgr" directory before you invoke the API. Also keep in mind that in Windows batch scripts all method arguments to ExternalFreeze() and ExternalThaw() of type string need to be entered with three double quotation marks on either side.

Windows
..\bin\irisdb -s. -U%%SYS ##Class(Backup.General).ExternalFreeze()
rem note that we need to check errorlevel from highest to lowest here....
if errorlevel 5 goto OK
if errorlevel 3 goto FAIL
echo errorlevel returned wrong value
goto END
:OK
echo SYSTEM IS FROZEN
goto END
:FAIL
echo SYSTEM FREEZE FAILED
:END
rem Now unfreeze the system
..\bin\irisdb -s. -U%%SYS ##Class(Backup.General).ExternalThaw()
Unix

The following example assumes that the instance name is syu72.

iris terminal syu72 -U%SYS "##Class(Backup.General).ExternalFreeze()"
status=$?
	if [ $status -eq 5 ]; then
		echo "SYSTEM IS FROZEN"
	elif [ $status -eq 3 ]; then
		echo "SYSTEM FREEZE FAILED"
	fi
# Now unfreeze the system
iris terminal syu72 -U%SYS "##Class(Backup.General).ExternalThaw()"
Note that if you pass parameters into the call, you may need to escape them depending on the O/S you are running on. For example the quotes "" are escaped below:
..\bin\irisdb -s. -U%SYS ##Class(Backup.General).ExternalFreeze(\"c:\data\freeze.log\")
classmethod ExternalSetHistory(LogFile As %String = "", Description As %String = "") as %Status

This method is intended to be called when you perform an external backup as described in External Backup. Use this method to record the fact that you have successfully performed an external backup and to note the name of the log file for that backup. ExternalSetHistory adds an entry to the backup history and counts that backup in the journal purge criteria. Call this method after a successful backup and after calling ExternalThaw().



Arguments:
LogFileThis is the name of the log file to be recorded in the backup history.

Description A description of this backup to be recorded in backup history.

Returns:Always returns OK.
classmethod ExternalThaw(LogFile As %String = "", Username As %String = "", Password As %String = "") as %Status

This method is intended to be called when you perform an external backup as described in External Backup.

ExternalThaw is used to resume InterSystems IRIS after Backup.General.ExternalFreeze(). Note that when ##Class(Backup.General).ExternalThaw is passed in on the `iris terminal` command line, the process does not go through the normal authentication method. Instead the username and password passed in as parameters is checked against the username and password passed into the ExternalFreeze method.

Arguments:
LogFile If this is not NULL then this is a filename which is opened for output where messages from the execution of this method are logged. The file is created if it does not exist. If the file exists, new messages are appended to the end of the file. By default, all messages are also logged to the messages.log file.

Username Username which was passed to the ExternalFreeze() method. Default="".

Password Password which was passed to the ExternalFreeze() method. Default="".

Returns: On error a descriptive message is included as part of the return code. If an error occurs, the system may still be suspended.
If the method is invoked via an OS script, exit status 5 indicates success and 3, failure. See ExternalFreeze() for sample code to check exit status.
classmethod GetAbortStatus() as %Integer
Return the status of backup abort flag.
Returns 0 - Abort is NOT in progress. 1 - Abort is in progress.
classmethod GetBackupVolumeInfo(Volume As %String, ByRef Info As %String) as %String
Return Information about a backup volume.
Returns the following information in the Info array:

Info("BackupVersion") - Internal version of the BACKUP utility (currently 1)
Info("CacheVersion") - Product version which created the backup
Info("BackupVolume") - Backup volume #
Info("BackupDate") - Date of the backup (AUG 2 2012)
Info("BackupTime") - Time of the backup (11:35AM)
Info("BackupType") - Type of backup (Full, Incremental, Cumulative Incremental)
Info("BackupTimeDH") - $h of backup. Can be used to reference ^SYS("BUHISTORY",Time) where time is calculated with +Info("BackupTimeDH")*1000000+$p(Info("BackupTimeDH"),",",2)
Info("PrevBackupDate") - Date of last backup (AUG 2 2012)
Info("PrevBackupTime") - Time of last backup (11:35AM)
Info("PrevBackupType") - Type of backup (Full, Incremental, Cumulative Incremental)
Info("LastFullBackupDate") - Date of last FULL backup (AUG 2 2012)
Info("LastFullBackupTime") - Time of last FULL backup (11:35AM)
Info("Description") - Description of the backup
Info("BufferCount") - Used for Magtapes backup
Info("Size") - Size in MB of the backup volume. "UNKNOWN for magtapes

The following fields are retrieved from the backup history global. If the backup history does not exist, they are returned as "UNKNOWN"

s Info("JournalFile") - Journal file in use at time of backup
s Info("LogFile") - Log results of the backup
s Info("Status") - Result of the backup. "Aborted","Warning","Completed", or "Failed"
s Info("WIJInfo") - Information from the WIJ file at the end of backup

If the backup was done on a Mirror or Async mirror, the following is also returned:

Info("MirrorName") - Name of the mirror
Info("FailoverMember") - Name of the failover member
Info("AsyncMember") - Name of the Async Member

Now for each database in the backup volume, we return the following (note that the index is in the order the database was backed up in the file):

Info("Database",index,"Directory") - Directory of the database
Info("Database",index,"ClusterFlag") - "P" (private mount) "C" (Cluster mount)
Info("Database",index,"ZU49") - $zu(49) flags at time backup started

If the database is mirrored, additional mirror information is returned in Info("Database",index,"Mirror")
classmethod GetDBNoBackupFlag(Directory As %String = "", ByRef Result As %Integer) as %Status
Get the GFNOBACKUP flag in the database.
The flag is returned in 'Result'. When it is one means don't mark incremental bitmaps, and if we attempt to backup the file we must do a full backup. This flag is set by file creation and by detecting a label error on an incremental backup bitmap.
classmethod GetLastFullBackupInfo() as %String
Get information about last full backup
Returns:
   $LB(0,"No information recorded about a full backup")
   $LB(1,<date>,<description>,<device>)
classmethod IsWDSuspended() as %Boolean
This method returned a value to tell whether the Write Daemon is suspended or not. Return value 1 indicates the WD is suspended, 0 indicates WD is NOT suspended.
classmethod IsWDSuspendedExt() as %Boolean
An external version of IsWDSuspended(). When called in an external script, exit status is set to 5 if WD is suspended or 3 otherwise.
classmethod QuiesceUpdates(TimeOut As %Integer, Hibernate As %Integer = 0, Verbose As %Boolean = 0) as %Status
Block new database update activity and wait for existing update activity to finish within a certain period of time
  • TimeOut: How long to wait (in seconds) before giving up. Default=10.
  • Hibernate: Number of times to hibernate (with database updates resuming) and retry the whole process of blocking and waiting, before returning failure. Default=0.
  • Verbose: Whether to print out messages on the screen about what is going on. Default=0.
WARNING: It is assumed that updates are not blocked before this call
classmethod QuiesceUpdatesClusterWide(TimeOut As %Integer, Hibernate As %Integer = 0, Verbose As %Boolean = 0) as %Status
Quiesce database update activity cluster wide
  • TimeOut: How long to wait (in seconds) before giving up. If not specified, the default is determined based on system configuration.
  • Hibernate: Number of times to hibernate (with database updates resuming) and retry the whole process of blocking and waiting, before returning failure. Default=0.
  • Verbose: Whether to print out messages on the screen about what is going on. Default=0.
WARNING: It is assumed that updates are not blocked on the local system before this call
classmethod RemoveDatabaseFromList(remdb As %String) as %Status
Remove a database from the list of databases to be included in a backup
classmethod ResumeUpdates() as %Status
Allow database updates to resume

Queries

query DatabaseList()
Selects Database As %String, Directory As %String
Provides the list of databases the user has specified to be included in a backup. Note that if the user has not defined a list of databases to be backed up then all databases except the IRISTEMP database will be backed up.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab