Class Reference
Cache for UNIX 2018.1.1
InterSystems: The power behind what matters   
Documentation  Search
Private  Storage  

abstract class Backup.General extends %SYSTEM.Help

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 31 1


Summary

Methods
AbortBackup AddDatabaseToList ClearAbortStatus ClearDatabaseList
ExternalFreeze ExternalSetHistory ExternalThaw GetAbortStatus
GetBackupVolumeInfo GetDBNoBackupFlag GetLastFullBackupInfo Help
IsWDSuspended IsWDSuspendedExt QuiesceUpdates QuiesceUpdatesClusterWide
RemoveDatabaseFromList ResumeUpdates


Parameters

• parameter DOMAIN = "%Utility";
Default Localization Domain

Methods

• classmethod AbortBackup() as %Integer
This method will abort the currently running Cache 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 CACHETEMP.
• 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
ExternalFreeze is used to freeze Cache' before starting an operation which will produce a valid full backup of a set of databases using technology external to Cache' such as disk mirroring or snapshots. The mechanisms used to freeze Cache' 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 cconsole.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 cconsole.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 Cache write daemon (WD) should remain suspended. Once the limit is reached or exceeded, WD would resume activity 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).

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 id 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:

Windows
..\bin\cache -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\cache -s. -U%SYS ##Class(Backup.General).ExternalThaw()

VMS
csession CACHE -"U%SYS" "##Class(Backup.General).ExternalFreeze()"
STATUS=$STATUS
if STATUS .eq. 5 then write sys$output "SYSTEM FROZEN"
if STATUS .eq. 3 then write sys$output "SYSTEM FREEZE FAILED"
csession CACHE -"U%SYS" "##Class(Backup.General).ExternalThaw()"

Unix
csession 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
csession syu72 -U%SYS "##Class(Backup.General).ExternalThaw()"
• classmethod ExternalSetHistory(LogFile As %String = "", Description As %String = "") as %Status
ExternalSetHistory is used to create a backup history entry and count it in the journal purge criteria.
This API is intended to be called for 'Paused External Backup' method. After ##Class(Backup.General).ExternalThaw is called to resume Cache, when the backup is successful use this API to record this backup in backup history and purge the journal.

Arguments:
LogFile This is the log file to be recorded in the backup history.

Description A description about this backup to be recorded in backup history entry.

Returns: Always return OK.
• classmethod ExternalThaw(LogFile As %String = "", Username As %String = "", Password As %String = "") as %Status
ExternalThaw is used to resume Cache' after Backup.General.ExternalFreeze(). Note that when ##Class(Backup.General).ExternalThaw is passed in on the csession 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 cconsole.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") - Version of Cache' 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 included in a backup. If a list has not been defined, all databases on the system except cachetemp are returned.


Copyright © 1997-2019, InterSystems Corporation