Backup.General
Class Backup.General Extends %SYSTEM.Help [ Abstract, System = 4 ]
Parameters
DOMAIN
Parameter DOMAIN = "%Utility";
Default Localization Domain
Methods
ExternalFreeze
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 [ PublicList = (ALRDY10, ALRDY13, FORCE, NOINPUT, NOFORCE, LOGONLY, CLUBACKUP, QUIET, QUIETLY, INTERNAL, gui, logfile, OK, CLUMEM, markinfo, DATE, TIME, TYPE, Y, lastfile, success, status, ans) ]
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:
- The system runs out of global buffers for processes to write to.
- 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")
ExternalThaw
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.
ExternalSetHistory
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.
StartTask
ClassMethod StartTask(taskname As %String, jobbackup As %Boolean = 0, quietflag As %Boolean = 1, Device As %String = "", IsTape As %String = "") As %Status [ Internal, PublicList = (gui, logfile, FORCE, NOFORCE, LOGONLY, P10, return) ]
Starts a backup using the specified task.
jobbackup FALSE means the backup should be run in the current process and the returned value reflects the success or failure of the backup. TRUE means the backup is jobbed off and the returned value reflects whether we successfully jobbed the backup off or not.
quietflagWhen jobbackup is false, this is FALSE if output should be displayed on the principle output device or TRUE if output should only be written to the log file.
When jobbackup is TRUE this is a signal whether the backup is being started via the ControlPanel. When quietflag is TRUE (the default) no output is generated on the principle output device. The log file still contains all of generated messages.
The combination of jobbackup=TRUE and quietflag=FALSE is not supported for customer written applications.
Returns: %Status to indicate whether the backup succeeded or failed or was jobbed off successfully.
GetFilename
ClassMethod GetFilename(taskname As %String = "", NextBackup As %Boolean = 1, LogFile As %Boolean = 1, Device As %String = "") As %String [ Internal ]
Given a task, a Last or Next flag and the file type flag (log file or backup file), add in the path information and return the fully expanded form of the file so it can be opened.
taskname - name of the task to get a filename for.
NextBackup - FALSE = Filename for last run, TRUE = Filename for next run
LogFile - FALSE = Get name of backup output file, TRUE = Get name of log file
Returns:
$LB(0,
$LB(1,
FreezeLog
ClassMethod FreezeLog(File As %String = "", Msg As %String = "", Level As %Integer = 0) [ Internal ]
SuspendWD
ClassMethod SuspendWD(TimeOut As %Integer, Hibernate As %Integer = 0, Verbose As %Boolean = 0, FreezeTimeout As %Integer = 0, WDSuspendLimit As %Integer = 0) As %Status [ Internal ]
This method suspends the wd and returns when it is suspended. This can be called for either clustered or non clustered systems. For non clustered systems if the system code supports a value of SFNMAX in the gfbackreq array, it works by setting SFNMAX into the gfbackreq array and setting the # of databases to 1. This suspends the wd w/out adjusting the incremental backup info for any of the databases. If the system code doesn't support this feature then it uses the traditional method of setting switch 13. Note that the TimeOut, hibernate and verbose settings are ignored if we use $ZU(182) to suspend the wd as this should never fail.
ResumeWD
ClassMethod ResumeWD() As %Status [ Internal ]
This method resumes the system after SuspendWD() has suspended it.
QuiesceUpdates
ClassMethod QuiesceUpdates(TimeOut As %Integer, Hibernate As %Integer = 0, Verbose As %Boolean = 0) As %Status [ PublicList = (ALRDY13, NOFORCE, CLUBACKUP, QUIET, QUIETLY, INTERNAL) ]
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
BlockUpdates
ClassMethod BlockUpdates() As %Status [ Internal ]
ResumeUpdates
ClassMethod ResumeUpdates() As %Status
Allow database updates to resume
QuiesceUpdatesClusterWide
ClassMethod QuiesceUpdatesClusterWide(TimeOut As %Integer, Hibernate As %Integer = 0, Verbose As %Boolean = 0) As %Status [ PublicList = (ALRDY13, NOFORCE, CLUBACKUP, QUIET, QUIETLY, INTERNAL) ]
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
BlockUpdatesClusterWide
ClassMethod BlockUpdatesClusterWide(AlreadyBlockedLocally As %Boolean = 0) As %Status [ Internal ]
BlockUpdatesSlaves
ClassMethod BlockUpdatesSlaves() As %Status [ Internal ]
ResumeUpdatesClusterWide
ClassMethod ResumeUpdatesClusterWide() As %Status [ Internal ]
Allow database updates to resume cluster wide (including local system)
ResumeUpdatesSlaves
ClassMethod ResumeUpdatesSlaves() As %Status [ Internal ]
AreUpdatesBlocked
ClassMethod AreUpdatesBlocked() As %Boolean [ Internal ]
Whether database updates are blocked on local system
AddDatabaseToList
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.
RemoveDatabaseFromList
ClassMethod RemoveDatabaseFromList(remdb As %String) As %Status
Remove a database from the list of databases to be included in a backup
ClearDatabaseList
ClassMethod ClearDatabaseList() As %Status
Remove all databases from the list of databases to be included in a backup
GetLastFullBackupInfo
ClassMethod GetLastFullBackupInfo() As %String
Get information about last full backup
Returns:
$LB(0,"No information recorded about a full backup")
$LB(1,
GetBackupVolumeInfo
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")
DatabaseListExecute
ClassMethod DatabaseListExecute(ByRef qHandle As %Binary) As %Status [ Internal ]
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.
DatabaseListFetch
ClassMethod DatabaseListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]
DatabaseListClose
ClassMethod DatabaseListClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = DatabaseListExecute ]
IsWDSuspended
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.
IsWDSuspendedExt
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.
AbortBackup
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.
GetAbortStatus
ClassMethod GetAbortStatus() As %Integer
Return the status of backup abort flag.
Returns 0 - Abort is NOT in progress. 1 - Abort is in progress.
ClearAbortStatus
ClassMethod ClearAbortStatus() As %Integer
Clear backup abort flag.
Returns the original backup abort status.
GetDBNoBackupFlag
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.
CommandLineFreeze
ClassMethod CommandLineFreeze(doHalt As %Boolean = 1, ExternalFreezeTimeOut As %Integer = 0, ShardMasterNamespace As %String = "") As %Status [ Internal ]
This method supports the command line "iris freeze " option. On non-sharded systems, it calls Backup.General:ExternalFreeze. On sharded systems, it runs a coordinated freeze of the entire cluster via Backup.ShardedCluster:ExternalFreeze By default, this method terminates the process with either a success (0) or failure (1) status returned to the OS caller. If the doHalt flag is turned off, it returns a status code instead of halting.
Arguments:
doHalt = flag to halt process after freezing. Default is 1.
ExternalFreezeTimeOut = time, in seconds, to let processes run during a freeze before they are suspended. Uses the system default when 0. Default is 0. Note, if global buffers fill up, suspension may occur before this timeout.
ShardMasterNamespace = master namespace for a sharded cluster. Ignored on non-sharded systems. If left empty, defaults to the cluster metadata's MasterNamespace value (the shard master namespace from the data master's perspective).
CommandLineThaw
ClassMethod CommandLineThaw(doHalt As %Boolean = 1, ShardMasterNamespace As %String = "") As %Status [ Internal ]
This method supports the command line "iris thaw iris" option. It calls either Backup.General:ExternalThaw() or Backup.ShardedCluster:ExternalThaw() as appropriate. By default, this method terminates the process with either a success (0) or failure (1) status returned to the OS caller. If the doHalt flag is turned off, it returns a status code instead of halting.
Arguments:
doHalt = flag to halt process after thawing. Default is 1.
ShardMasterNamespace = shard master namespace for a sharded cluster. Ignored on non-sharded systems. If left empty, this method defaults to the cluster metadata's MasterNamespace value (the shard master namespace from the data master's perspective).